このページは Apigee と Apigee ハイブリッドに適用されます。
Apigee Edge のドキュメントを表示する
このページでは、API プロキシを YAML で Apigee 機能テンプレートとして定義し、Google Cloud CLI でデプロイする方法について説明します。まず、シンプルなプロキシを構築し、次に Gemini モデルをフロントエンドとするより実証済みの例を構築します。
背景情報については、YAML を使用したプロキシの構成をご覧ください。完全なスキーマについては、API プロキシ YAML 構成リファレンスをご覧ください。
始める前に
パート 2 のみ: モデルをホストする Google Cloud プロジェクトで Agent Platform API を有効にします。
gcloud services enable aiplatform.googleapis.com \ --project=PROJECT_IDPROJECT_ID は、モデルをホストするプロジェクトの ID(
my-apigee-projectなど)に置き換えます。このチュートリアルでは、Apigee 組織のプロジェクトを使用します。パート 1 では、この API は必要ありません。テンプレートはグローバル エンドポイントを使用するため、リージョンを選択する必要はありません。API を有効にしてから、API がアクティブになるまで少し時間がかかることがあります。- Google Cloud CLI をインストールして初期化します。
- Apigee 組織と少なくとも 1 つの環境がある。組織名と環境名をメモします。この例では、プレースホルダとして ORG と ENV を使用しています(このページで使用されているプレースホルダをご覧ください)。パート 2 の AI ゲートウェイには、中間環境または包括的環境(基本環境ではない)も必要です。Apigee 環境タイプをご覧ください。
- 必要な権限があることを確認します。
- API プロキシをインポート(作成)するには: API 管理者ロール(
roles/apigee.apiAdmin)、またはapigee.proxies.createを付与する同等のロール。 - API プロキシをデプロイする: ターゲット環境の環境管理者(
roles/apigee.environmentAdmin)と、プロジェクト レベルの API 読み取り(roles/apigee.apiReaderV2)。 - パート 2、ステップ 6 で API キーを生成する API プロダクト、デベロッパー、アプリを作成するには、API 管理者(
roles/apigee.apiAdmin)とデベロッパー管理者(roles/apigee.developerAdmin)が必要です。ロールの完全なリストについては、Apigee のロールをご覧ください。
- API プロキシをインポート(作成)するには: API 管理者ロール(
このページで使用されているプレースホルダ
コマンドの各プレースホルダを独自の値に置き換えます。ほとんどの値はすでに存在しており、それらを検索します。SA_NAME は自分で選択します。一部の値は、手順を進めるにつれて生成されます。
| プレースホルダ | ソース | 説明 |
|---|---|---|
| ORG | 検索 | Apigee 組織名。通常、これは PROJECT_ID と同じです。アクセス可能な組織を一覧表示するには、gcloud apigee organizations list を実行します。 |
| ENV | 検索 | 組織内の環境(test など)。パート 1 のステップ 4 で、それらを一覧表示する方法を説明しています。 |
| PROJECT_ID | 検索 | Apigee 組織を保持する Google Cloud プロジェクトの ID(例: my-apigee-project)。アクティブなプロジェクトを出力するには、gcloud config get project を実行します。 |
| HOSTNAME | 検索 | ENV を含む環境グループのホスト名(例: api.example.com)。パート 1、ステップ 5 で、この情報の確認方法を説明しています。 |
| SA_NAME | 選択 | パート 2、ステップ 3 で作成するサービス アカウントの名前(例: apigee-ai-gateway)。 |
| PROJECT_NUMBER | 検索 | PROJECT_ID のプロジェクト番号(例: 123456789012)。パート 2 のステップ 3 に、これを出力するコマンドが示されています。 |
| REGION | 選択 | 省略可。モデルを提供するリージョン(us-central1 など)。これは、gemini-target 機能をリージョン エンドポイントに切り替える場合にのみ必要です。 |
| REVISION | 生成済み | パート 2、ステップ 4 で import コマンドが出力するプロキシ リビジョン番号(例: 1)。 |
| API_KEY | 生成済み | パート 2、ステップ 6 でデベロッパー アプリを登録するときに Apigee が生成する API キー。 |
パート 1: シンプルな API プロキシを作成する
このセクションでは、Apigee モック ターゲット サービスにリクエストを転送し、レート制限を適用するプロキシを作成します。
ステップ 1: テンプレートを作成する
テンプレートは、デプロイするファイルです。プロキシのベースパス、ルート、バックエンド ターゲットを定義し、含める機能を一覧表示します。
テンプレートのプロジェクト ディレクトリを作成し、使用する機能の features サブディレクトリを作成します。
mkdir -p proxy-templates/features cd proxy-templates
このパートを完了すると、プロジェクト ディレクトリは次のようになります。
proxy-templates/ hello-proxy.yaml features/ spike-arrest.yaml
proxy-templates ディレクトリに、hello-proxy.yaml という名前のファイルを作成します。
gateway: apigee schemaVersion: 1.0.0 name: hello-proxy type: template description: A simple proxy to the Apigee mock target, protected by a rate limit. features: - ./features/spike-arrest.yaml endpoints: - name: default basePath: /hello routes: - name: default target: default targets: - name: default url: https://mocktarget.apigee.net
このテンプレートでは、次のものが定義されています。
- ベースパス
/helloを持つエンドポイント。クライアントは、このパスでプロキシを呼び出します。 defaultという名前のターゲットにリクエストを送信するルート。- バックエンド URL を指すターゲット。
- 特徴
spike-arrest.yaml。これは、次に作成します。
ステップ 2: 特徴を作成する
機能は、ポリシーを保持する再利用可能な構成単位です。テンプレートにポリシーを直接含めることはできないため、レート制限ポリシーは機能内に存在します。
features ディレクトリに、spike-arrest.yaml という名前のファイルを作成します。
gateway: apigee schemaVersion: 1.0.0 name: spike-arrest displayName: Spike Arrest type: feature description: Protects the backend by smoothing traffic spikes. categories: - traffic parameters: - name: RATE displayName: RATE description: Maximum request rate, for example 30ps (per second) or 100pm (per minute). default: 30ps examples: - 30ps - 100pm defaultEndpoint: name: default flows: - name: PreFlow mode: Request steps: - name: SA-SpikeArrest policies: - name: SA-SpikeArrest type: SpikeArrest content: SpikeArrest: metadata: name: SA-SpikeArrest enabled: "true" continueOnError: "false" DisplayName: SA-SpikeArrest Rate: "{RATE}"
この機能は:
- リクエスト率を制限する SpikeArrest ポリシーを定義します。
defaultEndpoint.flowsを使用して、リクエストの PreFlow にポリシーを追加します。これにより、リクエストごとにポリシーが実行されます。- パラメータ
RATEを宣言します。プロキシがコンパイルされると、デフォルト(30ps)が{RATE}に置き換えられます。
ステップ 3: プロキシをインポートする
テンプレートをインポートして API プロキシ リビジョンを作成します。テンプレートを含む proxy-templates ディレクトリから次のコマンドを実行します。
gcloud apigee apis import hello-proxy \
--from-template=hello-proxy.yaml \
--organization=ORGCLI は、テンプレートとその機能を API プロキシ バンドルにコンパイルしてアップロードし、新しいプロキシ リビジョンを出力します。インポートするとリビジョンが作成されますが、デプロイはされません。
ステップ 4: プロキシをデプロイする
組織内の環境を一覧表示します。
gcloud apigee environments list --organization=ORG
このコマンドにより、環境名が出力されます。ENV として使用するものを 1 つ選択し、リビジョンをデプロイします。
gcloud apigee apis deploy \
--api=hello-proxy \
--environment=ENV \
--organization=ORGデフォルトでは、このコマンドは最新のリビジョンをデプロイします。特定のリビジョンをデプロイするには、その番号を最初の引数として渡します(例: gcloud apigee apis deploy 1 --api=hello-proxy --environment=ENV)。同じベースパスに別のプロキシがすでにデプロイされている場合は、--override を追加して、ダウンタイムなしで置き換えます。
ステップ 5: プロキシを呼び出す
デプロイされたプロキシをネットワーク経由で呼び出すには、ルーティング可能なホスト名を持つ環境グループに環境を接続する必要があります。組織を作成したばかりの場合は、プロキシを呼び出す前に、これが設定されていることを確認します。環境と環境グループについてをご覧ください。
環境を含む環境グループのホスト名を見つけます。
- Google Cloud コンソールで、[Apigee] > [管理] > [環境] に移動します。
- [環境グループ] タブを選択します。
- 環境を含む環境グループを見つけて、[ホスト名] 列から値をコピーします。
テンプレートのベースパスを使用して、そのホスト名でプロキシを呼び出します。
curl https://HOSTNAME/hello
HOSTNAME は、コピーしたホスト名に置き換えます。成功レスポンスは、モック ターゲット サービスから返されます。
パート 2: Gemini 用の AI ゲートウェイを構築する
このセクションでは、より完全なプロキシを構築します。これは、Gemini Enterprise Agent Platform の Gemini モデルにリクエストを転送し、レート制限を適用し、API キーを必要とする AI ゲートウェイです。1 つのテンプレート、3 つの機能、1 つのサービス アカウントを使用します。
パート 1 のシンプルなプロキシとは異なり、このプロキシは Google Cloud サービス(Agent Platform)を呼び出します。gemini-target 機能は auth: GoogleAccessToken を使用するため、Apigee は Agent Platform への各リクエストに Google OAuth トークンを添付します。このトークンは、作成したサービス アカウントに対して発行され、プロキシのデプロイ時に提供されます。この部分では、サービス アカウントを作成するステップが追加されます(ステップ 3)。
始める前に、始める前にの説明に従って、モデルをホストするプロジェクトで Agent Platform API が有効になっていることを確認します。Agent Platform を使用したことがなくても問題ありません。
パート 2 の PROJECT_ID は、Apigee 組織のプロジェクトの ID です(例: my-apigee-project)。パート 2 では、この 1 つのプロジェクトを全体で使用します。このプロジェクトで API を有効にし、サービス アカウントを作成して、テンプレートの MODEL_PROJECT_ID 値として設定します。
ステップ 1: テンプレートを作成する
パート 1 の proxy-templates ディレクトリに、ai-gateway.yaml という名前のファイルを作成します。
gateway: apigee schemaVersion: 1.0.0 name: ai-gateway type: template description: AI gateway that fronts a Gemini model with throttling and API key enforcement. features: - ./features/spike-arrest.yaml - ./features/verify-api-key.yaml - ./features/gemini-target.yaml parameters: - name: MODEL_PROJECT_ID default: PROJECT_ID - name: MODEL default: gemini-3.8-flash endpoints: - name: gemini basePath: /v1/gemini routes: - name: default target: gemini
parameters リストは、gemini-target 機能が宣言するパラメータの値を設定します。これは次のステップで作成します。PROJECT_ID は、API を有効にするために使用したプロジェクト ID(my-apigee-project など)に置き換えます。
ステップ 2: 特徴を作成する
このテンプレートでは 3 つの機能を使用します。パート 1 の spike-arrest.yaml 機能を再利用し、features ディレクトリに他の 2 つを作成します。このステップを完了すると、プロジェクト ディレクトリは次のようになります。
proxy-templates/ hello-proxy.yaml ai-gateway.yaml features/ spike-arrest.yaml verify-api-key.yaml gemini-target.yaml
x-api-key ヘッダーに API キーを要求する features/verify-api-key.yaml を作成します。
gateway: apigee schemaVersion: 1.0.0 name: verify-api-key displayName: Verify API Key type: feature description: Requires a valid API key in the x-api-key request header. categories: - security defaultEndpoint: name: default flows: - name: PreFlow mode: Request steps: - name: VA-VerifyAPIKey policies: - name: VA-VerifyAPIKey type: VerifyAPIKey content: VerifyAPIKey: metadata: name: VA-VerifyAPIKey enabled: "true" continueOnError: "false" DisplayName: VA-VerifyAPIKey APIKey: metadata: ref: request.header.x-api-key
Google アクセス トークンで認証された Gemini モデルにルーティングする features/gemini-target.yaml を作成します。
gateway: apigee schemaVersion: 1.0.0 name: gemini-target displayName: Gemini Target type: feature description: Routes requests to a Gemini model on the Gemini Enterprise Agent Platform, authenticated with a Google access token. categories: - llm parameters: - name: MODEL_PROJECT_ID displayName: Model Project ID description: Google Cloud project that hosts the Gemini model. Supplied by the template; no default. - name: MODEL displayName: Model description: The Gemini model to route to. default: gemini-3.8-flash examples: - gemini-3.8-flash - gemini-4-argon targets: - name: gemini url: https://aiplatform.googleapis.com/v1/projects/{MODEL_PROJECT_ID}/locations/global/publishers/google/models/{MODEL}:generateContent auth: GoogleAccessToken scopes: - https://www.googleapis.com/auth/cloud-platform
gemini-target 機能は 2 つのパラメータを宣言し、それらをターゲット URL に代入します。
MODEL_PROJECT_ID: モデルをホストする Google Cloud プロジェクト。デフォルト値はないため、テンプレートでプロジェクト ID に設定する必要があります。MODEL: 呼び出す Gemini モデル。この機能のデフォルトはgemini-3.8-flashです。
CLI はテンプレートをコンパイルするときに、各パラメータを次のように解決します。
- テンプレートの
parametersリストに、同じ名前で空でないdefaultを持つエントリがある場合、CLI はその値を使用します。 - それ以外の場合、CLI は対象物の
defaultを使用します。 - どちらも値を設定しない場合、CLI は
{name}を空の文字列に置き換えます。インポートでエラーが報告されないため、MODEL_PROJECT_IDがないと、プロジェクト ID のないターゲット URL が生成されます。
インポート時にパラメータ値を設定するコマンドライン フラグはありません。別のプロジェクトまたはモデルを使用するには、テンプレートの parameters リストで値を編集し、テンプレートを再度インポートします。
gemini-target 機能は auth: GoogleAccessToken を使用して、Apigee が Agent Platform への各リクエストに Google アクセス トークンを添付します。
この URL は、グローバル エンドポイント(ホスト aiplatform.googleapis.com と locations/global)を使用します。このエンドポイントは、gemini-3.8-flash を提供し、リージョン間で利用可能な容量にリクエストをルーティングします。グローバル エンドポイントを使用する場合、リージョンを選択する必要はありません。
別のモデルを呼び出すには、テンプレートの parameters リストの MODEL をモデルの ID に設定します。呼び出し可能な Gemini モデルを一覧表示するには、次のコマンドを実行します。
gcloud ai model-garden models list --model-filter=gemini
MODEL_ID 列の各値は google/gemini-3.8-flash@default のようになります。MODEL を google/ と @ の間の部分(gemini-4-argon など)に設定します。Google Cloud コンソールの Model Garden にあるモデルのカードには、同じ ID が表示されます。モデルがグローバル エンドポイントをサポートしていることを確認するには、Google モデルのエンドポイントのロケーションの「グローバル」タブをご覧ください。
リクエストを処理するリージョンを制御する必要がある場合は、features/gemini-target.yaml の url 行をリージョン形式に置き換えます。これにより、リージョンがホストとパスの両方に配置されます。
url: https://REGION-aiplatform.googleapis.com/v1/projects/{MODEL_PROJECT_ID}/locations/REGION/publishers/google/models/{MODEL}:generateContent
REGION は、同じ Google モデル エンドポイントのロケーションの表に記載されている、モデルを提供するリージョンに置き換えます。グローバル エンドポイントを避けるべき場合については、グローバル エンドポイントをご覧ください。
ステップ 3: プロキシのサービス アカウントを作成する
gemini-target 機能は auth: GoogleAccessToken を使用するため、デプロイされたプロキシはサービス アカウントとして Agent Platform を呼び出します。そのサービス アカウントを作成し、Agent Platform へのアクセス権を付与して、Apigee サービス エージェントが使用できるようにします。このサービス アカウントは、ステップ 5 でプロキシをデプロイするときに指定します。詳細については、Google 認証システムの使用をご覧ください。
- Apigee 組織と同じ Google Cloud プロジェクトにユーザー管理のサービス アカウントを作成します。(Compute Engine のデフォルトのサービス アカウントは使用できません)。他の方法で作成するには、サービス アカウントの作成と管理をご覧ください。
gcloud iam service-accounts create SA_NAME \ --project=PROJECT_ID \ --display-name="Apigee AI gateway"SA_NAME にわかりやすい名前(
apigee-ai-gatewayなど)を選択します。このコマンドは、サービス アカウントSA_NAME@PROJECT_ID.iam.gserviceaccount.com(例:apigee-ai-gateway@my-apigee-project.iam.gserviceaccount.com)を作成します。 - サービス アカウントに、呼び出すバックエンドへのアクセス権を付与します。Agent Platform ターゲットの場合は、Agent Platform ユーザーロール(
roles/aiplatform.user)を付与します。gcloud projects add-iam-policy-binding PROJECT_ID \ --member="serviceAccount:SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \ --role="roles/aiplatform.user"プロジェクトの IAM ポリシーに条件付きロール バインディングがすでに含まれている場合は、このコマンドに
--condition=Noneを追加します。 - サービス アカウントに対するサービス アカウント トークン作成者のロール(
roles/iam.serviceAccountTokenCreator)を付与して、Apigee サービス エージェントがサービス アカウントのトークンを生成できるようにします。gcloud iam service-accounts add-iam-policy-binding \ SA_NAME@PROJECT_ID.iam.gserviceaccount.com \ --project=PROJECT_ID \ --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-apigee.iam.gserviceaccount.com" \ --role="roles/iam.serviceAccountTokenCreator"PROJECT_NUMBER を確認するには、
gcloud projects describe PROJECT_ID --format='value(projectNumber)'を実行します。
ステップ 4: プロキシをインポートする
テンプレートをインポートして API プロキシ リビジョンを作成します。テンプレートを含む proxy-templates ディレクトリから次のコマンドを実行します。
gcloud apigee apis import ai-gateway \
--from-template=ai-gateway.yaml \
--organization=ORGコマンド出力のリビジョン番号をメモします。これはステップ 5 で必要になります。リビジョン番号のみを出力するには、import コマンドに --format="value(revision)" を追加します。
ステップ 5: サービス アカウントを使用してプロキシをデプロイする
AI ゲートウェイのデプロイは、パート 1 のシンプルなプロキシとは次の 2 つの点で異なります。
- ステップ 3 で作成したサービス アカウントを指定する必要があります。トークンを指定せずにデプロイすると、
MISSING_SERVICE_ACCOUNTエラーでデプロイが失敗します。 - 中間環境または包括的環境にデプロイする必要があります。このプロキシは、Base 環境でサポートされていない拡張可能なポリシーを使用します。Base 環境にデプロイすると、「拡張可能なプロキシを Base 環境にデプロイできません」というエラーが発生します。
gcloud apigee environments listコマンドは環境タイプを出力しません。これを確認するには、 Google Cloud コンソールで [Apigee] > [管理] > [環境] に移動します。Apigee 環境タイプをご覧ください。
Apigee UI: プロキシをデプロイし、サービス アカウントの入力を求められたら「SA_NAME@PROJECT_ID.iam.gserviceaccount.com」と入力します。手順については、API プロキシのデプロイをご覧ください。
Deployment API: deployments API を呼び出し、サービス アカウントを serviceAccount クエリ パラメータとして渡します。REVISION は、ステップ 4 のリビジョン番号に置き換えます。
curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -X POST \ "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/ai-gateway/revisions/REVISION/deployments?serviceAccount=SA_NAME@PROJECT_ID.iam.gserviceaccount.com"
デプロイ リクエストはすぐに返されます。デプロイは非同期です。リビジョンのデプロイ ステータスをポーリングします。READY になるまで PROGRESSING が報告されます。
curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/ai-gateway/revisions/REVISION/deployments"
プロキシがコンパイルされると、spike-arrest 機能と verify-api-key 機能によってポリシーがリクエスト PreFlow に追加されます(最初にレート制限、次に API キーのチェック)。gemini-target 機能によって Agent Platform バックエンドが追加されます。デプロイが完了すると、プロキシはサービス アカウントとして Agent Platform に対する認証を行います。
ステップ 6: API キーを取得する
verify-api-key 機能は、有効な API キーを持たないリクエストを拒否するため、プロキシを呼び出す前にキーが必要です。API キーは、このプロキシを含む API プロダクトに関連付けられたデベロッパー アプリの認証情報です。公開の概要で説明されている次のタスクを完了します。
ai-gatewayプロキシを含む API プロダクトを作成します。プロダクト フォームに次のように入力し、[保存] をクリックします。- 名前と表示名: 任意の値(例:
ai-gateway-product)。 - Environment: プロキシをデプロイした環境(ENV)。
- アクセス: 公開。[Automatically approve access requests] は選択したままにします。これにより、アプリの登録時に API キーが承認されます。
- [Operations] セクションで、[+ ADD AN OPERATION] をクリックし、次のフィールドを設定します。
- API プロキシ:
ai-gateway。 - パス:
/。リクエストは、プロキシのベースパス/v1/geminiに送信され、その後に何も続きません。パス/はベースパスと一致します。/**はその下のパスのみと一致するため、/v1/geminiへのリクエストはエラーoauth.v2.InvalidApiKeyForGivenResourceで失敗します。リソースパスの構成をご覧ください。 - メソッド:
POST。
- API プロキシ:
- [API quota limit]、[LLM token quota limit]、オペレーションの [Quota]、[LLM Operations] セクションは空のままにします。プロキシの
spike-arrest機能により、レート制限が適用されます。
- 名前と表示名: 任意の値(例:
- アプリ デベロッパーを登録する。
- デベロッパー アプリを登録し、アプリの作成時に API プロダクトを選択します。これにより、新しいキーが最初からプロダクトに関連付けられます。
アプリを登録すると、鍵が生成されます。これを取得するには、API キーとシークレットを表示するをご覧ください。
ステップ 7: プロキシを呼び出す
パート 1、ステップ 5 の説明に沿って環境グループのホスト名を確認し、ベースパス /v1/gemini でプロキシを呼び出します。x-api-key ヘッダーで API キーを渡し、Gemini generateContent リクエスト本文を送信します。
curl -X POST https://HOSTNAME/v1/gemini \
-H "x-api-key: API_KEY" \
-H "Content-Type: application/json" \
-d '{"contents":[{"role":"user","parts":[{"text":"Say hello in one sentence."}]}]}'HOSTNAME は環境グループのホスト名に、API_KEY はステップ 6 のキーに置き換えます。成功したレスポンスは、モデルの JSON 出力です。キーを省略すると、VerifyAPIKey ポリシーから認証エラーが返されます。これにより、verify-api-key 機能が有効になっていることが確認されます。キーを渡すその他の方法については、有効な API キーを使用してリクエストを送信するをご覧ください。