Condizioni con variabili di flusso

Questa pagina si applica a Apigee e Apigee ibridi.

Visualizza la documentazione di Apigee Edge.

Le istruzioni condizionali sono una struttura di controllo comune in tutti i linguaggi di programmazione. Come un linguaggio di programmazione, la configurazione del proxy API supporta le istruzioni condizionali per flussi, criteri, passaggi e regole di routing. Se definisci istruzioni condizionali, definisci il comportamento dinamico per l'API. Questo comportamento dinamico ti consente di eseguire operazioni come la conversione di XML in JSON solo per i dispositivi mobili o il reindirizzamento a un URL di backend in base al tipo di contenuti o al verbo HTTP del messaggio di richiesta.

Questo argomento mostra come utilizzare le condizioni per applicare dinamicamente le funzionalità di gestione delle API in fase di esecuzione, senza scrivere codice.

Video

Nota: il seguente video mostra la versione classica dell'Editor proxy nello UI di Apigee. Apigee sta introducendo una nuova versione del proxy Editor, che ha un design diverso dalla versione classica mostrata nel video.

Per scoprire di più sulle variabili e sulle condizioni del flusso, guarda il seguente video:

Configurare istruzioni condizionali

Il comportamento condizionale viene implementato nei proxy API utilizzando una combinazione di condizioni e variabili. Un'istruzione condizionale viene creata utilizzando un elemento Condition. Le seguenti è una condizione vuota:

<Condition></Condition>

Per creare un'istruzione condizionale, aggiungi un operatore condizionale e una variabile utilizzando la seguente sintassi:

<Condition>VARIABLE_NAME OPERATOR "VALUE"</Condition>

Ad esempio:

<Condition>request.verb = "GET"</Condition>

Gli operatori condizionali supportati includono = (uguale a), != (non uguale a) e > (maggiore di). Per una maggiore leggibilità, puoi anche scrivere le condizioni come testo: equals, notequals, greaterthan.

Quando lavori con i percorsi URI, puoi utilizzare ~/ o MatchesPath. Puoi anche trovare corrispondenze con le espressioni regolari JavaRegex con l'operatore ~~.

Nota: per un esempio dell'operatore ~~, vedi quanto segue thread della community:

Come sostituisci alla fine dell'URL

Le condizioni vengono utilizzate per definire i flussi condizionali del proxy API verso le risorse API backend, in Creare flussi condizionali verso le risorse dell'API backend. Per un elenco completo dei condizionali, consulta la sezione Riferimento alle condizioni.

Variabili

Le condizioni svolgono il proprio lavoro valutando i valori delle variabili. Una variabile è una proprietà di una transazione HTTP eseguita da un proxy API o una proprietà della configurazione stessa di un proxy API. Ogni volta che un proxy API riceve una richiesta da un'app, Apigee compila una lungo elenco di variabili associate ad aspetti come l'ora di sistema, l'indirizzo informazioni, intestazioni HTTP dei messaggi, configurazione del proxy API, esecuzioni dei criteri e così via. Ciò crea un contesto dettagliato che puoi utilizzare per configurare dichiarazioni condizionali.

Le variabili utilizzano sempre una notazione con puntini. Ad esempio, le intestazioni HTTP nel messaggio di richiesta sono disponibili come variabili chiamate request.header.HEADER_NAME. Quindi, per valutare Content-type header, potresti usare la variabile request.header.Content-type. Per L'esempio request.header.Content-type = "application/json" indica che i contenuti il tipo di richiesta deve essere JSON.

Immagina di dover creare un'istruzione condizionale che imponga l'applicazione di una norma solo quando un messaggio di richiesta è un GET. Per creare una condizione che valuti il verbo HTTP di una richiesta, crei la seguente dichiarazione condizionale. La variabile in questa condizione è request.verb. Il valore della variabile è GET. L'operatore è =.

<Condition>request.verb = "GET"</Condition>

Puoi anche utilizzare:

<Condition>request.verb equals "GET"</Condition>

Apigee utilizza questa istruzione per valutare le condizioni. L'esempio precedente restituisce true se la Il verbo HTTP associato alla richiesta è GET. Se il verbo HTTP associato alla richiesta è POST, l'istruzione restituisce false.

Nota: Apigee archivia automaticamente tutte le intestazioni HTTP e parametri di ricerca come variabili accessibili utilizzando request.header. e request.queryparam. prefissi di variabili.

Per attivare il comportamento dinamico, puoi associare le condizioni a flussi, passaggi e regole di routing.

Quando colleghi una condizione a un flusso, crei un flusso condizionale. I flussi condizionali vengono eseguiti solo quando la condizione ha valore true. Puoi collegare tutti i criteri che vuoi un flusso condizionale. Un flusso condizionale ti consente di creare regole di elaborazione altamente specializzate per i messaggi di richiesta o risposta che soddisfano determinati criteri.

Ad esempio, per creare un flusso che viene eseguito solo quando il verbo di richiesta è GET:

<Flows>
  <Flow name="ExecuteForGETs">
  <Condition>request.verb="GET"</Condition>
  </Flow>
</Flows>

Per creare un flusso per le richieste GET e un altro per POST richieste:

<Flows>
  <Flow name="ExecuteForGETs">
    <Condition>request.verb="GET"</Condition>
  </Flow>
  <Flow name="ExecuteForPOSTs">
    <Condition>request.verb="POST"</Condition>
  </Flow>
</Flows>

Come mostrato nell'esempio di seguito, puoi applicare la condizione al passaggio del criterio stesso. La la seguente condizione fa sì che il criterioVerifyAPIKey venga applicato in modo forzato solo se un messaggio di richiesta è un POST.

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

Una volta definiti questi flussi condizionali, puoi associarvi i criteri, consentendo a un proxy API di applicare un insieme di criteri per le richieste GET e un altro insieme di criteri per le richieste POST.

Per informazioni di riferimento complete, consulta le seguenti risorse:

• Riferimento alle variabili di flusso
• Guida di riferimento alle condizioni

Esempio 1

L'esempio seguente mostra un singolo flusso condizionale denominato Convert-for-devices, configurato nel flusso di risposta ProxyEndpoint. Aggiungi la condizione come elemento all'entità a cui si applica. In questo esempio, la condizione è un componente del flusso. Pertanto, il flusso verrà eseguito ogni volta che l'istruzione restituisce true.

<Flows>
  <Flow name="Convert-for-devices">
  <Condition>(request.header.User-Agent = "Mozilla")</Condition>
    <Response>
      <Step><Name>ConvertToJSON</Name></Step>
    </Response>
  </Flow>
</Flows>

Per ogni richiesta ricevuta da un'app, Apigee memorizza i valori di tutte le intestazioni HTTP presenti come variabili. Se la richiesta contiene un'intestazione HTTP denominata User-Agent, questa intestazione e il suo valore vengono memorizzati come una variabile denominata request.header.User-Agent.

Data la configurazione ProxyEndpoint di cui sopra, Apigee controlla il valore request.header.User-Agent per verificare se la condizione ha come risultato vero.

Se la condizione ha un valore true, ovvero il valore della variabile request.header.User-Agent è uguale a Mozilla, quindi il flusso condizionale e viene applicato il criterio XMLtoJSON denominato ConvertToJSON. In caso contrario, lo stato del flusso non viene eseguito e la risposta XML viene restituita non modificata (in formato XML) alla richiesta dell'app.

Esempio 2

Utilizziamo un esempio specifico in cui devi trasformare il messaggio di risposta da XML a JSON, ma solo per i dispositivi mobili. Innanzitutto, crea il criterio che convertirà Risposta in formato XML dall'API Weather in formato JSON:

<XMLToJSON name="ConvertToJSON">
  <Options>
  </Options>
  <OutputVariable>response</OutputVariable>
  <Source>response</Source>
</XMLToJSON>

La configurazione dei criteri riportata sopra indica al proxy API di accettare il messaggio di risposta ed eseguire una conversione da XML a JSON con le impostazioni predefinite, quindi scrivi il risultato nella nuova risposta per creare un nuovo messaggio email. Se vuoi convertire un messaggio di richiesta da XML a JSON, devi semplicemente impostare entrambi questi valori in request.)

Suggerimento:il tipo di criterio XMLtoJSON definisce un insieme di valori ragionevoli valori predefiniti, il che significa che devi solo aggiungere elementi di configurazione per creare XML in strutture JSON.

Poiché vuoi convertire le risposte da XML a JSON, devi configurare un flusso di risposta condizionale per eseguire la conversione. Ad esempio, per convertire tutte le risposte da XML a JSON prima che vengano restituiti all'app client, configura la seguente risposta ProxyEndpoint Flusso.

<Flows>
  <Flow name="Convert-for-devices">
    <Response>
      <Step><Name>ConvertToJSON</Name></Step>
    </Response>
  </Flow>
</Flows>

Quando richiami l'API utilizzando la richiesta standard, la risposta è formattata in JSON.

Tuttavia, il tuo obiettivo è convertire i report meteo in JSON solo quando il client richiedente è un dispositivo mobile. Per attivare questo comportamento dinamico, devi aggiungere un'istruzione condizionale al flusso.

Testa il flusso condizionale

In questa richiesta di esempio, l'intestazione HTTP User-Agent è impostata su Mozilla, il che fa sì che l'istruzione condizionale venga valutata come true e il flusso condizionale Convert-for-devices venga eseguito.

curl -H "User-Agent:Mozilla" http://example.com/weather/forecastrss?w=12797282

oppure, per la formattazione del codice, se Python è disponibile:

curl -H "User-Agent:Mozilla" http://example.com/weather/forecastrss?w=12797282 | python -mjson.tool

Esempio di risposta:

. . .

"yweather_forecast": [
   {
      "code": "11",
      "date": "12 Dec 2012",
      "day": "Wed",
      "high": "55",
      "low": "36",
      "text": "Showers"
    },
    {
      "code": "32",
      "date": "13 Dec 2012",
      "day": "Thu",
      "high": "56",
      "low": "38",
      "text": "Sunny"
    }
  ]
}

. . .

Una richiesta inviata senza l'intestazione User-Agent o con un valore diverso da Mozilla genererà una risposta in formato XML.

$ curl http://example.com/weather/forecastrss?w=12797282

Viene restituita la risposta XML non modificata.

Esempio di risposta:

<yweather:forecast day="Wed" date="12 Dec 2012" low="36" high="55" text="Showers" code="11" /> <yweather:forecast day="Thu" date="13 Dec 2012" low="38" high="56" text="Sunny" code="32" />

Corrispondenza di pattern

Questa sezione descrive come utilizzare la corrispondenza di pattern con le condizioni in un'API Apigee flusso di lavoro.

Per approfondire

• Guida di riferimento alle condizioni
• "condition-pattern-matching proxy" nel nostro repository api-platform-samples in GitHub

Operatori

In questa sezione viene descritto come utilizzare i seguenti operatori di corrispondenza dei pattern nella estratti conto:

• Operatore Matches: semplice corrispondenza di pattern
• Operatore JavaRegex: controllo più preciso della corrispondenza
• Operatore MatchesPath: corrispondenza dei frammenti del percorso

Corrisponde a

Esaminiamo prima l'operatore condizionale Matches o ~. Questi due operatori sono uguali: la versione in inglese, Matches, è considerata un'opzione più leggibile.

Riepilogo:l'operatore Matches offre due possibilità. Corrisponde alla stringa in modo letterale o esegui una corrispondenza con caratteri jolly con *. Come previsto, il carattere jolly corrisponde a zero o più caratteri. Vediamo come funziona.

Nota: l'operatore Matches non corrisponde alla normale le espressioni regolari. Se vuoi utilizzare la corrispondenza con espressioni regolari, utilizza l'operatore JavaRegex

.

Il seguente XML mostra una condizione Step. Esegue il criterio SomePolicy quando la condizione restituisce true. In questo esempio, testiamo la variabile proxy.pathsuffix, una variabile integrata in Apigee che memorizza il suffisso del percorso della richiesta. Tieni presente, tuttavia, che puoi verificare il valore di qualsiasi variabile di flusso contenente una stringa. In questo caso, se il percorso di base della richiesta in entrata è /animals e la richiesta è /animals/cat, il suffisso del percorso è la stringa letterale /cat.

<PreFlow name="PreFlow">
  <Request>
    <Step>
      <Condition>(proxy.pathsuffix Matches "/cat")</Condition>
      <Name>SomePolicy</Name>
    </Step>
  </Request>
  <Response/>
</PreFlow>

Domanda: quale suffisso del percorso del proxy causerà l'esecuzione di SomePolicy? Esiste una sola possibilità.

Chiamata API:

GET http://example.com/matchtest/cat

Il criterio viene eseguito? Sì, perché il suffisso del percorso del proxy corrisponde esattamente a /cat. Non verrà eseguito se il suffisso è /bat o /dog oppure / o qualsiasi altra cosa.

Consideriamo ora questa istruzione condizionale in cui utilizziamo il carattere jolly *:

<Condition>(proxy.pathsuffix Matches "/*at")</Condition>

Chiamata API:

GET http://example.com/matchtest/cat

Il criterio viene eseguito? Sì, perché il carattere jolly corrisponde a qualsiasi carattere e "/cat" c'è una corrispondenza.

Chiamata API:

GET http://example.com/matchtest/bat

Il criterio viene eseguito? Sì, perché il carattere jolly corrisponde a qualsiasi carattere, "/bat" è una corrispondenza.

Chiamata API:

GET http://example.com/matchtest/owl

Il criterio viene eseguito? Ovviamente no, anche se il carattere jolly corrisponde al valore o, le lettere wl non corrispondono.

Ora spostiamo il carattere jolly alla fine del suffisso:

<Condition>(proxy.pathsuffix Matches "/cat*")</Condition>

Chiamata API:

GET http://example.com/matchtest/cat

Il criterio viene eseguito? Sì, perché il carattere jolly corrisponde a zero o più caratteri.

Chiamata API:

GET http://example.com/matchtest/bat

Il criterio viene eseguito? No, /bat non è una corrispondenza.

Chiamata API:

GET http://example.com/matchtest/cat123

Il criterio viene eseguito? Sì, il carattere jolly corrisponde a zero o più caratteri, quindi 123 produce una corrispondenza.

Chiamata API:

GET http://example.com/matchtest/cat/bird/mouse

Il criterio viene eseguito? Sì, perché il carattere jolly corrisponde a zero o più caratteri qualsiasi, quindi /bird/mouse genera una corrispondenza. Nota come un'espressione come questa può portarti perché crea corrispondenze con tutto ciò che segue i caratteri letterali.

Domanda: l'operatore Matches è sensibile alle maiuscole?

Sì. Supponi di avere una condizione come questa:

<Condition>(proxy.pathsuffix Matches "/*At")</Condition>

Chiamata API:

GET http://example.com/matchtest/cat

Il criterio viene eseguito? No, il carattere jolly corrisponde a qualsiasi lettera (indipendentemente dalle maiuscole), ma a minuscolo non corrisponde a A.

Chiamata API:

GET http://example.com/matchtest/bAt

Il criterio viene eseguito? Sì, la richiesta corrisponde.

Domanda: come faccio a convertire i caratteri in caratteri di escape con l'operatore Matches?

Utilizza il carattere percentuale % per inserire caratteri di escape per i caratteri riservati. Ad esempio:

<Condition>(proxy.pathsuffix Matches "/c%*at")</Condition>

Chiamata API:

GET http://example.com/matchtest/cat

Il criterio viene eseguito? No, l'operatore Matches cerca la stringa letterale c*at.

Chiamata API:

GET http://example.com/matchtest/c*at

Domanda:il criterio viene eseguito?

Sì, questo percorso, anche se un po' insolito, corrisponde.

JavaRegex

Come puoi vedere, l'operatore Matches è ideale per situazioni semplici. Ma puoi utilizzare un altro , l'operatore JavaRegex o ~~. Si tratta dello stesso operatore, tranne per il fatto che JavaRegex è considerato più leggibile. Si chiama JavaRegex perché consente la corrispondenza di pattern con espressioni regolari e Apigee segue le stesse regole delle classi nel package java.util.regex nel linguaggio Java. Il funzionamento dell'operatore JavaRegex è molto diverso da quello dell'operatore Matches, quindi è importante non confondere i due.

Nota: se sei abituato a utilizzare le espressioni regolari negli script Perl, è importante nota che l'operatore JavaRegex in Apigee verifica l'intera stringa oggetto. Ad esempio, se l'oggetto è abc e la regex è [a-z], non esiste alcuna corrispondenza perché [a-z] corrisponde esattamente a un carattere alfa. L'espressione [a-z]+ funzionerebbe, così come [a-z]{3}. Questa corrispondenza è diversa dalla normale applicazione delle espressioni regolari in strumenti come Perl, grep o mod_rewrite di Apache. JavaRegex utilizza java.util.regex.Pattern.matches(str), che è definito per restituire un valore positivo se l'intera stringa (str) corrisponde al pattern. La regex in Perl o mod_rewrite viene applicata a qualsiasi parte della stringa. Restituisce true se il pattern corrisponde in qualsiasi punto. Vedi l'esempio: Corrispondenza di stringhe arbitrarie con JavaRegex.

Nota: questa sezione non intende fornire un'introduzione dettagliata a espressioni regolari. L'intento principale è illustrare alcuni semplici esempi ed evidenziare la differenza tra gli operatori Matches e JavaRegex. Se vuoi saperne di più sulla funzionalità espressioni, esistono molte risorse da esplorare.

Riepilogo: l'operatore JavaRegex ti consente di utilizzare la sintassi delle espressioni regolari negli affermazioni condizionali.

Il seguente codice mostra una condizione Step. Esegue il criterio SomePolicy se la condizione restituisce true. In questo esempio, testiamo la variabile proxy.pathsuffix, una variabile integrata in Apigee che archivia il suffisso del percorso della richiesta. Se il percorso di base la richiesta in arrivo è /animals e la richiesta è /animals/cat, poi il suffisso del percorso è la stringa letterale /cat.

    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Condition>(proxy.pathsuffix JavaRegex "/cat")</Condition>
                <Name>SomePolicy</Name>
            </Step>
        </Request>
        <Response/>
    </PreFlow>

Nota: è importante ricordare che la variabile proxy.pathsuffix è una stringa che inizia sempre con un carattere barra (/), ad esempio /cat. Pertanto, se inserisci una corrispondenza /c*t, stai abbinando l'intera stringa, incluso /. / non fa parte del costrutto dell'espressione regolare. Se stai cercando di trovare una corrispondenza con un altro tipo di variabile, ad esempio un request.querystring, non è necessario un / (a meno che il parametro di query non inizi con un /).

Domanda: quale suffisso del percorso proxy causerà l'esecuzione di SomePolicy? Proprio come con l'operatore Matches, in questo caso esiste una sola possibilità.

Chiamata API:

GET http://example.com/matchtest/cat

Il criterio viene eseguito? Sì, perché il suffisso del percorso proxy corrisponde a /cat in modo esatto. Non verrà eseguito se il suffisso è /bat, /dog o un nome qualsiasi diverso.

Ora creiamo un'espressione regolare utilizzando il quantificatore *. Questo quantificatore corrisponde a 0 dei caratteri precedenti.

<Condition>(proxy.pathsuffix JavaRegex "/c*t")</Condition>

Chiamata API:

GET http://example.com/matchtest/cat

Il criterio viene eseguito? No! Il quantificatore * corrisponde a zero o più caratteri precedenti, ovvero un c.

Chiamata API:

GET http://example.com/matchtest/ccccct

Il criterio viene eseguito? Sì, perché il carattere jolly corrisponde a zero o più dei precedenti .

Successivamente, utilizziamo il quantificatore ?, che corrisponde al carattere precedente una volta o per niente.

<Condition>(proxy.pathsuffix JavaRegex "/ca?t")</Condition>

Chiamata API:

GET http://example.com/matchtest/cat

Il criterio viene eseguito? Sì. Il quantificatore ? corrisponde a zero o a un'occorrenza di il carattere precedente, a.

Chiamata API:

GET http://example.com/matchtest/ct

Il criterio viene eseguito? Sì. Il quantificatore ? corrisponde a uno o nessuno dei caratteri precedenti. In questo caso, non è presente alcun carattere a, quindi il la condizione restituisce true.

Chiamata API:

GET http://example.com/matchtest/caat

Il criterio viene eseguito? No. Il quantificatore ? corrisponde a uno dei precedenti che corrisponde a a.

Successivamente, utilizziamo lo stile di espressione regex [abc] o di raggruppamento. Corrisponde ai caratteri a, b o c.

<Condition>(proxy.pathsuffix JavaRegex "/[cbr]at")</Condition>

Chiamata API:

GET http://example.com/matchtest/cat

Il criterio viene eseguito? Sì. Qui utilizziamo le espressioni regolari e L'espressione [cbr] corrisponde a c, b o r. Queste chiamate sono anche corrispondenze:

GET http://example.com/matchtest/bat

GET http://example.com/matchtest/rat

Tuttavia, questa non è una corrispondenza:

GET http://example.com/matchtest/mat

Domanda: l'operatore JavaRegex è sensibile alle maiuscole?

Sì. Supponi di avere una condizione come questa:

<Condition>(proxy.pathsuffix JavaRegex "/ca?t")</Condition>

Chiamata API:

GET http://example.com/matchtest/cat

Il criterio viene eseguito? Sì, la regex corrisponde a zero o a uno dei caratteri precedenti, ovvero a.

Chiamata API:

GET http://example.com/matchtest/cAt

Domanda: il criterio viene eseguito?

No, perché la A maiuscola non corrisponde alla lettera minuscola a.

MatchesPath

L'operatore MatchesPath può essere specificato anche in questo modo ~/. it un po' come Matches (~) e gli operatori JavaRegex (~~). Ma MatchesPath è completamente diverso.

Ricorda solo che questo operatore considera un percorso come una serie di parti. Pertanto, se il percorso è /animals/cats/wild, puoi immaginarlo come costituito dalle parti /animals, /cats e /wild.

L'operatore MatchesPath consente di utilizzare due notazioni di caratteri jolly: un singolo asterisco (*) e un asterisco doppio (**). Il singolo asterisco corrisponde a un elemento del percorso. Il doppio asterisco corrisponde a uno o più elementi del percorso.

Vediamo un esempio. In questo esempio testiamo la variabile proxy.pathsuffix, una variabile integrata in Apigee che archivia il suffisso del percorso della richiesta. Tieni presente, tuttavia, che puoi verificare il valore di qualsiasi variabile di flusso contenente una stringa.

    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Condition>(proxy.pathsuffix MatchesPath "/animals/*")</Condition>
                <Name>SomePolicy</Name>
            </Step>
        </Request>
        <Response/>
    </PreFlow>

Domanda: quale suffisso del percorso del proxy causerà l'esecuzione di SomePolicy?

Chiamata API:

GET http://example.com/matchtest/animals

Domanda: il criterio viene eseguito?

No, perché la condizione richiede un altro elemento di percorso dopo /animals, come specificato da /*.

Chiamata API:

GET http://example.com/matchtest/animals/

Il criterio viene eseguito? Sì, il percorso ha un altro elemento (la parte successiva /animals/), ma è vuoto.

Chiamata API:

GET http://example.com/matchtest/animals/cats

Il criterio viene eseguito? Sì, perché il percorso contiene chiaramente un elemento (/cats) che viene dopo /animals

Chiamata API:

GET http://example.com/matchtest/animals/cats/wild

Domanda: il criterio viene eseguito?

No, perché l'asterisco singolo corrisponde a un solo elemento del percorso e questa API ha più di un elemento dopo /animals.

Ora utilizziamo il doppio asterisco:

    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Condition>(proxy.pathsuffix MatchesPath "/animals/**")</Condition>
                <Name>SomePolicy</Name>
            </Step>
        </Request>
        <Response/>
    </PreFlow>

Domanda: quale suffisso del percorso del proxy causerà l'esecuzione di SomePolicy?

Chiamata API:

GET http://example.com/matchtest/animals

Il criterio viene eseguito? No, perché la condizione richiede almeno un elemento del percorso successivo specificato da /**.

Chiamata API:

GET http://example.com/matchtest/animals/

Il criterio viene eseguito?

Sì, il percorso ha un altro elemento (la parte dopo /animals/), ma è vuoto.

Chiamata API:

GET http://example.com/matchtest/animals/cats

Il criterio viene eseguito?

Sì, perché il percorso ha almeno un elemento che segue /animals

Chiamata API:

GET http://example.com/matchtest/animals/cats/wild

Il criterio viene eseguito?

Sì, perché il percorso ha più di un elemento che segue /animals

Combinazione di asterischi

È possibile utilizzare combinazioni di asterisco singolo (*) e doppio (**) per perfezionare ulteriormente corrispondenza del percorso.

    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Condition>(proxy.pathsuffix MatchesPath "/animals/*/wild/**")</Condition>
                <Name>SomePolicy</Name>
            </Step>
        </Request>
        <Response/>
    </PreFlow>

Chiamata API:

Tutte queste chiamate API produrranno una corrispondenza:

GET http://example.com/matchtest/animals/cats/wild/

e

GET http://example.com/matchtest/animals/dogs/wild/austrailian

e

GET http://example.com/matchtest/animals/birds/wild/american/finches

Risorse API

I servizi RESTful sono raccolte di risorse API. Una risorsa API è un percorso URI che identifica un'entità a cui gli sviluppatori possono accedere chiamando la tua API. Ad esempio: Se il tuo servizio fornisce previsioni meteo e previsioni meteo, il servizio di backend potrebbe definire due risorse API:

• http://mygreatweatherforecast.com/reports
• http://mygreatweatherforecast.com/forecasts

Per approfondire

• Guarda questo breve video per un'introduzione al rapporto che intercorre tra i tuoi asset RESTful di backend e risorse proxy Apigee o flussi condizionali.
• Crea il tuo primo proxy API

Quando crei un proxy API (come mostrato in Creare il tuo primo proxy API), crei almeno un URL di base dell'alias che mappa al tuo servizio di backend. Ad esempio:

URL di base del backend	URL del proxy API nuovo/equivalente
http://mygreatweatherforecast.com	http://example.com/mygreatweatherforecast

A questo punto puoi effettuare chiamate API al tuo backend utilizzando uno dei due URL di base. Ma quando usi l'URL del proxy API, le cose iniziano a diventare interessanti.

Oltre all'analisi delle API che Apigee inizia a raccogliere quando utilizzi il proxy API, ti permettono anche di definire i flussi condizionali che mappano alle risorse sul tuo backend. In sostanza, se una chiamata GET arriva alla risorsa /reports, Apigee dovrebbe fare qualcosa.

L'immagine seguente mostra la differenza di comportamento tra due URL che accedono allo stesso backend. Uno è l'URL della risorsa senza proxy, l'altro è un proxy API Apigee con un flusso condizionale alla stessa risorsa di backend. Descriveremo i flussi condizionali in modo più dettagliato di seguito.

Come i proxy API vengono mappati a risorse di backend specifiche

Con un URL del proxy API mappato all'URL di base del servizio di backend (quando crei proxy), puoi aggiungere flussi condizionali a risorse specifiche, ad esempio /reports e /forecasts risorse menzionate in precedenza.

Supponiamo che tu voglia che Apigee faccia qualcosa quando arrivano chiamate alle risorse /reports o /forecasts. A questo punto non dici ad Apigee cosa fare, deve semplicemente ascoltare le chiamate a quelle risorse. Per farlo, utilizza le condizioni. Nel proxy API Apigee, puoi creare flussi condizionali per /reports e /forecasts. A scopo concettuale, l'API seguente il file XML del proxy mostra come potrebbero essere queste condizioni.

<Flows>
    <Flow name="reports">
        <Description/>
        <Request/>
        <Response/>
        <Condition>(proxy.pathsuffix MatchesPath "/reports") and (request.verb = "GET")</Condition>
    </Flow>
    <Flow name="forecasts">
        <Description/>
        <Request/>
        <Response/>
        <Condition>(proxy.pathsuffix MatchesPath "/forecasts") and (request.verb = "GET")</Condition>
    </Flow>
</Flows>

Queste condizioni indicano che quando viene inviata una richiesta GET con /reports e /forecasts nell'URL, Apigee eseguirà qualsiasi istruzione fornita da te (lo sviluppatore dell'API), tramite i criteri che colleghi a questi flussi.

Ecco un esempio di come comunicare ad Apigee cosa fare quando una condizione è soddisfatta. Nella seguente API XML del proxy, quando viene inviata una richiesta GET a https://example.com/mygreatweatherforecast/reports, Apigee esegue il criterio XML-to-JSON-1 nella risposta.

<Flows>
  <Flow name="reports">
    <Description/>
    <Request/>
    <Response>
      <Step>
        <Name>XML-to-JSON-1</Name>
      </Step>
    </Response>
  <Condition>(proxy.pathsuffix MatchesPath "/reports") and (request.verb = "GET")</Condition>
</Flow>

Oltre a questi flussi condizionali facoltativi, ogni proxy API è dotato anche di due flussi predefinite: un <PreFlow> eseguito prima dei flussi condizionali e un <PostFlow> eseguito dopo i flussi condizionali. Sono utili per dell'esecuzione dei criteri quando viene effettuata qualsiasi chiamata a un proxy API. Ad esempio, se vuoi verificare la chiave API di un'app a ogni chiamata, indipendentemente dalla risorsa di backend a cui si accede, potrebbe inserire un criterio di verifica della chiave API su <PreFlow>. Per saperne di più sui flussi, consulta Configurare i flussi.

Creazione di flussi condizionali verso le risorse di backend

La definizione di flussi condizionali alle risorse di backend in un proxy API è completamente facoltativa. Tuttavia, questi flussi condizionali ti offrono la possibilità di applicare una gestione granulare e il monitoraggio.

Sarai in grado di:

• Applica la gestione in modo che rifletta la semantica del tuo modello API
• Applica criteri e comportamento basato su script a singoli percorsi di risorse (URI)
• Raccogli metriche dettagliate per i servizi di analisi

Ad esempio, immagina di dover applicare diversi tipi di logica al tuo backend alle risorse /developers e /apps.

Per farlo, aggiungi due flussi condizionali nel proxy API: /developers e /apps.

Nota: Apigee sta introducendo una nuova versione dell'editor di proxy che semplifica la gestione dei proxy.

Le istruzioni nelle prime due schede spiegano come utilizza il nuovo editor proxy o l'editor proxy classico.

Nuovo editor proxy

Per aggiungere un flusso condizionale:

1. Seleziona la scheda Sviluppo nell'Editor proxy.
2. Seleziona Endpoint proxy > predefinita nel riquadro a sinistra.

   

3. Fai clic sul pulsante + sopra il riquadro Risposta.

   

4. Nella finestra di dialogo Add Conditional Flow (Aggiungi flusso condizionale), inserisci le seguenti configurazioni:
   • Nome flusso: Developers
   • Tipo di condizione: Path
   • Percorso: /developers

   

   La condizione verrà attivata (e i criteri verranno eseguiti) se viene inviata una chiamata al proxy con /developers alla fine dell'URI.

5. Ora aggiungi un flusso condizionale per /apps e supponi di voler attivare la condizione il giorno sia l'URI che il verbo POST in una richiesta. La configurazione prevede l'impostazione seguenti:
   • Nome flusso: Apps
   • Tipo di condizione: Path and Verb
   • Percorso: /apps
   • Verbo: POST

   La condizione verrà attivata (e i criteri verranno eseguiti) se viene inviata una chiamata al proxy con /apps alla fine dell'URI e un verbo POST.

I flussi aggiunti vengono visualizzati nel riquadro Risposta:

Editor proxy classico

Nel riquadro Sviluppo del riquadro Navigator dell'editor del proxy API, fai clic su accanto a default in Proxy Endpoints.

Nella finestra New Conditional Flow, inserisci le seguenti configurazioni chiave:

• Nome flusso: Developers
• Tipo di condizione: Path
• Percorso: /developers

La condizione verrà attivata (e i criteri verranno eseguiti) se viene inviata una chiamata al proxy con /developers alla fine dell'URI.

Ora aggiungi un flusso condizionale per /apps e supponiamo che tu voglia che la condizione venga attivata sia sull'URI sia sul verbo POST in una richiesta. La configurazione prevede l'impostazione seguenti:

• Nome flusso: Apps
• Tipo di condizione: Path and Verb
• Percorso: /apps
• Verbo: POST

La condizione verrà attivata (e i criteri verranno eseguiti) se viene inviata una chiamata al proxy con /apps alla fine dell'URI e un verbo POST.

Nel riquadro Navigator, vedrai nuovi flussi per App e Sviluppatori.

Seleziona uno dei flussi per visualizzare la configurazione del flusso condizionale nella visualizzazione del codice dell'editor del proxy API:

<Flow name="Apps">
    <Description>Developer apps registered in Developer Services</Description>
    <Request/>
    <Response/>
    <Condition>(proxy.pathsuffix MatchesPath "/apps") and (request.verb = "POST")</Condition>
</Flow>

Come puoi vedere, le risorse API sono semplicemente flussi agevolati che valutano il percorso URI della richiesta in entrata. (La variabile proxy.pathsuffix identifica l'URI della richiesta che segue il BasePath configurato nella configurazione ProxyEndpoint.)

Ogni risorsa API che definisci viene implementata da un flusso condizionale nel proxy API. (Vedi Configurare i flussi.)

Dopo aver eseguito il deployment del proxy API nell'ambiente di test, esegui la richiesta seguente:

http://example.com/PROXY_PATH/apps

La condizione verrà valutata come true e questo flusso, insieme a eventuali criteri associati, verrà eseguito.

La seguente condizione di esempio utilizza un'espressione regolare Java per riconoscere le chiamate effettuate alla risorsa /apps con o senza una barra verticale finale (/apps o /apps/**):

<Condition>(proxy.pathsuffix JavaRegex "/apps(/?)") and (request.verb = "POST")</Condition>

Per saperne di più su questo tipo di condizione, consulta Come eseguire la corrispondenza indipendentemente dal fatto che sia presente o meno un "/" finale nella community Apigee.

Modellazione di URI gerarchici

In alcuni casi, le risorse API saranno gerarchiche. Ad esempio, l'API Developer apps list fornisce un metodo per elencare tutte le app di proprietà di uno sviluppatore. Il percorso dell'URI è:

/developers/DEVELOPER_EMAIL/apps

Potresti avere risorse in cui viene generato un ID univoco per ogni entità di una raccolta, che talvolta viene annotata come segue:

/genus/:id/species

Questo percorso si applica allo stesso modo ai seguenti due URI:

/genus/18904/species
/genus/17908/species

Per rappresentare questa struttura in una risorsa API, puoi utilizzare i caratteri jolly. Ad esempio:

/developers/*/apps
/developers/*example.com/apps
/genus/*/species

Questi risolveranno gli URI gerarchici come risorse API in modo appropriato.

In alcuni casi, soprattutto per le API profondamente gerarchiche, potresti semplicemente voler risolvere tutto ciò che un certo frammento URI. A tal fine, utilizza un asterisco doppio jolly nella definizione della risorsa. Ad esempio, se definisci la seguente risorsa API:

/developers/**

Questa risorsa dell'API risolverà i seguenti percorsi URI:

/developers/DEVELOPER_EMAIL/apps
/developers/DEVELOPER_EMAIL/keys
/developers/DEVELOPER_EMAIL/apps/APP_ID/keys

Ecco come sarebbe la condizione del flusso condizionale nella definizione del proxy API:

<Condition>(proxy.pathsuffix MatchesPath "/developers/**") and (request.verb = "POST")</Condition>

Altri esempi

Condizione collegata a RouteRule

<RouteRule name="default">
  <!--this routing executes if the header indicates that this is an XML call. If true, the
    call is routed to the endpoint XMLTargetEndpoint-->
  <Condition>request.header.content-type = "text/xml"</Condition>
  <TargetEndpoint>XmlTargetEndpoint</TargetEndpoint>
</RouteRule>

Condizione associata a un criterio

<Step>
  <!--the policy MaintenancePolicy only executes if the response status code is exactly 503 -->
  <Condition>response.status.code = 503</Condition>
  <Name>MaintenancePolicy</Name>
</Step>

Flusso condizionale

<!-- this entire flow is executed only if the request verb is a GET-->
<Flow name="GetRequests">
  <Condition>request.verb="GET"</Condition>
  <Request>
    <Step>
<!-- this policy only executes if request path includes a term like statues-->
<Condition>request.path ~ "/statuses/**"</Condition>
      <Name>StatusesRequestPolicy</Name>
    </Step>
  </Request>
  <Response>
    <Step>
<!-- this condition has multiple expressions. The policy executes if the response code status is exactly 503 or 400-->
<Condition>(response.status.code = 503) or (response.status.code = 400)</Condition>
      <Name>MaintenancePolicy</Name>
    </Step>
  </Response>
</Flow>

Operatori di esempio nelle condizioni

Ecco alcuni esempi di operatori utilizzati per creare le condizioni:

• request.header.content-type = text/xml
• request.header.content-length < 4096 && request.verb = PUT
• response.status.code = 404 || response.status.code = 500
• request.uri MatchesPath /*/statuses/**
• request.queryparam.q0 NotEquals 10

Un esempio pratico: ignora/ alla fine di un percorso

Gli sviluppatori Apigee di solito preferiscono gestire entrambi i seguenti suffissi di percorso: /cat e /cat/. Il motivo è che alcuni utenti o clienti potrebbero chiamare l'API con lo barra alla fine del percorso, che devi essere in grado di gestire istruzioni. Questo esatto caso d'uso è stato discusso come trovare una corrispondenza a prescindere dalla presenza di una barra "/" finale all'URL....

Se preferisci, puoi ottenere questo risultato senza utilizzare le espressioni regolari, come descritto di seguito:

    <PreFlow name="PreFlow">
        <Request>
            <Step>
                <Condition>(proxy.pathsuffix = "/cat") OR (proxy.pathsuffix = "/cat/")</Condition>
                <Name>SomePolicy</Name>
            </Step>
        </Request>
        <Response/>
    </PreFlow>

Questa è una buona opzione. È chiara e leggibile.

Puoi fare la stessa cosa con le espressioni regolari in questo modo. Le parentesi vengono utilizzate per raggruppare la parte regex dell'istruzione, ma non sono obbligatorie.

<Condition>(proxy.pathsuffix JavaRegex "/cat(/?)"</Condition>

Chiamate API:

GET http://example.com/matchtest/cat
or GET http://example.com/matchtest/cat/

Il criterio viene eseguito? Sì. Tieni presente che in un'espressione regolare, il valore ? significa che corrisponde a zero o a uno dei caratteri precedenti. Pertanto, /cat e /cat/ sono corrispondenze.

Chiamata API:

GET http://example.com/matchtest/cat/spotted

Il criterio viene eseguito? No. L'espressione regolare corrisponde a zero o solo a una occorrenza del precedente e nient'altro è consentito.

Corrispondenza di stringhe arbitrarie con JavaRegex

In tutti gli esempi di questo argomento viene mostrato come associare una delle variabili di flusso predefinite: proxy.pathsuffix. È bene sapere che puoi eseguire corrispondenze con pattern su qualsiasi stringa arbitraria o che si tratti di una variabile di flusso integrata come proxy.pathsuffix.

Se, ad esempio, hai una condizione che verifica una stringa arbitraria, forse è stata restituita una stringa in un payload backend, o una stringa restituita da una ricerca del server di autenticazione, puoi utilizzare operatori corrispondenti per testarla. Se utilizzi JavaRegex, l'espressione regolare verrà confrontata rispetto all'intera stringa dell'oggetto. Se l'oggetto è abc e l'espressione regolare è [a-z], non esiste una corrispondenza, perché [a-z] corrisponde esattamente a un carattere alfa. La l'espressione [a-z]+ funziona, così come [a-z]* e [a-z]{3}.

Vediamo un esempio concreto. Supponiamo che il server di autenticazione restituisca un elenco di ruoli una stringa delimitata da virgole: editor, author, guest.

Per testare la presenza del ruolo di editor, questa costruzione non funzionerà, perché editor è solo parte dell'intera stringa.

<Condition>returned_roles ~~ "editor"</Condition>

Tuttavia, questa costruzione funzionerà:

<Condition>returned_roles ~~ ".*\beditor\b.*")</Condition>

Funziona perché tiene conto degli a capo e di eventuali altre parti della stringa con il prefisso e il suffisso .*.

In questo esempio, puoi anche testare editor con l'operatore Matches:

<Condition>returned_roles ~~ "*editor*")</Condition>

Tuttavia, nei casi in cui hai bisogno di una maggiore precisione, JavaRegex è spesso una scelta migliore.

Uso di virgolette doppie nelle espressioni JavaRegex

La sintassi delle condizioni richiede che un'espressione JavaRegex sia racchiusa tra virgolette doppie; Pertanto, se disponi un'espressione regolare che includa virgolette doppie, è necessario un modo alternativo per creare corrispondenze. La risposta è Unicode. Ad esempio, supponiamo di passare in un'intestazione che include virgolette doppie, come la seguente:

 -H 'content-type:multipart/related; type="application/xop+xml"'

Se provi a trovare una corrispondenza per l'intestazione in una condizione regex, verrà visualizzato un errore Invalid Condition perché l'espressione include le virgolette doppie:

request.header.Content-Type ~~ "(multipart\/related)(; *type="application\/xop\+xml\")"

La soluzione consiste nel sostituire le virgolette doppie basate su ASCII con l'equivalente Unicode, \u0022. Ad esempio: la seguente espressione è valida e produce il risultato previsto:

request.header.Content-Type ~~ "(multipart\/related)(; *type=\u0022application\/xop\+xml\u0022)"