本頁面由 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> 政策。

預設值	請參閱下方的「Default Policy」分頁
是否必要	必填
類型	類型
父項元素	不適用
子元素	`<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>`	選用	酬載的大小上限 (以千位元為單位)。
`<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。

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

預設值	`10`
是否必要？	選用
類型	整數
上層元素	`<GraphQL>`
子元素	無

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

語法

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

`<MaxPayloadSizeInBytes>`

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

注意：如果政策中未提供 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：表示根層級查詢定義索引的索引 (每個要求的預設值為 4)
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> 元素

語法