使用 GraphQL

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

GraphQL 政策可以將 GraphQL 要求酬載剖析為訊息流程變數，根據 GraphQL 結構定義驗證要求，或同時執行這兩項操作。

GraphQL 政策可將 GraphQL 酬載解析為訊息流程變數，並驗證 GraphQL 要求是否符合結構定義，或同時執行這兩項操作。

您可以使用 GraphQL 政策執行下列操作：

• 請確保 API 只處理符合您提供的結構定義要求。
• 設定允許的片段數量上限，對酬載限制加以限制。
• 將 GraphQL 與 API 產品建立關聯。
• 利用 Oauth2、VerifyAPIKey 和配額政策功能，就像在 REST 中一樣。

GraphQL 支援下列酬載類型：

• 使用 Content-Type : application/graphql 將 GraphQL 酬載 POST 到
• 使用 Content-Type: applcation/json 將 GraphQL 酬載 POST 到
• 取得 GraphQL 酬載 (酬載為查詢參數)

注意：如果是 application/json 酬載，格式如下：

{
"query": "...",
"operationName": "...",
"variables": { "myVariable": "someValue", ... }
}

Apigee 目前會忽略選用的 operationName 和 variables 欄位。

如需 GraphQL 政策選項的快速摘要，請參閱下方的「GraphQL 選項」。

如要進一步瞭解 GraphQL，請參閱 GraphQL.org。

範例

以下範例說明如何將 GraphQL 結構定義上傳至 Apigee，並使用該結構定義驗證含有 GraphQL 內容的要求。

注意： 根據結構定義驗證酬載通常是耗費資源的作業，建議謹慎選擇是否執行結構定義驗證。尤其當酬載和結構定義複雜時，結構定義驗證作業可能會耗用大量 CPU 資源，導致延遲時間大幅增加。

注意：每項政策只能提供一個結構定義。如需納入多個結構定義，請在 Proxy 中加入多個 GraphQL 政策。

注意：僅適用於傳統版 Proxy 編輯器：

• 新增 GraphQL 政策時，只能上傳 GraphQL 結構定義檔案。您無法在 Proxy 編輯器的「資源」窗格中上傳。
• 上傳 GraphQL 結構定義檔案後，您就無法在 Proxy 編輯器中查看或編輯該檔案。

這些限制不適用於新的 Proxy 編輯器。

建立結構定義檔案

如要執行範例，請先建立含有下列內容的 GraphQL 結構定義檔案：

type Query {
  allPersons(last: Int): [Person!]!
}

type Mutation {
  createPerson(name: String!, age: Int!): Person!
}

type Subscription {
  newPerson: Person!
}

type Person {
  name: String!
  sex: String!
  age: Int!
  posts: [Post!]!
}

type Post {
  title: String!
  author: Person!
}

以您要使用的名稱儲存檔案，並加上 .graphql 副檔名。

在 Apigee UI 中新增 GraphQL 政策

注意：Apigee 即將推出新版 Proxy 編輯器，方便您管理 Proxy。

下方前兩個分頁中的操作說明，分別介紹如何使用新版和舊版 Proxy 編輯器。

全新 Proxy 編輯器

首先，請按照下列步驟建立 GraphQL 政策：

1. 登入 Apigee 使用者介面。
2. 在導覽列中，依序選取「開發」>「API Proxy」。
3. 在 Proxy 清單中，選取要使用 GraphQL 政策的 API Proxy。
4. 按一下「DEVELOP」分頁標籤。
5. 在左側窗格中，按一下「政策」資料夾旁的「+」按鈕。

6. 在「建立政策」對話方塊中，點按「選取政策類型」欄位，然後向下捲動至「中介服務」，並選取「GraphQL」。

   

   輸入「顯示名稱」和「名稱」。

   接著，請按照下列方式選取 GraphQL 結構定義檔案：

   1. 按一下「結構定義檔案」欄位。系統會顯示下列選項：
      • 無結構定義。如果您選取這個選項，Apigee 就不會使用結構定義驗證要求。
      • 匯入 GraphQL 結構定義 (.graphql)

   2. 選取「Import GraphQL schema (.graphql)」(匯入 GraphQL 結構定義 (.graphql))。這會顯示下列內容：

      

   3. 按一下「選擇檔案」，然後選取先前建立的結構定義檔案 (副檔名必須為 .graphql)。 檔案會顯示在「結構定義名稱」欄位中。

      
7. 按一下「建立」，建立政策。

您已建立 GraphQL 政策，現在可以將其附加至 PreFlow 中的步驟：

1. 在左側窗格中，依序選取「Proxy Endpoints」>「default」>「PreFlow」：

   

2. 在 Visual Editor 右下方的「Response」(回覆) 窗格中，按一下「PreFlow」(前置流程) 旁的「+」按鈕：

   

3. 在「新增政策步驟」對話方塊中，選取 GQL- 政策。
   注意：這個範例使用預設名稱 GQL 做為 GraphQL 政策。如要變更政策名稱，請在政策的 XML 中，於 DisplayName 元素內，在 GQL- 後方加上描述性詞組。請參閱「 變更政策名稱」一文。
4. 按一下「新增」附加政策。
5. 按一下「儲存」，即可儲存變更後的目前修訂版本。
6. 如要部署變更，請按一下「總覽」分頁，然後選取「部署」。

如要瞭解可為 GraphQL 政策設定的選項，請參閱下方的 GraphQL 選項。

傳統 Proxy 編輯器

1. 登入 Apigee 使用者介面。
2. 在導覽列中，依序選取「開發」>「API Proxy」。
3. 在 Proxy 清單中，選取要使用 GraphQL 政策的 API Proxy。
4. 按一下「DEVELOP」分頁標籤。

5. 在「Flow: PreFlow」窗格中，按一下「+ Step」按鈕。

   

6. 在「新增步驟」窗格中，向下捲動至「中介服務」部分底部，然後選取「GraphQL」。

   

   「新增步驟」窗格會顯示下列選項：

   • 顯示名稱：政策的顯示名稱。
   • 名稱：政策的內部名稱。
   • 結構定義檔案：您可以上傳包含 GraphQL 結構定義的檔案，Apigee 會使用該結構定義驗證含有 GraphQL 內容的要求。

   如要使用結構定義，請執行下列操作：

   1. 按一下「結構定義檔案」欄位。系統會顯示下列選項：
      • 無結構定義。如果您選取這個選項，Apigee 就不會使用結構定義驗證要求。
      • 匯入 GraphQL 結構定義 (.graphql)

   2. 選取「Import GraphQL schema (.graphql)」(匯入 GraphQL 結構定義 (.graphql))。這會顯示下列內容：

      

   3. 按一下「選擇檔案」，然後選取您先前建立的結構定義檔案 (副檔名必須為 .graphql)。該檔案會顯示在「結構定義名稱」欄位中。

      

7. 按一下「Add」(新增)。「Flow: PreFlow」窗格現在會如下圖所示：

   

   如要瞭解可為 GraphQL 政策設定的選項，請參閱下方的 GraphQL 選項。在本例中，請保留預設值。

8. 如要部署 Proxy，請按一下「總覽」分頁標籤，然後選取「部署」。

   

現在，您可以使用下列 curl 指令測試 GraphQL 政策：

curl --location --request POST 'https://PROXY_BASEPATH/HOST_NAME' --data-raw 'query query_name {allPersons {name}}' -k

其中 PROXY_BASEPATH 是 Proxy 的基本路徑，HOST_NAME 則是 Proxy 的名稱，包括最新修訂版本號碼。執行指令時，Apigee 會根據結構定義驗證要求，並傳回下列輸出內容。

{
  "query query_name {allPersons {name}}": "",
  "id": 101
}

以下是另一個要求範例：

curl --location --request POST 'https://PROXY_BASEPATH/HOST_NAME' --data-raw 'query ilovegql {DEADBEEF}' -k

這次要求驗證失敗，並顯示下列錯誤訊息。

{"fault":{"faultstring":"steps.graphQL.SchemaValidationFailed","detail":{"errorcode":"steps.graphQL.SchemaValidationFailed"}}}

GraphQL 選項

GraphPolicy 具有下列選項：

• OperationType：作業類型。相關選項如下：
  • query：REST GET 作業的 GraphQL 對等項目。
  • mutation：REST PUT 作業的 GraphQL 對等項目。
  • query_mutation：query 和 mutation。
• MaxDepth：以樹狀結構表示時，查詢的最大深度。 MaxDepth 可讓您封鎖酬載中的深層查詢，這樣 Apigee 就不必建立非常大的流程變數來保留值。不過，無論 MaxDepth 的值為何，系統都會照常傳送酬載。
• MaxCount：酬載中可包含的片段數量上限。 您可以藉此防止客戶的 GraphQL 後端伺服器執行高度複雜的查詢，強制用戶端將邏輯分割為較小的酬載。
• Action：下列其中一個 GraphQL 動作：
  • parseApigee 會將 GraphQL 酬載剖析為流程變數。然後在 JavaCallout 等政策中使用流程變數的內容。請注意，parse 也會驗證酬載。
  • verify：Apigee 會驗證 GraphQL 酬載是否符合上傳至 Proxy 的結構定義。您可以使用 verify，確保不會收到不符合結構定義的請求。這可節省後端寶貴的 CPU 時間。
  • parse_verify：剖析及驗證酬載。
• ResourceURL：Apigee 用於驗證 GraphQL 要求的 GraphQL 結構定義檔案路徑。

如要進一步瞭解這些選項，請參閱 GraphQL 政策參考頁面。