匯入 GraphQL API

2025-05-20

適用於：所有 APIM 層

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

在本文中，您將：

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

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

必要條件

現有的 API 管理執行個體。若您還沒有執行個體，請加以建立。
GraphQL API。
Azure 命令列介面 (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]，從現有的 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 尾碼，以在此 APIM 執行個體中識別此特定 API。該尾碼在此 APIM 執行個體中必須是唯一的。
基底 URL	顯示 API 基底 URL 的無法編輯欄位
Tags (標籤)	將 GraphQL API 與新的或現有的標籤產生關聯。
產品	將 GraphQL API 與產品建立關聯，以將其發佈。
要為此 API 設定版本嗎?	選取即可將版本設定配置套用至 GraphQL API。

選取建立。
建立 API 之後，請在 [設計] 索引標籤中瀏覽或修改結構描述。

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

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

# 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 來更新設定。

測試 GraphQL API

瀏覽至 APIM 執行個體。
從側邊導覽功能表的 [API] 區段下，選取 [API]。
在 [所有 API] 底下，選取 GraphQL API。
選取 [測試] 索引標籤以存取測試主控台。
在 [標題] 底下：
1. 從 [名稱] 下拉式功能表中選取標題。
2. 在 [值] 欄位中輸入值。
3. 選取 [+ 新增標題] 以新增更多標題。
4. 使用垃圾桶圖示刪除標題。
如果您已將產品新增至 GraphQL API，請在 [套用產品範圍] 底下套用產品範圍。
在 [查詢編輯器] 下：
1. 從側邊功能表中的清單選取至少一個欄位或子欄位。您選取的欄位和子欄位會出現在查詢編輯器中。
2. 開始在查詢編輯器中輸入以撰寫查詢。
在 [查詢變數] 底下，新增變數以重複使用相同的查詢或變動，並傳遞不同的值。
請選取傳送。
檢視回應。
重複上述步驟以測試不同的承載。
測試完成時，結束測試主控台。