はじめに

最近、業務で Apigee に触れる機会があったのですが、プロキシ、ポリシー、API プロダクト、環境グループなど似たような用語が多く、関係がなかなか掴めなかったので、自分なりに整理してみました。

Apigee とは

Apigee は、Google Cloud のネイティブ API 管理プラットフォームです。あらゆるユースケース、環境、規模で API を構築、管理、保護できます。

https://cloud.google.com/apigee/docs/api-platform/get-started/what-apigee?hl=ja

バックエンドとクライアントの間に入り、認証やレート制限などをバックエンドを変えずに追加できる、というのが基本的な役割です。

Apigee の種類

Google Cloud の Apigee には、以下の 2 つの形態があります。

  • Apigee（Apigee X と呼ばれることもあります）: 管理プレーンもランタイムも Google Cloud 上で動き、Google が管理します
  • Apigee ハイブリッド: 管理プレーンは Google Cloud 上で動き、ランタイムは自分の Kubernetes クラスタに置いて管理します

https://cloud.google.com/apigee/docs/hybrid/latest/what-is-hybrid?hl=ja
公式ドキュメントのページ冒頭には「このページは Apigee と Apigee ハイブリッドに適用されます。」のような記載があり、どちらで使える機能かを確認できます。

ただし、両方に適用されると書かれていても、ハイブリッドではバージョンの条件が付く機能があります。
たとえば、意味の近いプロンプトの応答を使い回すセマンティックキャッシュ（SemanticCacheLookup / SemanticCachePopulate ポリシー）は、Apigee では使えますが、ハイブリッドでは 1.15.1 以降でないと使えません。

https://cloud.google.com/apigee/docs/api-platform/reference/policies/semantic-cache-lookup-policy?hl=en
なお、検索すると Apigee Edge という製品も出てきます。
Edge は以前からある製品で、Google Cloud 上で動くものではなく、Google Cloud のプロジェクトやコンソールからは使えません。
考え方は共通ですが細かい仕様は異なるので、調べた情報が Edge 向けのものでないかは確認するようにしましょう。

以降は Apigee（X）を前提に書いています。

API プロキシの構成

API プロキシ

Apigee で最初に作るのが API プロキシで、クライアントからのリクエストを受け取ってバックエンドに転送します。
API プロキシには、クライアント側の窓口である ProxyEndpoint と、バックエンド側の窓口である TargetEndpoint があります。

https://cloud.google.com/apigee/docs/api-platform/fundamentals/understanding-apis-and-api-proxies?hl=ja

フロー

それぞれのエンドポイントの中で、処理をどの順番で実行するかを決めるのがフローです。
フローには PreFlow、条件付きフロー、PostFlow があり、1 つのリクエストは以下の順番で処理されます。

  1. ProxyEndpoint のリクエスト（PreFlow → 条件付きフロー → PostFlow）
  2. TargetEndpoint のリクエスト（同上）
  3. バックエンドの呼び出し
  4. TargetEndpoint のレスポンス（同上）
  5. ProxyEndpoint のレスポンス（同上）

公式ドキュメントの図にすると、以下のようになります。

出典: フローによる API プロキシの制御 | Apigee | Google Cloud

図にある PostClientFlow は、クライアントにレスポンスを返したあとに実行されるフローで、ログの書き出しなどに使います。

ポリシー

フローの中に差し込む部品がポリシーです。
API キーの検証（VerifyAPIKey）、レート制限（SpikeArrest）、リクエストの書き換え（AssignMessage）など、用途ごとに用意されていて、<Step> として並べた順に実行されます。

<PreFlow name="PreFlow">
  <Request>
    <Step>
      <Name>VA-VerifyKey</Name>
    </Step>
    <Step>
      <Name>SA-SpikeArrest</Name>
    </Step>
  </Request>
</PreFlow>

認証やレート制限は、ProxyEndpoint の PreFlow に置くのが公式ドキュメントでも最適な場所とされています。

利用者の管理

API プロキシだけでは誰でも呼び出せてしまうので、利用者を以下の 3 つで管理します。

  • デベロッパー: API を使う人（または組織）です
  • アプリ: デベロッパーが登録するもので、API キーはアプリに発行されます
  • API プロダクト: どの API プロキシを、どのパスで、どれくらいの量まで使えるかをまとめたものです

https://cloud.google.com/apigee/docs/api-platform/publish/what-api-product?hl=ja
アプリの API キーでどの API プロキシを呼び出せるかは、キーに紐づけた API プロダクトで決まります。
この確認を行うのが VerifyAPIKey ポリシーで、API プロキシと利用者の管理をつなぐ役割をしています。
なお、キーの確認は自動では行われないので、API プロキシに VerifyAPIKey を置かないと誰でも呼び出せてしまう点には注意が必要です。

組織と環境

  • 組織: 一番外側の単位で、Google Cloud のプロジェクトと 1 対 1 で作られます
  • 環境: API プロキシをデプロイする場所で、test と prod のように分けて使います
  • 環境グループ: ホスト名を持ち、リクエストを環境に振り分けます

https://cloud.google.com/apigee/docs/api-platform/fundamentals/environments-overview?hl=ja

たとえば https://api.example.com/v1/hello の場合、api.example.com は環境グループに設定したホスト名、/v1/hello は API プロキシに設定したベースパスです。
環境グループは複数作ることができ、1 つの環境を複数の環境グループに所属させることもできます。
この場合、その環境にデプロイした API プロキシは、所属しているどの環境グループのホスト名からでも呼び出せます。

環境は、複数の環境グループに所属できます。このような環境にプロキシをデプロイする場合は、環境が属している環境グループごとに 1 つずつ、複数のアドレスがプロキシに存在します。

https://cloud.google.com/apigee/docs/api-platform/fundamentals/environments-overview?hl=ja
なお、同じ環境に同じベースパスの API プロキシは置けません。

環境のタイプと料金

従量課金制では、環境ごとにベース・中間・包括的の 3 つのタイプから選びます。
公式の料金ページでは、それぞれ以下のように説明されています。

ベース環境: 低料金でプラットフォームにオンボーディングし、複雑度の低い API を管理できます。

中間環境: アドオン機能にアクセスし、API のポートフォリオを管理できます。

包括的な環境: 高い信頼性とパフォーマンスを備え、ミッション クリティカルなアプリや予期しないトラフィック急増にも対応します。

https://cloud.google.com/apigee/pricing?hl=ja
料金は 1 リージョンあたり月額で、ベースが 365 ドル、中間が 1,460 ドル、包括的が 3,431 ドルです（2026 年 10 月時点）。
タイプは後から変更できるので、開発用はベース、本番用は包括的のように使い分けることもできます。

ベース環境で使えるのは、API プロキシを作ってリクエストを中継するといった基本的な部分です。
API プロダクトが使えるのは中間環境からで、API キーの検証（VerifyAPIKey）もここから使えるようになります。
包括的な環境では、Debug 画面で試すときに機密情報をマスクする機能なども使うことができます。

https://cloud.google.com/apigee/docs/api-platform/reference/pay-as-you-go-environment-types?hl=ja

包括的な環境を 1 リージョンで 1 年使うと、環境の料金だけで約 4 万ドルになり、これとは別に API の呼び出し回数に応じた料金もかかります。
かなり高額なので、そもそも Apigee が必要なのか、使うならどのタイプが合っているのかは、事前に検討しておいたほうがよさそうです。

Debug 画面で確認する

ここまでの要素がどの順番で動いているかを、Apigee の Debug 機能で確認しました。

Debug 画面では、API プロキシを通ったリクエストごとに、どのポリシーがどの順番で実行され、成功したかどうかが表示されます。
リクエストの流れが上に、レスポンスの流れが下に並び、各ステップを選ぶと、そのときの変数やヘッダーの値も確認できます。
公式ドキュメントの例では、以下のように表示されます。

出典: デバッグの使用 | Apigee | Google Cloud

検証用に、以下の API プロキシを中間環境にデプロイしました。

  • ベースパス: /v1/hello
  • ProxyEndpoint の PreFlow: VerifyAPIKey（x-api-key ヘッダーのキーを確認）→ AssignMessage（キーのヘッダーを削除）
  • TargetEndpoint: Apigee が用意しているモックの API（`https://mocktarget.apigee.net/json`）

API プロダクトにこの API プロキシを登録し、アプリを作って発行された API キーで呼び出しました。

$ curl -s -H "x-api-key: ${API_KEY}" https://api.example.com/v1/hello
{"firstName":"John","lastName":"Doe","city":"San Jose","state":"CA"}

モックの API の応答が返ってきており、バックエンドまでリクエストが届いていることが分かります。
Debug 画面でも、ProxyEndpoint の PreFlow で VerifyAPIKey が成功し、その後に TargetEndpoint を通ってバックエンドへリクエストが送られていました。

API キーを付けずに呼び出すと、401 が返ってきました。

$ curl -s -o /dev/null -w "%{http_code}\n" https://api.example.com/v1/hello
401
$ curl -s https://api.example.com/v1/hello
{"fault":{"faultstring":"Failed to resolve API Key variable request.header.x-api-key","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

エラーコードの steps.oauth.v2.FailedToResolveAPIKey から、VerifyAPIKey がヘッダーからキーを取得できずに失敗したことが分かります。
Debug 画面でも VerifyAPIKey の時点でエラーになっており、それ以降のポリシーは実行されず、バックエンドへのリクエストも送られていませんでした。

なお、Debug 画面にはリクエストヘッダーもそのまま表示されるため、API キーなども見えてしまいます。
公式ドキュメントでも、Debug はメッセージの内容をキャプチャするので、機密情報を含む場合はマスクを有効にするよう注意書きがあります。
包括的な環境であれば、マスク設定（debugmask）で隠すことができます。

https://cloud.google.com/apigee/docs/api-platform/security/data-masking?hl=ja

まとめ

Apigee の用語は多いですが、API プロキシの構成・利用者の管理・組織と環境の 3 つに分けると関係が掴みやすくなりました。
実際に API プロキシを作るときは、Debug 画面でリクエストの流れを見ながら進めると、各要素の役割が理解しやすいと思います。

また、Google Skills には Apigee X のハンズオンラボがいくつか用意されています。
たとえば「Publishing APIs with Apigee X」では、API キーの検証や API プロダクトを実際に設定できるので、自分の環境を用意する前に試してみるのもよさそうです。

https://www.skills.google/catalog?keywords=apigee

参考