Política ExtractVariables

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

O que

A política de extração de variáveis extrai o conteúdo de uma solicitação ou resposta e define o valor de uma variável para esse conteúdo. É possível extrair qualquer parte da mensagem, incluindo cabeçalhos, caminhos de URI, payloads JSON/XML, parâmetros de formulário e parâmetros de consulta. A política funciona aplicando um padrão de texto ao conteúdo da mensagem e, ao encontrar uma correspondência, define uma variável com o conteúdo da mensagem especificada.

Em geral, essa política é usada para extrair informações de uma mensagem de solicitação ou resposta, mas também é possível usá-la para extrair informações de outras origens, incluindo entidades criadas pela política AccessEntity, objetos XML ou objetos JSON.

Depois de extrair o conteúdo da mensagem especificada, é possível referenciar a variável em outras políticas como parte do processamento de uma solicitação e resposta.

Observação sobre frases de destaque de serviço: não é necessário usar essa política para extrair variáveis de frases de destaque de serviço. A política ServiceCallout tem as próprias variáveis de solicitação e resposta que podem ser usadas diretamente, como, por exemplo, em uma política AssignMessage.

Esta é uma política extensível. O uso dela pode ter implicações no custo ou na utilização, dependendo da sua licença da Apigee. Para informações sobre tipos de política e implicações de uso, consulte Tipos de política.

Vídeos

Observação: os vídeos a seguir mostram o editor proxy clássico na interface da Apigee. A Apigee está introduzindo uma nova versão do Editor de Proxy, que tem um design diferente da versão clássica mostrada nos vídeos.

Assista os vídeos a seguir para saber mais sobre a política ExtractVariables.

Vídeo	Descrição
Extrair variáveis do payload XML	Extraia variáveis de um payload XML usando a política de extração de variáveis.
Extrair variáveis do payload JSON	Extraia variáveis de um payload JSON usando a política de extração de variáveis.
Extrair variáveis de parâmetros	Extraia variáveis de parâmetros, como de consulta, cabeçalho, formulário ou URI.
Extrair variáveis de parâmetros de vários valores	Extraia variáveis de parâmetros de vários valores.

Amostras

Estas amostras de código de política ilustram como extrair variáveis dos seguintes tipos de artefatos:

URIs

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

Considere o código da política de amostra acima. O elemento <URIPath> indica que a política ExtractVariables extraia informações do caminho do URI. O elemento <Pattern> especifica o padrão a ser aplicado ao caminho do URI. O padrão é tratado como um modelo simples, com as chaves que denotam a parte variável do caminho do URI.

O nome da variável a ser definida é determinado pelo valor especificado no elemento <VariablePrefix>, bem como pelo valor entre chaves {} no elemento <Pattern>. Os dois valores são unidos por um ponto intermediário, resultando em um nome de variável urirequest.id, por exemplo. Se não houver o elemento <VariablePrefix>, o nome da variável será apenas o valor entre chaves.

Considere o código da política de amostra acima e trabalhe com a seguinte solicitação recebida:

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

Suponha que o caminho base para o proxy da API seja /svc1. Quando a Apigee aplica o código da política ExtractVariables acima para essa solicitação de entrada, a variável urirequest.id é definida como 12797282. Depois que a Apigee executar a política, as políticas ou o código subsequente no fluxo de processamento poderão referenciar a variável chamada urirequest.id para receber o valor da string 12797282.

Por exemplo, a política AssignMessage a seguir incorpora o valor dessa variável ao payload de uma nova mensagem de solicitação:

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

Parâmetros de consulta

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

Considere o código da política de amostra acima e trabalhe com a seguinte solicitação recebida:

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

Quando a Apigee aplica o código da política ExtractVariables acima para essa solicitação de entrada, a variável queryinfo.dbncode é definida como 88271. Depois que a Apigee executa a política, as políticas ou o código subsequentes no fluxo de processamento podem se referir à variável chamada queryinfo.dbncode para conseguir o valor da string 88271.

Agora, é possível acessar a variável queryinfo.dbncode no seu proxy. Por exemplo, a política AssignMessage a seguir a copia para o payload da solicitação:

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

Vários parâmetros

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

Suponha que o design da API permita especificar vários parâmetros de consulta com o mesmo nome. É possível usar uma política ExtractVariables para extrair o valor de várias instâncias do parâmetro de consulta. Para referenciar parâmetros de consulta com o mesmo nome na política, use índices em que a primeira instância do parâmetro de consulta não tenha índice, a segunda esteja no índice 2, o terceiro no índice 3, e assim por diante.

Considere o código da política de amostra acima e trabalhe com a seguinte solicitação recebida:

GET http://example.com/weather?w=Boston&w=Chicago

Quando a Apigee aplica o código de política ExtractVariables acima para essa solicitação, ele define a variável queryinfo.firstWeather como Boston e a variável queryInfo.secondWeather como Chicago.

Agora, é possível acessar as variáveis queryinfo.firstWeather e queryinfo.secondWeather no proxy. Por exemplo, a seguinte política AssignMessage as copia para o payload da solicitação:

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

Cabeçalhos

<ExtractVariables name='ExtractVariable-OauthToken'>
  <Source>request</Source>
  <Header name="Authorization">
    <Pattern ignoreCase="false">Bearer {oauthtoken}</Pattern>
  </Header>
  <VariablePrefix>clientrequest</VariablePrefix>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Suponha que sua API use tokens do portador OAuth v2.0. Considere o código de política de exemplo acima trabalhando com uma solicitação que carrega um token OAuth v2.0 que inclui um cabeçalho como este: Authorization: Bearer TU08xptfFfeM7aS0xHqlxTgEAdAM.

Como designer da API, suponha que você queira usar o valor do token (mas não o cabeçalho inteiro) como uma chave em uma pesquisa de cache. Use o código de política de ExtractVariables acima para extrair o token.

Quando a Apigee aplica o código de política de ExtractVariables acima nesse cabeçalho, ela define a variável clientrequest.oauthtoken como TU08xptfFfeM7aS0xHqlxTgEAdAM.

Agora é possível acessar a variável clientrequest.oauthtoken no seu proxy. Por exemplo, a seguinte política AssignMessage as copia para o payload da solicitação:

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

Considere o seguinte payload de resposta 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 a Apigee aplica o código de política ExtractVariables para esta mensagem JSON, ele define duas variáveis: geocoderesponse.latitude e geocoderesponse.longitude. Ambas as variáveis usam o mesmo prefixo de variável de geocoderesponse. O sufixo dessas variáveis é especificado explicitamente pelo atributo name do elemento <Variable>.

A variável geocoderesponse.latitude recebe o valor 37.42291810. A variável geocoderesponse.longitude recebe o valor -122.08542120.

Agora é possível acessar a variável geocoderesponse.latitude no seu proxy. Por exemplo, a seguinte política AssignMessage copia-o para um cabeçalho chamado latitude na resposta:

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

Considere o seguinte payload de resposta 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 a Apigee aplica o ExtractVariables de variáveis de extração acima a essa mensagem XML, ela define três variáveis: e .

• directionsresponse.travelmode: recebe o valor DRIVING.
• directionsresponse.duration: recebe o valor 19.
• directionsresponse.timeunit: recebe o valor minutes.

Todas as variáveis usam o mesmo prefixo de variável de directionsresponse. O sufixo dessas variáveis é especificado explicitamente pelo atributo <Variable> do elemento name.

Agora, é possível acessar a variável directionresponse.travelmode no seu proxy. Por exemplo, a política AssignMessage a seguir copia-o para um cabeçalho chamado tmode na resposta:

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

Observação: como definir Content-Type: ao extrair variáveis das mensagens XML (incluindo SOAP), a extração de variáveis só funcionará quando o Content-Type for definido no cabeçalho da mensagem (ou cabeçalho SOAP). Por exemplo application/xml.

Sobre a política ExtractVariables

Os desenvolvedores de API criam proxies de API que se comportam de maneira diferente com base no conteúdo das mensagens, incluindo cabeçalhos, caminhos de URI, payloads e parâmetros de consulta. Muitas vezes, o proxy extrai parte do conteúdo a ser usado em uma declaração de condição. Use a política ExtractVariables para fazer isso.

Ao definir a política ExtractVariables, é possível escolher:

• Nomes das variáveis a serem definidas
• Origem das variáveis
• Quantas variáveis extrair e definir

Quando executada, a política aplica um padrão de texto ao conteúdo e, ao encontrar uma correspondência, define o valor da variável designada com o conteúdo. Outras políticas e códigos podem consumir essas variáveis para ativar o comportamento dinâmico ou enviar dados da empresa para a API Apigee Analytics.

Aviso: a Apigee define diversas variáveis automaticamente durante o processamento da solicitação. Consulte a referência das variáveis de fluxo. Use a política ExtractVariables para definir outras variáveis.

Escopo

As variáveis definidas com a política ExtractVariables têm escopo global. Ou seja, depois que a política ExtractVariables define uma nova variável, é possível acessá-la de qualquer política ou código em qualquer estágio do fluxo (que é executado após a política ExtractVariables). Isso inclui:

• PreFlow: ProxyEndpoint e TargetEndpoint (solicitação e resposta)
• PostFlow: ProxyEndpoint e TargetEndpoint (solicitação e resposta)
• PostClientFlow: ProxyEndpoint (somente resposta, usando a política MessageLogging>)
• Fluxos de erro

Dica: se a variável recém-extraída não for exibida na ferramenta Debug, remova o elemento <VariablePrefix> se você o adicionou. Para mais informações, consulte o ExtractVariables não mostrado no trace.

Sobre a correspondência e a criação de variáveis

A política ExtractVariables extrai informações de uma solicitação ou resposta e grava essas informações em uma variável. Para cada tipo de informação que é possível extrair, como caminho URI ou dados XML, especifique o padrão a ser correspondido e o nome da variável usada para reter as informações extraídas.

No entanto, a maneira como a correspondência de padrões funciona depende da fonte da extração. As seções a seguir descrevem as duas categorias básicas de informações que é possível extrair.

Caminhos de URI, parâmetros de consulta, cabeçalhos, parâmetros de formulário e variáveis correspondentes

Ao extrair informações de um caminho de URI, parâmetros de consulta, cabeçalhos, parâmetros de formulário e variáveis, use a tag <Pattern> para especificar um ou mais padrões a serem correspondidos. O exemplo de política a seguir mostra um único padrão de correspondência para o caminho do URI:

<ExtractVariables name="ExtractVariables-1">
   <Source>request</Source>
   <URIPath>
      <Pattern ignoreCase="true">/a/{pathSeg}</Pattern>
   </URIPath>
   <VariablePrefix>urirequest</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Neste exemplo, a variável urirequest.pathSeg está definida como qualquer valor que apareça em proxy.pathsuffix depois de /a/. Por exemplo, suponha que o caminho base do proxy da API seja /basepath/v1. Com uma solicitação de entrada para http://myCo.com/basepath/v1/a/b, a variável é definida como b.

Como especificar vários padrões

É possível especificar vários colaboradores a serem correspondidas, equivalentes a tags <Pattern>, em que:

• Todos os padrões são testados para correspondência.
• Se nenhum dos padrões coincidirem, a política não fará nada, e as variáveis não serão criadas.
• Se houver mais de um padrão, o padrão com segmentos de caminhos mais longos será usado para extração.
• Se dois padrões correspondentes tiverem os mesmos segmentos de caminho mais longos, o padrão especificado primeiro na política será usado para extração.

No próximo exemplo, você cria uma política que contém três padrões de correspondência para o caminho do 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>

Suponha que, para um proxy de API com um caminho base de /basepath/v1, o URL de solicitação de entrada para o proxy de API esteja neste formato:

http://myCo.com/basepath/v1/a/b

Neste exemplo, o primeiro padrão corresponde ao URI e a variável urirequest.pathSeg é definida como b.

Se o URL de solicitação for:

http://myCo.com/basepath/v1/a/b/c/d

...o terceiro padrão corresponde, e a variável urirequest.pathSeg é definida como d.

Como especificar padrões com diversas variáveis

É possível especificar diversas variáveis no padrão correspondente. Por exemplo, você especifica um padrão correspondente com duas variáveis:

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

Novamente, supondo um proxy de API com um caminho base de /basepath/v1 para o URL de solicitação de entrada:

http://myCo.com/basepath/v1/a/b/c/d

...a variável urirequest.pathSeg1 está definida como b e a variável urirequest.pathSeg2 está definida como d.

Como fazer a correspondência de várias instâncias no padrão

Também é possível corresponder padrões quando há várias instâncias de um item com o mesmo nome. Por exemplo, é possível fazer uma solicitação que contenha vários parâmetros de consulta ou vários cabeçalhos com o mesmo nome. A solicitação a seguir contém dois parâmetros de consulta chamados "w":

http://myCo.com/basepath/v1/a/b/c/d?w=1&w=2

Para referenciar esses parâmetros de consulta na política ExtractVariables, use índices, em que a primeira instância do parâmetro de consulta não tem índice, a segunda está no índice 2, a terceira no índice 3 etc. Por exemplo, a política a seguir extrai o valor do segundo parâmetro de consulta chamado "w" na solicitação:

<ExtractVariables name="ExtractVariables-1">
  <Source>request</Source>
  <QueryParam name="w.2">
    <Pattern ignoreCase="true">{secondW}</Pattern>
  </QueryParam>
  <VariablePrefix>urirequest</VariablePrefix>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

A variável urirequest.secondW é definida como "2". Se o segundo parâmetro de consulta for omitido da solicitação, a variável urirequest.secondW estará vazia. Use a indexação sempre que houver vários itens com o mesmo nome na solicitação.

Como usar caracteres especiais no padrão

Ao corresponder caminhos de URI, é possível usar os caracteres curinga "*" e "*" no padrão, em que:

• "*" corresponde a qualquer segmento do caminho
• "**" corresponde a vários segmentos do caminho

Por exemplo, você especifica padrões para o elemento <URIPath>, como mostrado abaixo:

<URIPath>
  <Pattern ignoreCase="true">/a/*/{id}</Pattern>
  <Pattern ignoreCase="true">/a/**/{id}</Pattern>
</URIPath>

O primeiro padrão corresponde a solicitações com sufixos (a parte do caminho de URI após o caminho base), como "/a/b/c", "/a/foo/bar" etc. O segundo padrão corresponde a qualquer número de segmentos de caminho após "/a/", como "/a/foo/bar/baz/c", assim como "/a/b/c" e "/a/foo/bar".

Ao especificar padrões para parâmetros de consulta, cabeçalhos e formulários, o caractere "*" especifica para corresponder a qualquer número de caracteres. Por exemplo, ao corresponder a um cabeçalho, especifique o padrão como:

*;charset={encoding}

Esse padrão corresponde aos valores "text/xml;charset=UTF-16" e "application/xml;charset=ASCII".

Se o valor passado à política ExtractVariables contiver um caractere especial, como "{", use o caractere "%" para fazer o escape. O exemplo a seguir faz o escape dos caracteres "{" e "}" no padrão porque eles são usados como caracteres literais no valor do parâmetro de consulta:

<QueryParam>
  <Pattern ignoreCase="true">%{user%} {name}</Pattern>
</QueryParam>

Neste exemplo, o padrão corresponde ao valor "{user} Steve", mas não ao valor "user Steve".

JSON e XML correspondentes

Ao extrair dados de JSON e XML, especifique uma ou mais tags <Variable> na política. A tag <Variable> especifica o nome da variável de destino em que as informações extraídas são armazenadas e o JsonPath (JSON) ou XPATH (XML) nas informações extraídas.

Todas as tags <Variable> na política são avaliadas para que você possa preencher diversas variáveis de uma única política. Se a tag <Variable> não for avaliada como um campo válido no JSON ou XML, a variável correspondente não será criada.

O exemplo a seguir mostra uma política ExtractVariables que preenche duas variáveis do corpo JSON de uma resposta:

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

Como gravar na mesma variável em vários lugares

Cuidado ao escolher os nomes das variáveis que serão definidas. A política é executada sequencialmente desde o primeiro padrão de extração até o último. Se a política gravar um valor na mesma variável a partir de vários lugares, a última gravação na política determinará o valor da variável. Isso pode ser o que você quer.

Por exemplo, é possível extrair um valor de token que pode ser transmitido em um parâmetro de consulta ou em um cabeçalho, como mostrado abaixo:

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

Como controlar o que acontece quando não há correspondência

Se o padrão não for correspondente, a variável correspondente não será criada. Portanto, se outra política fizer referência à variável, isso poderá causar um erro.

Uma opção é definir <IgnoreUnresolvedVariables> como verdadeiro em uma política que faça referência à variável para configurar a política para tratar qualquer variável não resolvida como uma string vazia (nula):

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

Referência de elemento

A referência de elemento descreve os elementos e atributos da política de 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>

Atributos de <ExtractVariables>

<ExtractVariables async="false" continueOnError="false" enabled="true" name="Extract-Variables-1">

A tabela a seguir descreve atributos comuns a todos os elementos pai de políticas:

Atributo	Descrição	Padrão	Presence
name	O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hifens, sublinhados e pontos. Esse valor não pode exceder 255 caracteres. Opcionalmente, use o elemento <DisplayName> para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.	N/A	Obrigatório
continueOnError	Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado na maioria das políticas. Defina como true para que a execução do fluxo continue mesmo depois que uma política falhar. Consulte também: As regras de falha são acionadas SOMENTE em um estado de erro (sobre continueOnError) Como corrigir falhas no fluxo atual	false	Opcional
enabled	Defina como true para aplicar a política. Defina como false para desativar a política. A política não será aplicada mesmo se ela permanecer anexada a um fluxo.	true	Opcional
async	Esse atributo está obsoleto.	false	Descontinuado

Elemento <DisplayName>

Use em conjunto com o atributo name para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.

<DisplayName>Policy Display Name</DisplayName>

Padrão	N/A Se você omitir esse elemento, será usado o valor do atributo name da política.
Presence	Opcional
Tipo	String

Elemento <Source>

(Opcional) Especifica a variável a ser analisada. O valor de <Source> é definido por padrão como message. O valor message diferencia o contexto. Em um fluxo de solicitação, message resolve a mensagem de solicitação. Em um fluxo de resposta, message é resolvido para a mensagem de resposta.

Muitas vezes, quando você usa essa política para extrair informações de uma mensagem de resposta ou solicitação, é possível usá-la para extrair informações de qualquer variável. Por exemplo, é possível usá-la para extrair informações de uma entidade criada pela política AccessEntity, de dados retornados pela política ServiceCallout ou de um objeto JSON ou XML.

Se <Source> não puder ser resolvido ou se resolver para um tipo de mensagem, a política não responderá.

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

Padrão:	mensagem
Presença:	Opcional
Tipo:	String

Atributos

Atributo	Descrição	Padrão	Presence	Tipo
clearPayload	Defina como true se você quiser limpar o payload especificado em <Source> depois de extrair dados dele. Use a opção <clearPayload> somente se a mensagem de origem não for obrigatória depois que ExtractVariables for executada. Definir como true libera a memória usada pela mensagem.	false	Opcional	Booleano

Elemento <VariablePrefix>

(Opcional) O nome completo da variável é criado mesclando o <VariablePrefix>, um ponto e o nome definido entre {chaves} no elemento <Pattern> ou no elemento <Variable>. Por exemplo: myprefix.id, myprefix.dbncode ou myprefix.oauthtoken.

<VariablePrefix>myprefix</VariablePrefix>

Por exemplo, suponha que o valor do nome seja "user".

• Se <VariablePrefix> não for especificado, os valores extraídos serão atribuídos a uma variável chamada user.
• Se <VariablePrefix> for especificado como myprefix, os valores extraídos serão atribuídos a uma variável chamada myprefix.user.

Padrão:	N/A
Presença:	Opcional
Tipo:	String

Elemento <IgnoreUnresolvedVariables>

(Opcional) Defina como true para tratar qualquer variável não resolvida como uma string vazia (nula). Defina como false se você quiser que a política gere um erro quando qualquer variável referenciada não puder ser resolvida.

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

Padrão:	Falso
Presença:	Opcional
Tipo:	Booleano

Elemento <URIPath>

(Opcional, mas veja a linha de presença na tabela abaixo para saber mais.) Extrai um valor de proxy.pathsuffix de uma mensagem de origem de request. O caminho aplicado ao padrão é o proxy.pathsuffix, que não inclui o caminho base para o Proxy da API. Se a mensagem de origem for resolvida para um tipo de mensagem de response, esse elemento não fará nada.

<URIPath>
   <Pattern ignoreCase="false">/accounts/{id}</Pattern>
</URIPath>

É possível usar vários elementos <Pattern>:

<URIPath>
   <Pattern ignoreCase="false">/accounts/{id}</Pattern>
   <Pattern ignoreCase="false">/accounts/{id}/transactions/{index}</Pattern>
</URIPath>

Padrão:	N/A
Presença:	Opcional. No entanto, você precisa incluir pelo menos um dos seguintes itens: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> ou <XMLPayload>.
Tipo:	N/A

Atributos

Atributo	Descrição	Padrão	Presence	Tipo
ignoreCase	Especifica para ignorar a correspondência de maiúsculas e minúsculas.	false	Opcional	Booleano

Elemento <QueryParam>

(Opcional, mas veja a linha de presença na tabela abaixo para saber mais.) Extrai um valor do parâmetro de consulta especificado de uma mensagem de origem de request. Se a mensagem de origem for resolvida para um tipo de mensagem de response, esse elemento não fará nada.

<QueryParam name="code">
   <Pattern ignoreCase="true">DBN{dbncode}</Pattern>
</QueryParam>

Se vários parâmetros de consulta tiverem o mesmo nome, use índices para referenciar os parâmetros:

<QueryParam name="w.2">
   <Pattern ignoreCase="true">{secondW}</Pattern>
</QueryParam>

Padrão:	N/A
Presença:	Opcional. No entanto, você precisa incluir pelo menos um dos seguintes itens: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> ou <XMLPayload>.
Tipo:	N/A

Atributos

Atributo	Descrição	Padrão	Presence	Tipo
name	Especifica o nome do parâmetro de consulta. Se vários parâmetros de consulta tiverem o mesmo nome, use a referência indexada, em que a primeira instância do parâmetro de consulta não tem índice, a segunda está no índice 2, a terceira no índice 3 etc.	N/A	Obrigatório	String

Elemento <Header>

(Opcional, mas veja a linha de presença na tabela abaixo para saber mais.) Extrai um valor do cabeçalho HTTP especificado da mensagem request ou response especificada. Se vários cabeçalhos tiverem o mesmo nome, os valores serão armazenados em uma matriz.

<!-- 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 vários cabeçalhos tiverem o mesmo nome, use índices para referenciar cabeçalhos individuais na matriz:

<Header name="myHeader.2">
   <Pattern ignoreCase="true">{secondHeader}</Pattern>
</Header>

Ou o seguinte para listar todos os cabeçalhos na matriz:

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

Padrão:	N/A
Presença:	Opcional. No entanto, você precisa incluir pelo menos um dos seguintes itens: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> ou <XMLPayload>.
Tipo:	N/A

Atributos

Atributo	Descrição	Padrão	Presence	Tipo
name	Especifica o nome do cabeçalho a partir daquele que você extrai o valor. Se vários cabeçalhos tiverem o mesmo nome, use a referência indexada, em que a primeira instância do cabeçalho não tem índice, a segunda está no índice 2, a terceira no índice 3 etc. Use .values para receber todos os cabeçalhos na matriz.	N/A	Obrigatório	String

Elemento <FormParam>

(Opcional, mas veja a linha de presença na tabela abaixo para saber mais.) Extrai um valor do parâmetro de formulário especificado da mensagem request ou response especificada. Os parâmetros de formulário podem ser extraídos somente quando o cabeçalho Content-Type da mensagem especificada for application/x-www-form-urlencoded.

<FormParam name="greeting">
    <Pattern>hello {user}</Pattern>
</FormParam>

Padrão:	N/A
Presença:	Opcional. No entanto, você precisa incluir pelo menos um dos seguintes itens: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> ou <XMLPayload>.
Tipo:	N/A

Atributos

Atributo	Descrição	Padrão	Presence	Tipo
name	O nome do parâmetro de formulário do quem você extrai o valor.	N/A	Obrigatório	String

Elemento <Variable>

(Opcional, mas veja a linha de presença na tabela abaixo para saber mais.) Especifica o nome de uma variável da qual extrair um valor.

<Variable name="myVar">
    <Pattern>hello {user}</Pattern>
</Variable>

Para extrair dois valores da variável:

<Variable name="myVar">
   <Pattern>hello {firstName} {lastName}</Pattern>
</Variable>

Padrão:	N/A
Presença:	Opcional. No entanto, você precisa incluir pelo menos um dos seguintes itens: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> ou <XMLPayload>.
Tipo:	N/A

Atributos

Atributo	Descrição	Padrão	Presence	Tipo
name	O nome da variável da qual extrair o valor.	N/A	Obrigatório	String

Elemento <JSONPayload>

(Opcional, mas veja a linha de presença na tabela abaixo para saber mais.) Especifica a mensagem no formato JSON da qual o valor da variável será extraído. A extração de JSON é realizada somente quando o cabeçalho Content-Type da mensagem for application/json.

<JSONPayload>
   <Variable name="name" type="string">
      <JSONPath>{example}</JSONPath>
   </Variable>
</JSONPayload>

Padrão:	N/A
Presença:	Opcional. No entanto, você precisa incluir pelo menos um dos seguintes itens: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> ou <XMLPayload>.
Tipo:	N/A

Elemento <JSONPayload>/<Variable>

Obrigatório no elemento JSONPayload. Especifica a variável em que o valor extraído é atribuído. É possível incluir várias tags <Variable> no elemento <JSONPayload> para preencher várias variáveis.

<Variable name="name" type="string">
   <JSONPath>{example}</JSONPath>
</Variable>

Padrão:	N/A
Presença:	Obrigatório no elemento JSONPayload.
Tipo:	N/A

Atributos

Atributo	Descrição	Padrão	Presence	Tipo
name	Especifica o nome da variável a que o valor extraído será atribuído.	name	Obrigatório	String
tipo	Especifica o tipo de dados do valor da variável.	N/A	Opcional	String. Selecione uma destas opções: string boolean número inteiro long float duplo nodeset (retorna o fragmento JSON)

Elemento <JSONPayload>/<Variable>/<JSONPath>

Obrigatório no elemento JSONPayload:Variable. Especifica o caminho JSON usado para extrair um valor de uma mensagem formatada em JSON.

Observação: o elemento <JSONPath> é compatível com o recurso de substituição de strings dinâmico chamado modelo de mensagem.

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

Padrão:	N/A
Presença:	Obrigatório
Tipo:	String

Elemento <XMLPayload>

(Opcional, mas veja a linha de presença na tabela abaixo para saber mais.) Especifica a mensagem em formato XML da qual o valor da variável será extraído. Os payloads XML são extraídos somente quando o cabeçalho Content-Type da mensagem for text/xml, application/xml ou 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>

Padrão:	N/A
Presença:	Opcional. No entanto, você precisa incluir pelo menos um dos seguintes itens: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> ou <XMLPayload>.
Tipo:	N/A

Atributos

Atributo	Descrição	Padrão	Presence	Tipo
stopPayloadProcessing	Defina como true para interromper a avaliação da XPath após uma variável ser preenchida. Isso significa que somente uma única variável é preenchida pela política.	false	Opcional	Booleano

Elemento <XMLPayload>/<Namespaces>

(Opcional) Especifica o namespace a ser usado na avaliação XPath. Se você estiver usando namespaces nas expressões XPath, precisará declarar os namespaces aqui, conforme mostrado no exemplo a seguir.

<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 você não estiver usando namespaces nas expressões XPath, omita ou comente o elemento <Namespaces>, como no exemplo a seguir:

<XMLPayload stopPayloadProcessing="false">
  <!-- <Namespaces/> -->
  <Variable name="legName" type="string">
    <XPath>/Directions/route/leg/name</XPath>
  </Variable>
</XMLPayload>

Padrão:	N/A
Presença:	Opcional
Tipo:	String

Atributos

Atributo	Descrição	Padrão	Presence	Tipo
prefix	O prefixo do namespace.	N/A	Obrigatório	String

Elemento <XMLPayload>/<Variable>

(Opcional) Especifica a variável à qual o valor extraído será atribuído.

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

Padrão:	N/A
Presença:	Opcional
Tipo:	N/A

Atributos

Atributo	Descrição	Padrão	Presence	Tipo
name	Especifica o nome da variável a que o valor extraído será atribuído.	name	Obrigatório	String
tipo	Especifica o tipo de dados do valor da variável.	Booleano	Opcional	String. Selecione uma destas opções: string boolean número inteiro long float duplo nodeset (retorna um fragmento XML)

Elemento <XMLPayload>/<Variable>/<XPath>

(Obrigatório no elemento XMLPayload:Variable.) Especifica o XPath definido para a variável. Somente expressões XPath 1.0 são compatíveis.

O elemento <XPath> não é compatível com modelos de mensagem.

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

Exemplo com um namespace. Se você usar namespaces nas suas expressões XPath, declare os namespaces na seção <XMLPayload><Namespaces> da política.

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

Padrão:	N/A
Presença:	Obrigatório
Tipo:	String

Observação: o uso de parent, ancestor, following e preceding em expressões XPath não é compatível com a Apigee. Para ter os mesmos resultados correspondentes, use a correspondência ou a indexação explícita do nome do nó. Por exemplo:

• <XPath>/Attributes/Attribute[@Name=’foo_attribute']/Value</XPath>
  recebe o valor de foo_attribute.
• <XPath>/Attributes/Attribute[4]/Value</XPath>
  recebe o valor do quarto atributo.

Referência de erros

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>

Esquemas

Amostra: veja nossas amostras de repositório do GitHub para os esquemas mais recentes.

Temas relacionados

Referência de variáveis de fluxo