Crea un proxy API da un modello YAML

Questa pagina si applica ad Apigee e ad Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

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, creerai un proxy semplice, poi un esempio completo che si interfaccia con un modello Gemini.

Per informazioni di base, consulta Configurazione di un proxy con YAML. Per lo schema completo, consulta il riferimento alla configurazione YAML del proxy API.

Prima di iniziare

  • Solo per la Parte 2: abilita l'API Agent Platform nel progetto Google Cloud che ospita il modello:

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

    Sostituisci PROJECT_ID con l'ID del progetto che ospita il modello, ad esempio my-apigee-project. Questa procedura dettagliata utilizza il progetto della tua organizzazione Apigee. La Parte 1 non richiede questa API. Non è necessario scegliere una regione, perché il template utilizza l'endpoint globale. Potrebbe essere necessario un po' di tempo prima che l'API diventi attiva dopo averla abilitata.

  • Installa e inizializza Google Cloud CLI.
  • Avere un'organizzazione Apigee e almeno un ambiente. Prendi nota dei nomi dell'organizzazione e dell'ambiente; gli esempi utilizzano ORG e ENV come segnaposto (vedi Segnaposto utilizzati in questa pagina). Il gateway AI nella Parte 2 richiede inoltre un ambiente Intermedio o Completo (non un ambiente Base); consulta 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: Environment Admin (roles/apigee.environmentAdmin) nell'ambiente di destinazione e API Reader (roles/apigee.apiReaderV2) a livello di progetto.
    • Per creare il prodotto API, lo sviluppatore e l'app che generano la chiave API nella Parte 2, Passaggio 6: Amministratore API (roles/apigee.apiAdmin) e Amministratore sviluppatore (roles/apigee.developerAdmin). Per l'elenco completo dei ruoli, consulta Ruoli Apigee.

Segnaposto utilizzati in questa pagina

Sostituisci ogni segnaposto nei comandi con il tuo valore. La maggior parte dei valori esiste già e tu li cerchi. Scegli tu SA_NAME, mentre alcuni valori vengono generati man mano che procedi con i passaggi.

Segnaposto Origine Descrizione
ORG Cerca Il nome della tua organizzazione Apigee. In genere, è uguale a PROJECT_ID. Per elencare le organizzazioni a cui puoi accedere, esegui gcloud apigee organizations list.
ENV Cerca Un ambiente della tua organizzazione, ad esempio test. La Parte 1, Passaggio 4 mostra come elencarle.
PROJECT_ID Cerca L'ID del progetto Google Cloud che contiene la tua organizzazione Apigee, ad esempio my-apigee-project. Per stampare il progetto attivo, esegui gcloud config get project.
HOSTNAME Cerca Un nome host di un gruppo di ambienti che contiene ENV, ad esempio api.example.com. Parte 1, passaggio 5 mostra dove trovarlo.
SA_NAME Scegli tu Un nome per il account di servizio che crei nella Parte 2, passaggio 3, ad esempio apigee-ai-gateway.
PROJECT_NUMBER Cerca Il numero di progetto di PROJECT_ID, ad esempio 123456789012. Parte 2, passaggio 3 mostra il comando che lo stampa.
REGION Scegli tu Facoltativo. Una regione che gestisce il modello, ad esempio us-central1. È necessario solo se passi dalla funzionalità gemini-target a un endpoint regionale.
REVISION Generato Il numero di revisione del proxy stampato dal comando di importazione nella Parte 2, passaggio 4, ad esempio 1.
API_KEY Generato La chiave API generata da Apigee quando registri un'app per sviluppatori nella Parte 2, passaggio 6.

Parte 1: crea un proxy API semplice

In questa sezione, creerai un proxy che inoltra le richieste al servizio di destinazione fittizio di Apigee e applica la limitazione di frequenza.

Passaggio 1: crea il modello

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

Crea una directory di progetto per i template, con una sottodirectory features per le funzionalità che utilizzano:

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

Al termine di questa parte, la directory del progetto avrà il seguente aspetto:

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

Nella directory proxy-templates, 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:
- ./features/spike-arrest.yaml
endpoints:
- name: default
  basePath: /hello
  routes:
  - name: default
    target: default
targets:
- name: default
  url: https://mocktarget.apigee.net

Questo template definisce:

  • Un endpoint con il percorso di base /hello. I client chiamano il proxy in questo percorso.
  • Una route che invia richieste alla destinazione denominata default.
  • Una destinazione che punta all'URL di backend.
  • Una caratteristica, spike-arrest.yaml, che creerai in seguito.

Passaggio 2: crea la funzionalità

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

Nella directory features, 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 proxy-templates, che contiene il template:

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

La CLI compila il modello e la relativa funzionalità in un bundle di 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

Elenca gli ambienti della tua organizzazione:

gcloud apigee environments list --organization=ORG

Il comando stampa i nomi degli ambienti. Scegline uno da utilizzare come ENV ed esegui il deployment della revisione:

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 un altro proxy è già stato distribuito 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 la tua organizzazione, verifica che sia configurata prima di chiamare il proxy. Consulta Informazioni su ambienti e gruppi di ambienti.

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

  1. Nella console Google Cloud , vai ad Apigee > Gestione > Ambienti.
  2. Seleziona la scheda Gruppi di ambienti.
  3. Trova il gruppo di ambiente 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 tuo modello:

curl https://HOSTNAME/hello

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

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 Gemini Enterprise Agent Platform, applica la limitazione di frequenza e richiede una chiave API. Utilizza un template, tre funzionalità e un account di servizio.

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

Prima di iniziare, assicurati che l'API Agent Platform sia abilitata nel progetto che ospita il modello, come descritto in Prima di iniziare. Non è necessario aver utilizzato Agent Platform in precedenza.

Nella Parte 2, PROJECT_ID è l'ID del progetto della tua organizzazione Apigee, ad esempio my-apigee-project. La Parte 2 utilizza questo progetto in tutto il processo: abiliti l'API, crei l'account di servizio e lo imposti come valore MODEL_PROJECT_ID del template.

Passaggio 1: crea il modello

Nella directory proxy-templates della Parte 1, 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:
- ./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

L'elenco parameters imposta i valori per i parametri dichiarati dalla funzionalità gemini-target, che creerai nel passaggio successivo. Sostituisci PROJECT_ID con l'ID progetto che hai utilizzato per abilitare l'API, ad esempio my-apigee-project.

Passaggio 2: crea le caratteristiche

Il modello utilizza tre caratteristiche. Riutilizza la caratteristica spike-arrest.yaml della Parte 1 e crea le altre due nella directory features. Al termine di questo passaggio, la directory del progetto avrà il seguente aspetto:

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

Crea features/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 features/gemini-target.yaml per 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 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

La funzionalità gemini-target dichiara due parametri e li sostituisce nell'URL di destinazione:

  • MODEL_PROJECT_ID: il progetto Google Cloud che ospita il modello. Non ha un valore predefinito, quindi il template deve impostarlo sul tuo ID progetto.
  • MODEL: il modello Gemini da chiamare. Il valore predefinito della funzionalità è gemini-3.8-flash.

Quando l'interfaccia a riga di comando compila il template, risolve ogni parametro come segue:

  1. Se l'elenco parameters del template contiene una voce con lo stesso nome e un default non vuoto, l'interfaccia a riga di comando utilizza questo valore.
  2. In caso contrario, l'interfaccia a riga di comando utilizza il valore default della funzionalità.
  3. Se nessuna delle due imposta un valore, l'interfaccia a riga di comando sostituisce {name} con una stringa vuota. L'importazione non segnala un errore, quindi un MODEL_PROJECT_ID mancante produce un URL di destinazione senza ID progetto.

Non esiste un flag della riga di comando per impostare i valori dei parametri durante l'importazione. Per utilizzare un progetto o un modello diverso, modifica il valore nell'elenco parameters del modello e importa di nuovo il modello.

La funzionalità gemini-target utilizza auth: GoogleAccessToken in modo che Apigee alleghi un token di accesso Google a ogni richiesta alla piattaforma dell'agente.

L'URL utilizza l'endpoint globale (host aiplatform.googleapis.com e locations/global), che gestisce gemini-3.8-flash e instrada le richieste alla capacità disponibile tra le regioni. Con l'endpoint globale, non è necessario scegliere una regione.

Per chiamare un modello diverso, imposta MODEL nell'elenco parameters del template sull'ID del modello. Per elencare i modelli Gemini che puoi chiamare, esegui:

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

Ogni valore nella colonna MODEL_ID è simile a google/gemini-3.8-flash@default. Imposta MODEL sulla parte compresa tra google/ e @, ad esempio gemini-4-argon. La scheda del modello in Model Garden nella consoleGoogle Cloud mostra lo stesso ID. Per verificare che un modello supporti l'endpoint globale, consulta la scheda Globale in Posizioni degli endpoint dei modelli Google.

Se devi controllare quale regione elabora le richieste, sostituisci la riga url in features/gemini-target.yaml con il formato regionale, che inserisce la regione sia nell'host sia nel percorso:

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

Sostituisci REGION con una regione che gestisce il tuo modello, come elencato nelle stesse tabelle delle località degli endpoint dei modelli Google. Per sapere quando evitare l'endpoint globale, consulta Endpoint globale.

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 Agent Platform come service account. Crea il account di servizio, concedigli l'accesso ad Agent Platform e consenti all'agente di servizio Apigee di utilizzarlo. Questo account di servizio viene fornito quando esegui il deployment del proxy nel passaggio 5. Per maggiori dettagli, consulta Utilizzo dell'autenticazione Google.

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

    Scegli un nome descrittivo per SA_NAME, ad esempio apigee-ai-gateway. Il comando crea il account di servizio SA_NAME@PROJECT_ID.iam.gserviceaccount.com, ad esempio apigee-ai-gateway@my-apigee-project.iam.gserviceaccount.com.

  2. Concedi al account di servizio l'accesso al backend che chiama. Per un target Agent Platform, concedi il ruolo 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"

    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 creare token per l'account di servizio concedendogli il ruolo Creatore token account di servizio (roles/iam.serviceAccountTokenCreator) nell'account di servizio:
    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. Esegui questo comando dalla directory proxy-templates, che contiene il template:

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

Prendi nota del numero di revisione nell'output comando, che ti servirà nel 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 nella Parte 1 in due modi:

  • Devi fornire il service account che hai creato nel passaggio 3. Se esegui il deployment senza un account di servizio, il deployment non riesce e viene visualizzato un errore MISSING_SERVICE_ACCOUNT.
  • Devi eseguire il deployment in un ambiente intermedio o completo. Questo proxy utilizza una policy estensibile, che non è supportata da un ambiente Base; il deployment in un ambiente Base non va a buon fine e viene visualizzato l'errore Impossibile eseguire il deployment del proxy estensibile in un ambiente Base. Il comando gcloud apigee environments list non stampa il tipo di ambiente. Per verificarlo, nella console Google Cloud , vai ad Apigee > Gestione > Ambienti. Consulta Tipi di ambiente Apigee.

UI di Apigee: esegui il deployment del proxy e, quando ti viene richiesto un account di servizio, inserisci SA_NAME@PROJECT_ID.iam.gserviceaccount.com. Per i passaggi, consulta Deployment di un proxy API.

API Deployment: chiama l'API deployments, passando il account di servizio come parametro di query serviceAccount. 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 del deployment della revisione, che segnala 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 proprie policy al PreFlow della richiesta (prima la limitazione di frequenza, poi il controllo della chiave API) e la funzionalità gemini-target aggiunge il backend di Agent Platform. Una volta completato il deployment, il proxy si autentica su Agent Platform 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 è necessaria 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à, descritte in Panoramica della pubblicazione:

  1. Crea un prodotto API che includa il proxy ai-gateway. Nel modulo del prodotto, inserisci quanto segue e fai clic su Salva:
    • Nome e Nome visualizzato: qualsiasi valore, ad esempio ai-gateway-product.
    • Ambiente: l'ambiente in cui hai eseguito il deployment del proxy (ENV).
    • Accesso: Pubblico. Lascia selezionata l'opzione Approva automaticamente le richieste di accesso in modo che la chiave API venga approvata quando registri l'app.
    • Nella sezione Operazioni, fai clic su + AGGIUNGI UN'OPERAZIONE e imposta i seguenti campi:
      • Proxy API: ai-gateway.
      • Path: /. Le richieste vengono inviate al percorso di base del proxy, /v1/gemini, senza nulla dopo. Il percorso / corrisponde al percorso di base; /** corrisponde solo ai percorsi sottostanti, quindi una richiesta a /v1/gemini non va a buon fine con l'errore oauth.v2.InvalidApiKeyForGivenResource. Consulta Configurazione dei percorsi delle risorse.
      • Metodi: POST.
    • Lascia vuoti i campi Limite di quota API, Limite di quota token LLM, Quota dell'operazione e la sezione Operazioni LLM. La funzionalità spike-arrest nel proxy applica il limite di frequenza.
  2. Registra uno sviluppatore di app.
  3. Registra un'app per sviluppatori e seleziona il prodotto API quando crei l'app, in modo che la nuova chiave venga associata al prodotto fin dall'inizio.

La registrazione dell'app genera la chiave. Per recuperarla, consulta Visualizzazione di una chiave API e di un secret.

Passaggio 7: chiama il proxy

Trova il nome host del tuo gruppo di ambienti come descritto nella Parte 1, passaggio 5, 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 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."}]}]}'

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

Passaggi successivi