Azure API Management 中的 GraphQL API 概述

适用于：所有 API 管理层级

可以使用 API Management 管理 GraphQL API - 基于 GraphQL 查询语言的 API。 GraphQL 提供 API 中数据的完整且易于理解的描述，使客户端能够有效地检索所需的数据。 详细了解 GraphQL

API Management 可帮助你导入、管理、保护、测试、发布和监视 GraphQL API。 可选择以下两个 API 模型之一：

可用性

• 所有 API Management 服务层级都支持 GraphQL API
• API 管理工作区当前不支持合成 GraphQL API
• 对综合 GraphQL API 中的 GraphQL 订阅的支持目前处于预览状态，在消耗层中不可用

什么是 GraphQL?

GraphQL 是 API 的已开源的行业标准查询语言。 与围绕资源上的操作设计的 REST 风格 API 不同，GraphQL API 支持更广泛的用例，并专注于数据类型、模式和查询。

GraphQL 规范明确解决了依赖于 REST API 的客户端 Web 应用遇到的常见问题：

• 可能需要大量的请求来满足单个页面的数据需求
• REST API 返回的数据往往多于呈现页面所需的数据
• 客户端应用需要轮询才能获取新信息

使用 GraphQL API 时，客户端应用可以指定在查询文档中呈现页面所需的数据，该文档作为单个请求发送到 GraphQL 服务。 客户端应用还可以实时订阅从 GraphQL 服务推送的数据更新。

架构和类型

在 API Management 中，从 GraphQL 架构添加后端 GraphQL API 终结点检索的或由你上传的 GraphQL API。 GraphQL 架构描述：

• 客户端可从 GraphQL API 请求的数据对象类型和字段
• 允许对数据执行的操作类型，例如查询
• 可提供对于数据的额外的灵活性和控制的其他类型（例如联合和接口）

例如，用户数据的基本 GraphQL 架构和所有用户的查询可能如下所示：

type Query {
    users: [User]
}

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

操作类型

API Management 支持 GraphQL 架构中的以下操作类型。 有关这些操作类型的详细信息，请参阅 GraphQL 规范。

• 查询 - 提取数据，类似于 REST 中的 GET 操作

• 突变 - 修改服务器端数据，类似于 REST 中的 PUT 或 PATCH 操作

• 订阅 - 允许实时通知订阅客户端 GraphQL 服务上的数据更改

  例如，通过 GraphQL 突变修改数据时，订阅的客户端可能会自动收到有关更改的通知。

  重要

  API Management 支持使用 graphql-ws WebSocket 协议实现的订阅。 WebSocket 不支持查询和变更。

其他类型

API 管理支持 GraphQL 架构中的联合和接口类型。

解析程序

解析程序负责将 GraphQL 架构映射到后端数据，为对象类型中的每个字段生成数据。 数据源可以是 API、数据库或其他服务。 例如，解析程序函数将负责返回上一示例中 users 查询的数据。

在 API 管理中，可以创建解析程序，将对象类型中的字段映射到后端数据源。 可以在合成 GraphQL API 架构中为字段配置解析程序，但也可以将其配置为替代直通 GraphQL API 使用的默认字段解析程序。

API 管理目前支持基于 HTTP API、Cosmos DB 和 Azure SQL 数据源的解析程序，以返回 GraphQL 架构中各字段的数据。 每个解析程序都使用定制的策略进行配置，以连接到数据源并检索数据：

例如，上述 users 查询的基于 HTTP API 的解析程序可能映射到后端 REST API 中的 GET 操作：

<http-data-source>
	<http-request>
		<set-method>GET</set-method>
		<set-url>https://myapi.contoso.com/api/users</set-url>
	</http-request>
</http-data-source>

有关设置解析程序的详细信息，请参阅配置 GraphQL 解析程序。

管理 GraphQL API

• 应用现有访问控制策略和 GraphQL 验证策略来保护 GraphQL API，从而防范和抵御特定于 GraphQL 的攻击。
• 在 Azure 和开发人员门户中浏览 GraphQL 架构并针对 GraphQL API 运行测试查询。

后续步骤

• 导入 GraphQL API
• 导入 GraphQL 架构并设置字段解析程序