Crea un proxy API da un modello YAML

Questa pagina si applica ad Apigee e 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, crea un proxy semplice, poi crea un esempio più completo che funge da front-end per un modello Gemini.

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

Prima di iniziare

  • Attiva 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 Google Cloud CLI.
  • Per accedere ai comandi utilizzati in questo tutorial, installa il componente gcloud beta: 
    gcloud components install beta
  • 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. 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 conceda 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 nella 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 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.
  • Un target che indirizza all'URL di backend.
  • Una funzionalità, spike-arrest.yaml, che creerai successivamente.

Passaggio 2: crea la funzionalità

Una funzionalità è un'unità di configurazione riutilizzabile che contiene le policy. Un modello non può contenere direttamente 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 alla richiesta PreFlow, in modo che venga eseguita su ogni richiesta.
  • Dichiara un parametro, RATE, il cui valore predefinito (30ps) viene sostituito a {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

La CLI compila il modello e la relativa funzionalità in un bundle proxy API, lo carica e stampa la nuova revisione del proxy. L'importazione crea una revisione, ma non la 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, il tuo 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 sugli ambienti e sui gruppi di ambienti.

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

  1. Nella console Google Cloud , vai a Apigee > Management > Environments (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 a 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 semplice proxy nella Parte 1, questo proxy chiama un servizio Google Cloud (Vertex AI). La funzionalità gemini-target utilizza auth: GoogleAccessToken, pertanto 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 implementi il 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 delle funzionalità.

Riutilizza la funzionalità spike-arrest.yaml della 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 indirizzare 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 utilizzi (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à che utilizzi. L'URL precedente è il modulo regionale, che funziona per un modello pubblicato da una regione specifica, ad esempio gemini-2.5-flash in us-central1. Gli 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, consulta Località dell'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 questo account di servizio, concedigli l'accesso a Vertex AI e consenti all'agente di servizio Apigee di utilizzarlo. Fornisci questo account di servizio quando esegui il deployment del proxy nel passaggio 5. Per maggiori dettagli, vedi Utilizzo dell'autenticazione Google.

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

    In questo modo 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 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"

    Se il criterio 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 account di servizio concedendogli il ruolo Creatore token service account (roles/iam.serviceAccountTokenCreator) nel 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:

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

L'implementazione del gateway AI differisce dal semplice proxy della Parte 1 in due modi:

  • Devi fornire il service account che hai creato nel passaggio 3. Se esegui il deployment senza uno di questi file, 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 un criterio estensibile, che un ambiente Base non supporta. Il deployment in un ambiente di questo tipo non va a buon fine e viene visualizzato l'errore Extensible proxy can not be deployed to a base environment. Consulta Tipi di ambiente Apigee.

UI Apigee:esegui il deployment del proxy e, quando ti viene chiesto un account di servizio, inserisci SA_NAME@PROJECT_ID.iam.gserviceaccount.com. Per una descrizione dei passaggi, consulta la sezione 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 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 i loro criteri al PreFlow della richiesta (prima limitazione di frequenza, poi il controllo della chiave API), mentre la funzionalità gemini-target aggiunge il backend Vertex AI. Al termine del deployment, il proxy si autentica in Vertex AI comeaccount di serviziot.

Passaggio 6: ottieni una chiave API

La funzionalità verify-api-key rifiuta qualsiasi richiesta che non contenga una chiave API valida, quindi devi disporre di 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 e l'ambiente in cui è stato eseguito il deployment.
  2. Registra uno sviluppatore di app.
  3. Registra un'app per sviluppatori associata a quel prodotto API.

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

Passaggio 7: chiama il proxy

Trova il nome host del 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 riuscita è l'output JSON del modello. Se ometti la chiave, si verifica un errore di autorizzazione della policy VerifyAPIKey, 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