匯入 GraphQL API

適用於：所有 APIM 層

在 APIM 中，您可以使用兩種模型新增 GraphQL API：傳遞至現有的 GraphQL 端點，或匯入 GraphQL 結構描述，並使用自訂欄位解析器建立綜合 GraphQL API。如需詳細資訊，請參閱 GraphQL 概觀。

在本文中，您將：

將傳遞 GraphQL API 新增至 APIM 執行個體。
測試 GraphQL API。

如果您想要匯入 GraphQL 結構描述並設定使用 REST 或 SOAP API 端點的欄位解析器，請參閱匯入 GraphQL 結構描述並設定欄位解析器。

先決條件

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 管理實例。
在左窗格中，選取 APIs>APIs。
選取 [ 新增 API]。
在 [定義新 API] 底下，選取 [GraphQL ] 磚。

在產生的對話方塊中，選取 [完整]，然後在必要欄位中輸入值，如下表所述。

價值觀	描述
顯示名稱	將會據以顯示 GraphQL API 的名稱。
名稱	GraphQL API 的原始名稱。當您輸入顯示名稱時，會自動填入。
GraphQL 類型	選取 [傳遞 GraphQL]，從現有的 GraphQL API 端點匯入。
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 的不可編輯欄位。
Tags (標籤)	選擇性地將您的 GraphQL API 與新的或現有的標籤建立關聯。
產品	將 GraphQL API 與產品建立關聯，以將其發佈。
要為此 API 設定版本嗎?	選取核取方塊，將版本控制配置套用至您的 GraphQL API。

選取 [建立]。
建立 API 之後，請檢閱或修改 [結構描述] 索引標籤上的結構描述。

下列範例會使用 az apim api import 命令，將 GraphQL 傳遞 API 從指定的 URL 匯入至名為 apim-hello-world 的 APIM 執行個體。

# 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 的 APIM 執行個體。

# 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. 開始在查詢編輯器中輸入以撰寫查詢。
在 [查詢變數] 底下，新增變數以重複使用相同的查詢或變動，並傳遞不同的值。
選取 [傳送]。
檢視回應。
重複上述步驟以測試不同的承載。
完成測試後，請退出測試控制台。