导入 GraphQL API

2024-05-21

适用于：所有 API 管理层级

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

在本文中，你将：

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

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

先决条件

现有的 API 管理实例。如果还没有实例，请创建一个。
一个 GraphQL API。
Azure 命令行接口 (CLI)
- 在 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
- 如果选择在本地使用 Azure PowerShell：
  - 安装最新版本的 Az PowerShell 模块。
  - 使用 Connect-AzAccount cmdlet 连接到 Azure 帐户。
- 如果选择使用 Azure Cloud Shell：
  - 有关详细信息，请参阅 Azure Cloud Shell 概述。

添加 GraphQL API

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

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

用于创建 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.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 后，在“设计”选项卡上浏览或修改架构。Screenshot of exploring the GraphQL schema in the portal.

以下示例使用 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 更新设置。