Norme relative ai callout estensioni

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

Utilizza il criterio 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 costituita da servizi 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, vedi Che cosa sono le estensioni? Per un tutorial introduttivo, vedi Tutorial: aggiungere e utilizzare un'estensione.

Prima di accedere a un'estensione dal criterio ExtensionCallout, devi aggiungere, configurare e implementare l'estensione da un pacchetto di estensioni già installato nella tua organizzazione Apigee Edge.

Esempi

Di seguito è riportato un esempio di policy 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 Panoramica del riferimento alle estensioni.

Informazioni sulla policy ExtensionCallout

Utilizza il criterio ExtensionCallout quando vuoi utilizzare un'estensione configurata per accedere a una risorsa esterna da un proxy API.

Prima di utilizzare questo criterio, devi:

• Alcuni dettagli sulla risorsa esterna a cui vuoi accedere da questa policy. Questi dettagli saranno specifici per la risorsa. Ad esempio, se il criterio accederà al tuo database Cloud Firestore, dovrai conoscere il nome della raccolta e del documento che vuoi creare o a cui vuoi accedere. In genere, utilizzerai informazioni specifiche per le risorse per configurare la gestione delle richieste e delle risposte di questa policy.
• Un'estensione aggiunta, configurata e di cui è stato eseguito il deployment all'ambiente in cui verrà eseguito il deployment del proxy API. In altre parole, se intendi utilizzare questa policy per accedere a un determinato 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 della policy ExtensionCallout in un PostClientFlow

Puoi richiamare il criterio ExtensionCallout da PostClientFlow di un proxy API. PostClientFlow viene eseguito dopo l'invio della risposta al client richiedente, il che garantisce che tutte le metriche siano disponibili per la registrazione. Per informazioni dettagliate sull'utilizzo di PostClientFlow, consulta Riferimento alla configurazione del proxy API.

Se vuoi utilizzare la policy 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 di Apigee Edge per il cloud pubblico, il flag features.allowExtensionsInPostClientFlow è impostato su true per impostazione predefinita.

• Se sei un cliente di Apigee Edge for Private Cloud, utilizza l'API Update organization properties per impostare il flag features.allowExtensionsInPostClientFlow su true.

Tutte le limitazioni relative alla chiamata delle norme MessageLogging da PostClientFlow si applicano anche alle norme ExtensionCallout. Per saperne di più, consulta la sezione Note sull'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 del criterio:

&lt;DisplayName&gt; elemento

Da utilizzare in aggiunta all'attributo name per etichettare il criterio in editor proxy della UI di gestione con un nome diverso e in linguaggio naturale.

<DisplayName>Policy Display Name</DisplayName>

Elemento <Action>

L'azione esposta dall'estensione che deve essere richiamata dal criterio.

<Action>action-exposed-by-extension</Action>

Ogni estensione espone il proprio insieme di azioni che forniscono l'accesso alle funzionalità della risorsa che rappresenta. Puoi considerare un'azione come una funzione che chiami con questa policy, utilizzando 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 per l'estensione che stai chiamando da questa policy.

Elemento <Connector>

Il nome dell'estensione configurata da utilizzare. Questo è il nome con ambito ambiente assegnato all'estensione quando è stata configurata per il deployment in un ambiente.

<Connector>name-of-configured-extension</Connector>

Un'estensione ha valori di configurazione che potrebbero differire da un'altra estensione di cui è stato eseguito il deployment in base allo stesso pacchetto di estensione. Questi valori di configurazione possono rappresentare differenze importanti 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>

Si tratta essenzialmente di un argomento per l'azione specificata con l'elemento <Action>. Il valore dell'elemento <Input> varia a seconda dell'estensione e dell'azione che stai richiamando. Per informazioni dettagliate sulle proprietà di ogni azione, consulta la documentazione del pacchetto di estensioni.

Tieni presente che, sebbene molti valori degli elementi <Input> funzionino correttamente senza essere inclusi come sezione <![CDATA[]]>, le regole di JSON consentono valori che non verranno analizzati come XML. Come best practice, racchiudi il JSON in una sezione CDATA per evitare errori di analisi in fase di runtime.

Il valore dell'elemento <Input> è un JSON ben formato le cui proprietà specificano i valori da inviare all'azione di estensione da richiamare. Ad esempio, l'estensione Google Cloud Logging Extension l'azione log accetta valori che specificano il log in cui scrivere (logName), i metadati da includere nella 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 trattato come un modello di messaggio. Ciò significa che un nome di variabile racchiuso tra parentesi graffe verrà sostituito in fase di runtime con il valore della variabile a cui viene fatto 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 sia racchiuso tra virgolette in fase di runtime, assicurati di utilizzare le virgolette nel codice JSON. Ciò vale anche quando specifichi una variabile di flusso come valore della 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 nel seguente modo:

• Valore della proprietà logName: il valore letterale stringa example-log.
• Valore della proprietà metadata: il my.log.entry.metadatavalore della variabile di flusso senza virgolette. Questa opzione può essere utile se il valore della variabile è a sua volta un JSON che rappresenta un oggetto.
• Valore della proprietà message: il valore della variabile di flusso client.ip con virgolette di chiusura.

Elemento <Output>

Nome di una variabile che memorizza la risposta dell'azione dell'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 -->

Quando viene ricevuta la risposta, il valore di risposta viene inserito nella variabile specificata qui, dove puoi accedervi da altro codice del proxy API.

Gli oggetti di risposta dell'estensione sono in formato JSON. Esistono due opzioni per la gestione del JSON da parte della policy:

• Analizzata (impostazione predefinita): la policy analizza l'oggetto JSON e genera automaticamente variabili con i dati JSON. Ad esempio, se il file JSON contiene "messageId" : 12345; e assegni alla variabile di output il nome extensionOutput, puoi accedere a questo ID messaggio in altre norme utilizzando la variabile {extensionOutput.messageId}.
• Non analizzata: la variabile di output contiene la risposta JSON non analizzata e non elaborata dell'estensione. Se vuoi, puoi comunque analizzare il valore della risposta in un passaggio separato utilizzando il criterio JavaScript.

Attributi <Output>

Variabili di flusso

Nessuno.

Codici di errore

Gli errori restituiti dalle policy Apigee Edge seguono un formato coerente, come descritto in Riferimento agli errori delle policy.

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.

Errori di deployment

Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.