Riferimento per la configurazione YAML del proxy API

Questa pagina si applica ad Apigee e ad Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Questa pagina descrive il formato YAML per i modelli di funzionalità Apigee: i tipi di documento template, feature e proxy e tutti i relativi campi. Per un'introduzione concettuale, consulta Configurazione di un proxy con YAML. Per una procedura dettagliata, consulta Crea un proxy API da un modello YAML.

Convention

  • I nomi dei campi utilizzano la notazione camelCase. Ad esempio, schemaVersion, basePath, displayName, faultRules, defaultFaultRule, httpTargetConnection.
  • Lo schema è rigido. I campi sconosciuti causano un errore durante l'importazione del file.
  • Campi obbligatori. Solo gateway e schemaVersion vengono convalidati quando un file viene analizzato. Altri campi contrassegnati con Sì nelle tabelle seguenti sono obbligatori per produrre un proxy API funzionante.

Campi di primo livello comuni

Ogni documento template, feature e proxy inizia con i seguenti campi.

Nome Descrizione Predefinito Obbligatorio?
gateway Il gateway di destinazione. Deve essere apigee. N/D Sì
schemaVersion La versione dello schema del documento. Deve essere 1.0.0. N/D Sì
name Il nome del documento. Per un modello o un proxy, si tratta del nome del proxy API scritto nel bundle. N/D Sì
type Il tipo di documento: template, feature o proxy. N/D Sì
description Una descrizione leggibile. N/D No
priority Un numero intero che controlla l'ordine in cui vengono applicate le funzionalità durante la compilazione. I numeri più bassi vengono applicati per primi. 100 No

Tipo di documento: modello

Un template è il punto di ingresso che importi. Compone le funzionalità e definisce gli endpoint e i route del proxy. Un modello non contiene policy o risorse, che provengono dalle funzionalità a cui fa riferimento.

Nome Descrizione Predefinito Obbligatorio?
features Un elenco di file di funzionalità da comporre nel proxy. Ogni voce è un percorso di un file di caratteristiche, relativo alla directory che contiene il modello (ad esempio, ./features/spike-arrest.yaml). [] No
parameters Un elenco di parametri che impostano i valori per i parametri delle funzionalità. Il valore default di una voce esegue l'override del valore default del parametro della funzionalità con lo stesso valore name. Consulta il parametro. [] No
endpoints Un elenco di endpoint che definiscono percorsi e route di base. [] No
targets Un elenco di destinazioni che definiscono le connessioni di backend. [] No

Tipo di documento: elemento

Una funzionalità è un'unità di configurazione riutilizzabile che includi in un template. Una funzionalità contiene policy e risorse e può contribuire con flussi, endpoint e target al proxy compilato. Oltre ai campi di primo livello comuni, una caratteristica ha i seguenti campi.

Nome Descrizione Predefinito Obbligatorio?
displayName Un nome visualizzato leggibile. N/D No
uid Un identificatore univoco che distingue le policy e le risorse della funzionalità quando un modello include la funzionalità più di una volta. Se la funzionalità imposta un uid, l'interfaccia a riga di comando aggiunge il prefisso UID- a ogni nome di policy e risorsa e aggiorna i relativi riferimenti. Se la funzionalità non imposta un uid, l'interfaccia a riga di comando utilizza i nomi così come sono scritti. N/D No
documentation Documentazione estesa per la funzionalità. N/D No
categories Un elenco di etichette di categoria in formato libero. [] No
parameters Un elenco di parametri definiti dalla funzionalità. [] No
defaultEndpoint Un endpoint proxy i cui flussi e la regola di errore predefinita vengono uniti in ogni endpoint del proxy compilato. Utilizzalo per collegare le policy di una funzionalità al flusso di richiesta o risposta. N/D No
defaultTarget Un target proxy utilizzato come connessione di backend predefinita. N/D No
endpoints Un elenco di endpoint proxy da aggiungere al proxy. Un endpoint con lo stesso nome di uno esistente lo sostituisce. [] No
targets Un elenco di target proxy da aggiungere al proxy. Un target con lo stesso nome di uno esistente lo sostituisce. [] No
policies Un elenco di policy fornite dalla funzionalità. Se la funzionalità imposta un uid, l'interfaccia a riga di comando aggiunge un prefisso a ogni nome di policy con UID- durante la compilazione, ad esempio sa1-SA-SpikeArrest. In caso contrario, l'interfaccia a riga di comando utilizza i nomi delle policy così come sono scritti. [] No
resources Un elenco di risorse fornite dalla funzionalità, ad esempio file JavaScript o di proprietà. [] No

Tipo di documento: delega

Un proxy è il documento completamente risolto che la CLI produce quando compila un template con le sue funzionalità. In genere, questo tipo non viene creato direttamente; viene descritto qui perché è la forma che diventa il bundle del proxy API.

Un proxy ha gli stessi campi di una funzionalità, ad eccezione del fatto che utilizza endpoints e targets (non defaultEndpoint o defaultTarget) e rappresenta sempre un proxy completo e di cui è possibile eseguire il deployment. Il valore di type è proxy.

Oggetti nidificati

parametro

Un parametro fornisce un valore a una funzionalità. Una funzionalità dichiara i suoi parametri e un template può impostare i relativi valori nel proprio elenco parameters. Quando l'interfaccia a riga di comando compila un template, risolve ogni parametro della funzionalità come segue:

  1. Se l'elenco parameters del template contiene una voce il cui name corrisponde e il cui default non è vuoto, l'interfaccia a riga di comando utilizza questo valore. Se la funzionalità imposta un uid, il nome della voce del template deve essere FEATURE_NAME.UID.PARAMETER_NAME.
  2. In caso contrario, l'interfaccia a riga di comando utilizza il valore default del parametro della funzionalità.
  3. Se nessuna delle due imposta un valore, il parametro viene risolto in una stringa vuota. La CLI non segnala un errore.

Non esiste un flag della riga di comando per impostare i valori dei parametri al momento dell'importazione. Per modificare un valore, modifica il modello.

Nome Descrizione Predefinito Obbligatorio?
name Il nome del parametro. Riferimento nei contenuti in primo piano come {name}. N/D Sì
displayName Un nome leggibile. N/D No
description Una descrizione del parametro. N/D No
default In una funzionalità, il valore utilizzato quando il template non ne imposta uno. In un modello, il valore del parametro della funzionalità con lo stesso nome. La CLI ignora un valore vuoto. La CLI sostituisce il valore risolto per {name} nelle stringhe della funzionalità. N/D No
examples Un elenco di valori di esempio. [] No
maps Una mappa delle sostituzioni dei valori. Se il valore risolto è una chiave nella mappa, viene sostituito con il valore mappato. N/D No
paths Un elenco di espressioni JSONPath. Non supportato in questa release: l'utilizzo causa un errore. N/D No

endpoint

Utilizzato nell'elenco endpoints di un modello.

Nome Descrizione Predefinito Obbligatorio?
name Il nome dell'endpoint. N/D Sì
basePath Il percorso di base utilizzato dai client per chiamare il proxy, ad esempio /v1/gemini. N/D No
routes Un elenco di route che mappano le richieste alle destinazioni. [] No

proxyEndpoint

Utilizzato in defaultEndpoint e endpoints di una funzionalità e in un proxy compilato. Estende l'endpoint con la gestione del flusso.

Nome Descrizione Predefinito Obbligatorio?
flows Un elenco di flussi. I flussi denominati PreFlow o PostFlow vengono mappati al flusso Apigee corrispondente; qualsiasi altro nome viene inserito nel container dei flussi generici. [] No
postClientFlow Un singolo flusso che viene eseguito dopo l'invio della risposta al client. N/D No
faultRules Un elenco di flussi utilizzati come regole di errore. [] No
defaultFaultRule Una regola di errore che viene eseguita quando non vengono rilevate corrispondenze con altre regole di errore. N/D No

route

Nome Descrizione Predefinito Obbligatorio?
name Il nome della route. N/D Sì
target Il nome dell'endpoint di destinazione a cui eseguire il routing. N/D No
condition Una condizione che deve essere vera affinché questa route venga applicata. N/D No

stato di flow

Nome Descrizione Predefinito Obbligatorio?
name Il nome del flusso. Utilizza PreFlow o PostFlow per i flussi di richiesta/risposta standard. N/D Sì
mode Request o Response. Determina se i passaggi vengono eseguiti sulla richiesta o sulla risposta. Request No
condition Una condizione che deve essere vera affinché il flusso venga eseguito. N/D No
steps Un elenco ordinato di passaggi (chiamate di policy). [] No

passaggio

Un passaggio esegue una policy all'interno di un flusso.

Nome Descrizione Predefinito Obbligatorio?
name Il nome della policy da eseguire. All'interno di una funzionalità, utilizza il nome locale della policy; il compilatore lo riscrive nel nome con spazio dei nomi. N/D Sì
condition Una condizione che deve essere vera affinché il passaggio venga eseguito. N/D No

faultRule

Estende il flusso con un campo aggiuntivo.

Il campo mode ereditato dal flusso non si applica a una regola di errore. Poiché una regola di errore viene eseguita dopo che una richiesta non va a buon fine, non ha una fase di richiesta o risposta; i suoi passaggi vengono sempre eseguiti direttamente. Se imposti mode su una regola di errore, lo strumento registra un avviso e ignora il campo.

Nome Descrizione Predefinito Obbligatorio?
alwaysEnforce Se true, viene sempre applicata la regola di errore predefinita. false No

destinazione

Utilizzato nell'elenco targets di un modello.

Nome Descrizione Predefinito Obbligatorio?
name Il nome del target. A cui fa riferimento il campo target di un percorso. N/D Sì
url L'URL di backend. N/D No
auth Lo schema di autenticazione per un backend Google Cloud, ad esempio GoogleAccessToken o GoogleIDToken. N/D No
scopes Un elenco di ambiti OAuth da richiedere. Si applica quando è impostato auth. [] No
aud Il pubblico per il token. Si applica quando è impostato auth. N/D No

proxyTarget

Utilizzato in defaultTarget e targets di una funzionalità e in un proxy compilato. Estende target con la gestione del flusso e gli override della connessione non elaborata.

Nome Descrizione Predefinito Obbligatorio?
flows Un elenco di flussi eseguiti sulla richiesta o sulla risposta di destinazione. [] No
faultRules Un elenco di flussi utilizzati come regole di errore. [] No
defaultFaultRule Una regola di errore. N/D No
httpTargetConnection Una rappresentazione non elaborata dell'elemento HTTPTargetConnection per la configurazione avanzata. Se impostato, ha la precedenza su url, auth, scopes e aud. N/D No
localTargetConnection Una rappresentazione non elaborata di un elemento LocalTargetConnection. Se impostato, ha la precedenza su una connessione HTTP. N/D No

policy

Una policy è definita in una funzionalità. La sua configurazione è scritta in content utilizzando la convenzione attributo/testo descritta in Convenzione per i contenuti delle policy.

Nome Descrizione Predefinito Obbligatorio?
name Il nome del criterio. N/D Sì
type Il tipo di policy Apigee, ad esempio VerifyAPIKey, SpikeArrest o Javascript. Deve corrispondere alla singola chiave di primo livello in content. N/D Sì
content Un dizionario con una sola chiave, che corrisponde a type. Il valore nidificato descrive l'XML della policy utilizzando la convenzione riportata di seguito. {} Sì

Convenzione sui contenuti delle policy

Le policy di Apigee sono in formato XML. In YAML, rappresenti l'XML in content con queste regole:

  • Il dizionario content ha esattamente una chiave, che deve corrispondere al criterio type.
  • Gli attributi degli elementi sono inseriti sotto una chiave metadata.
  • Il testo dell'elemento viene inserito sotto una chiave _text. Ad esempio, <Foo bar="baz">qux</Foo> diventa Foo: {metadata: {bar: "baz"}, _text: "qux"}. Se un elemento contiene solo testo e nessun attributo, puoi scrivere il testo direttamente come valore.
  • Gli elementi secondari sono nidificati sotto il nome del tag. I tag ripetuti diventano un elenco.

Ad esempio, questo criterio delle funzionalità:

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

viene compilato in questo XML della policy:

<VerifyAPIKey continueOnError="false" enabled="true" name="verify-api-key-VA-VerifyAPIKey">
  <APIKey ref="request.header.x-api-key"></APIKey>
  <DisplayName>VA-VerifyAPIKey</DisplayName>
</VerifyAPIKey>

risorsa

Una risorsa è un file che una funzionalità contribuisce al bundle, ad esempio un file JavaScript o un file di proprietà.

Nome Descrizione Predefinito Obbligatorio?
name Il nome del file, ad esempio hello-world.js. Se la funzionalità imposta un uid, l'interfaccia a riga di comando aggiunge il prefisso UID- al nome della risorsa durante la compilazione. In caso contrario, l'interfaccia a riga di comando utilizza il nome così come è scritto. N/D Sì
type Il tipo di risorsa, che determina la sottodirectory nel bundle, ad esempio jsc (JavaScript) o properties. N/D Sì
content I contenuti del file non elaborati. N/D No

Campi non supportati in questa release

  • paths su un parametro (JSONPath). L'utilizzo di questo campo causa un errore di compilazione.
  • tests su qualsiasi documento. Il campo viene accettato, ma ignorato e non è incluso nel bundle generato.

Limiti

Il bundle del proxy API generato non deve superare 10 MiB non compressi o 256 file.

Passaggi successivi