Questa pagina si applica a Apigee e Apigee ibrido.
Visualizza la documentazione di
Apigee Edge.
Cosa
Il criterio ExtractVariables estrae contenuti da una richiesta o risposta e imposta il valore di una variabile su quel contenuto. Puoi estrarre qualsiasi parte del messaggio, tra cui intestazioni, percorsi URI, payload JSON/XML, parametri modulo e parametri di ricerca. Il criterio applica un pattern di testo ai contenuti del messaggio e, quando viene trovata una corrispondenza, imposta una variabile con il contenuto del messaggio specificato.
Sebbene utilizzi spesso ExtractVariables per estrarre informazioni da un messaggio di richiesta o risposta, puoi utilizzarlo anche per estrarre informazioni da altre origini, tra cui entità create dal criterio AccessEntity, oggetti XML o JSON.
Dopo aver estratto il contenuto specificato del messaggio, puoi fare riferimento alla variabile in altri criteri nell'ambito dell'elaborazione di una richiesta e di una risposta.
Questo criterio è un criterio estendibile e il suo utilizzo potrebbe avere implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni per l'utilizzo, consulta la pagina Tipi di criteri.
Video
Guarda i seguenti video per scoprire di più sul criterio ExtractVariables.
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. |
Esempi
Questi esempi di codice dei criteri illustrano come estrarre variabili dai seguenti tipi di artefatti:
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 campione del criterio riportato sopra. L'elemento <URIPath>
indica al criterio ExtractVariables di estrarre le informazioni dal percorso dell'URI. L'elemento <Pattern>
specifica il pattern da applicare al percorso dell'URI. Il
pattern viene considerato come un semplice modello, 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>
, nonché dal valore racchiuso tra parentesi graffe {}
nell'elemento <Pattern>
. I due valori sono uniti da un punto intermedio,
dando come risultato, ad esempio, il nome di variabile urirequest.id
. Se non è presente
l'elemento <VariablePrefix>
, il nome della variabile è solo il valore
racchiuso tra parentesi graffe.
Considera che il codice del criterio di esempio riportato sopra funziona con la seguente richiesta in entrata:
GET http://example.com/svc1/accounts/12797282
Supponiamo che il percorso base per il proxy API sia /svc1
. Quando Apigee applica il
codice del criterio ExtractVariables riportato sopra a questa richiesta in entrata, imposta la variabile
urirequest.id
su 12797282
. Dopo che Apigee 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 della stringa 12797282
.
Ad esempio, il seguente criterioAssignMessage 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 che il codice del criterio di esempio riportato sopra funziona con la seguente richiesta in entrata:
GET http://example.com/accounts/12797282?code=DBN88271
Quando Apigee applica il codice del criterio ExtractVariables riportato sopra a questa richiesta in entrata,
imposta la variabile queryinfo.dbncode
su 88271
. Dopo che Apigee
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 della stringa 88271
.
Ora puoi accedere alla variabile queryinfo.dbncode
nel tuo proxy.
Ad esempio, il seguente criterioAssignMessage 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>
Supponiamo che la progettazione della tua API consenta di specificare più parametri di ricerca con lo stesso nome. Puoi utilizzare un criterio ExtractVariables per estrarre il valore di più istanze del parametro di query. Per fare riferimento parametri di ricerca con lo stesso nome nel criterio, utilizza indici 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.
Considera che il codice del criterio di esempio riportato sopra funziona con la seguente richiesta in entrata:
GET http://example.com/weather?w=Boston&w=Chicago
Quando Apigee applica il codice del criterio ExtractVariables riportato sopra a questa richiesta in entrata,
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 criterioAssignMessage 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 l'API utilizzi token di connessione OAuth 2.0. Considera l'esempio di codice del criterio riportato sopra, che funziona con una richiesta con un token OAuth 2.0 che include un'intestazione come la seguente:
Authorization: Bearer TU08xptfFfeM7aS0xHqlxTgEAdAM.
In qualità di progettista dell'API, supponi di voler utilizzare il valore del token (ma non l'intera intestazione) come chiave in una ricerca cache. Puoi utilizzare il codice del criterio ExtractVariables in alto per estrarre il token.
Quando Apigee applica il codice del criterio ExtractVariables riportato sopra a questa intestazione, imposta la variabile clientrequest.oauthtoken
su
TU08xptfFfeM7aS0xHqlxTgEAdAM
.
Ora puoi accedere alla variabile clientrequest.oauthtoken
nel tuo
proxy. Ad esempio, il seguente criterioAssignMessage 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>
Considera il seguente payload per la 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 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 criterioAssignMessage lo copia in un'intestazione denominata
latitude
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>
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 applica il codice del criterio ExtractVariables riportato sopra a questo messaggio XML, imposta tre variabili:
directionsresponse.travelmode
: ottiene il valoreDRIVING
directionsresponse.duration
: ottiene il valore19
directionsresponse.timeunit
: ottiene il valoreminutes
Tutte
le variabili utilizzano lo stesso prefisso variabile di directionsresponse
. Il suffisso per
queste variabili è specificato esplicitamente dall'attributo
name
dell'elemento <Variable>
.
Ora puoi accedere alla variabile directionresponse.travelmode
nel
tuo proxy. Ad esempio, il seguente criterioAssignMessage 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 sul criterio 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 ricerca. Spesso, il proxy estrae una parte di questi contenuti per utilizzarli in un'istruzione 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, quando viene rilevata una corrispondenza, imposta il valore della variabile designata insieme al contenuto. Altri criteri e codice possono quindi utilizzare queste variabili per consentire il comportamento dinamico o per inviare dati aziendali all'analisi dell'API Apigee.
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 accedere a quella variabile da qualsiasi criterio o codice in qualsiasi fase del flusso (che viene eseguita dopo il criterio ExtractVariables). È incluso quanto segue:
- PreFlow: ProxyEndpoint e TargetEndpoint (richiesta e risposta)
- PostFlow: ProxyEndpoint e TargetEndpoint (richiesta e risposta)
- PostClientFlow: ProxyEndpoint (solo risposta, utilizzando il criterio MessageLogging>)
- Flussi di errori
Informazioni sulla corrispondenza e sulla creazione di variabili
Il criterio ExtractVariables estrae le informazioni da una richiesta o risposta e le scrive in una variabile. Per ogni tipo di informazioni che puoi estrarre, ad esempio percorso URI o dati XML, devi specificare il pattern da abbinare e il nome della variabile utilizzata per contenere le informazioni estratte.
Tuttavia, il funzionamento della corrispondenza dei pattern dipende dall'origine dell'estrazione. Le seguenti sezioni descrivono le due categorie di base di informazioni che puoi estrarre.
Percorsi degli URI, parametri di ricerca, intestazioni, parametri del modulo e variabili corrispondenti
Quando estrai informazioni da un percorso URI, parametri di ricerca, intestazioni, parametri di modulo e
variabili, utilizzi il tag <Pattern>
per specificare uno o più
pattern da abbinare. Ad esempio, il seguente criterio di esempio 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 qualsiasi valore visualizzato nel proxy.pathsuffix dopo /a/
. Ad esempio, supponiamo che il percorso di base per il proxy API sia /basepath/v1
. Con una richiesta in entrata
su http://myCo.com/basepath/v1/a/b
,
la variabile è impostata su b
.
Specificare più pattern
Puoi specificare più pattern da abbinare, corrispondenti ai tag <Pattern>
,
dove:
- Tutti i pattern vengono testati per rilevare 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 di percorso più lunghi.
- Se due pattern corrispondenti hanno gli stessi segmenti di percorso più lunghi, per l'estrazione viene utilizzato il pattern specificato per primo nel criterio.
Nel prossimo esempio crei 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 percorso base /basepath/v1
, che l'URL della richiesta in entrata al proxy API sia nel 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
...il terzo pattern corrisponde e la variabile urirequest.pathSeg
è
impostata su d
.
Specificare i 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>
Di nuovo , se supponiamo un proxy API con un percorso di base /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 far corrispondere i pattern quando sono presenti più istanze di un elemento con lo stesso nome. Ad esempio, puoi effettuare una richiesta contenente più parametri di ricerca o più intestazioni con lo stesso nome. La seguente richiesta contiene due parametri di ricerca denominati "w":
http://myCo.com/basepath/v1/a/b/c/d?w=1&w=2
Per fare riferimento a questi parametri di ricerca nel criterio ExtractVariables, utilizzerai 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. 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.
Utilizzo di caratteri speciali nel pattern
Quando cerchi corrispondenze per i percorsi URI, puoi utilizzare i caratteri jolly "*" e "**" nel pattern, dove:
- "*" corrisponde a uno qualsiasi dei segmenti del percorso
- "**" corrisponde a più segmenti del percorso
Ad esempio, specifichi i 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 associa le richieste ai percorsi (la parte del percorso URI che segue il percorso di base) come "/a/b/c", "/a/foo/bar" e così via. Il secondo pattern corrisponde a qualsiasi numero di segmenti di percorso dopo "/a/", ad esempio "/a/foo/bar/baz/c", nonché "/a/b/c" e "/a/foo/bar".
Quando specifichi i pattern per parametri di ricerca, le intestazioni e i parametri del modulo, il carattere "*" deve corrispondere a un qualsiasi numero 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 passato 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} Stefano" ma non al valore "utente Steve".
JSON e XML corrispondenti
Quando estrai i dati da JSON e XML, specifichi 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) per le 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 sulla 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 vuoi.
Ad esempio, vuoi estrarre un valore del token che può essere passato 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 in assenza di corrispondenze
Se il pattern non corrisponde, la variabile corrispondente non viene creata. Pertanto, se un altro criterio fa riferimento alla variabile, può causare 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 una stringa vuota (null):
<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
Riferimento elemento
Il riferimento all'elemento descrive gli elementi e gli attributi del criterio ExtractVariables.
<ExtractVariables async="false" continueOnError="false" enabled="true" name="Extract-Variables-1"> <DisplayName> 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 | Obbligatorio |
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
si risolve nel messaggio di richiesta. In
un flusso di risposta, message
si risolve nel messaggio di risposta.
Sebbene utilizzi spesso questo criterio per estrarre informazioni da un messaggio di richiesta o di risposta, puoi usarlo per estrarre informazioni da qualsiasi variabile. Ad esempio, puoi utilizzarla per estrarre informazioni da un'entità creata in base al criterio AccessEntity dai dati restituiti dal criterio ServiceCallout o estrarre informazioni da un oggetto XML o JSON.
Se <Source>
non può essere risolto o viene risolto in un tipo diverso dai messaggi, il criterio non risponderà.
<Source clearPayload="true|false">request</Source>
Predefinita: | messaggio |
Presenza: | Facoltativo |
Tipo: | String |
Attributi
Attributo | Descrizione | Predefinita | Presenza | Tipo |
---|---|---|---|---|
clearPayload |
Impostalo su true se vuoi cancellare il payload specificato in
Utilizza l'opzione |
false |
Facoltativo | Booleano |
Elemento <VariabilePrefix>
(Facoltativo) Il nome completo della variabile viene creato unendo <VariablePrefix>
, un punto e il nome definito tra {parentesi graffe} nell'elemento <Pattern>
o <Variable>
. Ad esempio:
myprefix.id
, myprefix.dbncode
o myprefix.oauthtoken.
<VariablePrefix>myprefix</VariablePrefix>
Ad esempio, supponiamo che il valore del nome sia "utente".
- Se
<VariablePrefix>
non è specificato, i valori estratti vengono assegnati a una variabile denominatauser
. - Se
<VariablePrefix>
viene specificato come mioprefisso, i valori estratti vengono assegnati a una variabile denominatamyprefix.user
.
Predefinita: | N/A |
Presenza: | Facoltativo |
Tipo: | String |
Elemento <IgnoraUnresolvedVariables>
(Facoltativo) Imposta su true
per trattare qualsiasi variabile non risolvibile come una stringa vuota
(null). Imposta su false
se vuoi che il criterio generi un errore quando una qualsiasi variabile di riferimento non è risolvibile.
<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
Predefinita: | False |
Presenza: | Facoltativo |
Tipo: | Booleano |
Elemento <URIPath>
(Facoltativo, ma per saperne di più consulta la riga Presenza nella tabella seguente). Estrae un valore da proxy.pathsuffix di un messaggio di origine request
. Il percorso applicato al pattern è proxy.pathsuffix, che non include il percorso base per il proxy API. Se il messaggio di origine viene risolto in un tipo di messaggio response
, questo elemento non produce alcun effetto.
<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>
Predefinita: | N/A |
Presenza: | Facoltativo. Tuttavia, devi includere almeno uno dei seguenti elementi:
<URIPath> , <QueryParam> , <Header> ,
<FormParam> , <JSONPayload> o
<XMLPayload>. |
Tipo: | N/A |
Attributi
Attributo | Descrizione | Predefinita | Presenza | Tipo |
---|---|---|---|---|
ignoreCase | Specifica di ignorare le maiuscole e le minuscole quando corrisponde alla descrizione. |
false |
Facoltativo | Booleano |
Elemento <QueryParam>
(Facoltativo, ma per saperne di più consulta la riga Presenza nella tabella seguente). Estrae un valore dal parametro di query specificato di un messaggio di origine request
. Se il messaggio di origine si risolve in un tipo di messaggio di response
, questo elemento non fa nulla.
<QueryParam name="code"> <Pattern ignoreCase="true">DBN{dbncode}</Pattern> </QueryParam>
Se più parametri di ricerca hanno lo stesso nome, utilizza gli indici per fare riferimento ai parametri:
<QueryParam name="w.2"> <Pattern ignoreCase="true">{secondW}</Pattern> </QueryParam>
Predefinita: | N/A |
Presenza: | Facoltativo. Tuttavia, devi includere almeno uno dei seguenti elementi:
<URIPath> , <QueryParam> , <Header> ,
<FormParam> , <JSONPayload> o
<XMLPayload>. |
Tipo: | N/A |
Attributi
Attributo | Descrizione | Predefinita | Presenza | Tipo |
---|---|---|---|---|
nome | Specifica il nome del parametro di query. Se più parametri di ricerca 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 |
Obbligatorio | String |
Elemento <Header>
(Facoltativo, ma per saperne di più consulta la riga Presenza nella tabella seguente). Estrae un valore
dall'intestazione HTTP specificata del messaggio request
o
response
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>
o di seguito per elencare tutte le intestazioni nell'array:
<Header name="myHeader.values"> <Pattern ignoreCase="true">{myHeaders}</Pattern> </Header>
Predefinita: | N/A |
Presenza: | Facoltativo. Tuttavia, devi includere almeno uno dei seguenti elementi:
<URIPath> , <QueryParam> , <Header> ,
<FormParam> , <JSONPayload> o
<XMLPayload>. |
Tipo: | N/A |
Attributi
Attributo | Descrizione | Predefinita | Presenza | Tipo |
---|---|---|---|---|
nome | Specifica il nome dell'intestazione da cui estrai il valore. Se più intestazioni hanno lo stesso nome, utilizza i riferimenti indicizzati, in cui la prima istanza dell'intestazione non ha un indice, la seconda si trova all'indice 2, la terza all'indice 3 e così via. Usa .values per ottenere tutte le intestazioni nell'array. |
N/A |
Obbligatorio | String |
Elemento <FormParam>
(Facoltativo, ma per saperne di più consulta la riga Presenza nella tabella seguente). Estrae un valore dal parametro del modulo specificato del messaggio request
o response
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>
Predefinita: | N/A |
Presenza: | Facoltativo. Tuttavia, devi includere almeno uno dei seguenti elementi:
<URIPath> , <QueryParam> , <Header> ,
<FormParam> , <JSONPayload> o
<XMLPayload>. |
Tipo: | N/A |
Attributi
Attributo | Descrizione | Predefinita | Presenza | Tipo |
---|---|---|---|---|
nome | Il nome del parametro del modulo da cui si estrae il valore. |
N/A |
Obbligatorio | String |
Elemento <Variabile>
(Facoltativo, ma per saperne di più consulta la riga Presenza nella tabella seguente). 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>
Predefinita: | N/A |
Presenza: | Facoltativo. Tuttavia, devi includere almeno uno dei seguenti elementi:
<URIPath> , <QueryParam> , <Header> ,
<FormParam> , <JSONPayload> o
<XMLPayload>. |
Tipo: | N/A |
Attributi
Attributo | Descrizione | Predefinita | Presenza | Tipo |
---|---|---|---|---|
nome | Il nome della variabile da cui estrarre il valore. |
N/A |
Obbligatorio | String |
Elemento <JSONPayload>
(Facoltativo, ma per saperne di più consulta la riga Presenza nella tabella seguente). 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>
Predefinita: | N/A |
Presenza: | Facoltativo. Tuttavia, devi includere almeno uno dei seguenti elementi:
<URIPath> , <QueryParam> , <Header> ,
<FormParam> , <JSONPayload> o
<XMLPayload>. |
Tipo: | N/A |
Elemento <JSONPayload>/<Variabile>
(Obbligatorio all'interno dell'elemento JSONPayload). Specifica la variabile in cui è 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>
Predefinita: | N/A |
Presenza: | Obbligatorio all'interno dell'elemento JSONPayload. |
Tipo: | N/A |
Attributi
Attributo | Descrizione | Predefinita | Presenza | Tipo |
---|---|---|---|---|
nome |
Specifica il nome della variabile a cui verrà assegnato il valore estratto. |
nome |
Obbligatorio | String |
Tipo | Specifica il tipo di dati del valore della variabile. | N/A | Facoltativo |
Stringa. Seleziona da:
|
Elemento <JSONPayload>/<Variabile>/<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>
Predefinita: | N/A |
Presenza: | Obbligatorio |
Tipo: | String |
Elemento <XMLPayload>
(Facoltativo, ma per saperne di più consulta la riga Presenza nella tabella seguente). 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>
Predefinita: | N/A |
Presenza: | Facoltativo. Tuttavia, devi includere almeno uno dei seguenti elementi:
<URIPath> , <QueryParam> , <Header> ,
<FormParam> , <JSONPayload> o
<XMLPayload>. |
Tipo: | N/A |
Attributi
Attributo | Descrizione | Predefinita | 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 dichiararli 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 mostrato nell'esempio seguente:
<XMLPayload stopPayloadProcessing="false"> <!-- <Namespaces/> --> <Variable name="legName" type="string"> <XPath>/Directions/route/leg/name</XPath> </Variable> </XMLPayload>
Predefinita: | N/A |
Presenza: | Facoltativo |
Tipo: | String |
Attributi
Attributo | Descrizione | Predefinita | Presenza | Tipo |
---|---|---|---|---|
prefix |
Il prefisso dello spazio dei nomi. |
N/A |
Obbligatorio | String |
Elemento <XMLPayload>/<Variabile>
(Facoltativo) Specifica la variabile a cui verrà assegnato il valore estratto.
<Variable name="name" type="boolean"> <XPath>/test/example</XPath> </Variable>
Predefinita: | N/A |
Presenza: | Facoltativo |
Tipo: | N/A |
Attributi
Attributo | Descrizione | Predefinita | Presenza | Tipo |
---|---|---|---|---|
nome |
Specifica il nome della variabile a cui verrà assegnato il valore estratto. |
nome |
Obbligatorio | String |
Tipo | Specifica il tipo di dati del valore della variabile. | Booleano | Facoltativo |
Stringa. Seleziona da:
|
Elemento <XMLPayload>/<Variabile>/<XPath>
(Obbligatorio all'interno dell'elemento XMLPayload:Variable.) Specifica l'XPath definito per la variabile. Sono supportate solo 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>
Predefinita: | N/A |
Presenza: | Obbligatorio |
Tipo: | String |
Messaggi di errore
Questa sezione descrive i codici e i messaggi di errore restituiti, nonché le variabili di errore impostate da Apigee quando questo criterio attiva un errore. È importante sapere se stai sviluppando regole di errore per gestire gli errori. Per saperne di più, consulta le sezioni Cosa devi sapere sugli errori dei criteri 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. | N/A |
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 ciò si verifica 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 può impostare il valore su una variabile. In genere l'errore si verifica se provi ad 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 ciò si verifica 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 nessuno degli elementi 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 sotto l'elemento XMLPayload , ma non viene definito alcun URI. |
build |
DuplicatePrefix |
Questo errore si verifica se il criterio ha lo stesso prefisso definito più di
una volta nell'elemento Namespace sotto l'elemento XMLPayload . |
build |
NoXPathsToEvaluate |
Se il criterio non ha l'elemento XPath all'interno dell'elemento XMLPayload , il deployment del proxy API non va a buon fine e restituisce 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 ha l'elemento JSONPath all'interno dell'elemento JSONPayload , il deployment del proxy API non va a buon fine e restituisce 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 come QueryParam , Header , FormParam o Variable , dove richiesto, il deployment del proxy API non va 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 set di nodi, il deployment del proxy API non va a buon fine. |
build |
JSONPathCompilationFailed |
Il criterio non può compilare un percorso JSON specificato. | N/A |
InstantiationFailed |
Impossibile creare un'istanza del criterio. | N/A |
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 riesce. |
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 il 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 elencato nella precedente tabella Errori di runtime. Il nome dell'errore è 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>
Schema
Argomenti correlati
Riferimento per le variabili di flusso