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 中的 PUTPATCH 操作

  • 订阅 - 允许实时通知订阅客户端 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 架构中各字段的数据。 每个解析程序都使用定制的策略进行配置,以连接到数据源并检索数据:

数据源 解析程序策略
基于 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 运行测试查询。

后续步骤