本頁面由 Cloud Translation API 翻譯而成。

GraphQL 政策

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

查看 Apigee Edge 說明文件。

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> 政策。

預設值	請參閱下方的「預設政策」分頁
是否必要	必填
類型	類型
父項元素	不適用
子項元素	`<Action>` `<MaxDepth>` `<MaxCount>` `<MaxPayloadSizeInBytes>` `<OperationType>` `<Source>` `<ResourceURL>`

語法

<GraphQL> 元素使用下列語法：

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Source>request</Source>
  <OperationType>[query|mutuation|all]</OperationType>
  <MaxDepth>MAX_DEPTH</MaxDepth>
  <MaxCount>MAX_NUMBER_OF_QUERIES</MaxCount>
  // [Start maxpayloadsize]
  <MaxPayloadSizeInBytes>MAX_PAYLOAD_SIZE_IN_BYTES&lt/MaxPayloadSizeInBytes>
  <Action>parse</Action>
  <ResourceURL>PATH/TO/SCHEMA.xsd</ResourceURL>
</GraphQL>

預設政策

下列範例顯示在 Apigee UI 中將 <GraphQL> 政策新增至流程時的預設設定：

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<GraphQL name="GraphQLParser">
  <Source>request</Source>
  <OperationType>query</OperationType>
  <MaxDepth>10</MaxDepth>
  <MaxCount>10</MaxCount>
  <MaxPayloadSizeInBytes></MaxPayloadSizeInBytes>
  <Action>parse</Action>
  <ResourceURL></ResourceURL>
</GraphQL>

這個元素包含下列所有政策都適用的屬性：

屬性	預設	是否必要？	說明
`name`	不適用	必要	政策的內部名稱。`name` 屬性的值可以包含英文字母、數字、空格、連字號、底線和句號。這個值不得超過 255 個半形字元。您可以選擇使用 `<DisplayName>` 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。
`continueOnError`	false	選用	將其設為 `false`，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 `true`，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：錯誤規則僅會在錯誤狀態下觸發 (關於 continueOnError) 處理目前流程中的錯誤
`enabled`	是	選用	設為 `true` 即可強制執行政策。設為 `false` 即可關閉政策。即使政策仍附加至流程，系統也不會強制執行這項政策。
`async`	false	已淘汰	此屬性已淘汰。

下表提供 <GraphQL> 子元素的高階說明：

子元素	是否必要	說明
常見作業
`<Action>`	選用	指定對要求採取的動作：`parse`、`verify` 或 `parse_verify` (兩者)。
`<MaxCount>`	選用	GraphQL 要求可產生的查詢或片段數量上限。預設值為 10。
`<MaxDepth>`	選用	查詢的樹狀結構深度上限。預設值為 4。
`<MaxPayloadSizeInBytes>`	選用	酬載大小上限 (以 KB 為單位)。
`<OperationType>`	必填	指定可剖析的要求類型：`query`、`mutation` 或 `query_mutation` (任一)。
`<ResourceURL>`	選用	說明。GraphQL 結構定義檔案的位置。
`<Source>`	必填	`request`

後續章節將說明這些子元素。

子元素參照

本節說明 <GraphQL> 的子元素。

`<Action>`

Action 代表下列其中一個 GraphQL 動作：

parse：Apigee 會將 GraphQL 酬載剖析為訊息流程變數。如要瞭解 Action 設為 parse 時設定的變數，請參閱訊息流程變數表示法範例。這可節省後端寶貴的 CPU 時間。請注意，verify 也會剖析酬載。
verify：Apigee 會驗證 GraphQL 酬載是否符合上傳至 Proxy 的結構定義。
parse_verify：Apigee 會剖析及驗證 GraphQL 要求。

預設值	`parse`
必填與否	選用
類型	字串
父項元素	`<GraphQL>`
子元素	無

<Action> 元素使用下列語法：

語法

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Action>parse</Action>
</GraphQL>

`<MaxCount>`

酬載中可包含的片段數量上限。您可以藉此防止客戶的 GraphQL 後端伺服器執行高度複雜的查詢，強制用戶端將邏輯分割為較小的酬載。

預設值	`10`
必填與否	選用
類型	字串
父項元素	`<GraphQL>`
子元素	無

<MaxCount> 元素使用下列語法：

語法

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <MaxCount>MAX_NUMBER_OF_QUERIES</MaxCount>
</GraphQL>

`<MaxDepth>`

以樹狀結構表示時，查詢的最大深度。 MaxDepth 可讓您封鎖酬載中的深層查詢，這樣 Apigee 就不必建立非常大的流程變數來保留值。不過，無論 MaxDepth 的值為何，系統都會照常傳送酬載。預設值為 10。

注意： 當 Action 元素設為 parse 或 parse-verify 時，MaxDepth 即可運作。建議您搭配使用 MaxDepth 和這些動作來檢查深度，而不是使用成本較高的 verify 動作。

預設值	`10`
必填與否	選用
類型	整數
父項元素	`<GraphQL>`
子元素	無

<MaxDepth> 元素使用下列語法：

語法

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <MaxDepth>MAX_DEPTH</MaxDepth>
</GraphQL>

`<MaxPayloadSizeInBytes>`

酬載大小上限 (以 KB 為單位)。您可以使用這項功能限制酬載大小，避免發生效能問題。

注意：如果政策中未提供 MaxPayloadSizeInByte，系統就不會強制執行大小限制。

預設值	`request`
必填與否	選用
類型	字串
父項元素	`<GraphQL>`
子元素	無

<MaxPayloadSizeInBytes> 元素使用下列語法：

語法

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <MaxPayloadSizeInBytes>MAX_PAYLOAD_SIZE_IN_BYTES</MaxPayloadSizeInBytes>
</GraphQL>

`<OperationType>`

指出可剖析的要求類型：

query：GraphQL 查詢。
mutation：GraphQL 異動
query_mutation：GraphQL 查詢或異動。

如果範圍是 query，且傳遞了變動要求，要求就會失敗並傳回 4xx 錯誤。

預設值	`query`
必填與否	選用
類型	字串
父項元素	`<GraphQL>`
子元素	無

<OperationType> 元素使用下列語法：

語法

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <OperationType>[query|mutation|query_mutation]</OperationType>
</GraphQL>

`<ResourceURL>`

GraphQL 政策用來驗證要求的 GraphQL 結構定義檔路徑。如需將 GraphQL 結構定義上傳至 Apigee 的範例，請參閱「範例」。

如果上傳的結構定義檔案名稱為 my-schema.graphql，則 <ResourceURL> 元素會是

<ResourceURL>graphql://my-schema.graphql</ResourceURL>

預設值	不適用
必填與否	選用
類型	字串
父項元素	`<GraphQL>`
子元素	無

ResourceURL 元素使用下列語法：

語法

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <ResourceURL>PATH/TO/SCHEMA.graphql</ResourceURL>
</GraphQL>

`<Source>`

執行這項政策的來源。

預設值	`request`
必填與否	選用
類型	字串
父項元素	`<GraphQL>`
子元素	無

<Source> 元素使用下列語法：

語法

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Source>request</Source>
</GraphQL>

GraphQL 剖析器

GraphQL 剖析器支援 GraphQL 查詢的所有功能，並以訊息流程虛線標記法表示為圖形。查詢可包含作業定義，以及 (選擇性) 識別為片段定義的片段。請參閱 GraphQL 規格。

GraphQL 要求的剖析

下圖顯示 GraphQL 要求的結構。

作業定義在訊息流程中的表示方式

剖析器實作涵蓋 GraphQL 語法的所有層面，包括支援查詢和變異。請參閱「訊息流程變數」。

訊息流程變數遵循以下慣例：

graphql.(root-index).(root definition)[(sub-indices).(child-definitions)…]

其中：

graphql：靜態前置字元，表示這是與 GraphQL 相關的訊息流程變數
root-Index：以 0 為準的索引，指出根層級查詢定義索引 (每個要求最多 4 個，預設為 1 個)
root-definition：根層級的 GraphQL 要求訊息主體、引數及其值
sub-indices：子項索引
child-definitions：與特定欄位及其值相關的葉層級定義

作業定義的訊息流程變數表示法

訊息中的欄位	類型	說明
名稱	字串	GraphQL 運算的名稱。請注意，這個名稱與訊息流程中的名稱無關。
定義	字串 - 作業	指出這包含查詢要求的主要訊息主體
operationType	查詢或異動	執行的作業類型。
variableDefinition	整數	這些定義的運作方式，與型別語言中函式的引數定義相同。其中列出所有變數，並以 $ 為前置字元，後面接著變數類型。
指令	整數	目前提供 @include 和 @skip 這兩項指令，可根據動態傳遞的值進行篩選。
selectionSet	整數	與物件相關聯的所有屬性，在邏輯上會歸為同一層級。

訊息流程中的片段定義表示法

訊息流程變數名稱	類型	說明
名稱	字串	片段名稱。
定義	字串片段	表示要求主體是主要要求的片段。
typeCondition	字串	片段的叫用條件。
variableDefinition	整數	以引數形式傳遞至片段的變數定義。

訊息流程變數表示法的範例

下列範例顯示範例要求酬載的訊息流程變數表示法。

查詢範例 1

這個範例顯示以引數做為輸入內容的查詢，可查詢員工的三項屬性。

{
 employee(id: 123) {
   id
   firstName
   lastName
 }
}

下表顯示對應的訊息流程變數表示法。

訊息流程變數	值
`graphql.operation.operationType`	`QUERY`
`graphql.fragment.count`	`1`
`graphql.operation.selectionSet.count`	`1`
`graphql.operation.variableDefinitions.count`	`0`
`graphql.operation.selectionSet.1.name`	`employee`
`graphql.operation.selectionSet.1.argument.count`	`1`
`graphql.operation.selectionSet.1.argument.1.name`	`id`
`graphql.operation.selectionSet.1.argument.1.value`	`IntValue{value=123}`
`graphql.operation.selectionSet.1.directive.count`	`0`
`graphql.operation.selectionSet.1.selectionSet.count`	`3`
`graphql.operation.selectionSet.1.selectionSet.1.name`	`id`
`graphql.operation.selectionSet.1.selectionSet.2.name`	`firstName`
`graphql.operation.selectionSet.1.selectionSet.3.name`	`lastName`

查詢範例 2

這個範例顯示以引數做為輸入內容的查詢，用於查詢好友名稱。

query Characters($episode: Episode, $withFriends: Boolean!) {
   friends @include(if: $withFriends) {
     friendsName
    }
}

下表顯示對應的訊息流程變數表示法。

訊息流程變數	值
`graphql.operation.operationType`	`QUERY`
`graphql.operation.selectionSet.count`	`1`
`graphql.operation.name`	`Characters`
`graphql.fragment.count`	`0`
`graphql.operation.selectionSet.1.name`	`friends`
`graphql.operation.variableDefinitions.count`	`2`
`graphql.operation.variableDefinitions.1.name`	`episode`
`graphql.operation.variableDefinitions.1.type`	`TypeName{name='Episode'}`
`graphql.operation.variableDefinitions.2.name`	`withFriends`
`graphql.operation.variableDefinitions.2.type`	`NonNullType{type=TypeName{name='Boolean'}}`
`graphql.operation.selectionSet.1.argument.count`	`0`
`graphql.operation.selectionSet.1.selectionSet.count`	`1`
`graphql.operation.selectionSet.1.selectionSet.1.name`	`friendsName`
`graphql.operation.selectionSet.1.directive.count`	`1`
`graphql.operation.selectionSet.1.directive.1.argument.1.name`	`if`
`graphql.operation.selectionSet.1.directive.1.argument.1.value`	`VariableReference{name='withFriends'}`

查詢範例 3

這個範例含有別名變數定義。

query getUsers {
  admins: users(role: ADMIN) {
    lastName
  }
  accountants: users(role: ACCOUNTANT) {
    firstName
  }
}

下表顯示對應的訊息流程變數表示法。

訊息流程變數	值
`graphql.operation.operationType`	`QUERY`
`graphql.operation.selectionSet.count`	`2`
`graphql.operation.selectionSet.1.name`	`users`
`graphql.operation.selectionSet.1.alias`	`admins`
`graphql.operation.variableDefinitions.count`	`0`
`graphql.operation.selectionSet.1.argument.count`	`1`
`graphql.operation.selectionSet.1.argument.1.name`	`role`
`graphql.operation.selectionSet.1.argument.1.value`	`EnumValue{name='ADMIN'}`
`graphql.operation.selectionSet.1.argument.2.name`	`null`
`graphql.operation.selectionSet.1.argument.2.value`	`null`
`graphql.operation.selectionSet.1.selectionSet.count`	`1`
`graphql.operation.selectionSet.1.selectionSet.count`	`1`
`graphql.operation.selectionSet.1.selectionSet.1.name`	`lastName`
`graphql.operation.selectionSet.1.selectionSet.1.alias`	`null`
`graphql.operation.selectionSet.1.selectionSet.2.name`	`null`
`graphql.operation.selectionSet.1.selectionSet.2.alias`	`null`
`graphql.operation.selectionSet.1.directive.count`	`0`
`graphql.operation.selectionSet.1.directive.1.argument.1.name`	`null`
`graphql.operation.selectionSet.1.directive.1.argument.1.value`	`null`
`graphql.operation.selectionSet.2.name`	`users`
`graphql.operation.selectionSet.2.alias`	`accountants`
`graphql.operation.selectionSet.2.argument.count`	`1`
`graphql.operation.selectionSet.2.argument.1.name`	`role`
`graphql.operation.selectionSet.2.argument.1.value`	`EnumValue{name='ACCOUNTANT'}`
`graphql.operation.selectionSet.2.selectionSet.count`	`1`
`graphql.operation.selectionSet.2.selectionSet.1.name`	`firstName`
`graphql.operation.selectionSet.2.directive.count`	`0`
`graphql.operation.selectionSet.2.selectionSet.1.alias`	`null`
`graphql.operation.selectionSet.2.selectionSet.2.name`	`null`
`graphql.operation.selectionSet.2.selectionSet.2.alias`	`null`
`graphql.operation.selectionSet.2.directive.count`	`0`

GraphQL 政策

結果

<GraphQL> 元素

語法

預設政策

子元素參照

<Action>

語法

<MaxCount>

語法

<MaxDepth>

語法

<MaxPayloadSizeInBytes>

語法

<OperationType>

語法

<ResourceURL>

語法

<Source>

語法

GraphQL 剖析器

GraphQL 要求的剖析

作業定義在訊息流程中的表示方式

作業定義的訊息流程變數表示法

訊息流程中的片段定義表示法

訊息流程變數表示法的範例

查詢範例 1

查詢範例 2

查詢範例 3

相關主題

`<GraphQL>` 元素

`<Action>`

`<MaxCount>`

`<MaxDepth>`

`<MaxPayloadSizeInBytes>`

`<OperationType>`

`<ResourceURL>`

`<Source>`