新增綜合 GraphQL API 並設定欄位解析器

發行項
04/05/2024

適用於：所有 API 管理層

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

在本文中，您將：

將 GraphQL 結構描述匯入至 API 管理執行個體
使用現有的 HTTP 端點為 GraphQL 查詢設定解析器
測試 GraphQL API

如果您要將現有的 GraphQL 端點公開為 API，請參閱匯入 GraphQL API。

必要條件

現有的 API 管理執行個體。若您還沒有執行個體，請加以建立。
副檔名為 .graphql 的有效 GraphQL 結構描述檔案。
此案例的後端 GraphQL 端點是選擇性的。

移至您的 API 管理執行個體

在 Azure 入口網站中，搜尋並選取 [API 管理服務]。
在 [API 管理服務] 頁面中，選取您的 API 管理執行個體。

新增 GraphQL 結構描述

從側邊導覽功能表的 [API] 區段下，選取 [API]。
在 [定義新的 API] 底下，選取 GraphQL 圖示。

在對話方塊中，選取 [完整]，然後完成必要的表單欄位。

用於建立 GraphQL API 的欄位螢幕快照。

欄位	描述
顯示名稱	將會據以顯示 GraphQL API 的名稱。
名稱	GraphQL API 的原始名稱。當您輸入顯示名稱時，會自動填入。
GraphQL 類型	選取 [綜合 GraphQL]，以便從 GraphQL 結構描述檔案匯入。
後援 GraphQL 端點	選擇性地輸入具有 GraphQL API 端點名稱的 URL。若未為欄位設定自訂解析器，API 管理會將 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 之後，請在 [設計] 索引標籤中瀏覽或修改結構描述。

設定解析器

設定解析器，將結構描述中的欄位對應至現有的 HTTP 端點。以下提供的是高階步驟。如需詳細資訊，請參閱設定 GraphQL 解析器。

假設您已匯入下列基本 GraphQL 結構描述，並想要為 users 查詢設定解析器。

type Query {
    users: [User]
}

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

從側邊導覽功能表的 [API] 區段下，選取 [API]> 您的 GraphQL API。
在 [結構描述] 索引標籤上，選擇您要設定解析器的物件類型，然後檢閱欄位的結構描述。
1. 選取欄位，然後在左邊界暫留指標。
2. 選取 [+ 新增解析器]
在 [建立解析器] 頁面上：
1. 視需要更新 [名稱] 屬性，選擇性地輸入 [描述]，然後確認或更新 [類型] 和 [欄位] 選取項目。
2. 在 [資料來源] 中，選取 [HTTP API]。

在 [解析器原則] 編輯器中，使用您案例中的子元素來更新 <http-data-source> 元素。例如，下列解析器會對現有的 HTTP 資料來源發出 GET 呼叫以擷取 [users] 欄位。

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

在入口網站中設定解析程序原則的螢幕快照。

選取建立。
若要解析結構描述中另一個欄位的資料，請重複上述步驟來建立解析器。

提示

當您編輯解析器原則時，請選取 [執行測試] 來檢查該資料來源的輸出，以便針對結構描述進行驗證。如果發生錯誤，回應會包含疑難排解資訊。

測試 GraphQL API

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

保護 GraphQL API 的安全

藉由套用現有的驗證和授權原則和 GraphQL 驗證原則來保護 GraphQL API，以防止 GraphQL 特定的攻擊。

下一步

轉換及保護已發佈的 API