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 membuat proxy sederhana terlebih dahulu, lalu membuat contoh yang lebih lengkap yang menggunakan model Gemini.

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

Sebelum memulai

  • Aktifkan Vertex AI API di project Google Cloud Anda agar proxy dapat berkomunikasi dengan model Gemini. 
    gcloud services enable aiplatform.googleapis.com
  • Instal dan lakukan inisialisasi Google Cloud CLI.
  • Untuk mengakses perintah yang digunakan dalam tutorial ini, instal komponen gcloud beta: 
    gcloud components install beta
  • Memiliki organisasi Apigee dan minimal satu lingkungan. Catat nama organisasi dan lingkungan; contohnya menggunakan ORG dan ENV sebagai placeholder. Gateway AI di Bagian 2 juga memerlukan lingkungan Menengah atau Komprehensif (bukan lingkungan Dasar); lihat jenis lingkungan Apigee.
  • Pastikan Anda memiliki izin yang diperlukan:
    • Untuk mengimpor (membuat) proxy API: peran API Admin (roles/apigee.apiAdmin), atau peran yang setara yang memberikan apigee.proxies.create.
    • Untuk men-deploy proxy API: Admin Lingkungan (roles/apigee.environmentAdmin) di lingkungan target, dan Pembaca API (roles/apigee.apiReaderV2) di tingkat 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.

Bagian 1: Membuat proxy API sederhana

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

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 untuk proxy Anda, lalu 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:
- 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 selanjutnya.

Langkah 2: Buat fitur

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

Di direktori yang sama dengan template, 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 permintaan PreFlow, sehingga berjalan di setiap permintaan.
  • Mendeklarasikan parameter, RATE, yang default-nya (30ps) digantikan dengan {RATE} saat proxy dikompilasi.

Langkah 3: Impor proxy

Impor template untuk membuat revisi proxy API. Jalankan perintah ini dari direktori yang berisi file Anda:

gcloud beta 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. Mengimpor akan membuat revisi, tetapi tidak men-deploy-nya.

Langkah 4: Deploy proxy

Deploy revisi ke lingkungan:

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 waktu henti.

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 organisasi ini 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 Grup lingkungan.
  3. Temukan grup lingkungan yang berisi lingkungan Anda, lalu salin nilai dari kolom Nama host-nya.

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 Vertex AI, menerapkan batas frekuensi, dan memerlukan kunci API. Aplikasi ini menggunakan satu template, tiga fitur, dan akun layanan.

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

Langkah 1: Buat template

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:
- spike-arrest.yaml
- verify-api-key.yaml
- gemini-target.yaml
endpoints:
- name: gemini
  basePath: /v1/gemini
  routes:
  - name: default
    target: gemini

Langkah 2: Buat fitur

Di direktori yang sama, buat tiga file fitur.

Gunakan kembali fitur spike-arrest.yaml dari Bagian 1.

Buat 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 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 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

Ganti PROJECT_ID dengan project ID Google Cloud Anda, dan REGION dengan region Vertex AI yang Anda gunakan (seperti us-central1). Fitur ini menggunakan auth: GoogleAccessToken sehingga Apigee melampirkan token akses Google ke setiap permintaan ke Vertex AI.

Model tidak tersedia di setiap lokasi, dan URL bergantung pada lokasi yang Anda gunakan. URL sebelumnya adalah bentuk regional, yang berfungsi untuk model yang ditayangkan dari region tertentu, seperti gemini-2.5-flash di us-central1. Model lainnya hanya ditayangkan dari endpoint global, yang menggunakan host dan locations/global yang berbeda:

  url: https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/MODEL:generateContent

Untuk menemukan lokasi yang didukung model, lihat Lokasi AI Generatif di Vertex AI.

Langkah 3: Buat akun layanan untuk proxy

Karena fitur gemini-target menggunakan auth: GoogleAccessToken, proxy yang di-deploy memanggil Vertex AI sebagai akun layanan. Buat akun layanan tersebut, beri akun layanan tersebut akses ke Vertex AI, 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 Google Cloud project yang sama dengan organisasi Apigee Anda. (Akun layanan default Compute Engine tidak diterima.) Untuk mengetahui cara lain dalam membuat akun layanan, lihat Membuat dan mengelola akun layanan. 
    gcloud iam service-accounts create SA_NAME \
    --project=PROJECT_ID \
    --display-name="Apigee AI gateway"

    Tindakan ini akan membuat akun layanan SA_NAME@PROJECT_ID.iam.gserviceaccount.com.

  2. Beri akun layanan akses ke backend yang dipanggilnya. Untuk target Vertex AI, berikan peran Vertex AI 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 memberikan peran Service Account Token Creator (roles/iam.serviceAccountTokenCreator) kepadanya 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:

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

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

Langkah 5: Deploy proxy dengan akun layanan

Penerapan 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 salah satunya, deployment akan gagal dengan error MISSING_SERVICE_ACCOUNT.
  • Anda harus men-deploy ke lingkungan Menengah atau Komprehensif. Proxy ini menggunakan kebijakan yang dapat di-extend, yang tidak didukung oleh lingkungan Dasar; deployment ke lingkungan tersebut akan gagal dengan error Extensible proxy can not be deployed to a base environment. Lihat Jenis lingkungan Apigee.

UI Apigee: deploy proxy dan, saat diminta 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 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 kecepatan terlebih dahulu, lalu pemeriksaan kunci API), dan fitur gemini-target menambahkan backend Vertex AI. Setelah deployment selesai, proxy melakukan autentikasi ke Vertex AI sebagai akun layanan Anda.

Langkah 6: Dapatkan kunci API

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

  1. Buat produk API yang menyertakan proxy ai-gateway dan lingkungan tempat Anda men-deploy-nya.
  2. Mendaftarkan developer aplikasi.
  3. Daftarkan aplikasi developer yang terkait dengan produk API tersebut.

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

Langkah 7: Panggil proxy

Temukan nama host grup lingkungan Anda seperti yang dijelaskan dalam 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. Menghilangkan kunci akan menampilkan kegagalan otorisasi dari kebijakan VerifyAPIKey, yang mengonfirmasi bahwa fitur verify-api-key berlaku. Untuk cara lain dalam meneruskan kunci, lihat bagian Mengirimkan permintaan dengan kunci API yang valid.

Langkah berikutnya