Criterio ExtractVariables

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Il criterio ExtractVariables estrae i contenuti da una richiesta o una 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 ricerca. La norma funziona applicando un pattern di testo ai contenuti del messaggio e, una volta trovata una corrispondenza, imposta una variabile con i contenuti del messaggio specificati.

Puoi anche utilizzare questa policy per estrarre informazioni da altre fonti, ad esempio entità create dalla policy AccessEntity, oggetti XML o oggetti JSON.

Dopo aver estratto i contenuti del messaggio specificati, puoi fare riferimento alla variabile in altre norme nell'ambito dell'elaborazione di una richiesta e di una risposta. Ad esempio, puoi aggiungere il criterio RaiseFault per restituire un errore se il valore estratto non è valido.

Nota sui callout di servizio: non è necessario utilizzare queste norme per estrarre le variabili dai callout di servizio. Le norme ServiceCallout hanno proprie variabili di richiesta e risposta che puoi utilizzare direttamente, ad esempio in una norma AssignMessage.

Quando definisci la policy ExtractVariables, puoi scegliere:

• Nomi delle variabili da impostare
• Origine delle variabili
• Quante variabili estrarre e impostare

Quando viene eseguita, la norma applica un pattern di testo ai contenuti e, una volta trovata una corrispondenza, imposta il valore della variabile designata con i contenuti. Altri criteri e codice possono quindi utilizzare queste variabili per attivare un comportamento dinamico o per inviare dati aziendali ad Apigee API Analytics.

Avviso: Apigee imposta automaticamente numerose variabili durante l'elaborazione delle richieste. Consulta Riferimento alle variabili di flusso. Utilizza la policy ExtractVariables per impostare variabili aggiuntive.

Queste norme sono estendibili e il loro utilizzo potrebbe avere implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di policy e sulle implicazioni di utilizzo, consulta Tipi di policy.

Esempi

Questi esempi di codice delle policy mostrano come estrarre le 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 delle norme di esempio riportato sopra. L'elemento <URIPath> indica alla policy ExtractVariables di estrarre informazioni dal percorso URI. L'elemento <Pattern> specifica il pattern da applicare al percorso URI. Il pattern viene trattato come un semplice modello, con le parentesi graffe che indicano la parte variabile del percorso 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, che genera un nome di variabile urirequest.id, ad esempio. Se non è presente l'elemento <VariablePrefix>, il nome della variabile è solo il valore racchiuso tra parentesi graffe.

Considera il codice della policy di esempio riportato sopra che funziona con la seguente richiesta in entrata:

GET http://example.com/svc1/accounts/12797282

Supponiamo che il percorso di base per il proxy API sia /svc1. Quando Apigee applica il codice dei criteri ExtractVariables riportato sopra a questa richiesta in entrata, imposta la variabile urirequest.id su 12797282. Dopo l'esecuzione del criterio da parte di Apigee, 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, la seguente policy AssignMessage incorpora il valore di questa 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 della policy di esempio riportato sopra che funziona con la seguente richiesta in entrata:

GET http://example.com/accounts/12797282?code=DBN88271

Quando Apigee applica il codice dei criteri ExtractVariables riportato sopra a questa richiesta in entrata, imposta la variabile queryinfo.dbncode su 88271. Dopo che Apigee esegue 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 proxy. Ad esempio, la seguente policy AssignMessage la 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 dell'API ti consenta di specificare più parametri di ricerca con lo stesso nome. Puoi utilizzare una policy 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 gli indici in cui la prima istanza del parametro di query non ha indice, la seconda è all'indice 2, la terza all'indice 3 e così via.

Considera il codice della policy di esempio riportato sopra che 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 alle variabili queryinfo.firstWeather e queryinfo.secondWeather nel tuo proxy. Ad esempio, la seguente policy AssignMessage la 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 autenticazione OAuth 2.0. Considera il codice del criterio di esempio riportato sopra che funziona con una richiesta che include un token OAuth v2.0 con un'intestazione come questa: Authorization: Bearer TU08xptfFfeM7aS0xHqlxTgEAdAM.

In qualità di progettista dell'API, supponiamo che tu voglia 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 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, la seguente policy AssignMessage la 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 della 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 della policy ExtractVariables riportato sopra a questo messaggio JSON, imposta due variabili: geocoderesponse.latitude e geocoderesponse.longitude. Entrambe le variabili utilizzano lo stesso prefisso di variabile geocoderesponse. Il suffisso di queste variabili è specificato in modo esplicito dall'attributo name dell'elemento <Variable>.

La variabile geocoderesponse.latitude riceve il valore 37.42291810. La variabile geocoderesponse.longitude riceve il valore -122.08542120.

Ora puoi accedere alla variabile geocoderesponse.latitude nel tuo proxy. Ad esempio, la seguente norma AssignMessage la 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 della norma ExtractVariables riportato sopra a questo messaggio XML, imposta tre variabili:

• directionsresponse.travelmode: restituisce il valore DRIVING
• directionsresponse.duration: restituisce il valore 19
• directionsresponse.timeunit: restituisce il valore minutes

Tutte le variabili utilizzano lo stesso prefisso di variabile 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, le seguenti norme AssignMessage lo copiano 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>

Nota:impostazione di Content-Type: quando estrai variabili dai messaggi XML (incluso SOAP), l'estrazione delle variabili funziona solo quando Content-Type è impostato nell'intestazione del messaggio (o nell'intestazione SOAP); ad esempio, application/xml.

Ambito variabile

Le variabili impostate con il criterio ExtractVariables hanno un ambito globale. ovvero, dopo che la norma ExtractVariables definisce una nuova variabile, puoi accedere a questa variabile da qualsiasi norma o codice in qualsiasi fase del flusso che viene eseguito dopo la norma ExtractVariables. Ciò include:

• PreFlow: ProxyEndpoint e TargetEndpoint (richiesta e risposta)
• PostFlow: ProxyEndpoint e TargetEndpoint (richiesta e risposta)
• PostClientFlow: ProxyEndpoint (solo risposta, utilizzando il MessageLogging policy>)
• Flussi di errori

Suggerimento:se la variabile appena estratta non viene visualizzata nello strumento di debug, prova a rimuovere l'elemento <VariablePrefix> se lo hai aggiunto. Per ulteriori informazioni, consulta la sezione ExtractVariables non mostrato nella traccia.

Corrispondenza e creazione di variabili

Il criterio ExtractVariables estrae informazioni da una richiesta o una risposta e le scrive in una variabile. Per ogni tipo di informazione che puoi estrarre, ad esempio il percorso URI o i dati XML, specifica 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 sezioni seguenti descrivono le due categorie di base di informazioni che puoi estrarre.

Corrispondenza di percorsi URI, parametri di ricerca, intestazioni, parametri del modulo e variabili

Quando estrai informazioni da un percorso URI, parametri di ricerca, intestazioni, parametri del modulo e variabili, utilizzi il tag <Pattern> per specificare uno o più pattern da corrispondere. Ad esempio, il seguente esempio di policy mostra un singolo pattern di corrispondenza per il percorso 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 venga visualizzato in proxy.pathsuffix dopo /a/. Ad esempio, supponiamo che il percorso di base del tuo 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 da abbinare, corrispondenti ai tag <Pattern>, dove:

• Tutti i pattern vengono testati per la corrispondenza.
• Se nessuno dei pattern corrisponde, il criterio non ha effetto e la variabile o le variabili non vengono create.
• Se più di un pattern corrisponde, viene utilizzato quello con i segmenti di percorso più lunghi per l'estrazione.
• Se due pattern corrispondenti hanno gli stessi segmenti di percorso più lunghi, per l'estrazione viene utilizzato il pattern specificato per primo nei criteri.

Nell'esempio successivo, crei una policy che contiene tre pattern di corrispondenza per il percorso 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 che per un proxy API con un basepath di /basepath/v1, l'URL della richiesta in entrata al proxy API sia di questo tipo:

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 viene trovata una corrispondenza con il terzo pattern e la variabile urirequest.pathSeg viene impostata su d.

Specificare pattern con più variabili

Puoi specificare più variabili nel pattern di corrispondenza. 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>

Supponendo ancora un proxy API con un percorso di base /basepath/v1 , per la richiesta in entrata URL:

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 trovare corrispondenze con i pattern quando ci sono più istanze di un elemento con lo stesso nome. Ad esempio, puoi inviare una richiesta che contiene 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, utilizzi gli indici, dove la prima istanza del parametro di query non ha indice, la seconda ha indice 2, la terza ha 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 metti in corrispondenza 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 corrisponde alle richieste con suffissi di percorso (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 "/a/b/c" e "/a/foo/bar".

Quando specifichi i pattern per parametri di ricerca, le intestazioni e i parametri del modulo, il carattere "*" indica di trovare una corrispondenza con qualsiasi numero di caratteri. Ad esempio, quando metti in corrispondenza 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, ad esempio "{", utilizza il carattere "%" per eseguirne l'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 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 vengono memorizzate le informazioni estratte e il JsonPath (JSON) o XPATH (XML) per le informazioni estratte.

Vengono valutati tutti i tag <Variable> nel criterio, in modo da poter compilare più variabili da un singolo criterio. Se il tag <Variable> non corrisponde a un campo valido in JSON o XML, la variabile corrispondente non viene creata.

L'esempio seguente mostra una policy ExtractVariables che popola 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>

Scrittura nella stessa variabile in più posizioni

Fai attenzione quando scegli i nomi delle variabili da impostare. Il criterio viene eseguito in sequenza dal primo pattern di estrazione all'ultimo. 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 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>

Controllare cosa succede quando non viene trovata alcuna corrispondenza

Se il pattern non corrisponde, la variabile corrispondente non viene creata. Pertanto, se un'altra norma fa riferimento alla variabile, può causare un errore.

Un'opzione consiste nell'impostare <IgnoreUnresolvedVariables> su true in un criterio che fa riferimento alla variabile per configurare il criterio in modo che tratti qualsiasi variabile non risolvibile come stringa vuota (nulla):

<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 di <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	Presence
name	Il nome interno del criterio. Il valore dell'attributo name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri. Se vuoi, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.	N/D	Obbligatorio
continueOnError	Imposta su false per restituire un errore quando un criterio non va a buon fine. Questo è un comportamento previsto per la maggior parte dei criteri. Imposta su true per continuare l'esecuzione del flusso anche dopo un fallimento del criterio. Vedi anche: Le regole di errore vengono attivate SOLO in uno stato di errore (informazioni su continueOnError) Gestione degli errori all'interno del flusso corrente	falso	Facoltativo
enabled	Imposta su true per applicare il criterio. Imposta su false per disattivare il criterio. Il criterio non verrà applicato anche se rimane collegato a un flusso.	true	Facoltativo
async	Questo attributo è stato ritirato.	falso	Deprecato

Elemento <DisplayName>

Da utilizzare insieme 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/D Se ometti questo elemento, viene utilizzato il valore dell'attributo name del criterio.
Presence	Facoltativo
Tipo	Stringa

Elemento <Source>

(Facoltativo) Specifica la variabile da analizzare. Il valore di <Source> è impostato per impostazione predefinita su message. Il valore message è sensibile al contesto. In un flusso di richieste, message viene risolto nel messaggio di richiesta. In un flusso di risposta, message viene risolto nel messaggio di risposta.

Sebbene questo criterio venga spesso utilizzato per estrarre informazioni da un messaggio di richiesta o 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 dal criterio ServiceCallout o estrarre informazioni da un oggetto XML o JSON.

Se <Source> non può essere risolto o viene risolto in un tipo non di messaggio, il criterio non risponderà.

<Source clearPayload="true|false">request</Source>

Valore predefinito:	messaggio
Presenza:	Facoltativo
Tipo:	Stringa

Attributi

Attributo	Descrizione	Predefinito	Presenza	Tipo
clearPayload	Imposta su true se vuoi cancellare il payload specificato in <Source> dopo aver estratto i dati. Utilizza l'opzione <clearPayload> solo se il messaggio di origine non è necessario dopo l'esecuzione di ExtractVariables. Se impostato su true, libera la memoria utilizzata dal messaggio.	falso	Facoltativo	Booleano

Elemento <VariablePrefix>

(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 di name sia "user".

• Se <VariablePrefix> non è specificato, i valori estratti vengono assegnati a una variabile denominata user.
• Se <VariablePrefix> è specificato come myprefix, i valori estratti vengono assegnati a una variabile denominata myprefix.user.

Valore predefinito:	N/D
Presenza:	Facoltativo
Tipo:	Stringa

Elemento <IgnoreUnresolvedVariables>

(Facoltativo) Imposta su true per considerare qualsiasi variabile non risolvibile come stringa vuota (null). Imposta false se vuoi che il criterio generi un errore quando una variabile a cui viene fatto riferimento non è risolvibile.

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

Valore predefinito:	Falso
Presenza:	Facoltativo
Tipo:	Booleano

Elemento <URIPath>

(Facoltativo, ma per saperne di più consulta la riga Presenza nella tabella riportata di seguito.) Estrae un valore da proxy.pathsuffix di un messaggio di origine request. Il percorso applicato al pattern è proxy.pathsuffix, che non include il basepath per il proxy API. Se il messaggio di origine viene risolto in un tipo di messaggio response, 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>

Valore predefinito:	N/D
Presenza:	Facoltativo. Tuttavia, devi includere almeno uno dei seguenti elementi: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> o <XMLPayload>.
Tipo:	N/D

Attributi

Attributo	Descrizione	Predefinito	Presenza	Tipo
ignoreCase	Specifica di ignorare la distinzione tra maiuscole e minuscole durante la corrispondenza del pattern.	falso	Facoltativo	Booleano

Elemento <QueryParam>

(Facoltativo, ma per saperne di più consulta la riga Presenza nella tabella riportata di seguito.) Estrae un valore dal parametro di query specificato di un messaggio di origine request. Se il messaggio di origine viene risolto in un tipo di messaggio 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>

Valore predefinito:	N/D
Presenza:	Facoltativo. Tuttavia, devi includere almeno uno dei seguenti elementi: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> o <XMLPayload>.
Tipo:	N/D

Attributi

Attributo	Descrizione	Predefinito	Presenza	Tipo
nome	Specifica il nome del parametro di ricerca. Se più parametri di ricerca hanno lo stesso nome, utilizza i riferimenti indicizzati, in cui la prima istanza del parametro di query non ha indice, la seconda ha indice 2, la terza ha indice 3 e così via.	N/D	Obbligatorio	Stringa

Elemento <Header>

(Facoltativo, ma per saperne di più consulta la riga Presenza nella tabella riportata di seguito.) Estrae un valore dall'intestazione HTTP specificata del messaggio request o response specificato. Se più intestazioni hanno lo stesso nome, i relativi valori vengono memorizzati 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 il seguente per elencare tutte le intestazioni nell'array:

<Header name="myHeader.values">
   <Pattern ignoreCase="true">{myHeaders}</Pattern>
</Header>

Valore predefinito:	N/D
Presenza:	Facoltativo. Tuttavia, devi includere almeno uno dei seguenti elementi: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> o <XMLPayload>.
Tipo:	N/D

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, in cui la prima istanza dell' intestazione non ha indice, la seconda ha indice 2, la terza ha indice 3 e così via. Utilizza .values per ottenere tutte le intestazioni nell'array.	N/D	Obbligatorio	Stringa

Elemento <FormParam>

(Facoltativo, ma per saperne di più consulta la riga Presenza nella tabella riportata di seguito.) 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>

Valore predefinito:	N/D
Presenza:	Facoltativo. Tuttavia, devi includere almeno uno dei seguenti elementi: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> o <XMLPayload>.
Tipo:	N/D

Attributi

Attributo	Descrizione	Predefinito	Presenza	Tipo
nome	Il nome del parametro del modulo da cui estrai il valore.	N/D	Obbligatorio	Stringa

Elemento <Variable>

(Facoltativo, ma per saperne di più consulta la riga Presenza nella tabella riportata 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>

Valore predefinito:	N/D
Presenza:	Facoltativo. Tuttavia, devi includere almeno uno dei seguenti elementi: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> o <XMLPayload>.
Tipo:	N/D

Attributi

Attributo	Descrizione	Predefinito	Presenza	Tipo
nome	Il nome della variabile da cui estrarre il valore.	N/D	Obbligatorio	Stringa

Elemento <JSONPayload>

(Facoltativo, ma per saperne di più consulta la riga Presenza nella tabella riportata 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>

Valore predefinito:	N/D
Presenza:	Facoltativo. Tuttavia, devi includere almeno uno dei seguenti elementi: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> o <XMLPayload>.
Tipo:	N/D

<JSONPayload>/<Variable> elemento

(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>

Valore predefinito:	N/D
Presenza:	Obbligatorio all'interno dell'elemento JSONPayload.
Tipo:	N/D

Attributi

Attributo	Descrizione	Predefinito	Presenza	Tipo
nome	Specifica il nome della variabile a cui verrà assegnato il valore estratto.	nome	Obbligatorio	Stringa
tipo	Specifica il tipo di dati del valore della variabile.	N/D	Facoltativo	Stringa. Seleziona una delle seguenti opzioni: string boolean integer Lungo float double nodeset (restituisce un frammento JSON)

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.

Nota: l'elemento <JSONPath> supporta la funzionalità di sostituzione dinamica delle stringhe chiamata modelli di messaggi.

<Variable name="name">
  <JSONPath>$.rss.channel.title</JSONPath>
</Variable>

Valore predefinito:	N/D
Presenza:	Obbligatorio
Tipo:	Stringa

Elemento <XMLPayload>

(Facoltativo, ma per saperne di più consulta la riga Presenza nella tabella riportata 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>

Valore predefinito:	N/D
Presenza:	Facoltativo. Tuttavia, devi includere almeno uno dei seguenti elementi: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> o <XMLPayload>.
Tipo:	N/D

Attributi

Attributo	Descrizione	Predefinito	Presenza	Tipo
stopPayloadProcessing	Imposta su true per interrompere la valutazione XPath dopo il popolamento di una variabile. Ciò significa che solo una variabile viene compilata dalla norma.	falso	Facoltativo	Booleano

<XMLPayload>/<Namespaces> element

(Facoltativo) Specifica lo spazio dei nomi da utilizzare nella valutazione 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 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>

Valore predefinito:	N/D
Presenza:	Facoltativo
Tipo:	Stringa

Attributi

Attributo	Descrizione	Predefinito	Presenza	Tipo
prefix	Il prefisso dello spazio dei nomi.	N/D	Obbligatorio	Stringa

<XMLPayload>/<Variable> element

(Facoltativo) Specifica la variabile a cui verrà assegnato il valore estratto.

<Variable name="name" type="boolean">
   <XPath>/test/example</XPath>
</Variable>

Valore predefinito:	N/D
Presenza:	Facoltativo
Tipo:	N/D

Attributi

Attributo	Descrizione	Predefinito	Presenza	Tipo
nome	Specifica il nome della variabile a cui verrà assegnato il valore estratto.	nome	Obbligatorio	Stringa
tipo	Specifica il tipo di dati del valore della variabile.	Booleano	Facoltativo	Stringa. Seleziona una delle seguenti opzioni: string boolean integer Lungo float double nodeset (restituisce un frammento XML)

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.

L'elemento <XPath> non supporta i modelli di messaggio.

<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> delle norme.

<Variable name="name" type="boolean">
   <XPath>/foo:test/foo:example</XPath>
</Variable>

Valore predefinito:	N/D
Presenza:	Obbligatorio
Tipo:	Stringa

Nota:l'utilizzo di parent, ancestor, following e preceding nelle espressioni XPath non è supportato in Apigee. Per ottenere gli stessi risultati di corrispondenza, prova la corrispondenza o l'indicizzazione esatta del nome del nodo. Ad esempio:

• <XPath>/Attributes/Attribute[@Name=’foo_attribute']/Value</XPath>
  ottiene il valore di foo_attribute.
• <XPath>/Attributes/Attribute[4]/Value</XPath>
  recupera il valore del quarto attributo.

Messaggi di errore

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

Fault code	HTTP status	Cause	Fix
steps.extractvariables.ExecutionFailed	500	This error occurs when: The input payload (JSON, XML) is empty. The input (JSON, XML, etc) passed to the policy is invalid or malformed.
steps.extractvariables.ImmutableVariable	500	A variable used in the policy is immutable. The policy was unable to set this variable.	N/A
steps.extractvariables.InvalidJSONPath	500	This error occurs if an invalid JSON path is used in the JSONPath element of the policy. For example, if a JSON payload does not have the object Name, but you specify Name as the path in the policy, then this error occurs.
steps.extractvariables.JsonPathParsingFailure	500	This error occurs when the policy is unable to parse a JSON path and extract data from the flow variable specified in Source element. Typically this happens if the flow variable specified in the Source element does not exist in the current flow.
steps.extractvariables.SetVariableFailed	500	This error occurs if the policy could not set the value to a variable. The error generally happens if you try to assign values to multiple variables whose names start with the same words in a nested dot-separated format.
steps.extractvariables.SourceMessageNotAvailable	500	This error occurs if the message variable specified in the Source element of the policy is either: Out of scope (not available in the specific flow where the policy is being executed) or Can't be resolved (is not defined)
steps.extractvariables.UnableToCast	500	This error occurs if the policy was unable to cast the extracted value to a variable. Typically this happens if you attempt to set the value of one data type to a variable of another data type.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Tip: Need help resolving an error? Click next to the error's cause description to visit the troubleshooting page.

Error name	Cause	Fix
NothingToExtract	If the policy does not have any of the elements URIPath, QueryParam, Header, FormParam, XMLPayload, or JSONPayload, the deployment of the API Proxy fails, because there's nothing to extract.
NONEmptyPrefixMappedToEmptyURI	This error occurs if the policy has a prefix defined in the Namespace element under the XMLPayload element, but no URI is defined.
DuplicatePrefix	This error occurs if the policy has the same prefix defined more than once in the Namespace element under the XMLPayload element.
NoXPathsToEvaluate	If the policy does not have the XPath element within the XMLPayload element, then the deployment of the API proxy fails with this error. If you want to extract variables from an XML Payload, then an XPath child element must be specified.
EmptyXPathExpression	If the policy has an empty XPath expression within the XMLPayload element, then the deployment of the API proxy fails.
NoJSONPathsToEvaluate	If the policy does not have the JSONPath element within the JSONPayload element, then the deployment of the API proxy fails with this error.
EmptyJSONPathExpression	If the policy has an empty XPath expression within the XMLPayload element, then the deployment of the API proxy fails.
MissingName	If the policy does not have the name attribute in any of the policy elements like QueryParam, Header, FormParam or Variable, where it is required, then the deployment of the API proxy fails.
PatternWithoutVariable	If the policy does not have a variable specified within the Pattern element, then the deployment of the API proxy fails. The Pattern element requires the name of the variable in which extracted data will be stored.
CannotBeConvertedToNodeset	If the policy has an XPath expression where the Variable type is defined as nodeset, but the expression cannot be converted to nodeset, then the deployment of the API proxy fails.
JSONPathCompilationFailed	The policy could not compile a specified JSON Path.	N/A
InstantiationFailed	The policy could not be instantiated.	N/A
XPathCompilationFailed	If the prefix or the value used in the XPath element is not part of any of the declared namespaces in the policy, then the deployment of the API proxy fails.
InvalidPattern	If the Pattern element definition is invalid in any of the elements like URIPath, QueryParam, Header, FormParam, XMLPayload or JSONPayload within the policy, then the deployment of the API proxy fails. The Pattern element is considered invalid if it doesn't include a variable. For more information about pattern matching, see About matching and variable creation.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Variables	Where	Example
fault.name="fault_name"	fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	fault.name = "SourceMessageNotAvailable"
extractvariables.policy_name.failed	policy_name is the user-specified name of the policy that threw the fault.	extractvariables.EV-ParseJsonResponse.failed = true

Example error response

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{
   "fault":{
      "detail":{
         "errorcode":"steps.extractvariables.SourceMessageNotAvailable"
      },
      "faultstring":"request message is not available for ExtractVariable: EV-ParseJsonResponse"
   }
}

Example fault rule

<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

Esempio: consulta gli esempi del nostro repository GitHub per gli schemi più recenti.

Argomenti correlati

Riferimento alle variabili di flusso