Utilizzo delle variabili di flusso

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Le variabili di flusso sono oggetti a cui puoi accedere dalle tue norme o dalle tue utilità (come lo strumento di debug). Consentono di mantenere lo stato associato a una transazione API elaborata da Apigee.

Che cosa sono le variabili di flusso?

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

  • L'indirizzo IP, le intestazioni, il percorso URL e il payload inviati dall'app richiedente
  • Informazioni di sistema, come la data e l'ora in cui Apigee riceve una richiesta
  • Dati derivati durante l'esecuzione di una policy. Ad esempio, dopo l'esecuzione di una norma che convalida un token OAuth, Apigee 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 Apigee 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 AssignMessage oppure nel codice JavaScript 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 tutti i criteri e il codice che vengono eseguiti in un secondo momento nel flusso di transazioni API.

Come vengono utilizzate le variabili di flusso?

Le variabili di flusso vengono utilizzate in norme e flussi condizionali:

  • Le norme 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 ed eseguire la verifica. Come altro esempio, una norma 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 Apigee, in modo simile al funzionamento di un'istruzione switch nella programmazione.

    Ad esempio, una policy per restituire un errore potrebbe essere eseguita solo quando viene impostata una determinata variabile di flusso.

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

Variabili di flusso nelle policy

Alcune norme accettano variabili di flusso come input.

Ad esempio, la seguente norma AssignMessage prende il valore della variabile di flusso client.ip e lo inserisce in un'intestazione della richiesta chiamata My-Client-IP. Se aggiunto al flusso di richiesta, questo criterio imposta un'intestazione che viene passata al target di 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, diverse variabili di flusso vengono compilate con valori correlati ai criteri. Una di queste variabili è chiamata ratelimit.my-quota-policy.used.count (dove my-quota-policy è il nome della norma relativa alla quota che ti interessa).

In un secondo momento potresti eseguire un flusso condizionale che dice "se il conteggio della quota attuale è inferiore al 50% del massimo e l'ora è compresa 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 chiamata system.time, che è una delle variabili Apigee 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 è un pattern comune utilizzato nelle configurazioni proxy API.

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

Ora, ti starai chiedendo da dove provengono variabili come request.verb, client.ip e system.time. Quando vengono istanziati e popolati con un valore? Per capire quando vengono create le variabili e quando sono disponibili, consulta Visualizzare il flusso di un proxy API.

Variabili di flusso nel codice JavaScript chiamate con il criterio JavaScript

Con i criteri JavaScript, puoi eseguire codice JavaScript all'interno del contesto di un flusso proxy API. Il codice JavaScript eseguito da questo criterio utilizza il modello a oggetti JavaScript di Apigee, che fornisce al tuo 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 di 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 fare con il criterio AssignMessage (mostrato in precedenza). È solo un altro modo per eseguire lo stesso tipo di operazioni su Apigee. La cosa fondamentale da ricordare è che il codice JavaScript eseguito dai criteri JavaScript ha accesso a tutte le variabili di flusso esistenti e ambito all'interno del flusso del proxy API.

Visualizzazione del flusso di un proxy API

Per comprendere l'ambito delle variabili di flusso, è importante capire 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. 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 potrebbe eseguire codice di policy o eseguire ramificazioni condizionali.

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 .

Una richiesta client HTTP passa attraverso un proxy API al servizio HTTP, quindi la risposta passa attraverso il proxy API e torna al client.

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

In che modo l'ambito delle variabili è correlato al flusso proxy

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

Ad esempio, se hai collegato un criterio al segmento della richiesta ProxyEndpoint, questo criterio non potrà accedere a nessuna variabile con ambito limitato al segmento della richiesta TargetEndpoint. Il motivo è che il segmento di 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 di ambiti delle variabili e indica quando diventano disponibili nel flusso del proxy.

Ambito della variabile Dove vengono compilate queste variabili
richiesta proxy Il segmento di richiesta ProxyEndpoint
richiesta target Il segmento di richiesta TargetEndpoint
risposta target Il segmento di risposta TargetEndpoint
risposta del proxy Il segmento di 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 Apigee integrata chiamata 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 l'intero ciclo di vita del flusso del proxy.

Esiste 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 inviata 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 inclusa nell'ambito, il proxy non esegue alcuna operazione, non genera un errore e non imposta la variabile.

Ecco un semplice esempio che mostra come considerare l'ambito delle variabili. Supponiamo che tu voglia copiare l'intero contenuto di un oggetto richiesta (intestazioni, parametri, corpo) e assegnarlo al payload della risposta da inviare di nuovo all'app chiamante. Puoi utilizzare il criterio AssignMessage 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>

Questi criteri copiano semplicemente l'oggetto request e lo assegnano all'oggetto response. Ma dove devono essere inserite queste norme nel flusso del proxy? La risposta è che deve essere inserita nella risposta TargetEndpoint, perché l'ambito della variabile di risposta è target response.

Fare riferimento alle variabili di flusso

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

Apigee riserva vari prefissi per organizzare le variabili pertinenti in modo appropriato. 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 chiamata 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, ad esempio String, Long, Integer, Boolean o Collection. Puoi trovare i tipi di dati elencati nel riferimento alle variabili di flusso. Per le variabili create da un criterio, consulta l'argomento di riferimento specifico del criterio 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.

Utilizzo delle variabili di flusso nei criteri

Molte norme creano variabili di flusso nell'ambito della loro normale esecuzione. I documenti Riferimento alle norme contengono tutte queste variabili specifiche delle norme.

Quando lavori con proxy e criteri, consulta il riferimento ai criteri per scoprire quali variabili vengono create e a cosa servono. Ad esempio, i criteri di quota creano un insieme di variabili che contengono informazioni su conteggi e limiti delle quote, ora di scadenza e così via.

Alcune variabili dei criteri sono utili per il debug. Puoi utilizzare lo strumento di debug), ad esempio, per vedere quali variabili sono state impostate in una particolare istanza di 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, il criterio ExtractVariables analizza un messaggio di risposta e archivia dati specifici estratti dalla risposta. Il criterio 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 variabili. Puoi accedere a queste variabili nel contesto del flusso proxy e sono documentate nel riferimento ai 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 eseguito nel contesto di un proxy API. Tramite il modello oggetto JavaScript di Apigee, JavaScript in esecuzione su Apigee ha accesso diretto alle variabili di flusso del proxy.

Per accedere alle variabili nel codice JavaScript, chiama i metodi getter/setter su uno qualsiasi 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 variabile scrivibile 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 del flusso (in sostanza, è come creare una variabile globale).

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

Cosa devi ricordare

Ecco alcuni aspetti importanti da ricordare sulle variabili di flusso:

  • Alcune variabili out-of-the-box vengono istanziate e compilate automaticamente dal proxy. Queste sono documentate nel 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 JavaScript policy.
  • 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 vengono eseguite, le norme possono creare e compilare variabili specifiche. La documentazione di ogni policy elenca tutte queste variabili specifiche pertinenti.
  • I flussi condizionali in genere valutano una o più variabili. Devi comprendere le variabili se vuoi creare flussi condizionali.
  • Molti criteri utilizzano le variabili come input o output. Ad esempio, una variabile creata da un criterio viene utilizzata in un secondo momento da un altro criterio.

Argomenti correlati

  • Tutte le variabili che vengono compilate automaticamente in un proxy API sono elencate nel riferimento alle variabili di flusso. Il riferimento elenca anche il tipo e l'ambito di ogni variabile.
  • Se vuoi sapere quali variabili vengono compilate da una policy specifica, consulta l'argomento di riferimento per la policy. Ad esempio, consulta Variabili di flusso nel riferimento ai criteri relativi alle quote.