Membuat proxy API dari template YAML

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Halaman ini menunjukkan cara menentukan proxy API sebagai Template Fitur Apigee dalam YAML dan men-deploy-nya dengan Google Cloud CLI. Anda akan membangun proxy sederhana terlebih dahulu, lalu membangun contoh yang lebih lengkap yang mengedepankan model Gemini.

Untuk mengetahui latar belakangnya, lihat Mengonfigurasi proxy dengan YAML. Untuk skema lengkap, lihat Referensi konfigurasi YAML proxy API.

Sebelum memulai

  • Khusus untuk Bagian 2: aktifkan Agent Platform API di project Google Cloud yang menghosting model:

    gcloud services enable aiplatform.googleapis.com \
        --project=PROJECT_ID

    Ganti PROJECT_ID dengan ID project yang menghosting model, misalnya my-apigee-project. Panduan ini menggunakan project organisasi Apigee Anda. Bagian 1 tidak memerlukan API ini. Anda tidak perlu memilih region, karena template menggunakan endpoint global. Mungkin perlu waktu beberapa saat hingga API aktif setelah Anda mengaktifkannya.

  • Instal dan lakukan inisialisasi pada Google Cloud CLI.
  • Memiliki organisasi Apigee dan setidaknya satu lingkungan. Perhatikan nama organisasi dan lingkungan; contoh menggunakan ORG dan ENV sebagai placeholder (lihat Placeholder yang digunakan di halaman ini). Gateway AI di Bagian 2 juga memerlukan lingkungan Intermediate atau Comprehensive (bukan lingkungan Base); lihat Jenis lingkungan Apigee.
  • Pastikan Anda memiliki izin yang diperlukan:
    • Untuk mengimpor (membuat) proxy API: peran API Admin (roles/apigee.apiAdmin), atau peran setara yang memberikan apigee.proxies.create.
    • Untuk men-deploy proxy API: Environment Admin (roles/apigee.environmentAdmin) di lingkungan target, dan API Reader (roles/apigee.apiReaderV2) di level project.
    • Untuk membuat produk API, developer, dan aplikasi yang menghasilkan kunci API di Bagian 2, Langkah 6: Admin API (roles/apigee.apiAdmin) dan Admin Developer (roles/apigee.developerAdmin). Untuk daftar lengkap peran, lihat Peran Apigee.

Placeholder yang digunakan di halaman ini

Ganti setiap placeholder dalam perintah dengan nilai Anda sendiri. Sebagian besar nilai sudah ada dan Anda mencarinya. Anda memilih sendiri SA_NAME, dan beberapa nilai akan dibuat saat Anda melakukan langkah-langkahnya.

Placeholder Sumber Deskripsi
ORG Cari Nama organisasi Apigee Anda. Nilai ini biasanya sama dengan PROJECT_ID. Untuk mencantumkan organisasi yang dapat Anda akses, jalankan gcloud apigee organizations list.
ENV Cari Lingkungan di organisasi Anda, misalnya test. Bagian 1, Langkah 4 menunjukkan cara mencantumkannya.
PROJECT_ID Cari ID project Google Cloud yang menyimpan organisasi Apigee Anda, misalnya my-apigee-project. Untuk mencetak project aktif, jalankan gcloud config get project.
HOSTNAME Cari Nama host grup lingkungan yang berisi ENV, misalnya api.example.com. Bagian 1, Langkah 5 menunjukkan tempat untuk menemukannya.
SA_NAME Anda memilih Nama untuk akun layanan yang Anda buat di Bagian 2, Langkah 3, misalnya apigee-ai-gateway.
PROJECT_NUMBER Cari Nomor project PROJECT_ID, misalnya 123456789012. Bagian 2, Langkah 3 menunjukkan perintah yang mencetaknya.
REGION Anda memilih Opsional. Region yang menyajikan model Anda, misalnya us-central1. Anda hanya memerlukannya jika mengalihkan fitur gemini-target ke endpoint regional.
REVISION Dibuat Nomor revisi proxy yang dicetak oleh perintah impor di Bagian 2, Langkah 4, misalnya 1.
API_KEY Dibuat Kunci API yang dihasilkan Apigee saat Anda mendaftarkan aplikasi developer di Bagian 2, Langkah 6.

Bagian 1: Membuat proxy API sederhana

Di bagian ini, Anda akan membuat proxy yang meneruskan permintaan ke layanan target tiruan Apigee dan menerapkan pembatasan kapasitas.

Langkah 1: Buat template

Template adalah file yang Anda deploy. File ini menentukan jalur dasar, rute, dan target backend proxy Anda, serta mencantumkan fitur yang akan disertakan.

Buat direktori project untuk template Anda, dengan subdirektori features untuk fitur yang digunakan:

mkdir -p proxy-templates/features
cd proxy-templates

Setelah Anda menyelesaikan bagian ini, direktori project akan terlihat seperti ini:

proxy-templates/
  hello-proxy.yaml
  features/
    spike-arrest.yaml

Di direktori proxy-templates, buat file bernama 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

Template ini menentukan:

  • Endpoint dengan jalur dasar /hello. Klien memanggil proxy di jalur ini.
  • Rute yang mengirim permintaan ke target bernama default.
  • Target yang mengarah ke URL backend.
  • Fitur, spike-arrest.yaml, yang akan Anda buat berikutnya.

Langkah 2: Buat fitur

Fitur adalah unit konfigurasi yang dapat digunakan kembali dan menyimpan kebijakan. Template tidak dapat berisi kebijakan secara langsung, sehingga kebijakan pembatasan kapasitas berada dalam fitur.

Di direktori features, buat file bernama 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}"

Fitur ini:

  • Menentukan kebijakan SpikeArrest yang membatasi rasio permintaan.
  • Menggunakan defaultEndpoint.flows untuk menambahkan kebijakan ke PreFlow permintaan, sehingga kebijakan tersebut berjalan pada setiap permintaan.
  • Mendeklarasikan parameter, RATE, yang default-nya (30ps) diganti dengan {RATE} saat proxy dikompilasi.

Langkah 3: Impor proxy

Impor template untuk membuat revisi proxy API. Jalankan perintah ini dari direktori proxy-templates, yang berisi template:

gcloud apigee apis import hello-proxy \
    --from-template=hello-proxy.yaml \
    --organization=ORG

CLI mengompilasi template dan fiturnya ke dalam paket proxy API, menguploadnya, dan mencetak revisi proxy baru. Pengimporan akan membuat revisi, tetapi tidak men-deploy-nya.

Langkah 4: Men-deploy proxy

Cantumkan lingkungan di organisasi Anda:

gcloud apigee environments list --organization=ORG

Perintah ini akan mencetak nama lingkungan. Pilih satu untuk digunakan sebagai ENV, dan deploy revisi ke sana:

gcloud apigee apis deploy \
    --api=hello-proxy \
    --environment=ENV \
    --organization=ORG

Secara default, perintah ini men-deploy revisi terbaru. Untuk men-deploy revisi tertentu, teruskan nomornya sebagai argumen pertama, misalnya gcloud apigee apis deploy 1 --api=hello-proxy --environment=ENV. Jika proxy lain sudah di-deploy di jalur dasar yang sama, tambahkan --override untuk menggantinya tanpa periode nonaktif.

Langkah 5: Panggil proxy

Untuk memanggil proxy yang di-deploy melalui jaringan, lingkungan Anda harus dilampirkan ke grup lingkungan yang memiliki nama host yang dapat dirutekan. Jika Anda baru saja membuat organisasi, pastikan hal ini sudah disiapkan sebelum Anda memanggil proxy; lihat Tentang lingkungan dan grup lingkungan.

Temukan nama host grup lingkungan yang berisi lingkungan Anda:

  1. Di konsol Google Cloud , buka Apigee > Management > Environments.
  2. Pilih tab Environment groups.
  3. Temukan grup lingkungan yang berisi lingkungan Anda, dan salin nilai dari kolom Hostnames.

Panggil proxy di nama host tersebut, menggunakan jalur dasar dari template Anda:

curl https://HOSTNAME/hello

Ganti HOSTNAME dengan nama host yang Anda salin. Respons yang berhasil berasal dari layanan target tiruan.

Bagian 2: Membangun gateway AI untuk Gemini

Bagian ini membangun proxy yang lebih lengkap: gateway AI yang meneruskan permintaan ke model Gemini di Gemini Enterprise Agent Platform, menerapkan pembatasan kapasitas, dan memerlukan kunci API. Solusi ini menggunakan satu template, tiga fitur, dan satu akun layanan.

Tidak seperti proxy sederhana di Bagian 1, proxy ini memanggil layanan Google Cloud (Agent Platform). Fitur gemini-target menggunakan auth: GoogleAccessToken, sehingga Apigee melampirkan token Google OAuth ke setiap permintaan ke Agent Platform. Token tersebut dikeluarkan untuk akun layanan yang Anda buat, lalu berikan saat Anda men-deploy proxy, sehingga bagian ini menambahkan langkah untuk membuat akun layanan tersebut (Langkah 3).

Sebelum memulai, pastikan Agent Platform API diaktifkan di project yang menghosting model, seperti yang dijelaskan dalam Sebelum memulai. Anda tidak perlu menggunakan Agent Platform sebelumnya.

Di Bagian 2, PROJECT_ID adalah ID project organisasi Apigee Anda, misalnya my-apigee-project. Bagian 2 menggunakan satu project ini secara keseluruhan: Anda mengaktifkan API di dalamnya, membuat akun layanan di dalamnya, dan menetapkannya sebagai nilai MODEL_PROJECT_ID template.

Langkah 1: Buat template

Di direktori proxy-templates dari Bagian 1, buat file bernama 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

Daftar parameters menetapkan nilai untuk parameter yang dideklarasikan oleh fitur gemini-target, yang Anda buat di langkah berikutnya. Ganti PROJECT_ID dengan project ID yang Anda gunakan untuk mengaktifkan API, misalnya my-apigee-project.

Langkah 2: Buat fitur

Template ini menggunakan tiga fitur. Gunakan kembali fitur spike-arrest.yaml dari Bagian 1, dan buat dua fitur lainnya di direktori features. Setelah Anda menyelesaikan langkah ini, direktori project akan terlihat seperti ini:

proxy-templates/
  hello-proxy.yaml
  ai-gateway.yaml
  features/
    spike-arrest.yaml
    verify-api-key.yaml
    gemini-target.yaml

Buat features/verify-api-key.yaml untuk mewajibkan kunci API di header x-api-key:

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

Buat features/gemini-target.yaml untuk merutekan ke model Gemini, yang diautentikasi dengan token akses Google:

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

Fitur gemini-target mendeklarasikan dua parameter dan menggantinya ke URL target:

  • MODEL_PROJECT_ID: project Google Cloud yang menghosting model. Variabel ini tidak memiliki default, sehingga template harus menetapkannya ke project ID Anda.
  • MODEL: model Gemini yang akan dipanggil. Default fitur ini adalah gemini-3.8-flash.

Saat mengompilasi template, CLI akan me-resolve setiap parameter sebagai berikut:

  1. Jika daftar parameters template memiliki entri dengan nama yang sama dan default yang tidak kosong, CLI akan menggunakan nilai tersebut.
  2. Jika tidak, CLI akan menggunakan default fitur.
  3. Jika tidak ada yang menetapkan nilai, CLI akan mengganti {name} dengan string kosong. Impor tidak melaporkan error, sehingga MODEL_PROJECT_ID yang tidak ada akan menghasilkan URL target tanpa project ID.

Tidak ada tanda command line untuk menetapkan nilai parameter saat Anda mengimpor. Untuk menggunakan project atau model lain, edit nilainya dalam daftar parameters template dan impor template lagi.

Fitur gemini-target menggunakan auth: GoogleAccessToken sehingga Apigee melampirkan token akses Google ke setiap permintaan ke Agent Platform.

URL menggunakan endpoint global (host aiplatform.googleapis.com dan locations/global), yang menyajikan gemini-3.8-flash dan merutekan permintaan ke kapasitas yang tersedia di seluruh region. Dengan endpoint global, Anda tidak perlu memilih region.

Untuk memanggil model yang berbeda, tetapkan MODEL dalam daftar parameters template ke ID model. Untuk mencantumkan model Gemini yang dapat Anda panggil, jalankan:

gcloud ai model-garden models list --model-filter=gemini

Setiap nilai dalam kolom MODEL_ID terlihat seperti google/gemini-3.8-flash@default. Tetapkan MODEL ke bagian antara google/ dan @, seperti gemini-4-argon. Kartu model di Model Garden di konsolGoogle Cloud menunjukkan ID yang sama. Untuk memeriksa apakah model mendukung endpoint global, lihat tab Global di Lokasi endpoint model Google.

Jika Anda perlu mengontrol region mana yang memproses permintaan, ganti baris url di features/gemini-target.yaml dengan bentuk regional, yang menempatkan region di host dan jalur:

  url: https://REGION-aiplatform.googleapis.com/v1/projects/{MODEL_PROJECT_ID}/locations/REGION/publishers/google/models/{MODEL}:generateContent

Ganti REGION dengan region yang menyajikan model Anda, seperti yang tercantum dalam tabel lokasi endpoint model Google yang sama. Untuk mengetahui kapan harus menghindari endpoint global, lihat Endpoint global.

Langkah 3: Buat akun layanan untuk proxy

Karena fitur gemini-target menggunakan auth: GoogleAccessToken, proxy yang di-deploy akan memanggil Agent Platform sebagai akun layanan. Buat akun layanan tersebut, beri akses ke Agent Platform, dan izinkan agen layanan Apigee menggunakannya. Anda memberikan akun layanan ini saat men-deploy proxy di Langkah 5. Untuk mengetahui detail selengkapnya, lihat Menggunakan autentikasi Google.

  1. Buat akun layanan yang dikelola pengguna di project Google Cloud yang sama dengan organisasi Apigee Anda. (Akun layanan default Compute Engine tidak diterima.) Untuk mengetahui cara lain dalam membuatnya, lihat Membuat dan mengelola akun layanan.
    gcloud iam service-accounts create SA_NAME \
        --project=PROJECT_ID \
        --display-name="Apigee AI gateway"

    Pilih nama deskriptif untuk SA_NAME, misalnya apigee-ai-gateway. Perintah ini membuat akun layanan SA_NAME@PROJECT_ID.iam.gserviceaccount.com, misalnya apigee-ai-gateway@my-apigee-project.iam.gserviceaccount.com.

  2. Beri akun layanan akses ke backend yang dipanggilnya. Untuk target Agent Platform, berikan peran Agent Platform User (roles/aiplatform.user):
    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member="serviceAccount:SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
        --role="roles/aiplatform.user"

    Jika kebijakan IAM project Anda sudah berisi binding peran bersyarat, tambahkan --condition=None ke perintah ini.

  3. Izinkan agen layanan Apigee membuat token untuk akun layanan dengan memberinya peran Service Account Token Creator (roles/iam.serviceAccountTokenCreator) di akun layanan:
    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"

    Untuk menemukan PROJECT_NUMBER, jalankan gcloud projects describe PROJECT_ID --format='value(projectNumber)'.

Langkah 4: Impor proxy

Impor template untuk membuat revisi proxy API. Jalankan perintah ini dari direktori proxy-templates, yang berisi template:

gcloud apigee apis import ai-gateway \
    --from-template=ai-gateway.yaml \
    --organization=ORG

Catat nomor revisi dalam output perintah; Anda memerlukannya di Langkah 5. Untuk mencetak nomor revisi saja, tambahkan --format="value(revision)" ke perintah impor.

Langkah 5: Deploy proxy dengan akun layanan

Men-deploy gateway AI berbeda dengan proxy sederhana di Bagian 1 dalam dua hal:

  • Anda harus memberikan akun layanan yang Anda buat di Langkah 3. Jika Anda men-deploy tanpa akun layanan, deployment akan gagal dengan error MISSING_SERVICE_ACCOUNT.
  • Anda harus men-deploy ke lingkungan Menengah atau Komprehensif. Proxy ini menggunakan kebijakan yang dapat diperluas, yang tidak didukung oleh lingkungan Base; deployment ke lingkungan tersebut akan gagal dengan error Extensible proxy can not be deployed to a base environment. Perintah gcloud apigee environments list tidak mencetak jenis lingkungan. Untuk memeriksanya, di konsol Google Cloud , buka Apigee > Management > Environments. Lihat Jenis lingkungan Apigee.

UI Apigee: deploy proxy dan, saat diminta untuk memasukkan akun layanan, masukkan SA_NAME@PROJECT_ID.iam.gserviceaccount.com. Untuk mengetahui langkah-langkahnya, lihat Men-deploy proxy API.

Deployment API: panggil deployments API, dengan meneruskan akun layanan sebagai parameter kueri serviceAccount. Ganti REVISION dengan nomor revisi dari Langkah 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"

Permintaan deployment akan segera ditampilkan; deployment bersifat asinkron. Lakukan polling pada status deployment revisi, yang melaporkan PROGRESSING hingga menjadi READY:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/ai-gateway/revisions/REVISION/deployments"

Saat proxy dikompilasi, fitur spike-arrest dan verify-api-key menambahkan kebijakannya ke PreFlow permintaan (pembatasan kapasitas terlebih dahulu, lalu pemeriksaan kunci API), dan fitur gemini-target menambahkan backend Agent Platform. Setelah deployment selesai, proxy akan melakukan autentikasi ke Agent Platform sebagai akun layanan Anda.

Langkah 6: Mendapatkan kunci API

Fitur verify-api-key menolak permintaan apa pun yang tidak memiliki kunci API yang valid, jadi Anda memerlukan kunci sebelum dapat memanggil proxy. Kunci API adalah kredensial aplikasi developer yang terkait dengan produk API yang berisi proxy ini. Selesaikan tugas-tugas berikut, yang dijelaskan dalam Ringkasan publikasi:

  1. Buat produk API yang menyertakan proxy ai-gateway. Di formulir produk, masukkan hal berikut, lalu klik Save:
    • Nama dan Nama tampilan: nilai apa pun, misalnya ai-gateway-product.
    • Lingkungan: lingkungan tempat Anda men-deploy proxy (ENV).
    • Akses: Publik. Biarkan Automatically approve access requests dipilih agar kunci API disetujui saat Anda mendaftarkan aplikasi.
    • Di bagian Operations, klik + ADD AN OPERATION dan tetapkan kolom berikut:
      • Proxy API: ai-gateway.
      • Path: /. Permintaan mengarah ke jalur dasar proxy, /v1/gemini, tanpa ada apa pun setelahnya. Jalur / cocok dengan jalur dasar; /** hanya cocok dengan jalur di bawahnya, sehingga permintaan ke /v1/gemini gagal dengan error oauth.v2.InvalidApiKeyForGivenResource. Lihat Mengonfigurasi jalur resource.
      • Metode: POST.
    • Kosongkan API quota limit, LLM token quota limit, Quota operasi, dan bagian LLM Operations. Fitur spike-arrest di proxy menerapkan pembatasan kapasitas.
  2. Mendaftarkan developer aplikasi.
  3. Daftarkan aplikasi developer dan pilih produk API saat Anda membuat aplikasi, sehingga kunci baru dikaitkan dengan produk sejak awal.

Mendaftarkan aplikasi akan menghasilkan kunci. Untuk mengambilnya, lihat Melihat kunci dan rahasia API.

Langkah 7: Panggil proxy

Temukan nama host grup lingkungan Anda seperti yang dijelaskan di Bagian 1, Langkah 5, lalu panggil proxy di jalur dasar /v1/gemini. Teruskan kunci API di header x-api-key, dan kirim isi permintaan generateContent Gemini:

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."}]}]}'

Ganti HOSTNAME dengan nama host grup lingkungan Anda dan API_KEY dengan kunci dari Langkah 6. Respons yang berhasil adalah output JSON model. Jika kunci dihilangkan, kegagalan otorisasi akan ditampilkan dari kebijakan VerifyAPIKey, yang mengonfirmasi bahwa fitur verify-api-key berlaku. Untuk cara lain meneruskan kunci, lihat Mengirimkan permintaan dengan kunci API yang valid.

Langkah berikutnya