GraphQL ポリシー

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

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

詳しくは、次のリソースをご覧ください。

このポリシーは標準ポリシーであり、任意の環境タイプにデプロイできます。すべてのユーザーがポリシーや環境のタイプを知る必要はありません。ポリシータイプと各環境タイプでの利用可否については、ポリシータイプをご覧ください。

このポリシーを使用する例については、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 に設定します。関連情報:
enabled true 省略可 ポリシーを適用するには、true に設定します。ポリシーを無効にするには、false に設定します。ポリシーがフローに接続されている場合でも適用されません。
async   false 非推奨 この属性は非推奨となりました。

次の表は、<GraphQL> の子要素の概要をまとめたものです。

子要素 必須かどうか 説明
一般的な操作
<Action> 省略可 リクエストに対して実行するアクション parseverify、またはその両方である parse_verify のいずれかを指定します。
<MaxCount> 省略可 GraphQL リクエストが生成できるクエリまたはフラグメントの最大数。デフォルト値は 10 です。
<MaxDepth> 省略可 クエリのツリーの最大深度。デフォルト値は 4 です。
<MaxPayloadSizeInBytes> 省略可 ペイロードの最大サイズ(キロバイト)。
<OperationType> 必須 解析できるリクエストの種類(querymutationquery_mutation のいずれか)を指定します。
<ResourceURL> 省略可 説明。GraphQL スキーマ ファイルの場所です。
<Source> 必須 request

後続のセクションでは、これらの子要素についてそれぞれ説明します。

子要素のリファレンス

このセクションでは、<GraphQL> の子要素について説明します。

<Action>

Action は、次のいずれかの GraphQL アクションを表します。

  • parse: Apigee は GraphQL ペイロードを解析してメッセージ フロー変数に変換します。Actionparse に設定されている場合に設定される変数の説明については、メッセージ フロー変数の表現の例をご覧ください。これにより、バックエンドの貴重な 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 です。

デフォルト値 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 構文のすべての側面をカバーします。メッセージ フロー変数をご覧ください。

メッセージ フロー変数は次の規則に従います。

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 の使用