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
gatewayeschemaVersionvengono 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:
- Se l'elenco
parametersdel template contiene una voce il cuinamecorrisponde e il cuidefaultnon è vuoto, l'interfaccia a riga di comando utilizza questo valore. Se la funzionalità imposta unuid, il nome della voce del template deve essereFEATURE_NAME.UID.PARAMETER_NAME. - In caso contrario, l'interfaccia a riga di comando utilizza il valore
defaultdel parametro della funzionalità. - 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
contentha esattamente una chiave, che deve corrispondere al criteriotype. - 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>diventaFoo: {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
pathssu un parametro (JSONPath). L'utilizzo di questo campo causa un errore di compilazione.testssu 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.