Configurazione di un proxy con YAML

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza Apigee Edge documentazione.

Puoi definire un proxy API Apigee in YAML ed eseguirne il deployment con Google Cloud CLI, in alternativa alla creazione del bundle di proxy XML tradizionale. Puoi descrivere gli endpoint, le route, le policy e le destinazioni di backend di un proxy nei file YAML denominati modelli di funzionalità Apigee e Apigee li compilerà in un bundle di proxy API standard.

Poiché il risultato è un normale bundle di proxy API Apigee, un proxy creato in questo modo viene eseguito nello stesso runtime Apigee, con le stesse policy e lo stesso comportamento di un proxy creato nell'interfaccia utente di 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 gli strumenti basati sull'AI e sugli agenti. I modelli di funzionalità Apigee sono progettati per:

  • Sviluppatori e architetti di API che preferiscono un formato dichiarativo conciso 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 di piattaforma e DevOps che vogliono creare pacchetti di parti riutilizzabili della configurazione del proxy e applicarli in modo coerente a molti proxy.

Concetti fondamentali

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

Tipo di documento Valore type Finalità
Modello template Il punto di ingresso di cui esegui il deployment. Un modello compone 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 check, un limite di frequenza o una destinazione di backend, che includi in un modello. Le funzionalità contengono le policy e le risorse.
Proxy proxy Il proxy completamente risolto che l'interfaccia a riga di comando produce quando compila un modello con le relative funzionalità. Sebbene in genere sia un output intermedio generato dall'interfaccia a riga di comando, puoi anche importare direttamente un file proxy da tradurre in un bundle di proxy API.

Puoi creare modelli e funzionalità. Apigee genera il proxy durante la compilazione.

Come funziona

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

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

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

YAML template + feature files
  |  gcloud beta 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 molto semplice

Il seguente modello definisce un proxy che compone due funzionalità: una che aggiunge una destinazione di 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 di funzionalità a cui viene fatto riferimento deve trovarsi nella stessa directory del modello. Per un esempio completo ed eseguibile e per i file di funzionalità utilizzati, vedi Creare un proxy API da un modello YAML.

Cosa puoi fare

  • Definisci gli endpoint, i percorsi di base, le route, i flussi e le destinazioni di backend di un proxy in YAML.
  • Crea pacchetti di policy e risorse riutilizzabili come funzionalità e componili in un modello.
  • Aggiungi l'autenticazione del backend per le destinazioni di 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, quindi 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 ai file di funzionalità che si trovano nella stessa directory. Non è supportato il riferimento alle funzionalità tramite URL o da un catalogo condiviso.
  • I valori dei parametri utilizzano i valori predefiniti. Le funzionalità possono definire i parametri, ma i valori dei parametri vengono risolti nel valore predefinito definito nella funzionalità. Non esiste un flag della riga di comando per sostituire i valori dei parametri al momento dell'importazione.
  • I parametri JSONPath non sono supportati. Un parametro che utilizza un paths (JSONPath) espressione causa un errore di compilazione.
  • I test non sono supportati. Una sezione tests viene 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 l'XML generato. L'interfaccia utente e il runtime di Apigee funzionano con il bundle generato. Non è possibile tornare all'origine YAML nell'interfaccia utente.

Passaggi successivi