Configurazione di un proxy con YAML

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Puoi definire un proxy API Apigee in YAML ed eseguirne il deployment con Google Cloud CLI, in alternativa alla creazione del bundle proxy XML tradizionale. Descrivi gli endpoint, le route, le policy e i target di backend di un proxy in file YAML chiamati Apigee Feature Templates e Apigee li compila in un bundle proxy API standard.

Poiché il risultato è un normale bundle proxy API Apigee, un proxy che crei in questo modo viene eseguito nello stesso runtime Apigee, con le stesse norme e lo stesso comportamento di un proxy che crei nell'interfaccia utente Apigee o da un bundle XML.

Perché utilizzare YAML per definire i proxy

Il formato tradizionale del proxy API Apigee è un archivio ZIP di file XML. YAML offre un'alternativa che molti sviluppatori trovano più veloce da leggere, scrivere e rivedere e che funziona bene con strumenti basati su AI e agenti. I modelli di funzionalità di Apigee sono progettati per:

  • Sviluppatori e architetti di API che preferiscono un formato conciso e dichiarativo e vogliono mantenere la configurazione del proxy nel controllo del codice sorgente.
  • Professionisti dell'AI che vogliono un modo standardizzato per inserire un gateway Apigee davanti a un backend del modello.
  • Team della piattaforma e DevOps che vogliono raggruppare parti riutilizzabili di configurazione proxy e applicarle in modo coerente a molti proxy.

Concetti fondamentali

I modelli di funzionalità di Apigee utilizzano tre tipi di documenti. Ciascuno è un file YAML identificato dal campo type.

Tipo di documento Valore type Finalità
Modello template L'entry point di cui esegui il deployment. Un modello è composto da una o più funzionalità e definisce gli endpoint e le route del proxy.
Funzionalità feature Un'unità di configurazione riutilizzabile, ad esempio un controllo di autenticazione, un limite di frequenza o un target di backend, che includi in un modello. Le funzionalità contengono i criteri e le risorse.
Proxy proxy Il proxy completamente risolto che la CLI produce quando compila un modello con le relative funzionalità. Sebbene in genere si tratti di un output intermedio generato dalla CLI, puoi anche importare un file proxy direttamente per convertirlo in un bundle proxy API.

Crei modelli e funzionalità. Apigee genera il proxy per te durante la compilazione.

Come funziona

Quando importi un modello, Google Cloud CLI esegue i seguenti passaggi localmente, quindi carica il risultato su Apigee:

  1. Compila. La CLI legge il modello e i file delle funzionalità a cui fa riferimento, li unisce e produce una singola definizione di proxy.
  2. Converti. La CLI converte la definizione del proxy in un bundle proxy API Apigee standard (il file ZIP dei file XML previsto da Apigee).
  3. Importa. La CLI carica il bundle su Apigee, che crea una nuova revisione del proxy API.

L'importazione di un proxy non lo rende attivo. Come passaggio separato, esegui il deployment della revisione in un ambiente, esattamente come faresti per qualsiasi altro proxy API:

YAML template + feature files
  |  gcloud apigee apis import --from-template
  v
API proxy revision   (created, not yet serving traffic)
  |  gcloud apigee apis deploy
  v
Deployed proxy       (serving traffic in an environment)

Per istruzioni passo passo, vedi Creare un proxy API da un modello YAML.

Un esempio minimo

Il seguente modello definisce un proxy che compone due funzionalità: una che aggiunge una destinazione backend e una che aggiunge un messaggio di risposta:

gateway: apigee
schemaVersion: 1.0.0
name: HelloWorld-v1
type: template
description: API proxy for HelloWorld-v1
features:
- proxy-apigeemock.yaml
- response-helloworld.yaml

Ogni file delle funzionalità a cui viene fatto riferimento deve trovarsi nella stessa directory del modello. Per un esempio completo e eseguibile e i file delle funzionalità che utilizza, consulta Crea un proxy API da un modello YAML.

Cosa puoi fare

  • Definisci gli endpoint, i percorsi di base, le route, i flussi e i target di backend di un proxy in YAML.
  • Raggruppa criteri e risorse riutilizzabili come funzionalità e componili in un modello.
  • Aggiungi l'autenticazione backend per le destinazioni Google Cloud (ad esempio, un token di accesso Google per un backend Vertex AI).
  • Importa un modello come nuova revisione del proxy API con Google Cloud CLI, poi esegui il deployment con il comando di deployment standard.

Limitazioni

Quando crei modelli e funzionalità, tieni presente quanto segue:

  • Le funzionalità sono file locali. Un modello può fare riferimento solo a file delle funzionalità che si trovano nella stessa directory. Il riferimento alle funzionalità tramite URL o da un catalogo condiviso non è supportato.
  • I valori dei parametri utilizzano i valori predefiniti. Le funzionalità possono definire i parametri, ma i valori dei parametri vengono risolti in base al valore predefinito definito nella funzionalità. Non esiste alcun flag della riga di comando per ignorare i valori dei parametri al momento dell'importazione.
  • I parametri JSONPath non sono supportati. Un parametro che utilizza un'espressione paths (JSONPath) causa un errore di compilazione.
  • I test non sono supportati. Una sezione tests è accettata dallo schema, ma viene ignorata e non inclusa nel bundle generato.
  • Lo schema è rigoroso. I campi sconosciuti causano un errore. Sono supportati solo gateway: apigee e schemaVersion: 1.0.0.
  • La risoluzione dei problemi utilizza il file XML generato. L'interfaccia utente e il runtime di Apigee funzionano con il bundle generato. Non è possibile eseguire il round trip all'origine YAML nell'interfaccia utente.

Passaggi successivi