Utilizzo delle variabili di flusso

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

A livello concettuale, le variabili di flusso sono oggetti a cui puoi accedere dai tuoi criteri o dalle tue utilità (ad esempio lo strumento di traccia). Ti consentono di mantenere lo stato associato a una transazione API elaborata da Apigee Edge.

Che cosa sono le variabili di flusso?

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

  • L'indirizzo IP, le intestazioni, il percorso dell'URL e il payload inviati dall'app che effettua la richiesta
  • Informazioni di sistema, ad esempio la data e l'ora in cui Edge riceve una richiesta
  • Dati derivati quando viene eseguito un criterio. Ad esempio, dopo l'esecuzione di un criterio che convalida un token OAuth, Edge crea variabili di flusso che contengono 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 l'intera transazione API. Puoi anche creare le tue variabili personalizzate utilizzando criteri come il criterio Assegna messaggio o in codice JavaScript, Node.js e Java.

Come vedrai, le variabili hanno un ambito e la loro accessibilità dipende in parte da quando vengono create nel flusso del proxy API. In generale, quando viene creata una variabile, questa è disponibile per tutti i criteri e il codice che vengono eseguiti successivamente nel flusso di transazione dell'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 utilizzarlo per svolgere il proprio lavoro.

    Ad esempio, un criterio VerifyJWT può recuperare il token da verificare da una variabile di flusso ed eseguire la verifica. Un altro esempio è un regolamento JavaScript che può recuperare le variabili di flusso e codificare i dati contenuti al loro interno.

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

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

Vediamo alcuni esempi di come le variabili vengono utilizzate in ciascuno di questi contesti.

Variabili di flusso nei criteri

Alcune norme accettano come input le variabili di flusso.

Ad esempio, il seguente criterio AssignMessage 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 della richiesta, questo criterio imposta un'intestazione che viene passata alla destinazione del backend. Se impostato nel flusso di risposta, l'intestazione viene inviata nuovamente 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>

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

In seguito, potresti eseguire un flusso condizionale con il messaggio "Se il conteggio delle quote attuale è inferiore al 50% del massimo ed è compreso tra le 9:00 e le 17:00, applica una quota diversa". Questa condizione potrebbe dipendere dal valore del conteggio corrente della quota e da una variabile di flusso chiamata system.time, che è una delle variabili di 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 in genere utilizzate per modificare il comportamento di flussi, passaggi e regole di routing.

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 VerifyAPIKey. Questo è uno schema comune utilizzato nelle configurazioni proxy API.

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

Ora potresti chiederti da dove provengono variabili come request.verb, client.ip e system.time. Quando vengono attivati e completati con un valore? Per aiutarti a capire quando vengono create le variabili e quando sono disponibili, consulta Informazioni sull'ambito delle variabili di flusso.

Variabili di flusso nel codice JavaScript chiamato con il criterio JavaScript

Con il criterio JavaScript, puoi eseguire codice JavaScript nel contesto di un flusso proxy API. Il codice JavaScript eseguito da questo criterio utilizza il modello di oggetti JavaScript Apigee, che fornisce l'accesso con codice personalizzato agli oggetti di richiesta, risposta e contesto associati al flusso proxy API in 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 per usare JavaScript per leggere e impostare variabili è simile al lavoro che puoi svolgere con il criterioAssignMessage (mostrato in precedenza). È solo un altro modo per eseguire le stesse operazioni su Edge. La cosa importante da ricordare è che il codice JavaScript eseguito dal criterio JavaScript ha accesso a tutte le variabili di flusso esistenti e in ambito all'interno del flusso del proxy API.

Variabili di flusso nel codice Node.js

Se richiedi il modulo apigee-access, puoi impostare e accedere alle variabili di flusso dal codice Node.js di cui è stato eseguito il deployment in Edge.

Ecco un semplice esempio in cui una variabile denominata custom.foo viene impostata sul valore Bar. Una volta impostata, questa nuova variabile diventa disponibile per qualsiasi criterio o altro codice presente nel flusso 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 scoprire di più sull'utilizzo di apigee-access per lavorare con le variabili, consulta Accedere alle variabili di flusso in Node.js.

Informazioni sull'ambito delle variabili di flusso

L'ambito della variabile è correlato al flusso o al "ciclo di vita" complessivo di una chiamata del 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. In ogni passaggio di un flusso proxy, il proxy valuta le informazioni a sua disposizione e decide cosa fare dopo. Durante il percorso, il proxy può eseguire codice di criteri o eseguire ramificazioni condizionali.

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

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

Come l'ambito della variabile è correlato al flusso del proxy

Non appena riesci a visualizzare il flusso dei messaggi attraverso un proxy, come descritto in precedenza, puoi iniziare a comprendere l'ambito variabile. Per ambito si intende il punto nel ciclo di vita del flusso proxy in cui viene eseguita l'inizializzazione di una variabile.

Ad esempio, se hai un criterio collegato al segmento di richiesta ProxyEndpoint, questo criterio non potrà accedere alle variabili con ambito nel segmento di richiesta 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 tabella seguente elenca l'insieme completo di ambiti delle variabili e indica quando diventano disponibili nel flusso del proxy.

Ambito della variabile Dove vengono completate queste variabili
richiesta proxy Il segmento di richiesta ProxyEndpoint
richiesta target Il segmento di richiesta TargetEndpoint
risposta target Il segmento di risposta TargetEndpoint
risposta proxy Il segmento di risposta ProxyEndpoint
sempre disponibili Non appena il proxy riceve una richiesta. Queste variabili sono disponibili durante tutto il ciclo di vita del flusso proxy.

Ad esempio, esiste una variabile Edge integrata chiamata client.ip. Questa variabile ha 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 l'intero ciclo di vita del flusso proxy.

C'è un'altra variabile integrata chiamata target.url. L'ambito di questa variabile è "richiesta target". Viene compilato nel segmento della richiesta TargetEndpoint con l'URL della richiesta inviato al target di backend. Se provi ad 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 considerare l'ambito delle variabili. Supponi di voler copiare l'intero contenuto di un oggetto della richiesta (intestazioni, parametri, corpo) e assegnarlo al payload della risposta da restituire all'app chiamante. Puoi utilizzare il criterioAssignMessage per questa attività. Il codice delle norme ha il seguente aspetto:

<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 posizionata sulla 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 puntini. Questa convenzione semplifica la determinazione dello scopo della variabile. Ad esempio system.time.hour e request.content.

Apigee riserva vari prefissi per organizzare correttamente le variabili pertinenti. 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:

Tipo di dati delle variabili di flusso

Ogni proprietà di una variabile di flusso ha un tipo di dati ben definito, come Stringa, Long, Integer, Booleano o Raccolta. Puoi trovare i tipi di dati elencati nel Riferimento per le variabili di flusso. Per le variabili create da un criterio, consulta l'argomento di riferimento del criterio specifico per informazioni sui tipi di dati.

Le variabili create 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, null o non definito.

Utilizzare le variabili di flusso nei criteri

Molti criteri creano variabili di flusso durante la normale esecuzione. La pagina Documentazione dei criteri descrive tutte queste variabili specifiche dei criteri.

Quando utilizzi proxy e criteri, assicurati di consultare il riferimento al criterio per scoprire quali variabili vengono create e per cosa vengono utilizzate. Ad esempio, i criteri per le quote creano un insieme di variabili contenenti informazioni su conteggio 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 di traccia per vedere quali variabili sono state impostate in una determinata istanza in un flusso proxy.

Il criterio ExtractVariables ti consente di compilare 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, Estrai variabili analizza un messaggio di risposta e memorizza dati specifici ricavati dalla risposta. Il criterio crea due variabili personalizzate, geocoderesponse.latitude e geocoderesponse.longitude, e li assegna ai 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>

Tieni presente che molti criteri creano automaticamente variabili. Puoi accedere a queste variabili all'interno del contesto del flusso proxy e sono documentate nella sezione di riferimento dei criteri in ogni singolo argomento dei criteri.

Utilizzare le variabili di flusso nel codice JavaScript

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

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

  • context
  • proxyRequest
  • proxyResponse
  • targetRequest
  • targetResponse

Come puoi vedere, questi riferimenti agli oggetti mappano ai segmenti familiari del modello di flusso del proxy, come spiegato in precedenza in Visualizzare il 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 corrente:

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

Analogamente, puoi chiamare setVariable() per impostare il valore di una variabile personalizzata o di qualsiasi variabile scrivibile pronta all'uso. 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 (in pratica, è come creare una variabile globale).

Puoi anche ottenere/impostare le variabili del flusso del proxy nel codice Java che esegui con il criterio JavaCallout.

Accedere alle variabili di flusso nelle applicazioni Node.js

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

Che cosa devi ricordare

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

  • Alcune variabili "out-of-the-box" vengono create e compilate automaticamente dal proxy stesso. Queste sono documentate nella sezione Riferimento alle variabili di flusso.
  • Puoi creare variabili personalizzate disponibili per l'utilizzo nel flusso proxy. È possibile creare variabili utilizzando criteri come AssignMessage policy e Criterio JavaScript, e nel codice Node.js.
  • Le variabili hanno un ambito. Ad esempio, alcune variabili vengono completate automaticamente quando il primo proxy riceve una richiesta da un'app. Altre variabili vengono completate nel segmento del flusso di risposta del proxy. Queste variabili di risposta rimangono non definite fino all'esecuzione del segmento di risposta.
  • Quando vengono eseguiti, i criteri possono creare e compilare variabili specifiche. La documentazione di ciascun criterio elenca tutte queste variabili specifiche del criterio pertinenti.
  • I flussi condizionali in genere valutano una o più variabili. Devi conoscere le variabili se vuoi creare flussi condizionali.
  • Molti criteri utilizzano le variabili come input o output. È possibile che una variabile creata da un criterio venga utilizzata in un secondo momento da un altro.
  • Puoi ottenere e impostare molte variabili di flusso da Node.js utilizzando JavaScript puro (e il nostro modello di oggetti JavaScript) o il criterio JavaCallout, che esegue il codice su Edge.

Esempi di codice correlati

Gli esempi di proxy API sono disponibili su GitHub e sono facili da scaricare e utilizzare. Consulta la sezione Utilizzare i proxy API di esempio per informazioni su come scaricare e utilizzare gli esempi. Consulta l'elenco dei sample per una descrizione dei sample proxy API e della loro funzionalità.

Alcuni esempi di proxy che utilizzano le variabili e il relativo trattamento sono:

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

Argomenti correlati