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	Presença
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	falso	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.	verdadeiro	Opcional
async	Esse atributo está obsoleto.	falso	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.
Presença	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	Presença	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.	falso	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	Presença	Tipo
ignoreCase	Especifica para ignorar a correspondência de maiúsculas e minúsculas.	falso	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	Presença	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	Presença	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	Presença	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	Presença	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	Presença	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	Presença	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.	falso	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	Presença	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	Presença	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

Esta seção descreve os códigos de falha e as mensagens de erro que são retornadas e as variáveis de falha definidas pela Apigee quando essa política aciona um erro. Essas informações são importantes para saber se você está desenvolvendo regras de falha para lidar com falhas. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.

Erros de execução

Esses erros podem ocorrer quando a política é executada.

Dica: precisa de ajuda para resolver um erro? Clique em na coluna "Correção" para ver informações detalhadas sobre solução de problemas.

Código de falha	Status HTTP	Causa	Correção
steps.extractvariables.ExecutionFailed	500	Esse erro ocorre quando: O payload de entrada (JSON, XML) está vazio. A entrada (JSON, XML etc.) passada para a política é inválida ou está incorreta.
steps.extractvariables.ImmutableVariable	500	Uma variável usada na política é imutável. A política não conseguiu definir essa variável.	N/A
steps.extractvariables.InvalidJSONPath	500	Esse erro ocorrerá se um caminho JSON inválido for usado no elemento JSONPath da política. Por exemplo, se um payload JSON não tiver o objeto Name, mas você especificar Name como o caminho na política, esse erro ocorrerá.
steps.extractvariables.JsonPathParsingFailure	500	Esse erro ocorre quando a política não consegue analisar um caminho JSON e extrair dados da variável de fluxo especificada no elemento Source. Normalmente, isso acontece se a variável de fluxo especificada no elemento Source não existir no fluxo atual.
steps.extractvariables.SetVariableFailed	500	Esse erro ocorre se a política não puder definir o valor como uma variável. O erro geralmente acontece se você tentar atribuir valores a diversas variáveis com nomes que começam com as mesmas palavras em um formato aninhado separado por ponto.
steps.extractvariables.SourceMessageNotAvailable	500	Esse erro ocorrerá se a variável message especificada no elemento Source da política for: Fora do escopo (não disponível no fluxo específico em que a política está sendo executada) ou Não é possível resolver (não está definida)
steps.extractvariables.UnableToCast	500	Esse erro ocorre se a política não conseguiu converter o valor extraído para uma variável. Normalmente, isso ocorre quando você tenta definir o valor de um tipo de dados para uma variável de outro tipo de dados.

Erros na implantação

Esses erros podem ocorrer quando você implanta um proxy que contém esta política.

Dica: precisa de ajuda para resolver um erro? Clique em ao lado da descrição do erro para acessar a página de solução de problemas.

Nome do erro	Causa	Correção
NothingToExtract	Se a política não tiver nenhum dos elementos URIPath, QueryParam, Header, FormParam, XMLPayload ou JSONPayload, a implantação do proxy da API falha, porque não há nada para extrair.
NONEmptyPrefixMappedToEmptyURI	Esse erro ocorre se a política tiver um prefixo definido no elemento Namespace no elemento XMLPayload, mas nenhum URI será definido.
DuplicatePrefix	Esse erro ocorre se a política tiver o mesmo prefixo definido mais de uma vez no elemento Namespace no elemento XMLPayload.
NoXPathsToEvaluate	Se a política não tiver o elemento XPath dentro do elemento XMLPayload, a implantação do proxy de API falhará com este erro. Se você quiser extrair variáveis de um payload XML, um elemento filho XPath precisará ser especificado.
EmptyXPathExpression	Se a política tiver uma expressão XPath vazia no elemento XMLPayload, a implantação do proxy da API falhará.
NoJSONPathsToEvaluate	Se a política não tiver o elemento JSONPath dentro do elemento JSONPayload, a implantação do proxy de API falhará com este erro.
EmptyJSONPathExpression	Se a política tiver uma expressão XPath vazia no elemento XMLPayload, a implantação do proxy da API falhará.
MissingName	Se a política não tiver o atributo name em nenhum dos elementos da política, como QueryParam, Header, FormParam ou Variable, quando necessário, a implantação do proxy da API falhará.
PatternWithoutVariable	Se a política não tiver uma variável especificada no elemento Pattern, a implantação do proxy de API falhará. O elemento Pattern requer o nome da variável em que os dados extraídos serão armazenados.
CannotBeConvertedToNodeset	Se a política tiver uma expressão XPath em que o tipo Variable é definido como nodeset, mas a expressão não pode ser convertida em nodeset, a implantação do proxy de API falhará.
JSONPathCompilationFailed	A política não conseguiu compilar um caminho JSON especificado.	N/A
InstantiationFailed	Não foi possível instanciar a política.	N/A
XPathCompilationFailed	Se o prefixo ou o valor usado no elemento XPath não fizer parte de nenhum dos namespaces declarados na política, a implantação do proxy de API falhará.
InvalidPattern	Se a definição de elemento Pattern for inválida em qualquer um dos elementos como URIPath, QueryParam, Header, FormParam, XMLPayload ou JSONPayload na política, a implantação do proxy de API falhará. O elemento Pattern é considerado inválido se não incluir uma variável. Para mais informações sobre a correspondência de padrões, consulte Sobre a correspondência e a criação de variáveis.

Variáveis de falha

Essas variáveis são definidas quando essa política aciona um erro no ambiente de execução. Para mais informações, consulte O que você precisa saber sobre erros de política.

Variáveis	Onde	Exemplo
fault.name="fault_name"	fault_name é o nome da falha, conforme listado na tabela Erros de ambiente de execução acima. O nome da falha é a última parte do código de falha.	fault.name = "SourceMessageNotAvailable"
extractvariables.policy_name.failed	policy_name é o nome especificado pelo usuário da política que causou a falha.	extractvariables.EV-ParseJsonResponse.failed = true

Exemplo de resposta de erro

Observação: para tratamento de erros, a prática recomendada é interceptar a parte errorcode da resposta de erro. Não confie no texto do faultstring, porque ele pode mudar.

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

Exemplo de regra de falha

<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