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

导入 GraphQL API

2025-10-09

适用于：所有 API 管理层级

在 API 管理中，可以在以下两个模型之一中添加 GraphQL API：直通到现有 GraphQL 终结点，或导入 GraphQL 架构并使用自定义字段解析程序创建合成 GraphQL API。有关详细信息，请参阅 GraphQL 概述。

在本文中，你将：

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

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

Prerequisites

一个 Azure API 管理实例。如果还没有实例，请创建一个。
Azure CLI，如果要使用它来导入 API。
- 在 Azure Cloud Shell 中使用 Bash 环境。有关详细信息，请参阅 Azure Cloud Shell 入门。
- 如果要在本地运行 CLI 引用命令，请安装 Azure CLI。如果在 Windows 或 macOS 上运行，请考虑在 Docker 容器中运行 Azure CLI。有关详细信息，请参阅如何在 Docker 容器中运行 Azure CLI。
  - 如果使用的是本地安装，请使用 az login 命令登录到 Azure CLI。要完成身份验证过程，请遵循终端中显示的步骤。有关其他登录选项，请参阅使用 Azure CLI 向 Azure 进行身份验证。
  - 如果系统发出提示，则在首次使用时安装 Azure CLI 扩展。有关扩展的详细信息，请参阅使用和管理 Azure CLI 中的扩展。
  - 运行 az version 以查找所安装的版本和依赖库。若要升级到最新版本，请运行 az upgrade。
如果您想使用 Azure PowerShell 来导入 API。
- 如果选择在本地使用 Azure PowerShell：
  - 安装最新版本的 Az PowerShell 模块。
  - 使用 Connect-AzAccount cmdlet 连接到 Azure 帐户。
- 如果选择使用 Azure Cloud Shell：
  - 有关详细信息，请参阅 Azure Cloud Shell 概述。

添加 GraphQL API

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

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

价值	说明
显示名称	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.net/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. 开始在查询编辑器中键入内容来撰写查询。
在“查询变量”下，添加变量来重用相同的查询或变更，并传递不同的值。
选择“发送”。
查看响应。
重复上述步骤以测试不同的有效负载。
完成测试后，退出测试控制台。