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

GraphQL ポリシーのオプションの概要については、後述の GraphQL のオプションをご覧ください。

GraphQL の詳細については、GraphQL.org をご覧ください。

例

次の例は、Apigee に 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 ポリシーを追加する

新しいプロキシ エディタ

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

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

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

    GraphQL の [Create Policy] ダイアログ。

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

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

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

    2. [GraphQL スキーマ (.graphql) のインポート] を選択します。次のように表示されます。

      スキーマ ファイルを選択します。

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

      スキーマを選択しました。
  7. [Create] をクリックしてポリシーを作成します。

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

  1. 左側のペインで [Proxy Endpoints] > [default] > [PreFlow] を選択します。

    プロキシ エディタで PreFlow のターゲット エンドポイントを選択します。

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

    [Response] ペインの [PreFlow] の横にある [+] ボタンをクリックします。

  3. [Add policy step] ダイアログで、[GQL-] ポリシーを選択します。
  4. [Add] をクリックしてポリシーを接続します。
  5. [Save] をクリックし、現在のリビジョンに変更を加えて保存します。
  6. 変更をデプロイするには、[Overview] タブをクリックして [Deploy] を選択します。

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

従来バージョンのプロキシ エディタ

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

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

    プラスステップ ボタン

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

    GraphQL ポリシーを追加します。

    [ステップの追加] ペインに次のオプションが表示されます。

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

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

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

    2. [GraphQL スキーマ (.graphql) のインポート] を選択します。次のように表示されます。

      スキーマ ファイルを選択します。

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

      スキーマを選択しました。

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

    GraphQL ポリシーを含む PreFlow ペイン。

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

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

    GraphQL ポリシーを含む PreFlow ペイン。

これで、次の 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 ポリシーのリファレンス ページをご覧ください。