添加合成 GraphQL API 并设置字段解析程序

Artículo
04/15/2024

适用于：所有 API 管理层级

GraphQL 是 API 的已开源的行业标准查询语言。基于终结点的（或 REST 样式的）API 围绕资源操作进行设计，而 GraphQL API 与它不同，它支持更广泛的一组用例，并且专注于数据类型、架构和查询。

通过使用 API 管理来公开 GraphQL API，你可以：

通过 Azure 门户、Azure CLI 或其他 Azure 工具将 GraphQL 终结点或 GraphQL 架构添加为 API。
（预览版）使用 REST 或 SOAP API 中的信息来增强或设计 GraphQL API，并将 HTTP 解析程序用于 GRAPHQL 架构中定义的字段。
应用现有访问控制策略和 GraphQL 验证策略来保护 GraphQL API，从而防范和抵御特定于 GraphQL 的攻击。
在 Azure 和开发人员门户中查看架构并针对 GraphQL API 运行测试查询。

注意

API 管理中的单个 GraphQL API 只能映射到单个 GraphQL 后端终结点。
GraphQL API 需要 GraphQL 架构，无论是从现有 GraphQL 终结点还是由你上传。
API 管理支持 GraphQL 架构中的查询、变更和订阅操作类型。
消耗服务层级中不支持订阅。
必须使用 graphql-ws WebSocket 协议来实现订阅。 WebSocket 不支持查询和变更。

在本文中，你将：

将 GraphQL 架构导入 API 管理实例
使用现有的 HTTP 终结点为 GraphQL 查询设置解析程序
测试 GraphQL API

若要将现有 GraphQL 终结点公开为 API，请参阅导入 GraphQL API。

先决条件

现有的 API 管理实例。如果还没有实例，请创建一个。
扩展名为 .graphql 的有效 GraphQL 架构文件。
后端 GraphQL 终结点对于此方案是可选的。

转到你的 API 管理实例

在 Azure 门户中搜索并选择“API 管理服务” 。
在“API 管理”服务页上，选择你的 API 管理实例。

添加 GraphQL 架构

在侧面导航菜单中的“API”部分下，选择“API” 。
在“定义新 API”下，选择“GraphQL”图标。

在对话框中，选择“完整”并填写必填的表单字段。

用于创建 GraphQL API 的字段的屏幕截图。

字段	说明
显示名称	GraphQL API 的显示名称。
名称	GraphQL API 的原始名称。键入显示名称时自动填充。
GraphQL 类型	选择要从 GraphQL 架构文件导出的合成 GraphQL。
回退 GraphQL 终结点	可以选择输入包含 GraphQL API 终结点名称的 URL。如果未为字段设置自定义解析程序，API 管理会将 GraphQL 查询传递给此终结点。
说明	添加 API 的说明。
URL 方案	根据 GraphQL 终结点进行选择。如果 GraphQL API 包含订阅类型，请选择其中一个包含 WebSocket 方案（WS 或 WSS）的选项。默认选择：HTTP(S)。
API URL 后缀	添加 URL 后缀以在该 API 管理实例中标识此特定 API。在该 API 管理实例中，后缀必须唯一。
基 URL	显示 API 基 URL 的不可编辑字段
标记	将 GraphQL API 与新标记或现有标记关联。
产品	将 GraphQL API 与产品关联来发布它。
对此 API 进行版本控制？	选择向你的 GraphQL API 应用某个版本控制方案。

选择“创建”。
创建 API 后，在“设计”选项卡上浏览或修改该架构。

配置解析程序

配置解析程序，以将架构中的字段映射到现有 HTTP 终结点。此处提供了大致步骤。如需详细信息，请参阅配置 GraphQL 解析程序。

假设你导入了以下基本 GraphQL 架构并想要为 users 查询设置解析程序。

type Query {
    users: [User]
}

type User {
    id: String!
    name: String!
}

在边侧导航菜单中的“API”部分下，选择“API”> 你的 GraphQL API。
在“架构”选项卡上，查看（要在其中配置解析程序的）对象类型中字段的架构。
1. 选择一个字段，然后在左边距中悬停指针。
2. 选择“+ 添加解析程序”
在“创建解析程序”页上：
1. 根据需要更新“名称”属性，可选择输入“说明”，并确认或更新“类型”和“字段”选择。
2. 在“数据源”中，选择“HTTP API”。
在解析程序策略编辑器中，使用适用于方案的子元素更新 <http-data-source> 元素。例如，以下解析程序通过对现有 HTTP 数据源发出 GET 调用来检索“用户”字段。
```
    <http-data-source>
        <http-request>
            <set-method>GET</set-method>
            <set-url>https://myapi.contoso.com/users</set-url>
        </http-request>
    </http-data-source>
```
选择“创建”。
要解析架构中其他字段的数据，请重复上述步骤以创建解析程序。

提示

编辑解析程序策略时，选择“运行测试”以检查数据源的输出，可以根据架构进行验证。如果发生错误，响应将包含故障排除信息。

测试 GraphQL API

导航到 API 管理实例。
在侧面导航菜单中的“API”部分下，选择“API” 。
在“所有 API”下，选择 GraphQL API。
选择“测试”选项卡以访问“测试”控制台。
在“标头”下：
1. 从“名称”下拉菜单中选择标头。
2. 在“值”字段中输入值。
3. 选择“+ 添加标头”来添加更多标头。
4. 使用垃圾桶图标删除标头。
如果已将产品添加到 GraphQL API，请应用“应用产品范围”下的产品范围。
在“查询编辑器”下：
1. 从侧菜单中的列表中选择至少一个字段或子字段。选择的字段和子字段将显示在查询编辑器中。
2. 开始在查询编辑器中键入内容来撰写查询。
在“查询变量”下，添加变量来重用相同的查询或变更，并传递不同的值。
选择“发送”。
查看响应。
重复上述步骤以测试不同的有效负载。
测试完成后，退出测试控制台。

注意

可以在测试控制台中测试订阅：

在查询编辑器中设置订阅查询，然后选择“连接”以便与后端服务建立 WebSocket 连接。
在“订阅”窗格中查看连接详细信息。
在断开 WebSocket 连接或连接到新的 WebSocket 订阅之前，将一直保持 WebSocket 连接。

保护 GraphQL API

同时应用现有的身份验证和授权策略和 GraphQL 验证策略来保护 GraphQL API，以防范特定于 GraphQL 的攻击。

后续步骤

转换和保护已发布的 API

Compartir a través de

添加合成 GraphQL API 并设置字段解析程序

先决条件

转到你的 API 管理实例

添加 GraphQL 架构

配置解析程序

测试 GraphQL API

保护 GraphQL API

后续步骤

Recursos adicionales

Compartir a través de

添加合成 GraphQL API 并设置字段解析程序

先决条件

转到你的 API 管理实例

添加 GraphQL 架构

配置解析程序

测试 GraphQL API

保护 GraphQL API

相关主题

后续步骤

Recursos adicionales