Stai visualizzando la documentazione di Apigee Edge.
Vai alla
documentazione di Apigee X. informazioni
Utilizza le norme ExtensionCallout per incorporare un'estensione in un proxy API.
Un'estensione fornisce l'accesso a una risorsa specifica esterna ad Apigee Edge. La risorsa potrebbe essere servizi della piattaforma Google Cloud come Cloud Storage o Cloud Speech-to-Text. Tuttavia, la risorsa potrebbe essere qualsiasi risorsa esterna accessibile tramite HTTP o HTTPS.
Per una panoramica delle estensioni, consulta l'articolo Che cosa sono le estensioni? Per un tutorial introduttivo, consulta Tutorial: aggiungere e utilizzare un'estensione.
Prima di accedere a un'estensione dal criterio ExtensionCallout, devi aggiungere, configurare ed eseguire il deployment dell'estensione da un pacchetto di estensioni già installato nell'organizzazione Apigee Edge.
Samples
Di seguito è riportato un criterio di esempio da utilizzare con l'estensione Cloud Logging:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="false" enabled="true" name="Logging-Extension">
<DisplayName>Logging Extension</DisplayName>
<Connector>cloud-extension-sample</Connector>
<Action>log</Action>
<Input>{
"logName" : "example-log",
"metadata" : "test-metadata",
"message" : "This is a test"
}</Input>
<Output>cloud-extension-example-log</Output>
</ConnectorCallout>
Consulta Tutorial: utilizzo delle estensioni per un tutorial completo sull'utilizzo dell'estensione Cloud Logging.
Per esempi di tutte le estensioni disponibili, consulta la panoramica dei riferimenti per le estensioni.
Informazioni sulle norme relative ai callout per le estensioni
Utilizza il criterio ExtensionCallout quando vuoi usare un'estensione configurata per accedere a una risorsa esterna dall'interno di un proxy API.
Prima di utilizzare questo criterio, ti serviranno:
- Alcuni dettagli sulla risorsa esterna a cui vuoi accedere da questo criterio. Questi dettagli saranno specifici per la risorsa. Ad esempio, se il criterio accede al database Cloud Firestore, devi conoscere il nome della raccolta e del documento che vuoi creare o a cui vuoi accedere. In genere, utilizzerai informazioni specifiche delle risorse per configurare la gestione di richieste e risposte di questo criterio.
- Un'estensione aggiunta, configurata e sottoposta a deployment nell'ambiente in cui verrà eseguito il deployment del proxy API. In altre parole, se vuoi utilizzare questo criterio per accedere a un particolare servizio Google Cloud, nel tuo ambiente deve esistere un'estensione di cui è stato eseguito il deployment per quel servizio. I dettagli di configurazione in genere includono le informazioni richieste per limitare l'accesso alla risorsa, ad esempio un ID progetto o un nome account.
Utilizzo delle norme ExtensionCallout in un PostClientFlow
Puoi richiamare la norma ExtensionCallout da PostClientFlow di un proxy API. PostClientFlow viene eseguito dopo che la risposta viene inviata al client richiedente, il che garantisce che tutte le metriche siano disponibili per il logging. Per maggiori dettagli sull'utilizzo di PostClientFlow, consulta il riferimento per la configurazione del proxy API.
Se vuoi utilizzare il criterio ExtensionCallout per chiamare l'estensione Google Cloud Logging da un PostClientFlow, assicurati che il flag features.allowExtensionsInPostClientFlow
sia impostato su true
nella tua organizzazione.
Se sei un cliente Apigee Edge for Public Cloud, il flag
features.allowExtensionsInPostClientFlow
è impostato sutrue
per impostazione predefinita.Se sei un cliente Apigee Edge per il cloud privato, utilizza l'API Aggiorna proprietà organizzazione per impostare il flag
features.allowExtensionsInPostClientFlow
sutrue
.
Tutte le limitazioni relative alle chiamate al criterio MessageLogging da PostClientFlow si applicano anche al criterio ExtensionCallout. Per saperne di più, consulta Note di utilizzo.
Riferimento elemento
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="false" enabled="true" name="Extension-Callout-1">
<DisplayName/>
<Connector/>
<Action/>
<Input/>
<Output/>
</ConnectorCallout>
Attributi <ConnectorCallout>
<ConnectorCallout name="Extension-Callout-1" continueOnError="false" enabled="true" async="false">
La tabella seguente descrive gli attributi comuni a tutti gli elementi principali dei criteri:
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
name |
Il nome interno della norma. Il valore dell'attributo Facoltativamente, utilizza l'elemento |
N/A | Obbligatorie |
continueOnError |
Impostalo su Imposta su |
false | Facoltativo |
enabled |
Imposta il criterio su Impostala su |
true | Facoltativo |
async |
Questo attributo è obsoleto. |
false | Deprecata |
Elemento <DisplayName>
Utilizzalo in aggiunta all'attributo name
per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.
<DisplayName>Policy Display Name</DisplayName>
Predefinito |
N/A Se ometti questo elemento, viene utilizzato il valore dell'attributo |
---|---|
Presenza | Facoltativo |
Tipo | Stringa |
Elemento <Action>
L'azione esposta dall'estensione che il criterio deve richiamare.
<Action>action-exposed-by-extension</Action>
Predefinito | Nessuno |
---|---|
Presenza | Obbligatorie |
Tipo | Stringa |
Ogni estensione espone il proprio insieme di azioni che forniscono l'accesso alle funzionalità della risorsa che l'estensione rappresenta. Puoi considerare un'azione come una funzione chiamata con questo criterio, che utilizza i contenuti dell'elemento <Input>
per specificare gli argomenti della funzione. La risposta dell'azione viene memorizzata nella variabile specificata con l'elemento <Output>
.
Per un elenco delle funzioni dell'estensione, consulta il riferimento relativo all'estensione che stai chiamando da questo criterio.
Elemento <Connector>
Il nome dell'estensione configurata da utilizzare. Si tratta del nome con ambito ambiente assegnato all'estensione quando è stata configurata per il deployment in un ambiente.
<Connector>name-of-configured-extension</Connector>
Predefinito | Nessuno |
---|---|
Presenza | Obbligatorie |
Tipo | Stringa |
Un'estensione contiene valori di configurazione che potrebbero essere diversi da un'altra estensione di cui è stato eseguito il deployment in base allo stesso pacchetto di estensioni. Questi valori di configurazione possono rappresentare importanti differenze nella funzionalità di runtime tra le estensioni configurate dallo stesso pacchetto, quindi assicurati di specificare l'estensione corretta da richiamare.
Elemento <Input>
JSON contenente il corpo della richiesta da inviare all'estensione.
<Input><![CDATA[ JSON-containing-input-values ]]></Input>
Predefinito | Nessuno |
---|---|
Presenza | Facoltativo o obbligatorio, a seconda dell'estensione. |
Tipo | Stringa |
Si tratta essenzialmente di un argomento per l'azione specificata con l'elemento <Action>
. Il valore dell'elemento <Input>
varierà in base all'estensione e all'azione che stai richiamando. Consulta la documentazione del pacchetto di estensioni per i dettagli sulle proprietà di ogni azione.
Tieni presente che sebbene molti valori dell'elemento <Input>
funzionino correttamente senza essere racchiusi in una sezione <![CDATA[]]>
, le regole di JSON consentono i valori che non verranno analizzati come XML. Come best practice, racchiudi il file JSON in una sezione CDATA
per evitare errori di analisi del runtime.
Il valore dell'elemento <Input>
è JSON con formato corretto le cui proprietà specificano i valori da inviare all'azione dell'estensione da richiamare. Ad esempio, l'azione log
dell'estensione Google Cloud Logging accetta valori che specificano il log in cui scrivere (logName
), i metadati da includere con la voce (metadata
) e il messaggio di log (data
). Ecco un esempio:
<Input><![CDATA[{
"logName" : "example-log",
"metadata" : {
"resource": {
"type": "global",
"labels": {
"project_id": "my-test"
}
}
},
"message" : "This is a test"
}]]></Input>
Utilizzo delle variabili di flusso in <Input>
JSON
Il contenuto di <Input>
viene considerato come un
modello di messaggio. Ciò significa che il nome di una variabile racchiuso tra parentesi graffe verrà sostituito in fase di esecuzione con il valore della variabile di riferimento.
Ad esempio, potresti riscrivere il blocco <Input>
precedente per utilizzare la variabile di flusso client.ip
per ottenere l'indirizzo IP del client che chiama il proxy API:
<Input><![CDATA[{
"logName" : "example-log",
"metadata" : {
"resource": {
"type": "global",
"labels": {
"project_id": "my-test"
}
}
},
"message" : "{client.ip}"
}]]></Input>
Se vuoi che un valore di proprietà nel JSON deve essere racchiuso tra virgolette al momento dell'esecuzione, assicurati di utilizzare le virgolette nel codice JSON. Questo vale anche quando specifichi una variabile di flusso come valore di una proprietà JSON da risolvere in fase di runtime.
Il seguente esempio di <Input>
include due riferimenti a variabili di flusso:
<Input><![CDATA[{
"logName" : "example-log",
"metadata" : {my.log.entry.metadata},
"message" : "{client.ip}"
}]]></Input>
In fase di runtime, i valori delle proprietà JSON verranno risolti come segue:
- Valore proprietà
logName
. Il valore letterale stringaexample-log
. - Valore della proprietà
metadata
: il valore della variabile di flussomy.log.entry.metadata
senza racchiudere le virgolette. Questo può essere utile se il valore della variabile è, a sua volta, JSON che rappresenta un oggetto. - Valore della proprietà
message
. Il valore della variabile di flussoclient.ip
tra virgolette.
Elemento <Output>
Nome di una variabile che memorizza la risposta dell'azione di estensione.
<Output>variable-name</Output> <!-- The JSON object inside the variable is parsed -->
o
<Output parsed="false">variable-name</Output> <!-- The JSON object inside the variable is raw, unparsed -->
Predefinito | Nessuno |
---|---|
Presenza | Facoltativo o obbligatorio, a seconda dell'estensione. |
Tipo | Oggetto o stringa analizzati, a seconda dell'impostazione dell'attributo parsed . |
Quando la risposta viene ricevuta, il valore della risposta viene inserito nella variabile specificata qui, dove potrai accedervi da un altro codice proxy API.
Gli oggetti delle risposte delle estensioni sono in formato JSON. Sono disponibili due opzioni per la modalità di gestione del JSON da parte del criterio:
- Analizzato (impostazione predefinita): il criterio analizza l'oggetto JSON e genera automaticamente variabili con i dati JSON. Ad esempio, se il codice JSON contiene
"messageId" : 12345;
e assegni alla variabile di output il nomeextensionOutput
, puoi accedere all'ID messaggio in altri criteri utilizzando la variabile{extensionOutput.messageId}
. - Non analizzata: la variabile di output contiene la risposta JSON non elaborata e non analizzata dell'estensione. Se vuoi, puoi comunque analizzare il valore della risposta in un passaggio separato utilizzando il criterio JavaScript.
Attributi <Output>
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
analizzato | Analizza l'oggetto JSON restituito dall'estensione, in modo che altri criteri possano accedere ai dati nell'oggetto JSON come variabili. | true | Facoltativo |
Variabili di flusso
Nessuna.
Codici di errore
Gli errori restituiti dai criteri di Apigee Edge seguono un formato coerente, come descritto in Riferimento agli errori dei criteri.
Questa sezione descrive i messaggi di errore e le variabili di flusso impostate quando questo criterio attiva un errore. Queste informazioni sono importanti per sapere se stai sviluppando regole di errore per un proxy. Per scoprire di più, vedi le informazioni relative agli errori delle norme e la gestione degli errori.
Errori di runtime
Questi errori possono verificarsi durante l'esecuzione del criterio.
Nome errore | Stato HTTP | Causa |
---|---|---|
Esecuzione non riuscita | 500 |
L'estensione risponde con un errore. |
Errori di deployment
Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.
Nome errore | Si verifica quando | Correggi |
---|---|---|
InvalidConnectorInstance |
L'elemento <Connector> è vuoto. |
build |
ConnectorInstanceDoesNotExists |
L'estensione specificata nell'elemento <Connector>
non esiste nell'ambiente. |
build |
InvalidAction |
Elemento <Action> nel criterio ExtensionCallout mancante o impostato su un valore vuoto. |
build |
AllowExtensionsInPostClientFlow |
È vietato avere le norme su callout callout in un flusso PostClient. | build |