Utilizzo delle variabili di flusso

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

Concettualmente, le variabili di flusso sono oggetti a cui puoi accedere dall'interno dei tuoi criteri o come lo strumento Trace. Consentono di mantenere uno stato associato Transazione API elaborata da Apigee Edge.

Che cosa sono le variabili di flusso?

Le variabili di flusso esistono nel contesto di un flusso proxy API e tracciano lo stato in un'API transazione come le variabili con nome monitorano lo stato in un programma software. Archiviazione delle variabili di flusso informazioni quali:

  • Indirizzo IP, intestazioni, percorso dell'URL e payload inviato dall'app richiedente
  • Informazioni sul sistema come 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 della richiesta un'applicazione.
  • Informazioni sulla risposta del sistema di destinazione

Alcune variabili sono "integrate" a Edge e vengono compilate automaticamente ogni volta che viene richiesta quando riceve il messaggio di errore. Sono disponibili durante una transazione API. Puoi anche creare variabili personalizzate utilizzando criteri come Criterio AttributionMessage o in JavaScript, Node.js e Codice Java.

Come vedrai, le variabili hanno un ambito e il loro accesso dipende in parte da quando vengono create nel flusso proxy API. In generale, quando una variabile viene creata, è disponibile tutti i criteri e il codice che verranno 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:

  • Criteri possono recuperare lo stato dalle variabili di flusso e utilizzarle per l'esecuzione delle proprie al lavoro.

    Ad esempio, un criterio VerifyJWT può recuperare il token da verificare una variabile di flusso, quindi eseguire la verifica su questa variabile. Per fare un altro esempio, Il criterio JavaScript può recuperare le variabili di flusso e codificare i dati contenuti queste variabili.

  • I flussi condizionali possono fare riferimento a variabili di flusso per indirizzare il flusso di un'API tramite Edge, un po' come un'istruzione di switch nella programmazione.

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

Vediamo alcuni esempi di utilizzo delle variabili in ciascuno di questi contesti.

Variabili di flusso nei criteri

Alcune norme prendono piede come input.

Ad esempio, il seguente criterioAssignMessage richiede il valore della variabile di flusso client.ip e lo inserisce nell'intestazione della richiesta chiamato My-Client-IP. Se viene aggiunto al flusso di richiesta, questo criterio imposta un'intestazione. una volta passata alla destinazione del backend. Se impostata nel flusso di 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>

Per un altro esempio, quando viene eseguito un criterio per le quote, vengono compilate diverse variabili di flusso. con valori legati alle norme. Una di queste variabili è chiamato 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 che dice: "Se il conteggio delle quote attuale è inferiore al 50% del massimo ed è compreso tra le 09:00 e le 17:00, imporre una quota diversa". Questa condizione potrebbe dipendere dal valore del conteggio della quota attuale e su una variabile di flusso denominata system.time, che è una delle risorse come la codifica one-hot delle variabili categoriche.

Variabili di flusso in condizioni flussi

Flussi condizionali valutare le variabili di flusso e abilitare il comportamento dinamico dei proxy. Di solito si utilizzano le condizioni 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 verbo di richiesta è POST, viene eseguito il criterioVerifyAPIKey. Questo è un metodo comune utilizzato in Configurazioni del proxy API.

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

A questo punto potresti chiederti dove si trovano le variabili come request.verb, client.ip e system.time provengono da? Quando vengono create un'istanza compilata con un valore? Per aiutarti a capire quando vengono create le variabili disponibili, consulta Informazioni sulle variabili di flusso ambito di interesse.

Variabili di flusso nel codice JavaScript richiamate con il metodo norme

Con il criterio JavaScript, puoi eseguire il codice JavaScript nel contesto di un Flusso del proxy API. Il codice JavaScript eseguito da questo criterio utilizza la piattaforma Apigee Modello a oggetti JavaScript, che fornisce l'accesso al codice personalizzato 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 variabili è simile al lavoro che puoi svolgere con il criterioAssignMessage (mostrato in precedenza). È solo un altro modo per realizzare lo stesso diversi tipi di elementi su Edge. La chiave da ricordare è che JavaScript eseguito dal criterio JavaScript ha accesso a tutte le variabili di flusso esistenti e che rientrano nell'ambito del flusso proxy API.

Variabili di flusso nel codice Node.js

Se richiedi il modulo apigee-access, puoi impostare e accedere alle variabili di flusso da all'interno del codice Node.js di cui viene eseguito il deployment in 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 che si verificano 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 ulteriori informazioni 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 della variabile è correlato al flusso o al "ciclo di vita" complessivo di un proxy API chiamata.

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 un flusso di dati attraverso un proxy API. Un proxy API è costituito da una serie di passaggi di elaborazione dei messaggi organizzati come un flusso. In ogni fase di un flusso del proxy, il proxy valuta le informazioni disponibili e decide cosa fare. Durante il processo, il proxy potrebbe eseguire il codice del criterio o eseguire ramificazione condizionale.

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

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

Correlazione tra l'ambito variabile e il flusso proxy

Non appena riesci a visualizzare il flusso dei messaggi attraverso un proxy, come descritto in precedenza, iniziare a capire l'ambito delle variabili. Per ambito, intendiamo il punto nel ciclo di vita del flusso proxy quando viene creata un'istanza per la prima volta.

Ad esempio, se un criterio è associato alla segmento di richiesta ProxyEndpoint, questo criterio non sarà in grado di accedere a nessuna variabile con ambito al segmento di richiesta TargetEndpoint. Il motivo è che l'oggetto TargetEndpoint segmento di richiesta del flusso non è stato ancora eseguito, quindi il proxy API non ha avuto l'opportunità di per compilare le variabili in quell'ambito.

La tabella seguente elenca l'insieme completo di ambiti delle variabili e indica quando nel proxy e il flusso di lavoro disponibili.

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

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

C'è 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 al target di backend. Se provi ad accedere a target.url nella 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. Supponiamo che tu voglia per copiare l'intero contenuto di un oggetto della richiesta (intestazioni, parametri, corpo) e assegnarlo al payload di risposta da rinviare all'app chiamante. Puoi utilizzare il criterioAssignMessage per questa attività. Il codice del criterio 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 Oggetto response. Ma dove deve essere inserito questo criterio nel flusso di proxy? La è che deve essere posizionata sulla risposta TargetEndpoint, perché l'ambito è "risposta target".

Fare riferimento alle variabili di flusso

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

Apigee riserva vari prefissi per organizzare correttamente le variabili pertinenti. Questi prefissi include:

  • 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 String, Long, Integer, Booleano o di raccolta. Puoi trovare i tipi di dati elencati nella sezione consulta il riferimento sulle variabili di flusso. Per le variabili create da un criterio, fai riferimento all'argomento Riferimento alle norme specifico per informazioni sui tipi di dati.

Le variabili create manualmente presuppongono il tipo specificato al momento della creazione e dipendono sui tipi di valori consentiti. Ad esempio, le variabili create nel codice Node.js vengono limitato 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. I documenti Riferimento alle norme tutte queste variabili specifiche delle norme.

Quando utilizzi proxy e criteri, assicurati di consultare il riferimento alle norme per scoprire quali variabili sono state create e a quale scopo. Per Ad esempio, i criteri per le quote creano un insieme di variabili contenenti informazioni sul conteggio delle quote limiti, data di scadenza e così via.

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

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

Nell'esempio seguente, Estrai variabili analizza un messaggio di risposta e archivia dati specifici preso dalla risposta. La norma crea due variabili personalizzate: geocoderesponse.latitude e geocoderesponse.longitude e assegna i loro 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>

Ricorda che molti criteri creano automaticamente variabili. Puoi accedere a questi all'interno del contesto del flusso proxy e sono documentate nel Riferimento alle norme nella sezione ogni singolo argomento delle norme.

Utilizzo delle 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, richiama 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 proxy come spiegato in precedenza in Visualizzare il flusso di un proxy API.

L'oggetto context corrisponde a "globalmente" come le variabili di sistema come la codifica one-hot delle variabili categoriche. Ad esempio, puoi chiamare getVariable() sull'oggetto context per conoscere l'anno in corso:

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

Analogamente, puoi richiamare setVariable() per impostare il valore di una variabile personalizzata qualsiasi variabile pronta all'uso riscrivibile. In questo caso, creiamo una variabile personalizzata organization.name.myorg e assegnargli un valore.

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

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

Puoi anche ottenere/impostare variabili di flusso proxy nel codice Java che esegui con Norme JavaCallout.

Accesso alle variabili di flusso nelle applicazioni Node.js

Puoi recuperare, impostare ed eliminare le variabili di flusso dal codice Node.js di cui è stato eseguito il deployment su Edge. Tutto ciò di cui hai bisogno è "richiedere" nel modulo apigee-access nel tuo codice. Per maggiori dettagli, consulta Accesso 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 funzionalità "pronte all'uso" vengono create un'istanza e compilate automaticamente dal proxy per trovare le regole. Questi passaggi sono documentati nel Riferimento alle variabili di flusso.
  • Puoi creare variabili personalizzate che possono essere utilizzate nel flusso di proxy. È possibile per creare variabili utilizzando criteri come criteri di assegnazione del messaggio e criterio 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 flusso di risposta del proxy. Queste variabili di risposta rimangono non definite finché il segmento di risposta .
  • Quando i criteri vengono eseguiti, possono creare e compilare variabili specifiche dei criteri. La nella documentazione di ciascuna norma l'elenco di tutte queste variabili specifiche della norma pertinenti.
  • I flussi condizionali in genere valutano una o più variabili. Devi comprendere per creare flussi condizionali.
  • Molti criteri utilizzano le variabili come input o output. Supponiamo che venga creata da una variabile in seguito viene usato da un altro criterio.
  • Puoi ottenere e impostare molte variabili di flusso dall'interno di Node.js utilizzando JavaScript diretto (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 per gli utilizzi odierni. Consulta Utilizzo dei proxy API di esempio per informazioni sul download e sull'utilizzo degli esempi. Consulta l'elenco di esempi per una descrizione dell'API dei proxy e la loro funzione.

I proxy di esempio che utilizzano variabili e l'elaborazione delle variabili includono:

  • variabili - Illustra come estrarre e impostare le variabili in base al trasporto e al messaggio JSON e XML contenuti.
  • policy-mashup-cookbook: un'applicazione completa che utilizza policy composizione per chiamare due API pubbliche, combina i risultati e genera una risposta più completa per il client dell'app. Per ulteriori informazioni su questo esempio, consulta Utilizzo dei criteri composizione.
  • conditional-policy - Implementazione semplice dell'applicazione forzata di criteri condizionali in base a valori variabili.

Argomenti correlati