Crea un proxy API da un modello YAML

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza Apigee Edge documentazione.

Questa pagina mostra come definire un proxy API come modello di funzionalità Apigee in YAML ed eseguirne il deployment con Google Cloud CLI. Per prima cosa crei un proxy semplice, poi un esempio più completo che si trova davanti a un modello Gemini.

Per informazioni di base, consulta Configurare un proxy con YAML. Per lo schema completo, consulta Riferimento per la configurazione YAML del proxy API.

Prima di iniziare

  • Abilita l'API Vertex AI nel tuo progetto Google Cloud in modo che il proxy possa comunicare con i modelli Gemini. 
    gcloud services enable aiplatform.googleapis.com
  • Installa e inizializza il Google Cloud CLI.
  • Per accedere ai comandi utilizzati in questo tutorial, installa il componente gcloud beta: 
    gcloud components install beta
  • Disponi di un'organizzazione Apigee e di almeno un ambiente. Prendi nota dei nomi dell'organizzazione e dell'ambiente; gli esempi utilizzano ORG e ENV come segnaposto. Il gateway AI nella Parte 2 richiede inoltre un ambiente Intermedio o Completo (non un ambiente Base); vedi Tipi di ambiente Apigee.
  • Assicurati di disporre delle autorizzazioni necessarie:
    • Per importare (creare) un proxy API: il ruolo Amministratore API (roles/apigee.apiAdmin) o un ruolo equivalente che concede apigee.proxies.create.
    • Per eseguire il deployment di un proxy API: Amministratore ambiente (roles/apigee.environmentAdmin) nell'ambiente di destinazione, e Lettore API (roles/apigee.apiReaderV2) a livello di progetto.
    • Per creare il prodotto API, lo sviluppatore e l'app che generano la chiave API in Parte 2, Passaggio 6: Amministratore API (roles/apigee.apiAdmin) e Amministratore sviluppatore (roles/apigee.developerAdmin). Per l'elenco completo dei ruoli, vedi Ruoli Apigee.

Parte 1: crea un proxy API semplice

In questa sezione crei un proxy che inoltra le richieste al servizio di destinazione simulato di Apigee e applica un limite di frequenza.

Passaggio 1: crea il modello

Un modello è il file di cui esegui il deployment. Definisce il percorso di base, le route e la destinazione di backend del proxy ed elenca le funzionalità da includere.

Crea una directory per il proxy, quindi crea un file denominato 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

Questo modello definisce:

  • Un endpoint con il percorso di base /hello. I client chiamano il proxy in questo percorso.
  • Una route che invia le richieste alla destinazione denominata default.
  • Una destinazione che rimanda all'URL di backend.
  • Una funzionalità, spike-arrest.yaml, che creerai nel passaggio successivo.

Passaggio 2: crea la funzionalità

Una funzionalità è un'unità di configurazione riutilizzabile che contiene le policy. Un modello non può contenere direttamente le policy, quindi la policy di limitazione della frequenza si trova in una funzionalità.

Nella stessa directory del modello, crea un file denominato 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}"

Questa funzionalità:

  • Definisce una policy SpikeArrest che limita il tasso di richieste.
  • Utilizza defaultEndpoint.flows per aggiungere la policy al PreFlow della richiesta, in modo che venga eseguita su ogni richiesta.
  • Dichiara un parametro, RATE, il cui valore predefinito (30ps) viene sostituito da {RATE} quando il proxy viene compilato.

Passaggio 3: importa il proxy

Importa il modello per creare una revisione del proxy API. Esegui questo comando dalla directory che contiene i file:

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

L'interfaccia a riga di comando compila il modello e la relativa funzionalità in un pacchetto del proxy API, lo carica e stampa la nuova revisione del proxy. L'importazione crea una revisione, ma non ne esegue il deployment.

Passaggio 4: esegui il deployment del proxy

Esegui il deployment della revisione in un ambiente:

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

Per impostazione predefinita, questo comando esegue il deployment dell'ultima revisione. Per eseguire il deployment di una revisione specifica, passa il relativo numero come primo argomento, ad esempio gcloud apigee apis deploy 1 --api=hello-proxy --environment=ENV. Se è già stato eseguito il deployment di un proxy diverso nello stesso percorso di base, aggiungi --override per sostituirlo senza tempi di inattività.

Passaggio 5: chiama il proxy

Per chiamare il proxy di cui è stato eseguito il deployment sulla rete, l'ambiente deve essere collegato a un gruppo di ambienti con un nome host instradabile. Se hai appena creato l'organizzazione, verifica che sia configurata prima di chiamare il proxy; vedi Informazioni sugli ambienti e sui gruppi di ambienti.

Trova il nome host di un gruppo di ambienti che contiene il tuo ambiente:

  1. Nella Google Cloud console, vai ad Apigee > Gestione > Ambienti.
  2. Seleziona la scheda Gruppi di ambienti.
  3. Trova il gruppo di ambienti che contiene il tuo ambiente e copia un valore dalla colonna Nomi host.

Chiama il proxy in quel nome host, utilizzando il percorso di base del modello:

curl https://HOSTNAME/hello

Sostituisci HOSTNAME con il nome host che hai copiato. Una risposta positiva proviene dal servizio di destinazione simulato.

Parte 2: crea un gateway AI per Gemini

Questa sezione crea un proxy più completo: un gateway AI che inoltra le richieste a un modello Gemini su Vertex AI, applica un limite di frequenza e richiede una chiave API. Utilizza un modello, tre funzionalità e un account di servizio.

A differenza del proxy semplice nella Parte 1, questo proxy chiama un servizio Google Cloud (Vertex AI). La funzionalità gemini-target utilizza auth: GoogleAccessToken, quindi Apigee allega un token OAuth di Google a ogni richiesta a Vertex AI. Questo token viene emesso per un service account che crei e fornisci quando esegui il deployment del proxy, quindi questa parte aggiunge un passaggio per creare il account di servizio (Passaggio 3).

Passaggio 1: crea il modello

Crea un file denominato 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

Passaggio 2: crea le funzionalità

Nella stessa directory, crea i tre file di funzionalità.

Riutilizza la funzionalità spike-arrest.yaml da Parte 1.

Crea verify-api-key.yaml per richiedere una chiave API nell'intestazione 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

Crea gemini-target.yaml per eseguire il routing a un modello Gemini, autenticato con un token di accesso 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

Sostituisci PROJECT_ID con l'ID progetto Google Cloud e REGION con la regione Vertex AI che stai utilizzando (ad esempio us-central1). Questa funzionalità utilizza auth: GoogleAccessToken in modo che Apigee alleghi un token di accesso Google a ogni richiesta a Vertex AI.

I modelli non sono disponibili in tutte le località e l'URL dipende dalla località utilizzata. L'URL precedente è il formato regionale, che funziona per un modello pubblicato da una regione specifica, ad esempio gemini-2.5-flash in us-central1. Altri modelli vengono pubblicati solo dall'endpoint globale, che utilizza un host diverso e locations/global:

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

Per trovare le località supportate da un modello, vedi Località di AI generativa su Vertex AI.

Passaggio 3: crea un account di servizio per il proxy

Poiché la funzionalità gemini-target utilizza auth: GoogleAccessToken, il proxy di cui è stato eseguito il deployment chiama Vertex AI come service account. Crea il account di servizio, concedigli l'accesso a Vertex AI e consenti all'agente di servizio Apigee di utilizzarlo. Fornisci questo service account quando esegui il deployment del proxy nel Passaggio 5. Per maggiori dettagli, vedi Utilizzare l'autenticazione Google.

  1. Crea un account di servizio gestito dall'utente nello stesso Google Cloud progetto dell' organizzazione Apigee. (Il account di servizio predefinito Compute Engine non è accettato.) Per altri modi per crearne uno, vedi Creare e gestire i service account. 
    gcloud iam service-accounts create SA_NAME \
    --project=PROJECT_ID \
    --display-name="Apigee AI gateway"

    Viene creato il account di servizio SA_NAME@PROJECT_ID.iam.gserviceaccount.com.

  2. Concedi al account di servizio l'accesso al backend che chiama. Per una destinazione Vertex AI, concedi il ruolo Utente 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"

    Se la policy IAM del progetto contiene già associazioni di ruoli condizionali, aggiungi --condition=None a questo comando.

  3. Consenti all'agente di servizio Apigee di generare token per il service account mediante la concessione del ruolo Creatore token account di servizio (roles/iam.serviceAccountTokenCreator) sul service account: 
    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"

    Per trovare PROJECT_NUMBER, esegui gcloud projects describe PROJECT_ID --format='value(projectNumber)'.

Passaggio 4: importa il proxy

Importa il modello per creare una revisione del proxy API:

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

Prendi nota del numero di revisione nell'output comando; ti servirà in Passaggio 5. Per stampare solo il numero di revisione, aggiungi --format="value(revision)" al comando di importazione.

Passaggio 5: esegui il deployment del proxy con il account di servizio

Il deployment del gateway AI differisce dal proxy semplice in Parte 1 in due modi:

  • Devi fornire il service account che hai creato in Passaggio 3. Se esegui il deployment senza un service account, il deployment non riesce e viene visualizzato l'erro0/}.MISSING_SERVICE_ACCOUNT
  • Devi eseguire il deployment in un ambiente intermedio o completo. Questo proxy utilizza una policy estensibile, che un ambiente Base non supporta; il deployment in un ambiente di questo tipo non riesce e viene visualizzato l'errore Extensible proxy can not be deployed to a base environment. Vedi Tipi di ambiente Apigee.

Interfaccia utente di Apigee: esegui il deployment del proxy e, quando ti viene chiesto di inserire un account di servizio, inserisci SA_NAME@PROJECT_ID.iam.gserviceaccount.com. Per i passaggi, vedi Eseguire il deployment di un proxy API.

API Deployment: chiama l' API Deployments, passando il account di servizio come serviceAccount parametro di query. Sostituisci REVISION con il numero di revisione del Passaggio 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"

La richiesta di deployment viene restituita immediatamente; il deployment è asincrono. Esegui il polling dello stato di deployment della revisione, che indica PROGRESSING finché non diventa 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"

Quando il proxy viene compilato, le funzionalità spike-arrest e verify-api-key aggiungono le relative policy al PreFlow della richiesta (prima limitazione di frequenza, poi il controllo della chiave API) e la funzionalità gemini-target aggiunge il backend Vertex AI. Al termine del deployment, il proxy esegue l'autenticazione a Vertex AI come account di servizio.

Passaggio 6: ottieni una chiave API

La funzionalità verify-api-key rifiuta qualsiasi richiesta che non contenga una chiave API valida, quindi devi avere una chiave prima di poter chiamare il proxy. Una chiave API è una credenziale di un' app per sviluppatori associata a un prodotto API contenente questo proxy. Completa le seguenti attività, che sono descritte in Panoramica della pubblicazione:

  1. Crea un prodotto API che includa il proxy ai-gateway e l'ambiente in cui hai eseguito il deployment.
  2. Registra uno sviluppatore di app.
  3. Registra un'app per sviluppatori associata a questo prodotto API.

La registrazione dell'app genera la chiave. Per recuperarla, vedi Visualizzare una chiave API e un secret.

Passaggio 7: chiama il proxy

Trova il nome host del gruppo di ambienti come descritto in Passaggio 5 della Parte 1, quindi chiama il proxy nel percorso di base /v1/gemini. Passa la chiave API nell'intestazione x-api-key, e invia un corpo della richiesta GeminigenerateContent:

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

Sostituisci HOSTNAME con il nome host del gruppo di ambienti e API_KEY con la chiave del Passaggio 6. Una risposta positiva è l'output JSON del modello. Se ometti la chiave, viene restituito un errore di autorizzazione dalla policy VerifyAPIKey, che conferma che la funzionalità verify-api-key è attiva. Per altri modi per passare una chiave, vedi Inviare una richiesta con una chiave API valida.

Passaggi successivi