导入 GraphQL API

2025-10-15

适用于：所有 API 管理层级

GraphQL 是 API 的开源行业标准查询语言。与基于终结点（或 REST 风格）的 API 不同，GraphQL API 用例范围更广，并更加专注于数据类型、模式和查询。

通过使用 API 管理来暴露你的 GraphQL APIs，您可以：

通过 Azure 门户、Azure CLI 或其他 Azure 工具将 GraphQL 终结点或 GraphQL 架构添加为 API。
（预览版）利用 REST 或 SOAP API 中的信息来扩展或设计 GraphQL API，并对 GraphQL 架构中定义的字段使用HTTP 解析程序。
通过应用现有的访问控制策略和 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 架构并设置字段解析程序。

先决条件

一个 Azure API 管理实例。创建一个（如果尚未创建）。
您可以使用 Azure CLI 导入 API。

可以使用本地 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 来导入 API。
- 如果选择在本地使用 Azure PowerShell：
  - 安装最新版本的 Az PowerShell 模块。
  - 使用 Connect-AzAccount -Environment AzureChinaCloud cmdlet 连接到 Azure 帐户。

添加 GraphQL API

在 Azure 门户中，转到 API 管理实例。
在左窗格中，选择 API>API。
选择 “添加 API”。
在 “定义新 API”下，选择 GraphQL 磁贴。

在生成的对话框中，选择“ 完整”，然后在必填字段中输入值，如下表所述。

价值	Description
显示名称	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 管理实例。

# Details specific to API Management instance.
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 管理实例。

# Details specific to API Management instance.
$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 更新设置。

测试 GraphQL API

导航到 API 管理实例。
在侧面导航菜单中的“API”部分下，选择“API”。
在“所有 API”下，选择 GraphQL API。
选择“测试”选项卡以访问“测试”控制台。
在“标头”下：
1. 从 “名称” 下拉菜单中选择标题。
2. 输入“ 值 ”字段的值。
3. 通过选择 “+ 添加标头”来添加更多标头。
4. 使用 垃圾桶图标删除标头。
如果已将产品添加到 GraphQL API，请在 “应用产品范围”下应用产品范围。
在 “查询编辑器”下，任一：
1. 从侧菜单中的列表中选择至少一个字段或子字段。选择的字段和子字段将显示在查询编辑器中。
2. 开始在查询编辑器中键入内容来撰写查询。
在“查询变量”下，添加变量来重用相同的查询或变更，并传递不同的值。
选择发送。
查看响应。
重复上述步骤以测试不同的有效负载。
测试完成后，退出测试控制台。