Utilizzo delle variabili di flusso

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X. informazioni

Concettualmente, le variabili di flusso sono oggetti a cui è possibile accedere dall'interno dei criteri o delle utilità (come lo strumento Strumento Traccia). Consentono di mantenere lo stato associato a una transazione API elaborata da Apigee Edge.

Video

Il seguente video fornisce un'introduzione alle variabili di flusso:

Che cosa sono le variabili di flusso?

Le variabili di flusso esistono nel contesto di un flusso proxy API e monitorano lo stato in una transazione API nel modo in cui le variabili denominate monitorano lo stato in un programma software. Le variabili di flusso memorizzano informazioni quali:

• Indirizzo IP, intestazioni, percorso URL e payload inviati dall'app richiedente
• Informazioni di sistema come la data e l'ora in cui Edge riceve una richiesta
• Dati derivati dall'esecuzione di un criterio. Ad esempio, dopo l'esecuzione di un criterio che convalida un token OAuth, Edge crea variabili di flusso contenenti informazioni come il nome dell'applicazione richiedente.
• Informazioni sulla risposta del sistema di destinazione

Alcune variabili sono "integrate" in Edge e vengono compilate automaticamente ogni volta che viene ricevuta una richiesta API. Sono disponibili durante una transazione API. Puoi anche creare variabili personalizzate utilizzando criteri come il criterioAssignMessage o nel codice JavaScript, Node.js e Java.

Come vedrai, le variabili hanno un ambito e la posizione in cui sono accessibili dipende in parte da quando vengono create nel flusso proxy API. In generale, quando viene creata una variabile, è disponibile per tutti i criteri e il codice che verranno eseguiti in un secondo momento nel flusso di transazione API.

Come vengono utilizzate le variabili di flusso?

Le variabili di flusso vengono utilizzate nei criteri e nei flussi condizionali:

• I criteri possono recuperare lo stato dalle variabili di flusso e utilizzarle per svolgere le proprie attività.

  Ad esempio, un criterio VerificationJWT può recuperare il token per la verifica da una variabile di flusso e quindi eseguire la verifica su quest'ultima. Un altro esempio: un criterio JavaScript può recuperare le variabili di flusso e codificare i dati contenuti al loro interno.

• I flussi condizionali possono fare riferimento a variabili di flusso per indirizzare il flusso di un'API attraverso Edge, in modo simile al funzionamento di un'istruzione switch nella programmazione.

  Ad esempio, un criterio per restituire un errore può essere eseguito solo quando è impostata una determinata variabile di flusso. Infine, puoi ottenere e impostare le variabili di flusso in un'applicazione di destinazione Node.js.

Di seguito sono riportati alcuni esempi di utilizzo delle variabili in ciascuno di questi contesti.

Variabili di flusso nei criteri

Alcuni criteri utilizzano le variabili di flusso come input.

Ad esempio, il seguente criterioAssignMessage prende il valore della variabile di flusso client.ip e lo inserisce in un'intestazione della richiesta denominata My-Client-IP. Se viene aggiunto al flusso di richiesta, questo criterio imposta un'intestazione che viene passata alla destinazione del backend. Se impostata nel flusso di risposta, l'intestazione viene inviata di nuovo all'app client.

<AssignMessage name="set-ip-in-header">
    <AssignTo createNew="false" transport="http" type="request">request</AssignTo>
    <Set>
        <Headers>
            <Header name="My-Client-IP">{client.ip}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Per un altro esempio, quando viene eseguito un criterio per le quote, diverse variabili di flusso vengono completate con valori relativi ai criteri. Una di queste variabili è denominata ratelimit.my-quota-policy.used.count (dove my-quota-policy è il nome del criterio per le quote che ti interessa).

In seguito potresti eseguire un flusso condizionale con il messaggio "Se il conteggio della quota attuale è inferiore al 50% del limite massimo ed è compreso tra le 9:00 e le 17:00, applica una quota diversa". Questa condizione potrebbe dipendere dal valore del conteggio della quota attuale e da una variabile di flusso denominata system.time, che è una delle variabili Edge integrate.

Variabili di flusso nei flussi condizionali

I flussi condizionali valutano le variabili di flusso e consentono ai proxy di comportarsi in modo dinamico. Le condizioni vengono generalmente utilizzate per modificare il comportamento di flussi, passaggi e regole di route.

Ecco un flusso condizionale che valuta il valore della variabile request.verb in un passaggio del flusso proxy. In questo caso, se il verbo della richiesta è POST, viene eseguito il criterio VerificationAPIKey. Questo è un pattern comune utilizzato nelle configurazioni dei proxy API.

<PreFlow name="PreFlow">
    <Request>
        <Step>
            <Condition>request.verb equals "POST"</Condition>
            <Name>VerifyApiKey</Name>
        </Step>
    </Request>
</PreFlow>

A questo punto potresti chiederti da dove provengono variabili come request.verb, client.ip e system.time? Quando vengono create un'istanza e compilate con un valore? Per capire quando vengono create le variabili e quando sono disponibili, consulta Informazioni sull'ambito delle variabili di flusso.

Variabili di flusso nel codice JavaScript richiamate con il criterio JavaScript

Con i criteri JavaScript, puoi eseguire codice JavaScript nel contesto di un flusso proxy API. Il codice JavaScript eseguito da questo criterio utilizza il modello a oggetti JavaScript Apigee, che fornisce l'accesso al codice personalizzato per gli oggetti di richiesta, risposta e contesto associati al flusso proxy API su cui viene eseguito il codice. Ad esempio, questo codice imposta un'intestazione della risposta con il valore ottenuto dalla variabile di flusso target.name.

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"));

Questa tecnica di utilizzo di JavaScript per leggere e impostare le variabili è simile a quella che puoi svolgere con il criterioAssignMessage (mostrato in precedenza). È solo un altro modo per svolgere gli stessi tipi di attività su Edge. La chiave da ricordare è che il codice JavaScript eseguito dal criterio JavaScript ha accesso a tutte le variabili di flusso esistenti e incluse nell'ambito del flusso proxy API.

Variabili di flusso nel codice Node.js

Richiedendo il modulo apigee-access, puoi impostare e accedere alle variabili di flusso dall'interno del codice Node.js di cui è stato eseguito il deployment su Edge.

Ecco un semplice esempio in cui una variabile denominata custom.foo è impostata sul valore Bar. Una volta impostata, questa nuova variabile diventa disponibile per qualsiasi criterio o altro codice presente nel flusso del proxy dopo l'esecuzione del codice Node.js.

var http = require('http');
var apigee = require('apigee-access');

http.createServer(function (request, response) {
  apigee.setVariable(request, "custom.foo", "Bar");
  response.writeHead(200, {'Content-Type': 'text/plain'});
  response.end('Hello World\n');
}).listen(8124);

console.log('Server running at http://127.0.0.1:8124/');

Per saperne di più sull'utilizzo di apigee-access per lavorare con le variabili, consulta Accesso alle variabili di flusso in Node.js.

Informazioni sull'ambito delle variabili di flusso

L'ambito delle variabili è correlato al flusso o al "ciclo di vita" complessivo di una chiamata proxy API.

Visualizzazione del flusso di un proxy API

Per comprendere l'ambito delle variabili di flusso, è importante comprendere o visualizzare il modo in cui i messaggi passano attraverso un proxy API. Un proxy API è costituito da una serie di passaggi di elaborazione dei messaggi organizzati come flusso. A ogni passaggio di un flusso proxy, il proxy valuta le informazioni disponibili e decide cosa fare dopo. Durante la procedura, il proxy potrebbe eseguire il codice dei criteri o eseguire la diramazione condizionale.

La figura seguente illustra questa sequenza di flussi. Nota come i flussi sono composti da quattro segmenti principali: richiesta ProxyEndpoint, richiesta TargetEndpoint, risposta TargetEndpoint e risposta ProxyEndpoint.

Tieni presente questa struttura dei flussi quando iniziamo a esplorare le variabili di flusso nel resto di questo argomento.

Correlazione dell'ambito variabile al flusso proxy

Non appena riesci a visualizzare il modo in cui i messaggi passano attraverso un proxy, come descritto in precedenza, potrai iniziare a capire l'ambito della variabile. Per ambito, intendiamo il punto nel ciclo di vita del flusso proxy in cui viene creata l'istanza di una variabile.

Ad esempio, se al segmento di richiesta ProxyEndpoint è associato un criterio, questo non potrà accedere alle variabili con ambito al segmento di richieste TargetEndpoint. Il motivo è che il segmento di richiesta TargetEndpoint del flusso non è stato ancora eseguito, quindi il proxy API non ha avuto la possibilità di compilare le variabili in quell'ambito.

La seguente tabella elenca l'insieme completo degli ambiti delle variabili e indica quando nel flusso proxy diventano disponibili.

Ambito variabile	Dove vengono compilate queste variabili
richiesta proxy	Segmento di richiesta ProxyEndpoint
richiesta di destinazione	Segmento di richiesta TargetEndpoint
risposta target	Il segmento della risposta TargetEndpoint
risposta proxy	Il segmento della risposta ProxyEndpoint
sempre disponibile	Non appena il proxy riceve una richiesta. Queste variabili sono disponibili durante l'intero ciclo di vita del flusso proxy.

Ad esempio, esiste una variabile Edge integrata denominata client.ip. Questa variabile ha l'ambito "Richiesta proxy". Viene compilato automaticamente con l'indirizzo IP del client che ha chiamato il proxy. Viene compilato quando una richiesta raggiunge per la prima volta ProxyEndpoint e rimane disponibile per tutto il ciclo di vita del flusso proxy.

Esiste un'altra variabile integrata chiamata target.url. L'ambito di questa variabile è "richiesta di destinazione". Viene compilato nel segmento di richiesta TargetEndpoint con l'URL della richiesta inviato alla destinazione di backend. Se tenti di accedere a target.url nel segmento di richiesta ProxyEndpoint, riceverai un valore NULL. Se provi a impostare questa variabile prima che rientri nell'ambito, il proxy non fa nulla: non genera un errore e non imposta la variabile.

Ecco un semplice esempio che mostra come pensare all'ambito variabile. Supponi di voler copiare l'intero contenuto di un oggetto di richiesta (intestazioni, parametri, corpo) e assegnarlo al payload della risposta da restituire all'app chiamante. Per questa attività puoi utilizzare il criterioAssignMessage. Il codice del criterio è simile al seguente:

<AssignMessage name="CopyRequestToResponse">
    <AssignTo type="response" createNew="false">response</AssignTo>
    <Copy source="request"/>
</AssignMessage>

Questo criterio copia semplicemente l'oggetto request e lo assegna all'oggetto response. Ma dove deve essere posizionato questo criterio nel flusso del proxy? La risposta è che deve essere inserita nella risposta TargetEndpoint, perché l'ambito della variabile di risposta è "risposta target".

Fare riferimento alle variabili di flusso

Tutte le variabili integrate in Apigee Edge seguono una convenzione di denominazione con la notazione dei punti. Questa convenzione semplifica la determinazione dello scopo della variabile. Ad esempio system.time.hour e request.content.

Apigee si riserva diversi prefissi per organizzare le variabili pertinenti in modo appropriato. Questi prefissi includono:

• request
• response
• system
• target

Per fare riferimento a una variabile in un criterio, racchiudila tra parentesi graffe. Ad esempio, il seguente criterioAssignMessage prende il valore della variabile client.ip e lo inserisce in un'intestazione della richiesta denominata Client-IP.

<AssignMessage name="set-ip-in-header">
    <AssignTo createNew="false" transport="http" type="request">request</AssignTo>
    <Set>
        <Headers>
            <Header name="Client-IP">{client.ip}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Nei flussi condizionali, le parentesi graffe non sono necessarie. La seguente condizione di esempio valuta la variabile request.header.accept:

<Step>
    <Condition>request.header.accept = "application/json"</Condition>
    <Name>XMLToJSON</Name>
</Step>

Puoi anche fare riferimento alle variabili di flusso nel codice JavaScript e Java. Per ulteriori informazioni, vedi:

• Lavorare con le variabili in JavaScript
• Accesso alle variabili di flusso in Node.js
• Norme relative a JavaScript

Tipo di dati delle variabili di flusso

Ogni proprietà di una variabile di flusso ha un tipo di dati ben definito, ad esempio Stringa, Lungo, Numero intero, Booleano o Raccolta. Puoi trovare i tipi di dati elencati nel riferimento per le variabili di flusso. Per le variabili create da un criterio, fai riferimento all'argomento specifico di riferimento ai criteri per informazioni sui tipi di dati.

Le variabili che crei manualmente presuppongono il tipo specificato al momento della creazione e dipendono dai tipi di valori consentiti. Ad esempio, le variabili create nel codice Node.js sono limitate a Numero, Stringa, Booleano, nullo o Non definito.

Utilizzo delle variabili di flusso nei criteri

Molti criteri creano variabili di flusso nell'ambito della normale esecuzione. Il riferimento ai criteri documenta tutte queste variabili specifiche per le norme.

Mentre utilizzi i proxy e i criteri, assicurati di consultare il riferimento alle norme per scoprire quali variabili vengono create e per cosa vengono utilizzate. Ad esempio, i criteri per le quote crea un insieme di variabili contenenti informazioni su conteggi e limiti delle quote, data di scadenza e così via.

Alcune variabili dei criteri sono utili per il debug. Ad esempio, puoi utilizzare lo strumento Traccia per vedere quali variabili sono state impostate in una determinata istanza in un flusso proxy.

Il criterio ExtractVariables consente di completare le variabili personalizzate con i dati estratti dai messaggi. Puoi estrarre parametri di query, intestazioni e altri dati. Ad esempio, puoi analizzare i messaggi di richiesta e risposta utilizzando pattern per estrarre dati specifici dai messaggi.

Nell'esempio seguente, la funzione Estrai variabili analizza un messaggio di risposta e archivia dati specifici ricavati dalla risposta. Il criterio crea due variabili personalizzate, geocoderesponse.latitude e geocoderesponse.longitude, a cui assegna valori.

<ExtractVariables name="ParseGeocodingResponse">
  <Source>response</Source>
  <VariablePrefix>geocoderesponse</VariablePrefix>
  <JSONPayload>
    <Variable name="latitude">
      <JSONPath>$.results[0].geometry.location.lat</JSONPath>
    </Variable>
    <Variable name="longitude">
      <JSONPath>$.results[0].geometry.location.lng</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

Anche in questo caso, tieni presente che molti criteri creano automaticamente variabili. Puoi accedere a queste variabili nel contesto del flusso proxy, che sono documentate nel riferimento alle norme in ogni singolo argomento delle norme.

Utilizzo delle variabili di flusso nel codice JavaScript

Puoi accedere alle variabili e impostarle direttamente nel codice JavaScript in esecuzione nel contesto di un proxy API. Tramite il modello a oggetti JavaScript di Apigee, l'esecuzione di JavaScript su Edge ha accesso diretto alle variabili di flusso proxy.

Per accedere alle variabili nel codice JavaScript, richiama i metodi getter/setter su uno di questi oggetti:

• context
• proxyRequest
• proxyResponse
• targetRequest
• targetResponse

Come puoi vedere, questi riferimenti agli oggetti corrispondono ai segmenti familiari del modello di flusso proxy, come spiegato in precedenza nella sezione Visualizzazione del flusso di un proxy API.

L'oggetto context corrisponde alle variabili disponibili "a livello globale", come le variabili di sistema. Ad esempio, puoi chiamare getVariable() sull'oggetto context per ottenere l'anno in corso:

var year = context.getVariable('system.time.year');

Allo stesso modo, puoi chiamare setVariable() per impostare il valore di una variabile personalizzata o di qualsiasi variabile pronta all'uso scrivibile. Qui, creiamo una variabile personalizzata denominata organization.name.myorg e le assegniamo un valore.

var org = context.setVariable('organization.name.myorg', value);

Poiché questa variabile viene creata con l'oggetto context, sarà disponibile per tutti i segmenti di flusso (essenzialmente, è come creare una variabile globale).

Puoi anche ottenere/impostare variabili di flusso proxy nel codice Java eseguito con il criterio JavaCallout.

Accesso alle variabili di flusso nelle applicazioni Node.js

Puoi ottenere, impostare ed eliminare variabili di flusso dal codice Node.js di cui è stato eseguito il deployment su Edge. Tutto ciò che devi fare è "richiedere" il modulo apigee-access nel codice. Per maggiori dettagli, vedi Accesso alle variabili di flusso in Node.js.

Cosa devi ricordare

Di seguito sono riportati alcuni aspetti importanti da ricordare sulle variabili di flusso:

• Alcune variabili " pronte all'uso" vengono create e compilate automaticamente dal proxy stesso. Questi sono indicati nel riferimento alle variabili di flusso.
• Puoi creare variabili personalizzate da utilizzare nel flusso del proxy. È possibile creare variabili utilizzando criteri come i criteri AssegnaMessage e JavaScript e nel codice Node.js.
• Le variabili hanno un ambito. Ad esempio, alcune variabili vengono compilate automaticamente quando il primo proxy riceve una richiesta da un'app. Altre variabili vengono compilate nel segmento del flusso di risposta del proxy. Queste variabili di risposta rimangono non definite fino all'esecuzione del segmento di risposta.
• Quando i criteri vengono eseguiti, possono creare e compilare variabili specifiche per i criteri. La documentazione relativa a ciascun criterio elenca tutte queste variabili pertinenti specifiche per i criteri.
• In genere, i flussi condizionali valutano una o più variabili. Devi comprendere le variabili per creare flussi condizionali.
• Molti criteri utilizzano le variabili come input o output. Può darsi che una variabile creata da un criterio venga utilizzata in seguito da un altro.
• Puoi ottenere e impostare molte variabili di flusso da Node.js utilizzando direttamente JavaScript (e il nostro modello a oggetti JavaScript) o il criterio JavaCallout, che esegue il codice su Edge.

Esempi di codice correlati

Gli esempi di proxy API sono su GitHub e sono facili da scaricare e utilizzare. Consulta Utilizzo dei proxy API di esempio per informazioni sul download e sull'utilizzo degli esempi. Consulta l'elenco degli esempi per una descrizione degli esempi di proxy API e della loro funzione.

Esempi di proxy che presentano l'utilizzo di variabili e dell'elaborazione delle variabili includono:

• Variabili: mostra come estrarre e impostare variabili in base al trasporto e ai contenuti dei messaggi JSON e XML.
• policy-mashup-cookbook: un'applicazione completa che utilizza la composizione dei criteri per chiamare due API pubbliche, combina i risultati e genera una risposta avanzata per l'app client. Per saperne di più su questo esempio, consulta la sezione Utilizzo della composizione dei criteri.
• conditional-policy: implementa una semplice applicazione condizionale dei criteri in base ai valori delle variabili.

Argomenti correlati

• Tutte le variabili che vengono compilate automaticamente in un proxy API sono elencate nel riferimento sulle variabili di flusso. Il riferimento elenca anche il tipo e l'ambito di ogni variabile.
• Se vuoi sapere quali variabili vengono compilate da un criterio specifico, fai riferimento all'argomento di riferimento per il criterio. Ad esempio, consulta Variabili di flusso nel riferimento Criteri per le quote.