Questa pagina è stata tradotta dall'API Cloud Translation.

Norme relative ai callout estensioni

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 su true 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 su true.

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 `name` può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri. Facoltativamente, utilizza l'elemento `<DisplayName>` per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.	N/A	Obbligatorie
`continueOnError`	Impostalo su `false` per restituire un errore in caso di errore di un criterio. Questo è il comportamento previsto per la maggior parte dei criteri. Imposta su `true` per fare in modo che l'esecuzione del flusso continui anche in caso di errore di un criterio.	false	Facoltativo
`enabled`	Imposta il criterio su `true` per applicare il criterio. Impostala su `false` per disattivare il criterio. Il criterio non verrà applicato anche se rimane associato a un flusso.	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

Predefinito	N/A Se ometti questo elemento, viene utilizzato il valore dell'attributo `name` del criterio.
Presenza	Facoltativo
Tipo	Stringa

N/A

Se ometti questo elemento, viene utilizzato il valore dell'attributo name del criterio.

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 stringa example-log.
Valore della proprietà metadata: il valore della variabile di flusso my.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 flusso client.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 -->

<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 nome extensionOutput, 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.
`ConnectorInstanceDoesNotExists`	L'estensione specificata nell'elemento `<Connector>` non esiste nell'ambiente.
`InvalidAction`	Elemento `<Action>` nel criterio ExtensionCallout mancante o impostato su un valore vuoto.
`AllowExtensionsInPostClientFlow`	È vietato avere le norme su callout callout in un flusso PostClient.