Condizioni con variabili di flusso

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Le dichiarazioni condizionali sono una struttura di controllo comune in tutti i linguaggi di programmazione. Analogamente a un linguaggio di programmazione, la configurazione del proxy API supporta istruzioni condizionali per Flows, Policy, Steps e RouteRules. Con la definizione di istruzioni condizionali, definisci il comportamento dinamico dell'API. Questo comportamento dinamico ti consente di eseguire operazioni come la conversione di XML in JSON solo per i dispositivi mobili o il routing 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 runtime, senza scrivere alcun codice.

Video

Nota: il seguente video mostra il proxy Editor classico nell'interfaccia utente di Apigee. Apigee sta introducendo una nuova versione dell'Editor proxy, che ha un design diverso dalla versione classica mostrata nel video.

Per ulteriori informazioni sulle variabili e sulle condizioni di flusso, guarda il seguente video:

Configurare istruzioni condizionali

Il comportamento condizionale viene implementato nei proxy API utilizzando una combinazione di conditions e conditions. Un'istruzione condizionale viene creata utilizzando un elemento Condition. La condizione seguente è 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) e > (maggiore di). Per una migliore leggibilità, puoi anche scrivere condizionali come testo: equals, notequals, greaterthan.

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

Nota: per un esempio dell'operatore ~~, vedi il seguente thread della community:

Come eseguire l'override alla fine dell'URL

Le condizioni vengono utilizzate per definire i flussi condizionali del proxy API verso le risorse dell'API di backend, descritti in Creare flussi condizionali alle risorse dell'API di backend. Per un elenco completo delle condizioni, consulta la documentazione di riferimento sulle condizioni.

Variabili

Le condizioni svolgono il loro lavoro valutando i valori delle variabili. Una variabile è una proprietà di una transazione HTTP eseguita da un proxy API o una proprietà della configurazione di un proxy API. Ogni volta che un proxy API riceve una richiesta da un'app, Apigee compila un lungo elenco di variabili associate a elementi come l'ora di sistema, le informazioni di rete dell'app, le intestazioni HTTP dei messaggi, la configurazione del proxy API, le esecuzioni dei criteri e così via. In questo modo viene creato un contesto dettagliato che puoi utilizzare per configurare istruzioni condizionali.

Le variabili utilizzano sempre una notazione punteggiata. Ad esempio, le intestazioni HTTP nel messaggio di richiesta sono disponibili come variabili chiamate request.header.HEADER_NAME. Per valutare Content-type header, potresti quindi utilizzare la variabile request.header.Content-type. Ad esempio, request.header.Content-type = "application/json" indica che il tipo di contenuti della richiesta deve essere JSON.

Immagina di dover creare un'istruzione condizionale che farà sì che un criterio venga applicato solo quando un messaggio di richiesta è un GET. Per creare una condizione che valuti il verbo HTTP di una richiesta, crea l'istruzione condizionale di seguito. 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 riportato sopra restituisce true se 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 a cui è possibile accedere utilizzando i prefissi delle variabili request.header. e request.queryparam..

Per abilitare il comportamento dinamico, puoi collegare le condizioni a Flows, Steps e RouteRules.

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

Ad esempio, per creare un Flow che venga eseguito solo quando il verbo della 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 le richieste POST:

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

Come mostrato nell'esempio seguente, puoi applicare la condizione al passaggio relativo alle norme. La condizione seguente causa l'applicazione del criterio VerificationAPIKey solo se un messaggio di richiesta è POST.

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

Dopo aver definito questi flussi condizionali, puoi collegarli ai criteri, abilitando un proxy API per 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 per le variabili di flusso
• Informazioni sulle condizioni

Esempio 1

L'esempio seguente mostra un singolo flusso condizionale denominato Convert-for-devices, configurato nel flusso di risposta di ProxyEndpoint. Aggiungi la condizione come elemento all'entità a cui si applica la condizione. In questo esempio, la condizione è un componente del flusso. Di conseguenza, 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 archivia i valori di tutte le intestazioni HTTP presenti come variabili. Se la richiesta contiene un'intestazione HTTP denominata User-Agent, l'intestazione e il relativo valore vengono archiviati come una variabile denominata request.header.User-Agent.

Data la configurazione ProxyEndpoint sopra riportata, Apigee controlla il valore della variabile request.header.User-Agent per verificare se la condizione restituisce true.

Se la condizione restituisce true, ovvero il valore della variabile request.header.User-Agent è uguale a Mozilla, viene eseguito il flusso condizionale e viene applicato il criterio XMLtoJSON denominato ConvertToJSON. In caso contrario, il Flow non viene eseguito e la risposta XML viene restituita senza modifiche (in formato XML) all'app richiedente.

Esempio 2

Utilizziamo un esempio specifico in cui è necessario trasformare il messaggio di risposta da XML a JSON, ma solo per i dispositivi mobili. Innanzitutto, crea il criterio che convertirà la risposta in formato XML dall'API Weather in 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, eseguire una conversione da XML a JSON con le impostazioni predefinite e scrivere il risultato nel nuovo messaggio di risposta. Se vuoi convertire un messaggio di richiesta da XML a JSON, è sufficiente impostare entrambi questi valori su request.

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

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 in JSON prima che vengano restituite all'app client, configura il seguente flusso di risposta ProxyEndpoint.

<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 bollettini meteo in JSON solo quando il client richiedente è un dispositivo mobile. Per abilitare 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, causando la valutazione dell'istruzione condizionale su true e l'esecuzione del flusso condizionale Convert-for-devices.

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

oppure, per creare i testi in cui è disponibile Python:

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 dei pattern con le condizioni in un flusso Apigee.

Per approfondire

• Informazioni sulle condizioni
• Il "condition-pattern-matching proxy" nel nostro repository api-platform-samples in GitHub

Operatori

Questa sezione descrive come utilizzare i seguenti operatori di corrispondenza di pattern nelle istruzioni condizionali:

• Operatore Matches: corrispondenza semplice di pattern
• Operatore JavaRegex: controllo più preciso sulla corrispondenza
• Operatore MatchesPath: corrispondenza con frammento del percorso

Corrisponde a

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

Riepilogo: l'operatore Matches offre due possibilità. Crea una corrispondenza letterale della stringa o 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 alle espressioni regolari. Se vuoi utilizzare la corrispondenza delle espressioni regolari, usa l'operatore JavaRegex.

Il seguente codice XML mostra una condizione di passaggio. Esegue il criterio SomePolicy quando la condizione ha valore true. In questo esempio, testiamo la variabile proxy.pathsuffix, una variabile integrata in Apigee che archivia il suffisso del percorso della richiesta. Tuttavia, puoi verificare il valore di qualsiasi variabile di flusso contenente una stringa. Quindi, 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 proxy comporterà l'esecuzione di SomePolicy? C'è una sola possibilità.

Chiamata API:

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

Il criterio viene eseguito? Sì, perché il suffisso del percorso proxy corrisponde esattamente a /cat. Non viene eseguito se il suffisso è /bat o /dog, / o altro.

Ora consideriamo questa affermazione 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" è una corrispondenza.

Chiamata API:

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

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

Chiamata API:

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

Il criterio viene eseguito? Certo no: anche se il carattere jolly corrisponde a 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 di qualsiasi tipo.

Chiamata API:

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

Il criterio viene eseguito? No, /bat non corrisponde.

Chiamata API:

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

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

Chiamata API:

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

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

Domanda: l'operatore Matches è sensibile alle maiuscole?

Sì. Supponi di avere una condizione come la seguente:

<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 e minuscole), ma il minuscolo a non corrisponde a A.

Chiamata API:

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

Il criterio viene eseguito? Sì, il caso corrisponde.

Domanda: come faccio a eseguire l'escape dei caratteri con l'operatore Matches?

Utilizza il carattere percentuale % per eseguire l'escape dei 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 sta cercando la stringa letterale c*at.

Chiamata API:

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

Question:Il criterio viene eseguito?

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

JavaRegex

Come puoi vedere, l'operatore Matches è ottimo per situazioni semplici. Tuttavia, puoi utilizzare un altro operatore, l'operatore JavaRegex o ~~. Questi due operatori sono gli stessi, ad eccezione del fatto che JavaRegex è considerato più leggibile. Si chiama JavaRegex perché consente la corrispondenza con pattern di espressioni regolari e Apigee segue le stesse regole delle classi nel pacchetto java.util.regex nel linguaggio Java. Il funzionamento dell'operatore JavaRegex è molto diverso dall'operatore Matches, quindi è importante non confondere i due.

Nota: se sei abituato a eseguire le espressioni regolari negli script Perl, è importante notare che l'operatore JavaRegex in Apigee testa l'intera stringa del soggetto. Ad esempio, se l'oggetto è abc e l'espressione regolare è [a-z] , non ci sono corrispondenze perché [a-z] corrisponde esattamente a un carattere alpha. L'espressione [a-z]+ funzionerebbe allo stesso modo di [a-z]{3}. Questa corrispondenza è diversa dalla solita applicazione delle espressioni regolari in strumenti come Perl, grep o mod_rewrite di Apache. JavaRegex utilizza java.util.regex.Pattern.matches(str), che viene definito per restituire un valore positivo se l'intera stringa (str) corrisponde al pattern. L'espressione regolare 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 essere un'introduzione dettagliata alle espressioni regolari. Lo scopo principale è illustrare alcuni semplici esempi e evidenziare la differenza tra gli operatori Matches e JavaRegex. Per saperne di più sulle espressioni regolari, puoi utilizzare molte risorse.

Riepilogo: l'operatore JavaRegex consente di utilizzare la sintassi delle espressioni regolari nelle istruzioni condizionali.

Il seguente codice mostra una condizione Passaggio. Esegue il criterio SomePolicy se la condizione ha valore 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 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 JavaRegex "/cat")</Condition>
                <Name>SomePolicy</Name>
            </Step>
        </Request>
        <Response/>
    </PreFlow>

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

Domanda: quale suffisso del percorso proxy comporterà l'esecuzione di SomePolicy? Come con l'operatore Matches, c'è solo una possibilità in questo caso.

Chiamata API:

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

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

Ora creiamo un'espressione regolare utilizzando il quantificatore *. Questo quantificatore corrisponde a zero o più 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ù dei caratteri precedenti, ovvero c.

Chiamata API:

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

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

Quindi utilizziamo il quantificatore ?, che corrisponde una sola volta al carattere che lo precede o non corrisponde affatto.

<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 del carattere precedente, che è un 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 la condizione restituisce true.

Chiamata API:

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

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

Quindi, utilizziamo lo stile [abc] o di raggruppamento dell'espressione regex. 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ì. Stiamo utilizzando espressioni regolari qui e l'espressione [cbr] corrisponde a un c, b, OR r. Queste chiamate corrispondono anche:

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 la seguente:

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

Chiamata API:

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

Il criterio viene eseguito? Sì, l'espressione regolare 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 lettera A in maiuscolo non corrisponde a a in minuscolo.

MatchesPath

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

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

L'operatore MatchesPath consente di utilizzare due notazioni con caratteri jolly: un singolo asterisco (*) e un doppio asterisco (**). 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. Tuttavia, puoi testare 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 proxy comporterà 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 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 dopo /animals/), ma è semplicemente vuoto.

Chiamata API:

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

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

Chiamata API:

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

Domanda: il criterio viene eseguito?

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

Ora usiamo 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 proxy comporterà 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 è semplicemente vuoto.

Chiamata API:

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

Il criterio viene eseguito?

Sì, perché il percorso ha almeno un elemento successivo a /animals

Chiamata API:

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

Il criterio viene eseguito?

Sì, perché il percorso ha più di un elemento successivo a /animals

Combinazione di asterischi

Puoi utilizzare combinazioni di asterischi (*) e doppi (**) per perfezionare ulteriormente la 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 frammento di percorso URI che identifica alcune entità a cui gli sviluppatori possono accedere chiamando l'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 alla relazione tra le risorse di backend RESTful e le risorse proxy Apigee o i flussi condizionali.
• Crea il tuo primo proxy API

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

URL di base di backend	URL 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. Tuttavia, quando utilizzi 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, i proxy consentono anche di definire 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. Di seguito verranno descritti i flussi condizionali in maggiore dettaglio.

In che modo 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 il proxy), puoi aggiungere flussi condizionali a risorse specifiche, ad esempio le risorse /reports e /forecasts menzionate in precedenza.

Supponiamo che tu voglia che Apigee svolga un'azione quando arrivano le chiamate alle risorse /reports o /forecasts. A questo punto non stai dicendo ad Apigee cosa fare, ma che dovrebbe ascoltare le chiamate a quelle risorse. Per farlo, devi utilizzare le condizioni. Nel proxy API Apigee, puoi creare flussi condizionali per /reports e /forecasts. A scopo concettuale, il seguente codice XML del proxy API mostra l'aspetto di 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 una richiesta GET arriva con /reports e /forecasts nell'URL, Apigee farà qualsiasi cosa ti dica (lo sviluppatore dell'API) attraverso i criteri che alleghi ai flussi.

Ora, ecco un esempio in cui viene indicato ad Apigee cosa fare quando una condizione è soddisfatta. Nel seguente codice XML del proxy API, 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 include anche due flussi predefiniti: un <PreFlow> eseguito prima dei flussi condizionali e un <PostFlow> eseguito dopo i flussi condizionali. Questi sono utili per l'esecuzione di criteri quando viene effettuata una chiamata qualsiasi 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 viene eseguito l'accesso, puoi inserire un criterio Verifica chiave API su <PreFlow>. Per saperne di più sui flussi, consulta Configurazione dei flussi.

Creazione di flussi condizionali alle risorse di backend

La definizione dei flussi condizionali alle risorse di backend in un proxy API è completamente facoltativa. Tuttavia, questi flussi condizionali ti consentono di applicare una gestione e un monitoraggio granulari.

Sarai in grado di:

• Applica la gestione in modo da riflettere la semantica del tuo modello API
• Applica criteri e comportamento basato su script a singoli percorsi di risorse (URI)
• Raccogliere metriche granulari per Analytics Services

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

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

Nota: Apigee sta introducendo una nuova versione dell'editor proxy, che semplificherà la gestione dei proxy.

Le istruzioni nelle prime due schede di seguito spiegano come utilizzare il nuovo Proxy Editor o la versione classica.

Nuovo editor proxy

Per aggiungere un flusso condizionale:

1. Seleziona la scheda Develop nell'editor proxy.
2. Seleziona Endpoint proxy > predefiniti nel riquadro a sinistra.

   

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

   

4. Nella finestra di dialogo 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 supponiamo che tu voglia attivare la condizione sia sull'URI sia sul verbo POST in una richiesta. La configurazione prevede l'impostazione di quanto segue:
   • 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 proxy API, fai clic su accanto a predefinita in Endpoint del proxy.

Nella finestra Nuovo flusso condizionale, inserisci le seguenti configurazioni di chiavi:

• 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 attivare la condizione sia sull'URI sia sul verbo POST in una richiesta. La configurazione prevede l'impostazione di quanto segue:

• 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 Navigazione, vedrai i nuovi flussi per App e Sviluppatori.

Seleziona uno dei flussi per visualizzare la configurazione del flusso condizionale nella visualizzazione codice dell'editor 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 condizionali che valutano il percorso dell'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 è implementata da un flusso condizionale nel proxy API. (Vedi Configurare i flussi.)

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

http://example.com/PROXY_PATH/apps

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

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

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

Per ulteriori informazioni su questo tipo di condizione, consulta Come effettuare una corrispondenza indipendentemente dal fatto che esista un carattere "/" ... finale nella community Apigee.

Modellazione degli URI gerarchici

In alcuni casi, avrai risorse API gerarchiche. Ad esempio, l'API Developer Apps List fornisce un metodo per elencare tutte le app che appartengono a uno sviluppatore. Il percorso dell'URI è:

/developers/DEVELOPER_EMAIL/apps

Potrebbero esserci risorse in cui viene generato un ID univoco per ogni entità in una raccolta, che a volte è annotata come segue:

/genus/:id/species

Questo percorso si applica anche 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

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

In alcuni casi, soprattutto per le API profondamente gerarchiche, potresti voler risolvere tutto ciò che si trova al di sotto di un determinato frammento URI. Per farlo, utilizza un carattere jolly con doppio asterisco nella definizione della risorsa. Ad esempio, se definisci la seguente risorsa API:

/developers/**

Quella risorsa 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 di 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 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 in genere vogliono gestire entrambi i seguenti suffissi di percorso: /cat e /cat/. Questo perché alcuni utenti o client potrebbero chiamare la tua API con la barra aggiuntiva alla fine del percorso e devi essere in grado di gestirla nelle istruzioni condizionali. Questo caso d'uso esatto è stato discusso in come trovare una corrispondenza a prescindere dalla presenza di un carattere "/" finale nell'URL....

Se preferisci, puoi ottenere questo risultato senza utilizzare le espressioni regolari come la seguente:

    <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. Sia chiaro e leggibile.

Tuttavia, puoi fare la stessa cosa con le espressioni regolari. 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 carattere ? indica: 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 a una sola occorrenza del carattere precedente e nient'altro è consentito.

Corrispondenza di stringhe arbitrarie con JavaRegex

In tutti gli esempi di questo argomento, mostriamo come associare una delle variabili di flusso integrate: proxy.pathsuffix. È utile sapere che puoi trovare una corrispondenza di pattern su qualsiasi stringa arbitraria o variabile di flusso, indipendentemente dal fatto che si tratti o meno di una variabile di flusso integrata come proxy.pathsuffix.

Se, ad esempio, hai una condizione che verifica una stringa arbitraria, magari una stringa restituita in un payload di 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 con l'intera stringa dell'oggetto. Se l'oggetto è abc e l'espressione regolare è [a-z], non ci sono corrispondenze perché [a-z] corrisponde esattamente a un carattere alpha. 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 sotto forma di stringa delimitata da virgole: editor, author, guest.

Per verificare la presenza del ruolo Editor, questa costruzione non funzionerà, perché editor fa solo parte dell'intera stringa.

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

Tuttavia, questa configurazione funzionerà:

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

Funziona perché tiene conto delle interruzioni di parola e di qualsiasi altra parte 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 è necessaria una maggiore precisione, JavaRegex è spesso una scelta migliore.

Carattere di escape con le virgolette doppie nelle espressioni JavaRegex

La sintassi della condizione richiede che l'espressione JavaRegex sia racchiusa tra virgolette doppie. Di conseguenza, se hai un'espressione regex che include le virgolette doppie, devi usare un modo alternativo per trovare una corrispondenza. La risposta è Unicode. Ad esempio, supponiamo che passi un'intestazione che include virgolette doppie, come segue:

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

Se provi a trovare una corrispondenza per l'intestazione in una condizione regex, riceverai 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)"