使用 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 酬載 (酬載為查詢參數)

如需 GraphQL 政策選項的簡要說明，請參閱下方的「GraphQL 選項」。

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

範例

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

建立結構定義檔案

如要執行範例，請先建立 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 政策

全新 Proxy 編輯器

首先，請建立 GraphQL 政策，如下所示：

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

  6. 在「Create policy」對話方塊中，點選「Select policy type」欄位，然後向下捲動至「Mediation」，並選取「GraphQL」。

    GraphQL 建立政策對話方塊。

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

    接著，請選取 GraphQL 結構定義檔案，如下所示：

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

    2. 選取「Import GraphQL schema (.graphql)」。這會顯示下列內容：

      選擇結構定義檔案。

    3. 按一下「Choose File」，然後選取先前建立的結構定義檔案 (必須具有副檔名 .graphql)。該檔案會顯示在「Schema name」欄位中。

      已選取結構定義。
  7. 按一下「建立」，建立政策。

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

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

    Proxy Explorer 中 PreFlow 選取的目標端點。

  2. 在視覺編輯器右下方的「回覆」窗格中，按一下「PreFlow」旁的「+」按鈕：

    按一下「回應」窗格中「PreFlow」旁的 + 按鈕。

  3. 在「新增政策步驟」對話方塊中，選取「GQL」GQL-政策。
  4. 按一下「新增」，附加政策。
  5. 按一下「儲存」，即可儲存目前修訂版本的變更內容。
  6. 如要部署變更，請按一下「總覽」分頁標籤，然後選取「部署」。

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

傳統 Proxy 編輯器

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

  5. 在「流程：預流程」窗格中，按一下「+ 步驟」按鈕。

    「加號」按鈕。

  6. 在「Add Step」窗格中，向下捲動至「Mediation」部分的底部，然後選取「GraphQL」。

    新增 GraphQL 政策。

    「Add Step」窗格會顯示下列選項：

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

    如要使用結構定義，請按照下列步驟操作：

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

    2. 選取「Import GraphQL schema (.graphql)」。這會顯示下列內容：

      選擇結構定義檔案。

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

      已選取結構定義。

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

    顯示 GraphQL 政策的 PreFlow 窗格。

    如要瞭解可為 GraphQL 政策設定的選項，請參閱下方的「GraphQL 選項」。在本例中，請將這些值保留不變。

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

    顯示 GraphQL 政策的 PreFlow 窗格。

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

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

其中 PROXY_BASEPATH 是 Proxy 的 basepath，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：GraphQL 等同於 REST GET 作業。
    • mutation：GraphQL 等同於 REST PUT 作業。
    • 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 政策參考頁面。