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

2025-10-22

适用于：所有 API 管理层级

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

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

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

注释

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

在本文中，你将：

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

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

先决条件

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

转到你的 API 管理实例

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

添加 GraphQL 架构

在左窗格中的 API 下，选择 API。
在 “定义新 API”下，选择 GraphQL 磁贴。

在对话框中，选择“ 完整”，然后在必填字段中输入值，如下表所述。

价值	DESCRIPTION
显示名称	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. 如果需要，请更新 Name 属性，可以选择输入“说明”，然后确认或更新“类型和字段”选择。
2. 在“数据源”中，选择“HTTP API”。

在“解析程序策略”编辑器中，使用适用于你的方案的子元素更新元素。<http-data-source> 例如，以下解析程序通过users调用现有 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 特定的攻击。

Compartilhar via