你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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 运行测试查询。

后续步骤