API 管理

Apigee で GraphQL API を管理する方法

2021年12月17日

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 からクローン可能）を使用して、ポリシーがどのように機能するかを説明します。

ハイレベルのアーキテクチャは、以下のようになっています。

https://storage.googleapis.com/gweb-cloudblog-publish/images/high-level_architecture.max-1400x1400.jpg

シナリオの仕組み

私たちのシナリオは、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 コマンドを実行すると、上記とまったく同じ出力が返されます。このファイルのクエリを更新したり、コピーして独自のクエリファイルを作成することも可能です。