Azure APIM 中的 GraphQL API 概觀

發行項
05/05/2024

適用於：所有 API 管理層

您可以使用 APIM 來管理 GraphQL API，這是以 GraphQL 查詢語言為基礎的 API。 GraphQL 提供 API 中資料的完整且可理解的描述，讓用戶端能夠有效率地擷取所需的資料。深入了解 GraphQL (英文)

APIM 可協助您匯入、管理、保護、測試、發佈及監視 GraphQL API。您可以選擇兩個 API 模型的其中之一：

傳遞 GraphQL	合成 GraphQL
▪️ 將 API 傳遞至現有的 GraphQL 服務端點 ▪️ 支援 GraphQL 查詢、變動和訂用帳戶	▪️ 以自訂 GraphQL 結構描述為基礎的 API ▪️ 支援 GraphQL 查詢、變動和訂用帳戶 ▪️ 例如，將自訂解析器設定為 HTTP 資料來源 ▪️ 開發 GraphQL 結構描述和 GraphQL 型用戶端，同時從舊版 API 取用資料

可用性

所有 APIM 服務層級都支援 GraphQL API
APIM 工作區目前不支援綜合 GraphQL API
綜合 GraphQL API 中的 GraphQL 訂用帳戶支援目前處於預覽狀態，無法在取用層中使用

什麼是 GraphQL？

GraphQL 是 API 的開放原始碼業界標準查詢語言。與專為資源上的動作所設計的 REST 樣式 API 不同，GraphQL API 支援更廣泛的使用案例，並著重在資料類型、結構描述和查詢。

GraphQL 規格會明確解決依賴 REST API 的用戶端 Web 應用程式所遇到的常見問題：

可能需要大量的要求來滿足單一頁面的資料需求
REST API 傳回的資料通常多於呈現頁面所需的資料
用戶端應用程式需要輪詢才能取得新資訊

使用 GraphQL API，用戶端應用程式可以指定在查詢文件中呈現頁面所需的資料，該查詢文件會以單一要求的形式傳送給 GraphQL 服務。用戶端應用程式還可以即時訂閱從 GraphQL 服務推送的資料更新。

架構和類型

在 APIM 中，從 GraphQL 結構描述中新增從後端 GraphQL API 端點擷取或由您上傳的 GraphQL API。 GraphQL 結構描述說明：

用戶端可從 GraphQL API 要求的物件類型類型和欄位
允許對資料執行的作業類型，例如查詢
其他類型，例如等聯集和介面，可提供額外的彈性並控制數據

例如，使用者資料的基本 GraphQL 結構描述和所有使用者的查詢看起來可能如下所示：

type Query {
    users: [User]
}

type User {
    id: String!
    name: String!
}

作業類型

APIM 支援 GraphQL 結構描述中的下列作業類型。如需這些作業類型的詳細資訊，請參閱 GraphQL 規格 (英文)。

查詢：擷取資料，類似於 REST 中的 GET 作業
變動：修改伺服器端資料，類似於 REST 中的 PUT 或 PATCH 作業
訂閱：允許即時通知已訂閱用戶端有關 GraphQL 服務的資料變更

例如，透過 GraphQL 變動修改資料時，已訂閱用戶端可能會自動收到變更的相關通知。

重要

APIM 支援使用 graphql-ws WebSocket 通訊協定實作的訂閱。 WebSocket 不支援查詢與變動。

其他類型

API 管理支援 GraphQL 架構中的等位和介面類型。

解析器

「解析器」負責將 GraphQL 結構描述對應到後端資料，為物件類型中的每個欄位產生資料。資料來源可以是 API、資料庫或其他服務。例如，解析器函式將負責傳回上述範例中 users 查詢的資料。

在 APIM 中，您可以建立解析器，將物件類型中的欄位對應到後端資料來源。您可以在綜合 GraphQL API 結構描述中設定欄位的解析器，但也可以將其設定為覆寫傳遞 GraphQL API 所使用的預設欄位解析器。

APIM 目前支援以 HTTP API、Cosmos DB 和 Azure SQL 資料來源為基礎的解析器，以傳回 GraphQL 結構描述中欄位的資料。每個解析器都使用量身打造的原則進行設定，以連線到資料來源並擷取資料：

資料來源	解析器原則
HTTP 型資料來源 (REST 或 SOAP API)	http-data-source
Cosmos DB 資料庫	cosmosdb-data-source
Azure SQL Database	sql-data-source

例如，上述 users 查詢的 HTTP API 型解析器可能會對應到後端 REST API 中的 GET 作業：

<http-data-source>
	<http-request>
		<set-method>GET</set-method>
		<set-url>https://myapi.contoso.com/api/users</set-url>
	</http-request>
</http-data-source>

如需設定解析器的詳細資訊，請參閱設定 GraphQL 解析器。

管理 GraphQL API

藉由套用現有的存取控制原則和 GraphQL 驗證原則保護 GraphQL API 的安全，來防範 GraphQL 特定攻擊。
探索 GraphQL 結構描述，並針對 Azure 和開發人員入口網站中的 GraphQL API 執行測試查詢。

共用方式為