Stai visualizzando la documentazione di Apigee Edge.
Vai alla
documentazione di Apigee X. informazioni
Cosa
Il criterio ExtractVariables estrae contenuti da una richiesta o risposta e imposta il valore di una variabile su questi contenuti. Puoi estrarre qualsiasi parte del messaggio, inclusi intestazioni, percorsi URI, payload JSON/XML, parametri del modulo e parametri di query. Il criterio funziona applicando un pattern di testo ai contenuti del messaggio e, quando viene trovata una corrispondenza, imposta una variabile con il contenuto del messaggio specificato.
Anche se spesso utilizzi questo criterio per estrarre informazioni da una richiesta o da un messaggio di risposta, puoi usarlo anche per estrarre informazioni da altre origini, tra cui entità create dal criterio AccessEntity, oggetti XML o oggetti JSON.
Dopo aver estratto i contenuti del messaggio specificati, puoi fare riferimento alla variabile in altri criteri durante l'elaborazione di una richiesta e una risposta.
Video
Guarda i seguenti video per scoprire di più sulla norma ExtractVariable.
Video | Descrizione |
---|---|
Estrai variabili dal payload XML | Estrai variabili da un payload XML utilizzando il criterio Estrai variabile. |
Estrai variabili dal payload JSON | Estrai variabili da un payload JSON utilizzando il criterio Estrai variabile. |
Estrai variabili dai parametri | Estrai variabili dai parametri, ad esempio parametri di query, intestazione, modulo o URI. |
Estrai variabili da parametri multivalore | Estrai variabili da parametri multivalore. |
Estrai variabili dal parametro di query (perimetro classico) | Estrai variabili da un parametro di query utilizzando l'interfaccia utente classica di Edge. |
Estrai variabili dal payload XML o JSON (Classic Edge) | Estrai variabili da un payload XML o JSON utilizzando la UI classica di Edge. |
Samples
Questi esempi di codice dei criteri mostrano come estrarre variabili dai seguenti tipi di artefatti:
GitHub
Questi link rimandano a esempi di proxy API funzionanti che puoi distribuire ed eseguire su Edge. Utilizzano ExtractVariables e si trovano nel repository api-platform-samples di Apigee su GitHub. I file README spiegano come ExtractVariables viene utilizzato in ogni caso e come eseguire il deployment e eseguire ogni campione.
URI
<ExtractVariables name="ExtractVariables-1"> <DisplayName>Extract a portion of the url path</DisplayName> <Source>request</Source> <URIPath> <Pattern ignoreCase="true">/accounts/{id}</Pattern> </URIPath> <VariablePrefix>urirequest</VariablePrefix> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </ExtractVariables>
Considera il codice dei criteri di esempio riportato sopra. L'elemento <URIPath>
indica al criterio ExtractVariables di estrarre informazioni dal percorso URI. L'elemento
<Pattern>
specifica il pattern da applicare al percorso dell'URI. Il pattern viene trattato come un modello semplice, con le parentesi graffe che indicano la parte variabile del percorso dell'URI.
Il nome della variabile da impostare è determinato dal valore specificato nell'elemento
<VariablePrefix>
, così come dal valore racchiuso tra parentesi graffe {}
nell'elemento <Pattern>
. I due valori vengono uniti da un punto intermedio,
generando, ad esempio, il nome della variabile urirequest.id
. Se non è presente alcun elemento <VariablePrefix>
, il nome della variabile è solo il valore racchiuso tra parentesi graffe.
Considera il codice dei criteri di esempio riportato sopra che lavora con la seguente richiesta in entrata:
GET http://org1-test.apigee.net/svc1/accounts/12797282
Supponiamo che il percorso base per il proxy API sia /svc1
. Quando Apigee Edge applica il
codice del criterio ExtractVariables riportato sopra a questa richiesta in entrata, imposta la variabile
urirequest.id
su 12797282
. Dopo che Apigee Edge ha eseguito il criterio,
i criteri o il codice successivi nel flusso di elaborazione possono fare riferimento alla variabile denominata
urirequest.id
per ottenere il valore stringa 12797282
.
Ad esempio, il seguente criterio di AssegnaMessage incorpora il valore di quella variabile nel payload di un nuovo messaggio di richiesta:
<AssignMessage async="false" continueOnError="false" enabled="true" name="AssignPayload"> <DisplayName>AssignPayload</DisplayName> <Set> <Payload contentType="text/xml"> <IdExtractedFromURI>{urirequest.id}</IdExtractedFromURI> </Payload> </Set> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo createNew="true" transport="http" type="request">newRequest</AssignTo> </AssignMessage>
Parametri di query
<ExtractVariables name="ExtractVariables-2"> <DisplayName>Extract a value from a query parameter</DisplayName> <Source>request</Source> <QueryParam name="code"> <Pattern ignoreCase="true">DBN{dbncode}</Pattern> </QueryParam> <VariablePrefix>queryinfo</VariablePrefix> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </ExtractVariables>
Considera il codice dei criteri di esempio riportato sopra che lavora con la seguente richiesta in entrata:
GET http://org1-test.apigee.net/accounts/12797282?code=DBN88271
Quando Apigee Edge applica il codice del criterio ExtractVariables riportato sopra a questa richiesta in entrata,
imposta la variabile queryinfo.dbncode
su 88271
. Dopo che Apigee Edge
ha eseguito il criterio, i criteri o il codice successivi nel flusso di elaborazione possono fare riferimento alla
variabile denominata queryinfo.dbncode
per ottenere il valore stringa 88271
.
Ora puoi accedere alla variabile queryinfo.dbncode
nel tuo proxy.
Ad esempio, il seguente criterio AttributionMessage lo copia nel payload della richiesta:
<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath"> <DisplayName>GetQP</DisplayName> <Set> <Payload contentType="text/xml"> <ExtractQP>{queryinfo.dbncode}</ExtractQP> </Payload> </Set> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
Più parametri
<ExtractVariables name="ExtractVariables-2"> <DisplayName>Extract a value from a query parameter</DisplayName> <Source>request</Source> <QueryParam name="w"> <Pattern ignoreCase="true">{firstWeather}</Pattern> </QueryParam> <QueryParam name="w.2"> <Pattern ignoreCase="true">{secondWeather}</Pattern> </QueryParam> <VariablePrefix>queryinfo</VariablePrefix> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </ExtractVariables>
Supponi che la progettazione dell'API ti consenta di specificare più parametri di query con lo stesso nome. Puoi utilizzare questo criterio per estrarre il valore di più istanze del parametro di query "w". Per fare riferimento a questi parametri di query nel criterio ExtractVariables, utilizza gli indici, in cui la prima istanza del parametro di query non ha un indice, la seconda si trova all'indice 2, la terza all'indice 3 e così via.
Considera il codice dei criteri di esempio riportato sopra che lavora con la seguente richiesta in entrata:
GET http://org1-test.apigee.net/weather?w=Boston&w=Chicago
Quando Apigee Edge applica il codice del criterio ExtractVariables riportato sopra a questa richiesta in arrivo,
imposta la variabile queryinfo.firstWeather
su Boston
e la
variabile queryInfo.secondWeather
su Chicago
.
Ora puoi accedere alla variabile queryinfo.firstWeather
e
queryinfo.secondWeather nel
tuo proxy. Ad esempio, il seguente criterio di AssegnaMessage lo copia nel payload della richiesta:
<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath"> <DisplayName>GetQP</DisplayName> <Set> <Payload contentType="text/xml"> <ExtractQP1>{queryinfo.firstWeather}</ExtractQP1> <ExtractQP2>{queryinfo.secondWeather}</ExtractQP2> </Payload> </Set> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
Intestazioni
<ExtractVariables name='ExtractVariable-OauthToken'> <Source>request</Source> <Header name="Authorization"> <Pattern ignoreCase="false">Bearer {oauthtoken}</Pattern> </Header> <VariablePrefix>clientrequest</VariablePrefix> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </ExtractVariables>
Supponiamo che la tua API utilizzi token di connessione OAuth v2.0. Considera il codice dei criteri di esempio riportato sopra per una richiesta contenente un token OAuth 2.0 che include un'intestazione come la seguente:
Authorization: Bearer TU08xptfFfeM7aS0xHqlxTgEAdAM.
In qualità di designer dell'API, supponi di voler utilizzare il valore del token (ma non l'intera intestazione) come chiave in una ricerca nella cache. Puoi utilizzare il codice del criterio ExtractVariables riportato sopra per estrarre il token.
Quando Apigee Edge applica il codice del criterio ExtractVariables riportato sopra a questa intestazione, la variabile clientrequest.oauthtoken
verrà impostata su
TU08xptfFfeM7aS0xHqlxTgEAdAM
.
Ora puoi accedere alla variabile clientrequest.oauthtoken
nel tuo proxy. Ad esempio, il seguente criterio di AssegnaMessage lo copia nel payload della richiesta:
<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath"> <DisplayName>GetHeader</DisplayName> <Set> <Payload contentType="text/xml"> <ExtractHeader>{clientrequest.oauthtoken}</ExtractHeader> </Payload> </Set> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
JSON
<ExtractVariables name="ExtractVariables-3"> <Source>response</Source> <JSONPayload> <Variable name="latitude" type="float"> <JSONPath>$.results[0].geometry.location.lat</JSONPath> </Variable> <Variable name="longitude" type="float"> <JSONPath>$.results[0].geometry.location.lng</JSONPath> </Variable> </JSONPayload> <VariablePrefix>geocoderesponse</VariablePrefix> </ExtractVariables>
<JSONPayload>
$
Considera il seguente payload di risposta JSON:
{ "results": [{ "geometry": { "location": { "lat": 37.42291810, "lng": -122.08542120 }, "location_type": "ROOFTOP", "viewport": { "northeast": { "lat": 37.42426708029149, "lng": -122.0840722197085 }, "southwest": { "lat": 37.42156911970850, "lng": -122.0867701802915 } } } }] }
Quando Apigee Edge applica il codice del criterio ExtractVariables riportato sopra a questo messaggio JSON, imposta due variabili: geocoderesponse.latitude
e geocoderesponse.longitude
. Entrambe le variabili utilizzano lo stesso prefisso di variabile di
geocoderesponse
. Il suffisso per queste variabili è specificato esplicitamente
dall'attributo name
dell'elemento <Variable>
.
La variabile geocoderesponse.latitude
ottiene il valore
37.42291810
. La variabile geocoderesponse.longitude
ottiene il valore
-122.08542120
.
Ora puoi accedere alla variabile geocoderesponse.latitude
nel tuo proxy. Ad esempio, il seguente criterio di AssegnaMessage lo copia in un'intestazione denominata "latitudine" nella risposta:
<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath"> <DisplayName>GetJSONVar</DisplayName> <Add> <Headers> <Header name="latitude">{geocoderesponse.latitude}</Header> </Headers> </Add> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo createNew="false" transport="http" type="response"/> </AssignMessage>
XML
<ExtractVariables name="ExtractVariables-4"> <Source>response</Source> <XMLPayload> <Namespaces> <Namespace prefix="dir">urn:43BFF88D-D204-4427-B6BA-140AF393142F</Namespace> </Namespaces> <Variable name="travelmode" type="string"> <XPath>/dir:Directions/dir:route/dir:leg/dir:step/@mode</XPath> </Variable> <Variable name="duration" type="string"> <XPath>/dir:Directions/dir:route/dir:leg/dir:step/dir:duration/dir:value</XPath> </Variable> <Variable name="timeunit" type="string"> <XPath>/dir:Directions/dir:route/dir:leg/dir:step/dir:duration/dir:text</XPath> </Variable> </XMLPayload> <VariablePrefix>directionsresponse</VariablePrefix> </ExtractVariables>
<XMLPayload>
Considera il seguente payload di risposta XML:
<Directions xmlns="urn:43BFF88D-D204-4427-B6BA-140AF393142F"> <status>OK</status> <route> <summary>I-40 W</summary> <leg> <step mode="DRIVING"> <start_location> <lat>41.8507300</lat> <lng>-87.6512600</lng> </start_location> <end_location> <lat>41.8525800</lat> <lng>-87.6514100</lng> </end_location> <duration> <value>19</value> <text>minutes</text> </duration> </step> </leg> </route> </Directions>
Quando Apigee Edge applica il codice del criterio ExtractVariables riportato sopra a questo messaggio XML,
imposta tre variabili: directionsresponse.travelmode,
directionsresponse.duration
e directionsresponse.timeunit
. Tutte
le variabili utilizzano lo stesso prefisso di variabile di directionsresponse
. Il suffisso per queste variabili è specificato in modo esplicito dall'attributo name
dell'elemento <Variable>
.
La variabile directionsresponse.travelmode
ottiene il valore
DRIVING
. La variabile directionsresponse.duration
ottiene il valore
19
. La variabile directionsresponse.timeunit
ottiene il valore
minutes
.
Ora puoi accedere alla variabile directionresponse.travelmode
nel
proxy. Ad esempio, il seguente criterio di AssegnaMessage lo copia in un'intestazione denominata "tmode" nella risposta:
<AssignMessage async="false" continueOnError="false" enabled="true" name="GetURIPath"> <DisplayName>GetXMLVar</DisplayName> <Add> <Headers> <Header name="tmode">{directionsresponse.travelmode}</Header> </Headers> </Add> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
Informazioni sulla norma ExtractVariables
Gli sviluppatori di API creano proxy API che si comportano in modo diverso in base ai contenuti dei messaggi, inclusi intestazioni, percorsi URI, payload e parametri di query. Spesso, il proxy estrae una parte di questi contenuti per utilizzarla in una dichiarazione di condizione. Per farlo, utilizza il criterio ExtractVariables.
Quando definisci il criterio ExtractVariables, puoi scegliere:
- Nomi delle variabili da impostare
- Origine delle variabili
- Numero di variabili da estrarre e impostare
Quando viene eseguito, il criterio applica un pattern di testo ai contenuti e, se viene trovata una corrispondenza, imposta il valore della variabile designata con i contenuti. Altri criteri e codice possono quindi utilizzare queste variabili per abilitare il comportamento dinamico o per inviare dati aziendali ad Analisi delle API Edge.
Per scoprire come ExtractVariables può essere utilizzato per creare report di Analytics basati sui contenuti, consulta Analizzare i contenuti dei messaggi dell'API utilizzando strumenti di analisi personalizzati.
Ambito
Le variabili impostate con il criterio ExtractVariables hanno un ambito globale. In altre parole, dopo che il criterio ExtractVariables ha definito una nuova variabile, puoi accedervi da qualsiasi criterio o codice in qualsiasi fase del flusso (che viene eseguita dopo il criterio ExtractVariables). Ad esempio:
- PreFlow: ProxyEndpoint e TargetEndpoint (richiesta e risposta)
- PostFlow: ProxyEndpoint e TargetEndpoint (richiesta e risposta)
- PostClientFlow: ProxyEndpoint (solo risposta, utilizzando il criterio di logging dei messaggi)
- Flussi di errore
Informazioni sulla corrispondenza e sulla creazione delle variabili
Il criterio ExtractVariables estrae informazioni da una richiesta o risposta e le scrive in una variabile. Per ogni tipo di informazioni che puoi estrarre, come il percorso URI o i dati XML, devi specificare il pattern con cui trovare una corrispondenza e il nome della variabile utilizzata per contenere le informazioni estratte.
Tuttavia, il modo in cui funziona la corrispondenza dei pattern dipende dall'origine dell'estrazione. Le seguenti sezioni descrivono le due categorie di base di informazioni che puoi estrarre.
Percorsi dell'URI, parametri di query, intestazioni, parametri del modulo e variabili corrispondenti
Quando estrai informazioni da un percorso URI, parametri di query, intestazioni, parametri modulo e variabili, utilizzi il tag <Pattern> per specificare uno o più pattern da abbinare. Ad esempio, il seguente esempio di criterio mostra un singolo pattern corrispondente per il percorso dell'URI:
<ExtractVariables name="ExtractVariables-1"> <Source>request</Source> <URIPath> <Pattern ignoreCase="true">/a/{pathSeg}</Pattern> </URIPath> <VariablePrefix>urirequest</VariablePrefix> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </ExtractVariables>
In questo esempio, la variabile urirequest.pathSeg è impostata su ciò che viene visualizzato nel proxy.pathsuffix dopo "/a/". Ad esempio, supponi che il percorso di base per il proxy API sia /basepath/v1 . Con una richiesta in entrata a http://myCo.com/basepath/v1/a/b, la variabile è impostata su "b".
Specificare più pattern
Puoi specificare più pattern corrispondenti, corrispondenti ai tag <Pattern>, dove:
- Tutti i pattern vengono testati per verificare la corrispondenza.
- Se nessuno dei pattern corrisponde, il criterio non fa nulla e le variabili non vengono create.
- Se più pattern corrispondono, per l'estrazione viene utilizzato il pattern con segmenti del percorso più lunghi.
- Se due pattern corrispondenti hanno gli stessi segmenti del percorso più lunghi, per l'estrazione viene utilizzato il pattern specificato per primo nel criterio.
Nel prossimo esempio, creerai un criterio che contiene tre pattern corrispondenti per il percorso dell'URI:
<ExtractVariables name="ExtractVariables-1"> <Source>request</Source> <URIPath> <Pattern ignoreCase="true">/a/{pathSeg}</Pattern> <Pattern ignoreCase="true">/a/b/{pathSeg}</Pattern> <Pattern ignoreCase="true">/a/b/c/{pathSeg}</Pattern> </URIPath> <VariablePrefix>urirequest</VariablePrefix> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </ExtractVariables>
Supponiamo, per un proxy API con un percorso base di /basepath/v1 , che l'URL della richiesta in entrata al proxy API abbia il seguente formato:
http://myCo.com/basepath/v1/a/b
In questo esempio, il primo pattern corrisponde all'URI e la variabile urirequest.pathSeg è impostata su "b".
Se l'URL della richiesta è:
http://myCo.com/basepath/v1/a/b/c/d
...quindi il terzo pattern corrisponde e la variabile urirequest.pathSeg è impostata su "d".
Specificare pattern con più variabili
Puoi specificare più variabili nel pattern corrispondente. Ad esempio, specifichi un pattern di corrispondenza con due variabili:
<ExtractVariables name="ExtractVariables-1"> <Source>request</Source> <URIPath> <Pattern ignoreCase="true">/a/{pathSeg}</Pattern> <Pattern ignoreCase="true">/a/b/{pathSeg}</Pattern> <Pattern ignoreCase="true">/a/{pathSeg1}/c/{pathSeg2}</Pattern> </URIPath> <VariablePrefix>urirequest</VariablePrefix> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </ExtractVariables>
Anche in questo caso , supponi un proxy API con un percorso di base di /basepath/v1 per l'URL della richiesta in entrata:
http://myCo.com/basepath/v1/a/b/c/d
...la variabile urirequest.pathSeg1 è impostata su "b" e la variabile urirequest.pathSeg2 è impostata su "d".
Corrispondenza di più istanze nel pattern
Puoi anche creare corrispondenze con i pattern quando esistono più istanze di un elemento con lo stesso nome. Ad esempio, puoi effettuare una richiesta contenente più parametri di query o più intestazioni con lo stesso nome. La seguente richiesta contiene due parametri di query denominati "w":
http://myCo.com/basepath/v1/a/b/c/d?w=1&w=2
Per fare riferimento a questi parametri di query nel criterio ExtractVariables, utilizza gli indici, in cui la prima istanza del parametro di query non ha un indice, la seconda si trova nell'indice 2, la terza nell'indice 3 e così via. Ad esempio, il seguente criterio estrae il valore del secondo parametro di query denominato "w" nella richiesta:
<ExtractVariables name="ExtractVariables-1"> <Source>request</Source> <QueryParam name="w.2"> <Pattern ignoreCase="true">{secondW}</Pattern> </QueryParam> <VariablePrefix>urirequest</VariablePrefix> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </ExtractVariables>
La variabile urirequest.secondW è impostata su "2". Se il secondo parametro di query viene omesso dalla richiesta, la variabile urirequest.secondW è vuota. Utilizza l'indicizzazione ogni volta che nella richiesta sono presenti più elementi con lo stesso nome.
Utilizzare caratteri speciali nel pattern
Durante la corrispondenza dei percorsi dell'URI, puoi utilizzare i caratteri jolly "*" e "**" nel pattern, dove:
- "*" corrisponde a un segmento qualsiasi del percorso
- "**" corrisponde a più segmenti del percorso
Ad esempio, puoi specificare pattern per l'elemento <URIPath> come mostrato di seguito:
<URIPath> <Pattern ignoreCase="true">/a/*/{id}</Pattern> <Pattern ignoreCase="true">/a/**/{id}</Pattern> </URIPath>
Il primo pattern corrisponde alle richieste con pathuffix (la parte del percorso URI che segue il percorso base) come "/a/b/c", "/a/foo/bar" e così via. Il secondo pattern corrisponde a un numero qualsiasi di segmenti di percorso dopo "/a/", ad esempio "/a/foo/bar/baz/c", nonché "/a/b/c" e "/a/foo/bar".
Quando specifichi pattern per parametri di query, intestazioni e parametri del modulo, il carattere "*" specifica di corrispondere a un numero qualsiasi di caratteri. Ad esempio, quando cerchi una corrispondenza con un'intestazione, specifica il pattern come:
*;charset={encoding}
Questo pattern corrisponde ai valori "text/xml;charset=UTF-16" e "application/xml;charset=ASCII".
Se il valore trasmesso al criterio ExtractVariables contiene un carattere speciale, come "{", utilizza il carattere "%" come carattere di escape. L'esempio seguente esegue l'escape dei caratteri "{" e "}" nel pattern perché vengono utilizzati come caratteri letterali nel valore del parametro di query:
<QueryParam> <Pattern ignoreCase="true">%{user%} {name}</Pattern> </QueryParam>
In questo esempio, il pattern corrisponde al valore "{user} Steve", ma non al valore "user Steve".
JSON e XML corrispondenti
Quando estrai i dati da JSON e XML, devi specificare uno o più tag <Variable> nel criterio. Il tag <Variable> specifica il nome della variabile di destinazione in cui sono archiviate le informazioni estratte e il JsonPath (JSON) o XPATH (XML) alle informazioni estratte.
Tutti i tag <Variable> nel criterio vengono valutati in modo da poter completare più variabili da un singolo criterio. Se il tag <Variable> non restituisce un campo valido nel file JSON o XML, la variabile corrispondente non viene creata.
L'esempio seguente mostra un criterio ExtractVariables che compila due variabili dal corpo JSON di una risposta:
<ExtractVariables name="ExtractVariables-3"> <Source>response</Source> <JSONPayload> <Variable name="latitude" type="float"> <JSONPath>$.results[0].geometry.location.lat</JSONPath> </Variable> <Variable name="longitude" type="float"> <JSONPath>$.results[0].geometry.location.lng</JSONPath> </Variable> </JSONPayload> <VariablePrefix>geocoderesponse</VariablePrefix> </ExtractVariables>
Scrivere nella stessa variabile in più posizioni
Fai attenzione quando scegli i nomi delle variabili da impostare. Il criterio viene eseguito in sequenza dal primo all'ultimo pattern di estrazione. Se il criterio scrive un valore nella stessa variabile da più posizioni, l'ultima scrittura nel criterio determina il valore della variabile. (Potrebbe essere quello che volevi.)
Ad esempio, vuoi estrarre un valore del token che possa essere trasmesso in un parametro di query o in un'intestazione, come mostrato di seguito:
<!-- If token only in query param, the query param determines the value. If token is found in both the query param and header, header sets value. --> <QueryParam name="token"> <Pattern ignoreCase="true">{tokenValue}</Pattern> </QueryParam> <!-- Overwrite tokenValue even if it was found in query parameter. --> <Header name="Token"> <Pattern ignoreCase="true">{tokenValue}</Pattern> </Header>
Controllo di ciò che accade quando non si verifica alcuna corrispondenza
Se il pattern non corrisponde, la variabile corrispondente non viene creata. Di conseguenza, se un altro criterio fa riferimento alla variabile, può verificarsi un errore.
Un'opzione è impostare <IgnoreUnresolvedVariables>
su
true in un criterio che fa riferimento alla variabile per configurare il criterio in modo da trattare
qualsiasi variabile non risolvibile come stringa vuota (null):
<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
Riferimento elemento
Il riferimento elemento descrive gli elementi e gli attributi del criterio ExtractVariables.
<ExtractVariables async="false" continueOnError="false" enabled="true" name="Extract-Variables-1"> <DisplayName>Extract Variables 1</DisplayName> <Source clearPayload="true|false">request</Source> <VariablePrefix>myprefix</VariablePrefix> <IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables> <URIPath> <Pattern ignoreCase="false">/accounts/{id}</Pattern> </URIPath> <QueryParam name="code"> <Pattern ignoreCase="true">DBN{dbncode}</Pattern> </QueryParam> <Header name="Authorization"> <Pattern ignoreCase="false">Bearer {oauthtoken}</Pattern> </Header> <FormParam name="greeting"> <Pattern>hello {user}</Pattern> </FormParam> <Variable name="request.content"> <Pattern>hello {user}</Pattern> </Variable> <JSONPayload> <Variable name="name"> <JSONPath>{example}</JSONPath> </Variable> </JSONPayload> <XMLPayload stopPayloadProcessing="false"> <Namespaces/> <Variable name="name" type="boolean"> <XPath>/test/example</XPath> </Variable> </XMLPayload> </ExtractVariables>
Attributi <ExtractVariables>
<ExtractVariables async="false" continueOnError="false" enabled="true" name="Extract-Variables-1">
La tabella seguente descrive gli attributi comuni a tutti gli elementi principali dei criteri:
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
name |
Il nome interno della norma. Il valore dell'attributo Facoltativamente, utilizza l'elemento |
N/A | Obbligatorie |
continueOnError |
Impostalo su Imposta su |
false | Facoltativo |
enabled |
Imposta il criterio su Impostala su |
true | Facoltativo |
async |
Questo attributo è obsoleto. |
false | Deprecata |
Elemento <DisplayName>
Utilizzalo in aggiunta all'attributo name
per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.
<DisplayName>Policy Display Name</DisplayName>
Predefinito |
N/A Se ometti questo elemento, viene utilizzato il valore dell'attributo |
---|---|
Presenza | Facoltativo |
Tipo | Stringa |
Elemento <Source>
(Facoltativo) Specifica la variabile da analizzare. Il valore predefinito di <Source>
è message
. Il valore message
è sensibile al contesto. In un flusso di richiesta, message
risolve il messaggio della richiesta. In
un flusso di risposta, message
viene risolto nel messaggio di risposta.
Anche se spesso utilizzi questo criterio per estrarre informazioni da una richiesta o da un messaggio di risposta, puoi utilizzarlo per estrarre informazioni da qualsiasi variabile. Ad esempio, puoi utilizzarla per estrarre informazioni da un'entità creata dal criterio AccessEntity, dai dati restituiti dalle norme sui callout di servizio, oppure per estrarre informazioni da un oggetto XML o JSON.
Se <Source>
non può essere risolto o se restituisce un tipo diverso da messaggio, il criterio non risponderà.
<Source clearPayload="true|false">request</Source>
Predefinito: | messaggio |
Presenza: | Facoltativo |
Tipo: | Stringa |
Attributi
Attributo | Descrizione | Predefinito | Presenza | Tipo |
---|---|---|---|---|
clearPayload |
Impostalo su true se vuoi cancellare il payload specificato in <Source> dopo averli estratti i dati. |
false |
Facoltativo | Booleano |
Elemento <VariablePrefisso>
(Facoltativo) Il nome completo della variabile viene creato unendo
<VariablePrefix>
, un punto e il nome definito in {curly braces} nell'elemento
<Pattern>
o <Variable>. Ad esempio:
myprefix.id
, myprefix.dbncode
o myprefix.oauthtoken.
<VariablePrefix>myprefix</VariablePrefix>
Ad esempio, supponiamo che il valore di name sia "user".
- Se
<VariablePrefix>
non è specificato, i valori estratti vengono assegnati a una variabile denominatauser
. - Se
<VariablePrefix>
viene specificato come myprefix, i valori estratti vengono assegnati a una variabile denominatamyprefix.user
.
Predefinito: | N/A |
Presenza: | Facoltativo |
Tipo: | Stringa |
Elemento <IgnoraUnresolvedVariables>
(Facoltativo) Imposta true
per trattare qualsiasi variabile non risolvibile come stringa vuota
(null). Impostalo su false
se vuoi che il criterio restituisca un errore quando una variabile di riferimento non è risolvibile.
<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
Predefinito: | falso |
Presenza: | Facoltativo |
Tipo: | Booleano |
Se un riferimento XPath non è risolto in un <XMLPayload>
, il criterio genera il seguente errore:
{ "fault":{ "faultstring":"Unresolved xpath path in policy policy_name.", "detail":{ "errorcode":"steps.extractvariables.InvalidXPath" } } }
Elemento <URIPath>
(Facoltativo, ma per saperne di più vedi la riga Presenza nella tabella di seguito). Estrae un valore da proxy.pathsuffix di un messaggio di origine della richiesta. Il percorso applicato al pattern è proxy.pathsuffix, che non include il percorso base per il proxy API. Se il messaggio di origine si risolve in un tipo di messaggio di risposta, questo elemento non fa nulla.
<URIPath> <Pattern ignoreCase="false">/accounts/{id}</Pattern> </URIPath>
È possibile utilizzare più elementi <Pattern>:
<URIPath> <Pattern ignoreCase="false">/accounts/{id}</Pattern> <Pattern ignoreCase="false">/accounts/{id}/transactions/{index}</Pattern> </URIPath>
Predefinito: | N/A |
Presenza: | Campo facoltativo. Tuttavia, devi includere almeno uno dei seguenti elementi:
<URIPath> , <QueryParam> , <Header> ,
<FormParam> , <JSONPayload> o
<XMLPayload>. |
Tipo: | N/A |
Attributi
Attributo | Descrizione | Predefinito | Presenza | Tipo |
---|---|---|---|---|
ignoreCase | Specifica di ignorare le maiuscole/minuscole quando corrispondono al modello. |
false |
Facoltativo | Booleano |
Elemento <QueryParam>
(Facoltativo, ma per saperne di più vedi la riga Presenza nella tabella di seguito). Estrae un valore dal parametro di ricerca specificato di un messaggio di origine request. Se il messaggio di origine si risolve in un tipo di messaggio di risposta, questo elemento non fa nulla.
<QueryParam name="code"> <Pattern ignoreCase="true">DBN{dbncode}</Pattern> </QueryParam>
Se più parametri di query hanno lo stesso nome, utilizza gli indici per fare riferimento ai parametri:
<QueryParam name="w.2"> <Pattern ignoreCase="true">{secondW}</Pattern> </QueryParam>
Predefinito: | N/A |
Presenza: | Campo facoltativo. Tuttavia, devi includere almeno uno dei seguenti elementi:
<URIPath> , <QueryParam> , <Header> ,
<FormParam> , <JSONPayload> o
<XMLPayload>. |
Tipo: | N/A |
Attributi
Attributo | Descrizione | Predefinito | Presenza | Tipo |
---|---|---|---|---|
nome | Specifica il nome del parametro di ricerca. Se più parametri di query hanno lo stesso nome, utilizza i riferimenti indicizzati, in cui la prima istanza del parametro di query non ha un indice, la seconda è all'indice 2, la terza all'indice 3 e così via. |
N/A |
Obbligatorie | Stringa |
Elemento <Header>
(Facoltativo, ma per saperne di più vedi la riga Presenza nella tabella di seguito). Estrae un valore dall'intestazione HTTP specificata del messaggio di richiesta o risposta specificato. Se più intestazioni hanno lo stesso nome, i relativi valori vengono archiviati in un array.
<!-- The name is the actual header name. --> <Header name="Authorization"> <!-- Provide a name for your new custom variable here. --> <Pattern ignoreCase="false">Bearer {oauthtoken}</Pattern> </Header>
Se più intestazioni hanno lo stesso nome, utilizza gli indici per fare riferimento alle singole intestazioni nell'array:
<Header name="myHeader.2"> <Pattern ignoreCase="true">{secondHeader}</Pattern> </Header>
Oppure, quanto segue per elencare tutte le intestazioni dell'array:
<Header name="myHeader.values"> <Pattern ignoreCase="true">{myHeaders}</Pattern> </Header>
Predefinito: | N/A |
Presenza: | Campo facoltativo. Tuttavia, devi includere almeno uno dei seguenti elementi:
<URIPath> , <QueryParam> , <Header> ,
<FormParam> , <JSONPayload> o
<XMLPayload>. |
Tipo: | N/A |
Attributi
Attributo | Descrizione | Predefinito | Presenza | Tipo |
---|---|---|---|---|
nome | Specifica il nome dell'intestazione da cui estrai il valore. Se più intestazioni hanno lo stesso nome, utilizza i riferimenti indicizzati: la prima istanza dell'intestazione non ha un indice, la seconda è l'indice 2, la terza è l'indice 3 e così via. Utilizza .values per ottenere tutte le intestazioni dell'array. |
N/A |
Obbligatorie | Stringa |
Elemento <FormParam>
(Facoltativo, ma per saperne di più vedi la riga Presenza nella tabella di seguito). Estrae un valore dal parametro di modulo specificato del messaggio di richiesta o risposta specificato. I parametri del modulo
possono essere estratti solo quando l'intestazione Content-Type
del messaggio specificato è
application/x-www-form-urlencoded
.
<FormParam name="greeting"> <Pattern>hello {user}</Pattern> </FormParam>
Predefinito: | N/A |
Presenza: | Campo facoltativo. Tuttavia, devi includere almeno uno dei seguenti elementi:
<URIPath> , <QueryParam> , <Header> ,
<FormParam> , <JSONPayload> o
<XMLPayload>. |
Tipo: | N/A |
Attributi
Attributo | Descrizione | Predefinito | Presenza | Tipo |
---|---|---|---|---|
nome | Il nome del parametro del modulo da cui estrai il valore. |
N/A |
Obbligatorie | Stringa |
Elemento <Variable>
(Facoltativo, ma per saperne di più vedi la riga Presenza nella tabella di seguito). Specifica il nome di una variabile da cui estrarre un valore.
<Variable name="myVar"> <Pattern>hello {user}</Pattern> </Variable>
Per estrarre due valori dalla variabile:
<Variable name="myVar"> <Pattern>hello {firstName} {lastName}</Pattern> </Variable>
Predefinito: | N/A |
Presenza: | Campo facoltativo. Tuttavia, devi includere almeno uno dei seguenti elementi:
<URIPath> , <QueryParam> , <Header> ,
<FormParam> , <JSONPayload> o
<XMLPayload>. |
Tipo: | N/A |
Attributi
Attributo | Descrizione | Predefinito | Presenza | Tipo |
---|---|---|---|---|
nome | Il nome della variabile da cui estrarre il valore. |
N/A |
Obbligatorie | Stringa |
Elemento <JSONPayload>
(Facoltativo, ma per saperne di più vedi la riga Presenza nella tabella di seguito). Specifica il messaggio in formato JSON da cui verrà estratto il valore della variabile. L'estrazione JSON viene eseguita solo quando l'intestazione Content-Type del messaggio è application/json.
<JSONPayload> <Variable name="name" type="string"> <JSONPath>{example}</JSONPath> </Variable> </JSONPayload>
Predefinito: | N/A |
Presenza: | Campo facoltativo. Tuttavia, devi includere almeno uno dei seguenti elementi:
<URIPath> , <QueryParam> , <Header> ,
<FormParam> , <JSONPayload> o
<XMLPayload>. |
Tipo: | N/A |
Elemento <JSONPayload>/<Variable>
(Obbligatorio all'interno dell'elemento JSONPayload). Specifica la variabile a cui viene assegnato il valore estratto. Puoi includere più tag <Variable> nell'elemento <JSONPayload> per compilare più variabili.
<Variable name="name" type="string"> <JSONPath>{example}</JSONPath> </Variable>
Predefinito: | N/A |
Presenza: | Obbligatorio all'interno dell'elemento JSONPayload. |
Tipo: | N/A |
Attributi
Attributo | Descrizione | Predefinito | Presenza | Tipo |
---|---|---|---|---|
nome |
Specifica il nome della variabile a cui verrà assegnato il valore estratto. |
nome |
Obbligatorie | Stringa |
digita | Specifica il tipo di dati del valore della variabile. | N/A | Facoltativo |
Stringa. Seleziona una delle seguenti opzioni:
|
Elemento <JSONPayload>/<Variable>/<JSONPath>
(Obbligatorio all'interno dell'elemento JSONPayload:Variable). Specifica il percorso JSON utilizzato per estrarre un valore da un messaggio in formato JSON.
<Variable name="name"> <JSONPath>$.rss.channel.title</JSONPath> </Variable>
Predefinito: | N/A |
Presenza: | Obbligatorie |
Tipo: | Stringa |
Elemento <XMLPayload>
(Facoltativo, ma per saperne di più vedi la riga Presenza nella tabella di seguito). Specifica il messaggio in formato XML da cui verrà estratto il valore della variabile. I payload XML vengono estratti solo quando l'intestazione Content-Type
del messaggio è text/xml
, application/xml
o application/*+xml
.
<XMLPayload stopPayloadProcessing="false"> <Namespaces> <Namespace prefix="apigee">http://www.apigee.com</Namespace> <Namespace prefix="gmail">http://mail.google.com</Namespace> </Namespaces> <Variable name="name" type="boolean"> <XPath>/apigee:test/apigee:example</XPath> </Variable> </XMLPayload>
Predefinito: | N/A |
Presenza: | Campo facoltativo. Tuttavia, devi includere almeno uno dei seguenti elementi:
<URIPath> , <QueryParam> , <Header> ,
<FormParam> , <JSONPayload> o
<XMLPayload>. |
Tipo: | N/A |
Attributi
Attributo | Descrizione | Predefinito | Presenza | Tipo |
---|---|---|---|---|
stopPayloadProcessing |
Imposta su |
false |
Facoltativo | Booleano |
Elemento <XMLPayload>/<Namespaces>
(Facoltativo) Specifica lo spazio dei nomi da utilizzare nella valutazione di XPath. Se utilizzi gli spazi dei nomi nelle espressioni XPath, devi dichiarare gli spazi dei nomi qui, come mostrato nell'esempio seguente.
<XMLPayload stopPayloadProcessing="false"> <Namespaces> <Namespace prefix="apigee">http://www.apigee.com</Namespace> <Namespace prefix="gmail">http://mail.google.com</Namespace> </Namespaces> <Variable name="legName" type="string"> <XPath>/apigee:Directions/apigee:route/apigee:leg/apigee:name</XPath> </Variable> </XMLPayload>
Se non utilizzi gli spazi dei nomi nelle espressioni XPath, puoi omettere o commentare l'elemento <Namespaces>
, come illustrato nell'esempio seguente:
<XMLPayload stopPayloadProcessing="false"> <!-- <Namespaces/> --> <Variable name="legName" type="string"> <XPath>/Directions/route/leg/name</XPath> </Variable> </XMLPayload>
Predefinito: | N/A |
Presenza: | Facoltativo |
Tipo: | Stringa |
Attributi
Attributo | Descrizione | Predefinito | Presenza | Tipo |
---|---|---|---|---|
prefix |
Il prefisso dello spazio dei nomi. |
N/A |
Obbligatorie | Stringa |
Elemento <XMLPayload>/<Variable>
(Facoltativo) Specifica la variabile a cui verrà assegnato il valore estratto.
<Variable name="name" type="boolean"> <XPath>/test/example</XPath> </Variable>
Predefinito: | N/A |
Presenza: | Facoltativo |
Tipo: | N/A |
Attributi
Attributo | Descrizione | Predefinito | Presenza | Tipo |
---|---|---|---|---|
nome |
Specifica il nome della variabile a cui verrà assegnato il valore estratto. |
nome |
Obbligatorie | Stringa |
digita | Specifica il tipo di dati del valore della variabile. | Booleano | Facoltativo |
Stringa. Seleziona una delle seguenti opzioni:
|
Elemento <XMLPayload>/<Variable>/<XPath>
(Obbligatorio all'interno dell'elemento XMLPayload:Variable.) Specifica l'XPath definito per la variabile. Sono supportate solo le espressioni XPath 1.0.
<Variable name="name" type="boolean"> <XPath>/test/example</XPath> </Variable>
Esempio con uno spazio dei nomi. Se utilizzi gli spazi dei nomi nelle espressioni XPath, devi dichiararli nella sezione <XMLPayload><Namespaces>
del criterio.
<Variable name="name" type="boolean"> <XPath>/foo:test/foo:example</XPath> </Variable>
Predefinito: | N/A |
Presenza: | Obbligatorie |
Tipo: | Stringa |
Messaggi di errore
Questa sezione descrive i codici e i messaggi di errore restituiti e le variabili di errore impostate da Edge quando questo criterio attiva un errore. Queste informazioni sono importanti per sapere se si stanno sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta gli articoli Cosa devi sapere sugli errori relativi alle norme e Gestione degli errori.
Errori di runtime
Questi errori possono verificarsi quando il criterio viene eseguito.
Codice di errore | Stato HTTP | Causa | Correggi |
---|---|---|---|
steps.extractvariables.ExecutionFailed |
500 |
Questo errore si verifica quando:
|
build |
steps.extractvariables.ImmutableVariable |
500 | Una variabile utilizzata nel criterio è immutabile. Il criterio non è stato in grado di impostare questa variabile. | |
steps.extractvariables.InvalidJSONPath |
500 | Questo errore si verifica se viene utilizzato un percorso JSON non valido nell'elemento JSONPath del criterio. Ad esempio, se un payload JSON non ha l'oggetto Name ,
ma specifichi Name come percorso nel criterio, si verifica questo errore. |
build |
steps.extractvariables.JsonPathParsingFailure |
500 | Questo errore si verifica quando il criterio non è in grado di analizzare un percorso JSON ed
estrarre i dati dalla variabile di flusso specificata nell'elemento Source . In genere questo accade se la variabile di flusso specificata nell'elemento Source non esiste nel flusso attuale. |
build |
steps.extractvariables.SetVariableFailed |
500 | Questo errore si verifica se il criterio non riesce a impostare il valore su una variabile. L'errore in genere si verifica se tenti di assegnare valori a più variabili i cui nomi iniziano con le stesse parole in un formato nidificato e separato da punti. | build |
steps.extractvariables.SourceMessageNotAvailable |
500 | Questo errore si verifica se la variabile message
specificata nell'elemento Source del criterio
è:
|
build |
steps.extractvariables.UnableToCast |
500 | Questo errore si verifica se il criterio non è riuscito a trasmettere il valore estratto a una variabile. In genere questo accade se tenti di impostare il valore di un tipo di dati su una variabile di un altro tipo di dati. | build |
Errori di deployment
Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.
Nome errore | Causa | Correggi |
---|---|---|
NothingToExtract |
Se il criterio non contiene alcun elemento URIPath , QueryParam ,
Header , FormParam , XMLPayload o JSONPayload ,
il deployment del proxy API non va a buon fine perché non c'è nulla da estrarre. |
build |
NONEmptyPrefixMappedToEmptyURI |
Questo errore si verifica se il criterio ha un prefisso definito nell'elemento Namespace all'interno dell'elemento XMLPayload , ma non è definito alcun URI. |
build |
DuplicatePrefix |
Questo errore si verifica se il criterio ha lo stesso prefisso definito più di
una volta nell'elemento Namespace dell'elemento XMLPayload . |
build |
NoXPathsToEvaluate |
Se il criterio non contiene l'elemento XPath all'interno
dell'elemento XMLPayload , il deployment del proxy API non riesce e genera questo errore.
|
build |
EmptyXPathExpression |
Se il criterio ha un'espressione XPath vuota all'interno dell'elemento XMLPayload , il deployment del proxy API non va a buon fine. |
build |
NoJSONPathsToEvaluate |
Se il criterio non contiene l'elemento JSONPath all'interno
dell'elemento JSONPayload , il deployment del proxy API non riesce e genera questo errore. |
build |
EmptyJSONPathExpression |
Se il criterio ha un'espressione XPath vuota
all'interno dell'elemento XMLPayload , il deployment del proxy API non va a buon fine. |
build |
MissingName |
Se il criterio non ha l'attributo name in nessuno degli elementi del criterio, ad esempio QueryParam , Header , FormParam o Variable , ove richiesto, il deployment del proxy API non andrà a buon fine. |
build |
PatternWithoutVariable |
Se il criterio non ha una variabile specificata all'interno dell'elemento Pattern , il deployment del proxy API non va a buon fine. L'elemento Pattern richiede il nome della variabile in cui verranno archiviati i dati estratti. |
build |
CannotBeConvertedToNodeset |
Se il criterio ha un'espressione XPath in cui il tipo Variable
è definito come nodeset,
ma l'espressione non può essere convertita in nodeset, il deployment del proxy API non riesce. |
build |
JSONPathCompilationFailed |
Il criterio non ha potuto compilare un percorso JSON specificato. | |
InstantiationFailed |
Impossibile creare un'istanza del criterio. | |
XPathCompilationFailed |
Se il prefisso o il valore utilizzato nell'elemento XPath non fa parte di nessuno degli spazi dei nomi dichiarati nel criterio, il deployment del proxy API non va a buon fine. |
build |
InvalidPattern |
Se la definizione dell'elemento Pattern non è valida in uno qualsiasi degli elementi come URIPath ,
QueryParam , Header , FormParam , XMLPayload
o JSONPayload all'interno del criterio, il deployment del
proxy API non va a buon fine.
|
build |
Variabili di errore
Queste variabili vengono impostate quando questo criterio attiva un errore in fase di runtime. Per maggiori informazioni, consulta la sezione Cosa devi sapere sugli errori dei criteri.
Variabili | Dove | Esempio |
---|---|---|
fault.name="fault_name" |
fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime riportata sopra. Il nome del guasto è l'ultima parte del codice di errore. | fault.name = "SourceMessageNotAvailable" |
extractvariables.policy_name.failed |
policy_name è il nome specificato dall'utente del criterio che ha generato l'errore. | extractvariables.EV-ParseJsonResponse.failed = true |
Esempio di risposta di errore
{ "fault":{ "detail":{ "errorcode":"steps.extractvariables.SourceMessageNotAvailable" }, "faultstring":"request message is not available for ExtractVariable: EV-ParseJsonResponse" } }
Esempio di regola di errore
<FaultRule name="Extract Variable Faults"> <Step> <Name>AM-CustomErrorMessage</Name> <Condition>(fault.name = "SourceMessageNotAvailable") </Condition> </Step> <Condition>(extractvariables.EM-ParseJsonResponse.failed = true) </Condition> </FaultRule>
Schemi
Argomenti correlati
Analizza i contenuti dei messaggi dell'API utilizzando strumenti di analisi personalizzati