Utilizzo delle variabili di flusso

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

A livello concettuale, le variabili di flusso sono oggetti a cui puoi accedere dalle tue policy o utilità (ad esempio lo strumento Trace tool). Ti consentono di mantenere lo stato associato a un 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 tengono traccia dello stato in una transazione API, proprio come le variabili denominate tengono traccia dello 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 richiedente
  • Informazioni di sistema come la data e l'ora in cui Edge riceve una richiesta
  • Dati derivati quando viene eseguita una policy. Ad esempio, dopo l'esecuzione di una policy 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 una transazione API. Puoi anche creare le tue variabili personalizzate utilizzando policy come AssignMessage o nel codice JavaScript, Node.js e Java.

Come vedrai, le variabili hanno un ambito e la loro accessibilità dipende in parte dal momento in cui vengono create nel flusso del proxy API. In generale, quando viene creata una variabile, è disponibile per tutte le policy e il codice eseguiti in un secondo momento nel flusso della transazione API.

Come vengono utilizzate le variabili di flusso?

Le variabili di flusso vengono utilizzate nelle policy e nei flussi condizionali:

  • Le policy possono recuperare lo stato dalle variabili di flusso e utilizzarle per svolgere il proprio lavoro.

    Ad esempio, una policy VerifyJWT può recuperare il token da verificare da una variabile di flusso e quindi eseguire la verifica. Un altro esempio: una policy JavaScript può recuperare le variabili di flusso e codificare i dati contenuti in queste variabili.

  • 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 nella programmazione.

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

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

Variabili di flusso nelle policy

Alcune policy accettano le variabili di flusso come input.

Ad esempio, la seguente policy AssignMessage prende il valore della variabile di flusso client.ip e lo inserisce in un'intestazione della richiesta denominata My-Client-IP. Se aggiunta al flusso della richiesta, questa policy imposta un'intestazione che viene passata alla destinazione di backend. Se impostata sul flusso della risposta, l'intestazione viene inviata 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: quando viene eseguita una policy Quota, diverse variabili di flusso vengono compilate con valori correlati alla policy. Una di queste variabili è denominata ratelimit.my-quota-policy.used.count (dove my-quota-policy è il nome della policy Quota di cui ti interessa).

In un secondo momento potresti eseguire un flusso condizionale che dice: "Se il conteggio della quota 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 della quota attuale e da una variabile di flusso denominata system.time, che è una delle variabili integrate di Edge.

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

Ecco un flusso condizionale che valuta il valore della variabile request.verb in un passaggio del flusso del proxy. In questo caso, se il verbo della richiesta è POST, viene eseguita la policy VerifyAPIKey. Si tratta di 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>

Ora, potresti chiederti da dove provengono variabili come request.verb, client.ip, e system.time. Quando vengono create e compilate con un valore? Per capire quando vengono create le variabili e quando sono disponibili, consulta Comprendere l'ambito delle variabili di flusso scope.

Variabili di flusso nel codice JavaScript chiamato con la policy JavaScript

Con la policy JavaScript, puoi eseguire codice JavaScript dal contesto di un flusso di proxy API. Il codice JavaScript eseguito da questa policy utilizza il modello oggetto JavaScript di Apigee , che fornisce al codice personalizzato l'accesso agli oggetti di richiesta, risposta e contesto associati al flusso del 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 di utilizzo di JavaScript per leggere e impostare le variabili è simile al lavoro che puoi svolgere con la policy AssignMessage (mostrata in precedenza). È solo un altro modo per ottenere gli stessi risultati su Edge. La cosa fondamentale da ricordare è che il codice JavaScript eseguito dalla policy JavaScript ha accesso a tutte le variabili di flusso esistenti e nell'ambito del flusso del proxy API.

Variabili di flusso nel codice Node.js

Richiedendo il modulo apigee-access, puoi impostare e accedere alle variabili di flusso da codice Node.js di cui è stato eseguito il deployment su 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 tutte le policy o altro codice che si verifica 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/');

Puoi scoprire di più sull'utilizzo di apigee-access per lavorare con le variabili in Accesso alle variabili di flusso in Node.js.

Comprendere l'ambito delle variabili di flusso

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

Visualizzare il flusso di un proxy API

Per comprendere l'ambito delle variabili di flusso, è importante comprendere o visualizzare il modo in cui i messaggi fluiscono attraverso un proxy API. Un proxy API è costituito da una serie di passaggi di elaborazione dei messaggi organizzati come un flusso. A ogni passaggio di un flusso del proxy, il proxy valuta le informazioni a sua disposizione e decide cosa fare dopo. Durante il processo, il proxy può eseguire il codice della policy o eseguire una ramificazione condizionale.

La figura seguente illustra questa sequenza di flussi. Nota come i flussi siano composti da quattro segmenti principali: _richiesta_ ProxyEndpoint, _richiesta_ TargetEndpoint, _risposta_ TargetEndpoint e _risposta_ ProxyEndpoint.

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

Come l'ambito delle variabili è correlato al flusso del proxy

Non appena riesci a visualizzare il modo in cui i messaggi fluiscono attraverso un proxy, come descritto in precedenza, puoi iniziare a comprendere l'ambito delle variabili. Per ambito si intende il punto del ciclo di vita del flusso del proxy in cui una variabile viene creata per la prima volta.

Ad esempio, se hai una policy collegata al segmento della richiesta ProxyEndpoint, questa policy non sarà in grado di accedere a nessuna variabile con ambito nel segmento della richiesta TargetEndpoint. Il motivo è che il segmento della richiesta TargetEndpoint del flusso non è ancora stato eseguito, quindi il proxy API non ha avuto la possibilità di compilare le variabili in questo ambito.

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

Ambito delle variabili Dove vengono compilate queste variabili
Richiesta del proxy Il segmento della richiesta ProxyEndpoint
Richiesta del target Il segmento della richiesta TargetEndpoint
Risposta del target Il segmento della risposta TargetEndpoint
Risposta del proxy Il segmento della risposta ProxyEndpoint
Sempre disponibile Non appena il proxy riceve una richiesta. Queste variabili sono disponibili per l' intero ciclo di vita del flusso del proxy.

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

Esiste un'altra variabile integrata denominata target.url. L'ambito di questa variabile è "richiesta del target". Viene compilata nel segmento della richiesta TargetEndpoint con l'URL della richiesta inviato alla destinazione di backend. Se provi ad accedere a target.url nel segmento della richiesta ProxyEndpoint, riceverai un valore NULL. Se provi a impostare questa variabile prima che sia nell'ambito, il proxy non esegue alcuna operazione: non genera un errore e non imposta la variabile.

Ecco un semplice esempio che mostra come pensare all'ambito delle variabili. Supponiamo che tu voglia copiare l'intero contenuto di un oggetto di richiesta (intestazioni, parametri, corpo) e assegnarlo al payload della risposta da inviare all'app chiamante. Puoi utilizzare la policy AssignMessage per questa attività. Il codice della policy è il seguente:

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

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

Fare riferimento alle variabili di flusso

Tutte le variabili integrate in Apigee Edge seguono una convenzione di denominazione con notazione a punti. 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 una policy, racchiudila tra parentesi graffe. Ad esempio, la seguente policy AssignMessage 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 saperne di più, vedi:

Tipo di dati delle variabili di flusso

Ogni proprietà di una variabile di flusso ha un tipo di dati ben definito, ad esempio String, Long, Integer, Boolean o Collection. Puoi trovare i tipi di dati elencati in il riferimento alle variabili di flusso. Per le variabili create da una policy, consulta l'argomento di riferimento della policy specifica per informazioni sul tipo di dati.

Le variabili create manualmente assumono 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 Number, String, Boolean, null o undefined.

Utilizzo delle variabili di flusso nelle policy

Molte policy creano variabili di flusso come parte della loro normale esecuzione. Il riferimento alle policy documenta tutte queste variabili specifiche delle policy.

Quando lavori con proxy e policy, assicurati di consultare il riferimento alle policy per scoprire quali variabili vengono create e a cosa servono. Ad esempio, la policy Quota crea un insieme di variabili che contengono informazioni su conteggi e limiti delle quote, data di scadenza e così via.

Alcune variabili delle policy 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 del proxy.

La policy ExtractVariables consente di compilare 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, Extract Variables analizza un messaggio di risposta e memorizza dati specifici prelevati dalla risposta. La policy crea due variabili personalizzate, geocoderesponse.latitude e geocoderesponse.longitude, e assegna loro dei 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 molte policy creano automaticamente le variabili. Puoi accedere a queste variabili nel contesto del flusso del proxy e sono documentate nel riferimento alle policy in ogni argomento relativo alle singole policy.

Utilizzo delle variabili di flusso nel codice JavaScript

Puoi accedere e impostare le variabili direttamente nel codice JavaScript eseguito nel contesto di un proxy API. Tramite il modello oggetto JavaScript di Apigee, il codice JavaScript eseguito su Edge ha accesso diretto alle variabili di flusso del 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 corrispondono 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", ad esempio le variabili di sistema. Ad esempio, puoi chiamare getVariable() sull'oggetto context per ottenere l'anno corrente:

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

Allo stesso modo, puoi chiamare setVariable() per impostare il valore di una variabile personalizzata o per qualsiasi accessibile in scrittura variabile predefinita. 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 di flusso del proxy nel codice Java eseguito con la policy JavaCallout.

Accesso 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 su Edge. Devi solo "richiedere" il modulo apigee-access nel codice. Per i dettagli, consulta Accesso alle variabili di flusso in Node.js.

Cosa devi ricordare

Ecco alcuni aspetti importanti da ricordare sulle variabili di flusso:

  • Alcune variabili "predefinite" vengono create e compilate automaticamente dal proxy stesso. Sono documentate nel riferimento alle variabili di flusso.
  • Puoi creare variabili personalizzate che possono essere utilizzate nel flusso del proxy. È possibile creare variabili utilizzando policy come AssignMessage 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 esegue.
  • Quando le policy vengono eseguite, possono creare e compilare variabili specifiche delle policy. La documentazione di ogni policy elenca tutte queste variabili specifiche delle policy pertinenti.
  • I flussi condizionali in genere valutano una o più variabili. Devi comprendere le variabili se vuoi creare flussi condizionali.
  • Molte policy utilizzano le variabili come input o output. Forse una variabile creata da una policy viene utilizzata in un secondo momento da un'altra.
  • Puoi ottenere e impostare molte variabili di flusso da Node.js utilizzando JavaScript diretto (e il nostro modello oggetto JavaScript) o la policy 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. Per informazioni sul download e sull'utilizzo degli esempi, consulta Utilizzo degli esempi di proxy API. Per una descrizione degli esempi di proxy API e delle loro funzionalità, consulta Elenco degli esempi.

I proxy di esempio che utilizzano variabili ed elaborazione delle variabili includono:

  • variabili: mostra come estrarre e impostare le variabili in base al trasporto e al contenuto dei messaggi JSON e XML.
  • policy-mashup-cookbook: un'applicazione completa che utilizza la composizione delle policy per chiamare due API pubbliche, combina i risultati e genera una risposta arricchita per l'app client. Per ulteriori informazioni su questo esempio, consulta Utilizzo della composizione delle policy.
  • conditional-policy: implementa l'applicazione semplice delle policy condizionali in base ai valori delle variabili.

Argomenti correlati