GraphQL ポリシー

このページは Apigee と Apigee ハイブリッドに適用されます。

Apigee Edge ドキュメントを表示する

GraphQL ポリシーアイコン

What

GraphQL ポリシーでは、GraphQL ペイロードを解析してメッセージフロー変数に格納できます。また、GraphQL リクエストがスキーマに準拠しているかどうか検証できます。

GraphQL ポリシーを使用して、次のことを行えます。

指定したスキーマに準拠するリクエストのみを API で処理する。
許可するフラグメントの数に上限を設定して、ペイロードを制限する。
GraphQL を API プロダクトに関連付ける。
REST と同様に、Oauth2、VerifyAPIKey、割り当てポリシーの機能を活用する。

GraphQL は、次のタイプのペイロードをサポートしています。

Content-Type : application/graphql を含む GraphQL ペイロードの POST
Content-Type: applcation/json を含む GraphQL ペイロードの POST
ペイロードがクエリパラメータの場合は GraphQL ペイロードの GET

注: 次の形式の 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</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 文字を超えることはできません。管理 UI プロキシエディタで `<DisplayName>` 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。
`continueOnError`	false	省略可	ポリシーが失敗したときにエラーを返す場合は、`false` に設定します。これは、ほとんどのポリシーで想定される動作です。ポリシーが失敗した後もフローの実行を続行する場合は、`true` に設定します。関連情報: 障害ルールはエラー状態の場合にのみトリガーされる（continueOnError について）現在のフローにおける障害処理
`enabled`	true	省略可	ポリシーを適用するには、`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 ペイロードがプロキシにアップロードされたスキーマに準拠していることを検証します。
parse_verify: Apigee が GraphQL リクエストを解析して検証します。

デフォルト値	`parse`
必須かどうか	Optional
型	文字列
親要素	`<GraphQL>`
子要素	none

<Action> 要素の構文は次のとおりです。

構文

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

`<MaxCount>`

ペイロードに含めることができるフラグメントの最大数。これを利用して、お客様の GraphQL バックエンドサーバーが高度に複雑なクエリを実行しないようにし、クライアントがロジックをより小さなペイロードに分割するように強制できます。

デフォルト値	`10`
必須かどうか	Optional
型	文字列
親要素	`<GraphQL>`
子要素	none

<MaxCount> 要素の構文は次のとおりです。

構文

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

`<MaxDepth>`

ツリーとして表されたときの、クエリの最大深度。MaxDepth を使用すると、ペイロードで深いクエリをブロックできるため、値を保持するために非常に大きなフロー変数を作成する必要がなくなります。ただし、ペイロードは MaxDepth の値に関係なくそのまま送信されます。デフォルト値は 10 です。

注: MaxDepth は、Action 要素が parse または parse-verify に設定されている場合に機能します。コストのかかる verify アクションを使用するのではなく、これらのアクションで MaxDepth を使用して深度を確認することをおすすめします。

デフォルト値	`10`
必須かどうか	Optional
種類	整数
親要素	`<GraphQL>`
子要素	none

<MaxDepth> 要素の構文は次のとおりです。

構文

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

`<MaxPayloadSizeInBytes>`

ペイロードの最大サイズ（キロバイト）。これを使用してペイロードサイズを制限し、パフォーマンスの問題を回避できます。

注: ポリシーで MaxPayloadSizeInByte が指定されていない場合、サイズの制限は適用されません。

デフォルト値	`request`
必須かどうか	Optional
型	文字列
親要素	`<GraphQL>`
子要素	none

<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`
必須かどうか	Optional
型	文字列
親要素	`<GraphQL>`
子要素	none

<OperationType> 要素の構文は次のとおりです。

構文

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

`<ResourceURL>`

GraphQL ポリシーがリクエストを検証する GraphQL スキーマファイルへのパス。Apigee に GraphQL スキーマをアップロードする例については、その例をご覧ください。

アップロードしたスキーマファイルの名前が my-schema.graphql の場合、<ResourceURL> 要素は次のようになります。

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

デフォルト値	該当なし
必須かどうか	省略可
型	文字列
親要素	`<GraphQL>`
子要素	none

ResourceURL 要素の構文は次のとおりです。

構文

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

`<Source>`

このポリシーが実行されるソース。

デフォルト値	`request`
必須かどうか	Optional
型	文字列
親要素	`<GraphQL>`
子要素	none

<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: 特定のフィールドとその値に相関するリーフレベルの定義

オペレーション定義のメッセージフロー変数での表現

メッセージ内のフィールド	種類	説明
name	文字列	graphQL オペレーションの名前。この名前は、メッセージフローの名前とは無関係です。
定義	文字列 - オペレーション	クエリリクエストのメインメッセージ本文が含まれていることを示します。
operationType	クエリまたはミューテーション	実行されるオペレーションのタイプです。
variableDefinition	整数	これらは、型付け言語の関数の引数定義と同様に機能します。接頭辞 $ の後にタイプが続く、すべての変数がリスティングされます。
directives	整数	@include と @skip は、現在提供されている 2 つのディレクティブで、動的に渡される値に基づいてフィルタできます。
selectionSet	整数	オブジェクトに関連付けられているすべての属性を 1 レベルで論理的にグループ化したもの。

フラグメント定義のメッセージフローでの表現

メッセージフロー変数の名前	種類	説明
name	文字列	フラグメントの名前。
定義	文字列 - フラグメント	リクエストの本文がメインリクエストのフラグメントであることを示します。
typeCondition	文字列	フラグメントが呼び出される条件。
variableDefinition	整数	フラグメントに引数として渡される変数定義。

メッセージフロー変数の表現例

次の例は、サンプルリクエストペイロードのメッセージフロー変数表現を示しています。

クエリの例 1

次の例は、入力として渡された引数を含むクエリであり、従業員の 3 つの属性がクエリされます。

{
 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 ポリシー

What

<GraphQL> 要素

構文

デフォルト ポリシー

子要素のリファレンス

<Action>

構文

<MaxCount>

構文

<MaxDepth>

構文

<MaxPayloadSizeInBytes>

構文

<OperationType>

構文

<ResourceURL>

構文

<Source>

構文