このページは Apigee と Apigee ハイブリッドに適用されます。
Apigee Edge のドキュメントを表示する
このページでは、API プロキシを YAML の Apigee Feature Template として定義し、Google Cloud CLI でデプロイする方法について説明します。まず、シンプルなプロキシを構築し、次に Gemini モデルをフロントエンドとするより完全な例を構築します。
背景については、YAML を使用してプロキシを構成するをご覧ください。完全なスキーマについては、API プロキシ YAML 構成リファレンスをご覧ください。
始める前に
- プロキシが Gemini モデルと通信できるように、Google Cloud プロジェクトで Vertex AI API を有効にします。
gcloud services enable aiplatform.googleapis.com
- Google Cloud CLI をインストールして初期化します。
- このチュートリアルで使用するコマンドにアクセスするには、gcloud ベータ版コンポーネントをインストールします。
gcloud components install beta
- 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 管理者ロール（
パート 1: シンプルな API プロキシを作成する
このセクションでは、リクエストを Apigee の疑似ターゲット サービスに転送し、レート制限を適用するプロキシを作成します。
ステップ 1: テンプレートを作成する
テンプレートは、デプロイするファイルです。プロキシのベースパス、ルート、バックエンド ターゲットを定義し、含める機能を一覧表示します。
プロキシのディレクトリを作成し、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: - 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: 機能を作成する
機能は、ポリシーを保持する再利用可能な構成単位です。テンプレートにポリシーを直接含めることはできないため、レート制限ポリシーは機能に存在します。
テンプレートと同じディレクトリに、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 プロキシ リビジョンを作成します。ファイルを含むディレクトリから次のコマンドを実行します。
gcloud beta apigee apis import hello-proxy \
--from-template=hello-proxy.yaml \
--organization=ORGCLI は、テンプレートとその機能を API プロキシ バンドルにコンパイルしてアップロードし、新しいプロキシ リビジョンを出力します。インポートではリビジョンが作成されますが、デプロイはされません。
ステップ 4: プロキシをデプロイする
リビジョンを環境にデプロイします。
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 ゲートウェイを構築する
このセクションでは、より完全なプロキシ（Vertex AI の Gemini モデルにリクエストを転送し、レート上限を適用して、API キーを必要とする AI ゲートウェイ）を構築します。1 つのテンプレート、3 つの機能、1 つのサービス アカウントを使用します。
パート 1 の単純なプロキシとは異なり、このプロキシは Google Cloud サービス（Vertex AI）を呼び出します。gemini-target 機能は auth: GoogleAccessToken を使用するため、Apigee は Vertex AI への各リクエストに Google OAuth トークンを付加します。このトークンは、作成してプロキシのデプロイ時に指定するサービス アカウントに対して発行されます。このため、この部分では、そのサービス アカウントを作成する手順（ステップ 3）を追加します。
ステップ 1: テンプレートを作成する
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: - spike-arrest.yaml - verify-api-key.yaml - gemini-target.yaml endpoints: - name: gemini basePath: /v1/gemini routes: - name: default target: gemini
ステップ 2: 特徴を作成する
同じディレクトリに、3 つの機能ファイルを作成します。
パート 1 の spike-arrest.yaml 機能を再利用します。
x-api-key ヘッダーで API キーを必要とする 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 モデルに転送する 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 Vertex AI, authenticated with a Google access token. categories: - llm targets: - name: gemini url: https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/gemini-2.5-flash:generateContent auth: GoogleAccessToken scopes: - https://www.googleapis.com/auth/cloud-platform
PROJECT_ID は Google Cloud プロジェクト ID に置き換え、REGION は使用している Vertex AI リージョン（us-central1 など）に置き換えます。この機能は auth: GoogleAccessToken を使用するため、Apigee は Vertex AI への各リクエストに Google アクセス トークンを付加します。
モデルはすべてのロケーションで使用できるわけではなく、URL は使用するロケーションによって異なります。上記の URL はリージョン形式です。これは、us-central1 の gemini-2.5-flash など、特定のリージョンから提供されるモデルで機能します。他のモデルは、別のホストと locations/global を使用するグローバル エンドポイントからのみ提供されます。
url: https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/MODEL:generateContent
モデルがサポートするロケーションを確認するには、Vertex AI の生成 AI のロケーションをご覧ください。
ステップ 3: プロキシのサービス アカウントを作成する
gemini-target 機能は auth: GoogleAccessToken を使用するため、デプロイされたプロキシは サービス アカウントとして Vertex AI を呼び出します。そのサービス アカウントを作成し、Vertex AI へのアクセス権を付与して、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@PROJECT_ID.iam.gserviceaccount.comが作成されます。 - 呼び出すバックエンドへのアクセス権をサービス アカウントに付与します。Vertex AI ターゲットの場合は、Vertex AI ユーザー ロール（
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 プロキシ リビジョンを作成します。
gcloud beta apigee apis import ai-gateway \
--from-template=ai-gateway.yaml \
--organization=ORGコマンド出力のリビジョン番号をメモします。これはステップ 5 で必要になります。リビジョン番号のみを出力するには、インポート コマンドに --format="value(revision)" を追加します。
ステップ 5: サービス アカウントを使用してプロキシをデプロイする
AI ゲートウェイのデプロイは、パート 1 のシンプルなプロキシと次の 2 つの点で異なります。
- ステップ 3 で作成したサービス アカウントを指定する必要があります。デプロイ時に指定しないと、
MISSING_SERVICE_ACCOUNTエラーが発生してデプロイが失敗します。 - 中間環境または包括的環境にデプロイする必要があります。このプロキシは拡張可能なポリシーを使用しますが、Base 環境ではサポートされていません。このプロキシをデプロイすると、
拡張可能なプロキシを基本環境にデプロイできません
というエラーが発生します。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 機能は Vertex AI バックエンドを追加します。デプロイが完了すると、プロキシはサービス アカウントとして Vertex AI に対して認証を行います。
ステップ 6: API キーを取得する
verify-api-key 機能は、有効な API キーを含まないリクエストを拒否するため、プロキシを呼び出す前にキーが必要です。API キーは、このプロキシを含む API プロダクトに関連付けられたデベロッパー アプリの認証情報です。公開の概要で説明されている次のタスクを完了します。
ai-gatewayプロキシと、そのプロキシをデプロイした環境を含む API プロダクトを作成します。- アプリ デベロッパーを登録します。
- その 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 キーでリクエストを送信するをご覧ください。