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_IDSostituisci 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 concedeapigee.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.
- Per importare (creare) un proxy API: il ruolo Amministratore API (
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.flowsper 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=ORGLa 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=ORGPer 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:
- Nella console Google Cloud , vai ad Apigee > Gestione > Ambienti.
- Seleziona la scheda Gruppi di ambienti.
- 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:
- Se l'elenco
parametersdel template contiene una voce con lo stesso nome e undefaultnon vuoto, l'interfaccia a riga di comando utilizza questo valore. - In caso contrario, l'interfaccia a riga di comando utilizza il valore
defaultdella funzionalità. - 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 unMODEL_PROJECT_IDmancante 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.
- 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 servizioSA_NAME@PROJECT_ID.iam.gserviceaccount.com, ad esempioapigee-ai-gateway@my-apigee-project.iam.gserviceaccount.com. - 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=Nonea questo comando. - 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=ORGPrendi 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 comandogcloud apigee environments listnon 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:
- 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/gemininon va a buon fine con l'erroreoauth.v2.InvalidApiKeyForGivenResource. Consulta Configurazione dei percorsi delle risorse. - Metodi:
POST.
- Proxy API:
- Lascia vuoti i campi Limite di quota API, Limite di quota token LLM, Quota dell'operazione e la sezione Operazioni LLM.
La funzionalità
spike-arrestnel proxy applica il limite di frequenza.
- Nome e Nome visualizzato: qualsiasi valore, ad esempio
- Registra uno sviluppatore di app.
- 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
- Riferimento alla configurazione YAML del proxy API
- Configurazione di un proxy con YAML
- Deployment dei proxy API
- Panoramica della pubblicazione