GraphQL の使用

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

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

GraphQL ポリシーは、GraphQL リクエストのペイロードを解析してメッセージ フロー変数にすること、リクエストを GraphQL スキーマに照らして検証すること、またはその両方を行うことができます。

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 の詳細については、GraphQL.org をご覧ください。

例

次の例では、Apigee に GraphQL スキーマをアップロードし、それを使用して GraphQL コンテンツでリクエストを検証する方法を示します。

注意: スキーマに対するペイロードの検証は、一般に負荷の高いオペレーションです。スキーマ検証は慎重に実行することをおすすめします。特に、ペイロードとスキーマが複雑な場合、スキーマ検証オペレーションによって CPU 使用率が高くなることがあり、かなり大きいレイテンシが発生する可能性があります。

注: ポリシーごとに指定できるスキーマは 1 つのみです。複数のスキーマを含める必要がある場合は、プロキシに複数の GraphQL ポリシーを追加します。

注: 従来のプロキシ エディタの場合のみ:

• GraphQL ポリシーを追加する場合、GraphQL スキーマ ファイルのみをアップロードできます。プロキシ エディタの [リソース] ペインにはアップロードできません。
• 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 ポリシーを追加する

注: Apigee には、プロキシ エディタの新しいバージョンが導入されています。これにより、プロキシを簡単に管理できるようになります。

以下の最初の 2 つのタブでは、新しいプロキシ エディタの使用方法と従来のバージョンのプロキシ エディタの使用方法を説明します。

新しいプロキシ エディタ

まず、次のように GraphQL ポリシーを作成します。

1. Apigee UI にログインします。
2. ナビゲーション バーで、[Develop] > [API Proxies] を選択します。
3. プロキシのリストで、GraphQL ポリシーを使用する API プロキシを選択します。
4. [開発] タブをクリックします。
5. 左側のペインで、[ポリシー] フォルダの横にある [+] ボタンをクリックします。

6. [ポリシーの作成] ダイアログで、[Select policy type] フィールドをクリックして、[Mediation] まで下にスクロールし、[GraphQL] を選択します。

   

   表示名と名前を入力します。

   次に、以下のように GraphQL スキーマ ファイルを選択します。

   1. [Schema File] フィールドをクリックします。これにより、次の選択肢が表示されます。
      • No Schema: このオプションを選択すると、Apigee はリクエストの検証にスキーマを使用しません。
      • Import GraphQL schema (.graphql)

   2. [Import GraphQL schema（.graphql）] を選択します。次のように表示されます。

      

   3. [ファイルを選択] をクリックし、以前に作成したスキーマ ファイルを選択します（拡張子は .graphql である必要があります）。ファイルは [スキーマ名] フィールドに表示されます。

      
7. [作成] をクリックしてポリシーを作成します。

GraphQL ポリシーを作成したら、これを PreFlow のステップに接続できます。

1. 左側のペインで [Proxy Endpoints] > [デフォルト] > [PreFlow] を選択します。

   

2. ビジュアル エディタの右下にある [Response] ペインの [PreFlow] の横にある [+] ボタンをクリックします。

   

3. [Add policy step] ダイアログで、[GQL-] ポリシーを選択します。
   注: この例では、GraphQL ポリシーにデフォルト名（GQL）を使用しています。ポリシーで XML の DisplayName 要素の名前を変更する場合は、GQL の後に説明のための語句を追加します。ポリシー名を変更するをご覧ください。
4. [追加] をクリックしてポリシーを適用します。
5. [保存] をクリックし、現在のリビジョンに変更を加えて保存します。
6. 変更をデプロイするには、[概要] タブをクリックして [デプロイ] を選択します。

GraphQL ポリシーに設定できるオプションについては、後述の GraphQL のオプションをご覧ください。

従来のプロキシ エディタ

1. Apigee UI にログインします。
2. ナビゲーション バーで、[Develop] > [API Proxies] を選択します。
3. プロキシのリストで、GraphQL ポリシーを使用する API プロキシを選択します。
4. [DEVELOP] タブをクリックします。

5. [Flow: PreFlow] ペインで、[+ Step] ボタンをクリックします。

   

6. [Add Step] ペインで、[Mediation] セクションの一番下までスクロールし、[GraphQL] を選択します。

   

   [Add Step] ペインに次のオプションが表示されます。

   • Display Name: ポリシーの表示名。
   • Name: ポリシーの内部名。
   • Schema file: Apigee が GraphQL コンテンツでリクエストを検証するために使用する GraphQL スキーマを含むファイルをアップロードするオプション。

   スキーマを使用するには、次のようにします。

   1. [Schema File] フィールドをクリックします。これにより、次の選択肢が表示されます。
      • No Schema: このオプションを選択すると、Apigee はリクエストの検証にスキーマを使用しません。
      • Import GraphQL schema (.graphql)

   2. [Import GraphQL schema（.graphql）] を選択します。次のように表示されます。

      

   3. [ファイルを選択] をクリックし、以前に作成したスキーマ ファイルを選択します（拡張子は .graphql である必要があります）。ファイルは [スキーマ名] フィールドに表示されます。

      

7. [Add] をクリックします。[Flow: PreFlow] ペインが次のように表示されます。

   

   GraphQL ポリシーに設定できるオプションについては、後述の GraphQL のオプションをご覧ください。この例では、そのままにします。

8. プロキシをデプロイするには、[Overview] タブをクリックして [Deploy] を選択します。

   

これで、次の curl コマンドを使用して GraphQL ポリシーをテストできるようになりました。

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

ここで、PROXY_BASEPATH はプロキシのベースパスで、HOST_NAME は最新のリビジョン番号を含むプロキシの名前です。コマンドを実行すると、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: REST の GET オペレーションと同等の GraphQL。
  • mutation: REST の PUT オペレーションと同等の GraphQL。
  • query_mutation: query と mutation の両方。
• MaxDepth: ツリーとして表されたときの、クエリの最大深度。MaxDepth を使用すると、ペイロードで深いクエリをブロックできるため、値を保持するために非常に大きなフロー変数を作成する必要がなくなります。ただし、ペイロードは MaxDepth の値に関係なくそのまま送信されます。
• MaxCount: ペイロードに含めることができるフラグメントの最大数。これを利用して、お客様の GraphQL バックエンド サーバーが高度に複雑なクエリを実行しないようにし、クライアントがロジックをより小さなペイロードに分割するように強制できます。
• Action: 次の GraphQL アクションのいずれか。
  • parse: Apigee は GraphQL ペイロードを解析してフロー変数に変換します。作成したフロー変数の内容を JavaCallout などのポリシーで使用できます。なお、parse はペイロードも検証します。
  • verify: Apigee は、GraphQL ペイロードがプロキシにアップロードされたスキーマに準拠していることを検証します。verify を使用すると、スキーマに準拠していないリクエストを受け取らないようにすることができます。これにより、バックエンドの貴重な CPU 時間を節約できます。
  • parse_verify: ペイロードを解析して検証します。
• ResourceURL: Apigee が GraphQL リクエストの検証に使用する GraphQL スキーマ ファイルへのパス。

これらのオプションの詳細については、GraphQL ポリシーのリファレンス ページをご覧ください。