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_IDGanti 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 memberikanapigee.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.
- Untuk mengimpor (membuat) proxy API: peran API Admin
(
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.flowsuntuk 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=ORGCLI 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=ORGSecara 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:
- Di konsol Google Cloud , buka Apigee > Management > Environments.
- Pilih tab Environment groups.
- 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 adalahgemini-3.8-flash.
Saat mengompilasi template, CLI akan me-resolve setiap parameter sebagai berikut:
- Jika daftar
parameterstemplate memiliki entri dengan nama yang sama dandefaultyang tidak kosong, CLI akan menggunakan nilai tersebut. - Jika tidak, CLI akan menggunakan
defaultfitur. - Jika tidak ada yang menetapkan nilai, CLI akan mengganti
{name}dengan string kosong. Impor tidak melaporkan error, sehinggaMODEL_PROJECT_IDyang 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.
- 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 layananSA_NAME@PROJECT_ID.iam.gserviceaccount.com, misalnyaapigee-ai-gateway@my-apigee-project.iam.gserviceaccount.com. - 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=Noneke perintah ini. - 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=ORGCatat 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
. Perintahgcloud apigee environments listtidak 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:
- 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/geminigagal dengan erroroauth.v2.InvalidApiKeyForGivenResource. Lihat Mengonfigurasi jalur resource. - Metode:
POST.
- Proxy API:
- Kosongkan API quota limit, LLM token quota limit, Quota operasi, dan bagian LLM Operations.
Fitur
spike-arrestdi proxy menerapkan pembatasan kapasitas.
- Nama dan Nama tampilan: nilai apa pun, misalnya
- Mendaftarkan developer aplikasi.
- 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
- Referensi konfigurasi YAML proxy API
- Mengonfigurasi proxy dengan YAML
- Men-deploy proxy API
- Ringkasan publikasi