Riferimento per la configurazione YAML del proxy API

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Questa pagina descrive il formato YAML per i modelli di funzionalità di Apigee: i tipi di documenti 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 Creare 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 è rigoroso. I campi sconosciuti causano un errore durante l'importazione del file.
  • Campi obbligatori. Quando un file viene analizzato, vengono convalidati solo gateway e schemaVersion. Altri campi contrassegnati con Sì nelle tabelle seguenti sono necessari in pratica 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 modello è il punto di ingresso che importi. Definisce le funzionalità e gli endpoint e le route del proxy. Un modello non contiene criteri o risorse, che provengono dalle funzionalità a cui fa riferimento.

Nome Descrizione Predefinito Obbligatorio?
features Un elenco di nomi di file delle funzionalità da comporre nel proxy. Ogni nome deve corrispondere a un file nella stessa directory del modello. [] No
parameters Un elenco di valori dei parametri che forniscono i valori predefiniti alle funzionalità. [] No
endpoints Un elenco di endpoint che definiscono i percorsi di base e le route. [] No
targets Un elenco di destinazioni che definiscono le connessioni di backend. [] No

Tipo di documento: funzionalità

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

Nome Descrizione Predefinito Obbligatorio?
displayName Un nome visualizzato leggibile. N/D No
uid Un identificatore univoco utilizzato per lo spazio dei nomi delle norme e delle risorse della funzionalità. Se non è impostato, viene utilizzato name. N/D No
documentation Documentazione estesa per la funzionalità. N/D No
categories Un elenco di etichette di categorie in formato libero. [] No
parameters Un elenco di parametri definiti dalla funzionalità. [] No
defaultEndpoint Un endpoint proxy i cui flussi e la cui regola di errore predefinita vengono uniti a ogni endpoint del proxy compilato. Utilizza questo per allegare le norme 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 dei criteri forniti dalla funzionalità. I nomi delle policy vengono automaticamente preceduti dal prefisso uid (o name) della funzionalità durante la compilazione. [] No
resources Un elenco delle 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 modello con le relative funzionalità. In genere non crei direttamente questo tipo; è descritto qui perché è la forma che diventa il bundle del proxy API.

Un proxy ha gli stessi campi di una funzionalità, tranne per il fatto che utilizza endpoints e targets (non defaultEndpoint o defaultTarget) e rappresenta sempre un proxy completo e implementabile. Il suo type è proxy.

Oggetti nidificati

parametro

Un parametro fornisce un valore a una funzionalità. Il valore di un parametro viene risolto nel relativo default.

Nome Descrizione Predefinito Obbligatorio?
name Il nome del parametro. Citato nei contenuti della funzionalità come {name}. N/D Sì
displayName Un nome leggibile. N/D No
description Una descrizione del parametro. N/D No
default Il valore predefinito. Sostituito con {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: il suo 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 contenitore 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 viene trovata corrispondenza con altre regole di errore. N/D No

route

Nome Descrizione Predefinito Obbligatorio?
name Il nome della rotta. N/D Sì
target Il nome dell'endpoint di destinazione a cui eseguire il routing. N/D No
condition Una condizione che deve essere soddisfatta 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 standard di richiesta/risposta. 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 soddisfatta per l'esecuzione del flusso. N/D No
steps Un elenco ordinato di passaggi (invocazioni di policy). [] No

passaggio

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

Nome Descrizione Predefinito Obbligatorio?
name Il nome della norma da eseguire. All'interno di una funzionalità, utilizza il nome locale del criterio; il compilatore lo riscrive nel nome con spazio dei nomi. N/D Sì
condition Una condizione che deve essere soddisfatta per l'esecuzione del passaggio. N/D No

faultRule

Estende il flusso con un campo aggiuntivo.

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

target

Utilizzato nell'elenco targets di un modello.

Nome Descrizione Predefinito Obbligatorio?
name Il nome del target. Referenziato da 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 auth è impostato. [] No
aud Il pubblico del token. Si applica quando auth è impostato. 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 impostata, 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 norme.

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

Convenzione sui contenuti delle norme

I criteri Apigee sono XML. In YAML, dichiari che XML in content con queste regole:

  • Il dizionario content ha esattamente una chiave, che deve corrispondere a type del criterio.
  • Gli attributi dell'elemento sono associati a 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 delle norme:

<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. I nomi delle risorse hanno come prefisso uid (o name) della funzionalità durante la compilazione. 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). Il suo utilizzo causa la mancata compilazione.
  • tests su qualsiasi documento. Il campo viene accettato ma ignorato e non è incluso nel bundle generato.

Limiti

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

Passaggi successivi