Apigee で GraphQL API を管理する方法
Google Cloud Japan Team
※この投稿は米国時間 2021 年 12 月 3 日に、Google Cloud blog に投稿されたものの抄訳です。
過去 20 年間、REST API は、組織のデータやバックエンドを外部、パートナー、内部のアプリケーションに公開するための、軽量で柔軟な標準ツールとして使用されてきました。Google Cloud の Apigee は API 管理におけるリーダーであり、レート制限の定義、認証と認可の実施、API を悪用しようとするクライアントのブロック、API の更新後のシームレスな動作などの REST API 管理を可能にします。
GraphQL は、デベロッパーにとって使いやすく柔軟な API を構築するためのパラダイムとして急速に普及しています。アプリケーション デベロッパーが必要とする情報を、バックエンドのデータソースに過不足ない形でリクエストできるからです。現在、REST と GraphQL のどちらも強力な API の選択肢となりえ、API プロバイダは、この次世代の API をどう構築、管理するかという課題に直面しています。今回の Apigee のリリースにより、REST と GraphQL の併用が簡単に行えるようになりました。デベロッパーはどちらかを選ぶ必要はありません。自身のスタックに GraphQL を追加し、同時に REST に対する既存の投資を活用することができるのです。
Apigee は既存の豊富なポリシーに加える形で、新しい GraphQL ポリシーを追加しました。このポリシーはトラフィックの管理やパフォーマンス改善、さらにはバックエンド サービスの変更やコードの記述を伴わないセキュリティの向上を実現するものです。GraphQL ポリシーを Apigee で作成したプロキシに追加することで、デベロッパーは GraphQL のクエリとレスポンスが特定のスキーマに準拠しているかどうかを検証できます。また、Apigee の標準的なプロキシの PreFlow でこのポリシーをチェーンさせることで、バックエンド API に対して、他の検証や管理機能を実行できます。
Apigee は、StepZen とパートナーを組み、こうした GraphQL の機能をお客様にお届けします。StepZen は、ローコードの構成要素と API 開発を高速化するコネクタを主力とした、組織向け GraphQL プロバイダです。このブログ記事では、StepZen で構築された GraphQL API を含むプロジェクト（GitHub からクローン可能）を使用して、ポリシーがどのように機能するかを説明します。
ハイレベルのアーキテクチャは、以下のようになっています。
シナリオの仕組み
私たちのシナリオは、e コマースのカスタマイズです。1 つの GraphQL エンドポイントが複数の API をまとめており、Apigee を介してプロキシされています。例えば、ユーザーの住む都市名と、3 米ドル相当の商品がそこの現地通貨でいくらになるかが表示される e コマース エクスペリエンスがあるとします。たったの数ステップで、複数の API を結合した単一の GraphQL エンドポイントにクエリを実行できます。GraphQL エンドポイントは Apigee GraphQL ポリシーによって保護されています。
Apigee の役割
Apigee は、クエリがスキーマに適合しているかどうかをチェックし、API キーが有効であることを確認し、GraphQL 呼び出しの分析情報を収集します。Apigee の API プロダクトと GraphQL のサポートを利用して、割り当てを追加したり、特定の GraphQL オペレーションへのアクセスを制限したりできます。
この簡単な設定では、単一の GraphQL スキーマを検証できます。さらに、 Apigee がサポートするフローを活用すれば、ユーザーごとに異なるバージョンのスキーマを利用することも可能です。クエリを許可したままで、スキーマへのリクエストを完全にブロックすることもできます。また、GraphQL エンドポイントへのアクセスをデベロッパー ポータルで公開することで、セルフサービスで API を利用しているデベロッパーでも、新しいエンドポイントにアクセスするための一意の認証情報を登録し、取得できるようになります。
StepZen の役割
StepZen は、バックエンドでの GraphQL 呼び出しを実行します。具体的には以下を行います。
国、市町村、IP アドレスに基づいて割り出したユーザーの地域の現地通貨の情報を入手するため、api.ip-api.com を呼び出します。
最初の呼び出しで得られた通貨情報を使用して、通貨換算 API（api.frankfurter.com）から、現在の為替レートで該当する通貨に換算した商品の価格を取得します。
以下は、このシナリオに沿った GraphQL リクエストとレスポンスの例です。
GraphQL クエリ:
GraphQL のレスポンス:
上記のクエリは、単一のリクエストで地域および通貨の情報を両方取得しています。2 つの REST API が呼び出され、適切なレスポンスが生成されます。StepZen スキーマは、通貨換算 API を使って、priceInCountry フィールドを地域のレスポンスに追加します。デベロッパーが自身で複数の API を組み合わせる必要はありません。取得したいフィールドを指定するだけで、それに適したレスポンスが作成されます。
StepZen と Apigee はどちらも管理 API を持っているため、StepZen のエンドポイントに Apigee プロキシを作成するプロセスを自動化することができます。そのためのオープンソース ユーティリティもご用意しました。StepZen のアカウントをお持ちでない方には、ユーティリティでアカウントをプロビジョニングします。これにより、StepZen スキーマがデプロイされ、Apigee プロキシが自動的に構築されます。プロキシの呼び出しには API キーが必要となるように構成されており、GraphQL リクエストを StepZen のスキーマと照合して自動的に検証します。
環境の準備と運用
ご自身のアカウントにプロキシ、API プロダクト、デベロッパー、アプリ、プロパティ セットの作成とデプロイに必要な Apigee 権限が付与されていることを確認してください。
git clone git@github.com:apigee/stepzen.git を実行してリポジトリをクローンします。
先ほどリポジトリをクローンしたディレクトリに移動し、以下のコマンドを実行します。
./apizenSetup -o <your_org> -e <your_env> -t $(gcloud auth print-access-token) -i $(gcloud auth print-identity-token) -zこのスクリプトでは、いくつかのオプションのパラメータを実行できますが（リポの README ファイルで説明されています）、デフォルトで指定する必要があるパラメータは次のとおりです。
-o <Apigee 設定に使用する組織名またはプロジェクト名>
-e <環境名>
-t <必要な Apigee アーティファクトのデプロイと作成にアクセスできる gcloud トークン>
-i <gcloud が生成した ID トークン>
StepZen はこれを利用して、一意の StepZen アカウントを 1 つ生成します。
-z
これはオプションですが、提供された場合、スクリプトは StepZen の認証情報を出力します。StepZen ツールを後で使う場合には便利です。
スクリプトはいくつかのステップを実行し、以下のように随時進捗状況を出力します。
StepZen のエンドポイントを呼び出し、StepZen アカウントの詳細を取得する。
StepZen の認証情報を保存する Apigee PropertySet を作成または更新する。
StepZen アカウントを下りターゲットとして事前に構成された Apigee API プロキシをデプロイする（上記で構成された PropertySet に依存）。
エンドポイントの保護のための認証情報を持つデベロッパー、API プロダクト、アプリを作成または更新する。
スクリプトが完了すると、curl コマンドの例（下記参照）が表示され、設定時に作成された API キーが表示されます。
上記のようにオプション "-z" を提供した場合、スクリプトは StepZen アカウント、管理者キー、API キーを出力します（これらの情報は書き留めておき、大切に保存してください）。これらの詳細を YAML として保存し（実際にも YAML として出力されます）、後で StepZen ツールで使用することができます。
エンドポイントのテスト
スクリプトが完了すると、次のような curl コマンドの例が表示されます。
この curl コマンドは、上記の例で挙げたのと同じ GraphQL クエリを含む "gql-query.json" という名前のファイルを参照しています。この curl コマンドを実行すると、上記とまったく同じ出力が返されます。このファイルのクエリを更新したり、コピーして独自のクエリファイルを作成することも可能です。
API に Google マップを追加する
おまけとして、この API に Google マップを加えてみましょう。これにより、e コマースアプリでオンライン注文した商品を受け取ることができる最寄りの実店舗を表示できるようになります（これをもとに、配達と受け取りのどちらが簡単か判断することもできます）。
1. API キーを使って Google Maps API を StepZen から呼び出します。API キーを取得する手順: Google Maps Platform のスタートガイド
2. リポジトリにサンプル スキーマをご用意しています。StepZen Maps サンプル フォルダの config.yaml.sample ファイルの名前を config.yaml に変更してください。
3. config.yaml ファイルを編集して、<apikey> を自分のキーと入れ替えます。
4. このスクリプトを新しい StepZen スキーマで実行します。スクリプトは、前回作成された StepZen アカウントを検出し、再利用します。
5. では、この新しい設定を、先ほどの curl コマンドでテストしてみましょう。
今回は、stepzen-maps-example ディレクトリに保存された GraphQL クエリを指定します。新しい curl コマンドは以下のようになります（もちろん、エンドポイントの API キーとホスト名はご自身のものに更新してください）。
今回実行するクエリは以下のようなものです。
クエリの実行内容
このクエリでは、Google DNS の最初のロケーション クエリで返された IP の緯度 / 経度に対して、最も近いターゲット地域が検索されます。
この情報は、最初の検索結果で解決された緯度および経度として、埋め込まれた findNearby に渡されます。StepZen は、スキーマの構成時に提供された Google Maps API とキーを使用します。
これを api-ip-api.com のクエリ機能と組み合わせることで、単一の GraphQL クエリでターゲット ストアに最も近い実店舗を取得でき、エクスペリエンスを向上させることができます（今回はこの店舗での受け取りを想定していますが、他の店舗でもお試しください）。
次のステップ
Apigee ポリシーや StepZen GraphGL エンドポイントの構築と実行に関して詳しくは、以下の関連資料をご覧ください。
Apigee の GraphQL 対応のお知らせ- Apigee で GraphQL API を管理する方法
Apigee GraphQL ポリシー - GraphQL の使用 | Apigee X
StepZen のスタートガイド（英語） - https://stepzen.com/docs/quick-start
GraphQL スキーマの設計（英語）https://stepzen.com/docs/design-a-graphql-schema
- Google Cloud プロダクト マネージャー、Geir Sjurseth
- StepZen デベロッパー、Carlos Eberhardt
