导入 GraphQL API

项目
04/01/2024

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

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

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

注意

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

在本文中，你将：

将直通 GraphQL API 添加到 API 管理实例。
测试 GraphQL API。

如果要导入 GraphQL 架构并使用 REST 或 SOAP API 终结点设置字段解析程序，请参阅导入 GraphQL 架构并设置字段解析程序。

先决条件

现有的 API 管理实例。如果还没有实例，请创建一个。
一个 GraphQL API。
Azure CLI

可以使用本地 Azure CLI。
- 如果需要，请安装 Azure CLI 来运行 CLI 参考命令。
- 本地 Azure CLI，请了解如何安装 Azure CLI。如果在 Windows 或 macOS 上运行，请考虑在 Docker 容器中运行 Azure CLI。有关详细信息，请参阅如何在 Docker 容器中运行 Azure CLI。
  - 通过使用 az login 命令登录到 Azure CLI。若要完成身份验证过程，请遵循终端中显示的步骤。有关其他登录选项，请参阅使用 Azure CLI 登录。
  - 出现提示时，请在首次使用时安装 Azure CLI 扩展。有关扩展详细信息，请参阅使用 Azure CLI 的扩展。
  - 运行 az version 以查找安装的版本和依赖库。若要升级到最新版本，请运行 az upgrade。
Azure PowerShell
- 如果选择在本地使用 Azure PowerShell：
  - 安装最新版本的 Az PowerShell 模块。
  - 使用 Connect-AzAccount -Environment AzureChinaCloud cmdlet 连接到 Azure 帐户。

添加 GraphQL API

在 Azure 门户，导航到 API 管理实例。
在左侧菜单中，选择“API”>“+ 添加 API”。
在“定义新 API”下，选择“GraphQL”图标。

在对话框中，选择“完整”并填写必填的表单字段。

Screenshot of fields for creating a GraphQL API.

字段	说明
显示名称	GraphQL API 的显示名称。
名称	GraphQL API 的原始名称。键入显示名称时自动填充。
GraphQL 类型	选择要从现有 GraphQL API 终结点导入的直通 GraphQL。
GraphQL API 终结点	带有 GraphQL API 终结点名称的基 URL。例如：`https://example.com/your-GraphQL-name`。你还可以使用常见的“swapi”GraphQL 终结点（例如 `https://swapi-graphql.azure-api.cn/graphql`）作为演示。
上传架构	（可选）选择浏览并上传你的架构文件，以替换从 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 后，在“设计”选项卡上浏览或修改架构。

以下示例使用 az apim api import 命令将 GraphQL 传递 API 从指定的 URL 导入到名为 apim-hello-world 的 API 管理实例。

# API Management service-specific details
APIMServiceName="apim-hello-world"
ResourceGroupName="myResourceGroup"

# API-specific details
APIId="my-graphql-api"
APIPath="myapi"
DisplayName="MyGraphQLAPI"
SpecificationFormat="GraphQL"
SpecificationURL="<GraphQL backend endpoint>"

# Import API
az apim api import --path $APIPath --resource-group $ResourceGroupName \
    --service-name $APIMServiceName --api-id $APIId \
    --display-name $DisplayName --specification-format $SpecificationFormat --specification-url $SpecificationURL

导入 API 后，如果需要，可以使用 az apim api update 命令更新设置。

以下示例使用 Import-AzApiManagementApi Azure PowerShell cmdlet 将 GraphQL 传递 API 从指定的 URL 导入到名为 apim-hello-world 的 API 管理实例。

# API Management service-specific details
$apimServiceName = "apim-hello-world"
$resourceGroupName = "myResourceGroup"

# API-specific details
$apiId = "my-graphql-api"
$apiPath = "myapi"
$specificationFormat = "GraphQL"
$specificationUrl = "<GraphQL backend endpoint>"

# Get context of the API Management instance. 
$context = New-AzApiManagementContext -ResourceGroupName $resourceGroupName -ServiceName $apimServiceName

# Import API
Import-AzApiManagementApi -Context $context -ApiId $apiId -SpecificationFormat $specificationFormat -SpecificationUrl $specificationUrl -Path $apiPath

导入 API 后，如果需要，可以使用 Set-AzApiManagementApi cmdlet 更新设置。