YAML テンプレートから API プロキシを作成する

このページは 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_ID

    PROJECT_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 のロールをご覧ください。

このページで使用されているプレースホルダ

コマンドの各プレースホルダを独自の値に置き換えます。ほとんどの値はすでに存在しており、それらを検索します。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=ORG

CLI は、テンプレートとその機能を 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: プロキシを呼び出す

デプロイされたプロキシをネットワーク経由で呼び出すには、ルーティング可能なホスト名を持つ環境グループに環境を接続する必要があります。組織を作成したばかりの場合は、プロキシを呼び出す前に、これが設定されていることを確認します。環境と環境グループについてをご覧ください。

環境を含む環境グループのホスト名を見つけます。

  1. Google Cloud コンソールで、[Apigee] > [管理] > [環境] に移動します。
  2. [環境グループ] タブを選択します。
  3. 環境を含む環境グループを見つけて、[ホスト名] 列から値をコピーします。

テンプレートのベースパスを使用して、そのホスト名でプロキシを呼び出します。

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 はテンプレートをコンパイルするときに、各パラメータを次のように解決します。

  1. テンプレートの parameters リストに、同じ名前で空でない default を持つエントリがある場合、CLI はその値を使用します。
  2. それ以外の場合、CLI は対象物の default を使用します。
  3. どちらも値を設定しない場合、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 認証システムの使用をご覧ください。

  1. 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)を作成します。

  2. サービス アカウントに、呼び出すバックエンドへのアクセス権を付与します。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 を追加します。

  3. サービス アカウントに対するサービス アカウント トークン作成者のロール(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 プロダクトに関連付けられたデベロッパー アプリの認証情報です。公開の概要で説明されている次のタスクを完了します。

  1. 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 quota limit]、[LLM token quota limit]、オペレーションの [Quota]、[LLM Operations] セクションは空のままにします。プロキシの spike-arrest 機能により、レート制限が適用されます。
  2. アプリ デベロッパーを登録する。
  3. デベロッパー アプリを登録し、アプリの作成時に 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 キーを使用してリクエストを送信するをご覧ください。

次のステップ