Norme relative ai callout estensioni

Stai visualizzando la documentazione di Apigee Edge.
Vai alla sezione Documentazione di Apigee X. Informazioni

Utilizza il criterio ExtensionCallout per incorporare un'estensione in un proxy API.

Un'estensione consente di accedere 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 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 nella tua organizzazione Apigee Edge.

Esempi

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 il Tutorial: utilizzo delle estensioni per un tutorial completo utilizzando l'estensione Cloud Logging.

Per esempi di tutte le estensioni disponibili, consulta la panoramica dei riferimenti per le estensioni.

Informazioni sulle norme relative ai callout estensioni

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

Per poter utilizzare questo criterio, è necessario quanto segue:

• 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 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 sulle risorse per configurare la gestione delle richieste e delle 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 utilizzerai questo criterio per accedere a un particolare servizio Google Cloud, è necessario che nel tuo ambiente esista un'estensione di cui è stato eseguito il deployment per quel servizio. I dettagli di configurazione in genere includono le informazioni richieste per restringere accesso alla risorsa, ad esempio un ID progetto o un nome account.

Utilizzo del criterio 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, assicurando la disponibilità di tutte le metriche per il logging. Per maggiori dettagli sull'utilizzo di PostClientFlow, consulta Riferimento alla 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 è impostato su true nella tua organizzazione.

• Se sei un cliente Apigee Edge per il cloud pubblico, Il flag features.allowExtensionsInPostClientFlow è impostato su true per impostazione predefinita.

• Se sei un cliente Apigee Edge per il cloud privato, utilizza API Aggiorna le proprietà dell'organizzazione per impostare il flag features.allowExtensionsInPostClientFlow su true.

Tutte le restrizioni sulla chiamata al criterio MessageLogging da PostClientFlow si applicano anche alle norme EstensioneCallout. Per saperne di più, consulta le 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>

<ConnectorCallout> attributi

<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:

<DisplayName> 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>

<Action> elemento

L'azione esposta all'estensione che il criterio deve richiamare.

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

Ogni estensione espone il proprio insieme di azioni che forniscono accesso alla funzionalità della risorsa rappresentata. Un'azione può essere considerata una funzione che chiami con questo criterio, utilizzando i contenuti dell'elemento <Input> per specificare gli argomenti della funzione. La risposta dell'azione viene archiviata nella variabile specificata con l'elemento <Output>.

Per un elenco delle funzioni dell'estensione, consulta il riferimento dell'estensione che chiami da questo criterio.

<Connettore> elemento

Il nome dell'estensione configurata da utilizzare. Si tratta del nome con ambito a livello di ambiente dato l'estensione al momento della configurazione 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 dell'estensione. 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.

&lt;Input&gt; elemento

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> varierà a seconda dell'estensione e dell'azione che stai richiamando. Per informazioni dettagliate sulle proprietà di ogni azione, consulta la documentazione del pacchetto di estensione.

Tieni presente che, anche se molti valori dell'elemento <Input> funzioneranno correttamente senza essere racchiusi in una sezione <![CDATA[]]>, le regole di JSON consentono valori che non vengono analizzati come XML. Come best practice, racchiudi il file JSON come sezione CDATA per evitare errori di analisi del runtime.

Il valore dell'elemento <Input> è in un formato JSON le cui proprietà specificano dei valori da inviare all'azione dell'estensione da richiamare. Ad esempio, Estensione Google Cloud Logging l'azione log dell'estensione accetta valori che specificano il log in cui scrivere (logName), 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 JSON <Input>

I contenuti di <Input> vengono trattati come 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 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 il valore di una proprietà nel file JSON venga racchiuso tra virgolette in fase di runtime, assicurati di utilizzare le virgolette nel codice JSON. Questo vale anche se specifichi una variabile di flusso come valore della proprietà JSON da risolvere in fase di runtime.

Il seguente esempio di <Input> include due riferimenti alle 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 della proprietà logName: il valore letterale della stringa example-log.
• Valore della proprietà metadata: il valore della variabile di flusso my.log.entry.metadata senza 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 flusso client.ip con virgolette.

&lt;Output&gt; elemento

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 -->

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

Gli oggetti di risposta delle estensioni sono in formato JSON. Sono disponibili due opzioni per la gestione del file 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 file JSON contiene "messageId" : 12345; e assegni alla variabile di output il nome extensionOutput, puoi accedere a quell'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.

&lt;Output&gt; Attributi

Variabili di flusso

Nessuno.

Codici di errore

Gli errori restituiti dai criteri di Apigee Edge seguono un formato coerente, come descritto in Riferimento agli errori relativi ai criteri.

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules for a proxy. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.