Azure API Management 中的 GraphQL API 概述
适用于:所有 API 管理层级
可以使用 API Management 管理 GraphQL API - 基于 GraphQL 查询语言的 API。 GraphQL 提供 API 中数据的完整且易于理解的描述,使客户端能够有效地检索所需的数据。 详细了解 GraphQL
API Management 可帮助你导入、管理、保护、测试、发布和监视 GraphQL API。 可选择以下两个 API 模型之一:
直通 GraphQL | Synthetic GraphQL |
---|---|
▪️ 将 API 直通到现有 GraphQL 服务终结点 ▪️ 支持 GraphQL 查询、突变和订阅 |
▪️ 基于自定义 GraphQL 架构的 API ▪️ 支持 GraphQL 查询、突变和订阅 ▪️ 例如,将自定义解析程序配置为 HTTP 数据源 ▪️ 开发 GraphQL 架构和基于 GraphQL 的客户端,同时从旧 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 不支持查询和变更。
其他类型
解析程序
解析程序负责将 GraphQL 架构映射到后端数据,为对象类型中的每个字段生成数据。 数据源可以是 API、数据库或其他服务。 例如,解析程序函数将负责返回上一示例中 users
查询的数据。
在 API 管理中,可以创建解析程序,将对象类型中的字段映射到后端数据源。 可以在合成 GraphQL API 架构中为字段配置解析程序,但也可以将其配置为替代直通 GraphQL API 使用的默认字段解析程序。
API 管理目前支持基于 HTTP API、Cosmos DB 和 Azure SQL 数据源的解析程序,以返回 GraphQL 架构中各字段的数据。 每个解析程序都使用定制的策略进行配置,以连接到数据源并检索数据:
数据源 | 解析程序策略 |
---|---|
基于 HTTP 的数据源(REST 或 SOAP API) | http-data-source |
Cosmos DB 数据库 | cosmosdb-data-source |
Azure SQL 数据库 | sql-data-source |
例如,上述 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 运行测试查询。