Política ExtractVariables

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

Ícone de política

O quê

A política ExtractVariables extrai conteúdo de um pedido ou de uma resposta e define o valor de uma variável para esse conteúdo. Pode extrair qualquer parte da mensagem, incluindo cabeçalhos, caminhos 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, quando encontra uma correspondência, define uma variável com o conteúdo da mensagem especificado.

Embora use frequentemente o elemento ExtractVariables para extrair informações de uma mensagem de pedido ou resposta, também pode usá-lo 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 especificado, pode fazer referência à variável noutras políticas como parte do processamento de um pedido e uma resposta.

Esta política é uma política extensível e a utilização desta política pode ter implicações de custo ou utilização, consoante a sua licença do Apigee. Para ver informações sobre os tipos de políticas e as implicações de utilização, consulte Tipos de políticas.

Vídeos

Veja os vídeos seguintes para saber mais acerca da política ExtractVariables.

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

Amostras

Estes exemplos de código de políticas ilustram como extrair variáveis dos seguintes tipos de artefactos:

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 exemplo de código da política acima. O elemento <URIPath> indica à política ExtractVariables que extraia informações do caminho do URI. O elemento <Pattern> especifica o padrão a aplicar ao caminho do URI. O padrão é tratado como um modelo simples, com as chavetas a denotar a parte variável do caminho do URI.

O nome da variável a definir é determinado pelo valor especificado no elemento <VariablePrefix>, bem como pelo valor entre chavetas {} no elemento <Pattern>. Os dois valores são unidos por um ponto intermédio, o que resulta num nome de variável de, por exemplo, urirequest.id. Se não existir um elemento <VariablePrefix>, o nome da variável é apenas o valor entre chavetas.

Considere o código de política de amostra acima a funcionar com o seguinte pedido recebido:

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

Suponhamos que o caminho base do proxy de API é /svc1. Quando o Apigee aplica o código da política ExtractVariables acima a este pedido recebido, define a variável urirequest.id como 12797282. Depois de o Apigee executar a política, as políticas ou o código subsequentes no fluxo de processamento podem referir-se à variável denominada urirequest.id para obter o valor da string 12797282.

Por exemplo, a política AssignMessage seguinte incorpora o valor dessa variável no payload de uma nova mensagem de pedido:

<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 de política de amostra acima a funcionar com o seguinte pedido recebido:

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

Quando o Apigee aplica o código da política ExtractVariables acima a este pedido recebido, define a variável queryinfo.dbncode como 88271. Depois de o Apigee executar a política, as políticas ou o código subsequentes no fluxo de processamento podem referir-se à variável denominada queryinfo.dbncode para obter o valor da string 88271.

Já pode aceder à variável queryinfo.dbncode no seu proxy. Por exemplo, a seguinte política AssignMessage copia-o para a carga útil do pedido:

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

Suponhamos que a estrutura da sua API lhe permite especificar vários parâmetros de consulta com o mesmo nome. Pode usar uma política ExtractVariables para extrair o valor de várias instâncias do parâmetro de consulta. Para fazer referência a 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 tem índice, a segunda está no índice 2, a terceira no índice 3 e assim sucessivamente.

Considere o código de política de amostra acima a funcionar com o seguinte pedido recebido:

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

Quando o Apigee aplica o código da política ExtractVariables acima a este pedido recebido, define a variável queryinfo.firstWeather como Boston e a variável queryInfo.secondWeather como Chicago.

Já pode aceder às variáveis queryinfo.firstWeather e queryinfo.secondWeather no seu proxy. Por exemplo, a seguinte política AssignMessage copia-a para a carga útil do pedido:

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

Suponhamos que a sua API usa tokens de autorização OAuth v2.0. Considere o código de política de exemplo acima a funcionar com um pedido que contenha um token OAuth v2.0 que inclua um cabeçalho como este: Authorization: Bearer TU08xptfFfeM7aS0xHqlxTgEAdAM.

Como criador da API, suponha que quer usar o valor do token (mas não o cabeçalho completo) como uma chave numa pesquisa de cache. Pode usar o código da política ExtractVariables acima para extrair o token.

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

Já pode aceder à variável clientrequest.oauthtoken no seu proxy. Por exemplo, a seguinte política AssignMessage copia-o para a carga útil do pedido:

<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 o Apigee aplica o código da política ExtractVariables acima a esta mensagem JSON, define duas variáveis: geocoderesponse.latitude e geocoderesponse.longitude. Ambas as variáveis usam o mesmo prefixo de variável de geocoderesponse. O sufixo destas 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.

Já pode aceder à variável geocoderesponse.latitude no seu proxy. Por exemplo, a seguinte política AssignMessage copia-o para um cabeçalho denominado 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 o Apigee aplica o código da política ExtractVariables acima a esta mensagem XML, define três variáveis:

  • 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 destas variáveis é especificado explicitamente pelo elemento <Variable> no atributo name.

Já pode aceder à variável directionresponse.travelmode no seu proxy. Por exemplo, a seguinte política AssignMessage copia-o para um cabeçalho denominado 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>

Acerca da política ExtractVariables

Os programadores de APIs criam proxies de API que se comportam de forma 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 uma parte deste conteúdo para utilização numa declaração de condição. Use a política ExtractVariables para o fazer.

Ao definir a política ExtractVariables, pode escolher:

  • Nomes das variáveis a definir
  • 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ódigo podem, em seguida, consumir essas variáveis para ativar o comportamento dinâmico ou enviar dados empresariais para o Apigee API Analytics.

Âmbito

As variáveis definidas com a política ExtractVariables têm um âmbito global. Ou seja, depois de a política ExtractVariables definir uma nova variável, pode aceder a essa variável a partir de qualquer política ou código em qualquer fase do fluxo (que é executado após a política ExtractVariables). Isto inclui:

  • PreFlow: ProxyEndpoint e TargetEndpoint (pedido e resposta)
  • PostFlow: ProxyEndpoint e TargetEndpoint (pedido e resposta)
  • PostClientFlow: ProxyEndpoint (apenas resposta, usando a política MessageLogging>)
  • Fluxos de erros

Acerca da correspondência e da criação de variáveis

A política ExtractVariables extrai informações de um pedido ou de uma resposta e escreve essas informações numa variável. Para cada tipo de informação que pode extrair, como o caminho do URI ou os dados XML, especifica o padrão a corresponder e o nome da variável usada para reter a informação extraída.

No entanto, a forma como a correspondência de padrões funciona depende da origem da extração. As secções seguintes descrevem as duas categorias básicas de informações que pode extrair.

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

Quando extrai informações de um caminho de URI, parâmetros de consulta, cabeçalhos, parâmetros de formulário e variáveis, usa a etiqueta <Pattern> para especificar um ou mais padrões a corresponder. Por exemplo, o seguinte exemplo de política mostra um único padrão correspondente 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 é definida para o que quer que apareça em proxy.pathsuffix após /a/. Por exemplo, suponhamos que o caminho base do seu proxy de API é /basepath/v1 . Com um pedido de entrada, a variável http://myCo.com/basepath/v1/a/b é definida como b.

Especificar vários padrões

Pode especificar vários padrões a fazer corresponder, correspondentes a etiquetas <Pattern>, onde:

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

No exemplo seguinte, cria uma política que contém três padrões correspondentes 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>

Suponhamos que, para um proxy de API com um caminho base de /basepath/v1 , o URL de pedido de entrada para o proxy de API tem este 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 do pedido for:

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

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

Especificar padrões com várias variáveis

Pode especificar várias variáveis no padrão de correspondência. Por exemplo, especifica um padrão de correspondência 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>

Supondo novamente um proxy de API com um caminho base de /basepath/v1 , para o URL de pedido 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.

Encontrar várias instâncias no padrão

Também pode fazer a correspondência de padrões quando existem várias instâncias de um item com o mesmo nome. Por exemplo, pode fazer um pedido que contenha vários parâmetros de consulta ou vários cabeçalhos com o mesmo nome. O pedido seguinte contém dois parâmetros de consulta com o nome "w":

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

Para fazer referência a estes parâmetros de consulta na política ExtractVariables, usa í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 seguinte política extrai o valor do segundo parâmetro de consulta denominado "w" no pedido:

<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 está definida como "2". Se o segundo parâmetro de consulta for omitido do pedido, a variável urirequest.secondW fica vazia. Use a indexação sempre que existirem vários itens com o mesmo nome no pedido.

Usar carateres especiais no padrão

Quando faz a correspondência de caminhos de URI, pode usar os carateres universais "*" e "**" no padrão, em que:

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

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

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

O primeiro padrão corresponde a pedidos com sufixos de caminho (a parte do caminho do 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", bem como "/a/b/c" e "/a/foo/bar".

Quando especifica padrões para parâmetros de consulta, cabeçalhos e parâmetros de formulário, o caráter "*" especifica a correspondência com qualquer número de carateres. Por exemplo, quando faz a correspondência de um cabeçalho, especifique o padrão da seguinte forma:

*;charset={encoding}

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

Se o valor transmitido à política ExtractVariables contiver um caráter especial, como "{", use o caráter "%" para lhe aplicar o caráter de escape. O exemplo seguinte escapa os carateres "{" e "}" no padrão porque são usados como carateres 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".

Fazer corresponder JSON e XML

Quando extrai dados de JSON e XML, especifica uma ou mais etiquetas <Variable> na política. A etiqueta <Variable> especifica o nome da variável de destino onde as informações extraídas são armazenadas e o JsonPath (JSON) ou o XPATH (XML) para as informações extraídas.

Todas as etiquetas <Variable> na política são avaliadas para que possa preencher várias variáveis a partir 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 é criada.

O exemplo seguinte mostra uma política ExtractVariables que preenche duas variáveis a partir 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>

Escrever na mesma variável em vários locais

Tenha cuidado ao escolher os nomes das variáveis a definir. A política é executada sequencialmente do padrão de extração inicial ao final. Se a política escrever um valor na mesma variável a partir de vários locais, a última escrita na política determina o valor da variável. (Esta pode ser a opção que quer.)

Por exemplo, quer extrair um valor de token que pode ser transmitido num parâmetro de consulta ou num cabeçalho, conforme 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>

Controlar o que acontece quando não existe uma correspondência

Se o padrão não corresponder, a variável correspondente não é criada. Por conseguinte, se outra política fizer referência à variável, pode causar um erro.

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

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

Referência do elemento

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

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

A tabela seguinte descreve os atributos comuns a todos os elementos principais de políticas:

Atributo Descrição Predefinição Presença
name

O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hífenes, sublinhados e pontos finais. Este valor não pode exceder 255 carateres.

Opcionalmente, use o elemento <DisplayName> para etiquetar a política no editor de proxy da IU de gestão com um nome diferente em linguagem natural.

 N/A Obrigatória
continueOnError

Definido como false para devolver um erro quando uma política falha. Este comportamento é o esperado para a maioria das políticas.

Definido como true para que a execução do fluxo continue mesmo depois de uma política falhar. Veja também:

 falso Opcional
enabled

Defina como true para aplicar a política.

Defina como false para desativar a política. A política não é aplicada, mesmo que permaneça associada a um fluxo.

 verdadeiro Opcional
async

Este atributo foi descontinuado.

 falso Descontinuado

Elemento <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>
Predefinição

N/A

Se omitir este elemento, é 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> é predefinido como message. O valor message é sensível ao contexto. Num fluxo de pedidos, message é resolvido para a mensagem de pedido. Num fluxo de resposta, message é resolvido para a mensagem de resposta.

Embora use frequentemente esta política para extrair informações de uma mensagem de pedido ou resposta, pode usá-la para extrair informações de qualquer variável. Por exemplo, pode usá-la para extrair informações de uma entidade criada pela política AccessEntity, de dados devolvidos pela política ServiceCallout ou extrair informações de um objeto XML ou JSON.

Se não for possível resolver <Source> ou se for resolvido para um tipo que não seja de mensagem, a política não responde.

<Source clearPayload="true|false">request</Source>
Predefinição: mensagem
Presença: Opcional
Tipo: String

Atributos

Atributo Descrição Predefinição Presença Tipo
clearPayload

Defina como true se quiser limpar o payload especificado em <Source> depois de extrair dados do mesmo.

Use a opção <clearPayload> apenas se a mensagem de origem não for necessária após a execução de ExtractVariables. Se a opção for definida como verdadeira, a memória usada pela mensagem é libertada.

falso

 Opcional Booleano

Elemento <VariablePrefix>

(Opcional) O nome completo da variável é criado juntando o <VariablePrefix>, um ponto e o nome que define entre {chavetas} 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 é "user".

  • Se <VariablePrefix> não for especificado, os valores extraídos são atribuídos a uma variável denominada user.
  • Se <VariablePrefix> for especificado como myprefix, os valores extraídos são atribuídos a uma variável denominada myprefix.user.
Predefinição: N/A
Presença: Opcional
Tipo: String

Elemento <IgnoreUnresolvedVariables>

(Opcional) Defina como true para tratar qualquer variável não resolúvel como uma string vazia (nula). Defina como false se quiser que a política apresente um erro quando qualquer variável referenciada não for resolvível.

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
Predefinição: Falso
Presença: Opcional
Tipo: Booleano

Elemento <URIPath>

(Opcional, mas consulte a linha Presença na tabela abaixo para mais informações.) Extrai um valor de proxy.pathsuffix de uma mensagem de origem request. O caminho aplicado ao padrão é o proxy.pathsuffix, que não inclui o basepath para o proxy de API. Se a mensagem de origem for resolvida para um tipo de mensagem response, este elemento não faz 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>
Predefinição: N/A
Presença: Opcional. No entanto, tem de incluir, pelo menos, um dos seguintes elementos: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> ou <XMLPayload>.
Tipo: N/A

Atributos

Atributo Descrição Predefinição Presença Tipo
ignoreCase Especifica que as maiúsculas e minúsculas devem ser ignoradas quando o padrão é encontrado.

falso

 Opcional Booleano

Elemento <QueryParam>

(Opcional, mas consulte a linha Presença na tabela abaixo para mais informações.) Extrai um valor do parâmetro de consulta especificado de uma mensagem de origem request. Se a mensagem de origem for resolvida para um tipo de mensagem response, este elemento não faz 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 fazer referência aos parâmetros:

<QueryParam name="w.2">
   <Pattern ignoreCase="true">{secondW}</Pattern>
</QueryParam>
Predefinição: N/A
Presença: Opcional. No entanto, tem de incluir, pelo menos, um dos seguintes elementos: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> ou <XMLPayload>.
Tipo: N/A

Atributos

Atributo Descrição Predefinição Presença Tipo
nome Especifica o nome do parâmetro de consulta. Se vários parâmetros de consulta tiverem o mesmo nome, use referências indexadas, 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ória String

Elemento <Header>

(Opcional, mas consulte a linha Presença na tabela abaixo para mais informações.) Extrai um valor do cabeçalho HTTP especificado da mensagem request ou response especificada. Se vários cabeçalhos tiverem o mesmo nome, os respetivos valores são armazenados numa 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>
Predefinição: N/A
Presença: Opcional. No entanto, tem de incluir, pelo menos, um dos seguintes elementos: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> ou <XMLPayload>.
Tipo: N/A

Atributos

Atributo Descrição Predefinição Presença Tipo
nome Especifica o nome do cabeçalho do qual extrai o valor. Se vários cabeçalhos tiverem o mesmo nome, use referências indexadas, 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 obter todos os cabeçalhos na matriz.

N/A

 Obrigatória String

Elemento <FormParam>

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

<FormParam name="greeting">
    <Pattern>hello {user}</Pattern>
</FormParam>
Predefinição: N/A
Presença: Opcional. No entanto, tem de incluir, pelo menos, um dos seguintes elementos: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> ou <XMLPayload>.
Tipo: N/A

Atributos

Atributo Descrição Predefinição Presença Tipo
nome O nome do parâmetro do formulário a partir do qual extrai o valor.

N/A

 Obrigatória String

Elemento <Variable>

(Opcional, mas consulte a linha Presença na tabela abaixo para mais informações.) Especifica o nome de uma variável a partir 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>
Predefinição: N/A
Presença: Opcional. No entanto, tem de incluir, pelo menos, um dos seguintes elementos: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> ou <XMLPayload>.
Tipo: N/A

Atributos

Atributo Descrição Predefinição Presença Tipo
nome O nome da variável a partir da qual extrair o valor.

N/A

 Obrigatória String

Elemento <JSONPayload>

(Opcional, mas consulte a linha Presença na tabela abaixo para mais informações.) Especifica a mensagem formatada em JSON a partir da qual o valor da variável vai ser extraído. A extração de JSON é realizada apenas quando o cabeçalho Content-Type da mensagem é application/json.

<JSONPayload>
   <Variable name="name" type="string">
      <JSONPath>{example}</JSONPath>
   </Variable>
</JSONPayload>
Predefinição: N/A
Presença: Opcional. No entanto, tem de incluir, pelo menos, um dos seguintes elementos: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> ou <XMLPayload>.
Tipo: N/A

Elemento <JSONPayload>/<Variable>

(Obrigatório no elemento JSONPayload.) Especifica a variável à qual o valor extraído é atribuído. Pode incluir várias etiquetas <Variable> no elemento <JSONPayload> para preencher várias variáveis.

<Variable name="name" type="string">
   <JSONPath>{example}</JSONPath>
</Variable>
Predefinição: N/A
Presença: Obrigatório no elemento JSONPayload.
Tipo: N/A

Atributos

Atributo Descrição Predefinição Presença Tipo
nome

Especifica o nome da variável à qual o valor extraído vai ser atribuído.

nome

 Obrigatória String
escrever Especifica o tipo de dados do valor da variável. N/A Opcional

String. Selecione uma opção:

  • de string
  • booleano
  • número inteiro
  • longo
  • flutuante
  • dupla
  • nodeset (devolve 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. 

<Variable name="name">
  <JSONPath>$.rss.channel.title</JSONPath>
</Variable>
Predefinição: N/A
Presença: Obrigatória
Tipo: String

Elemento <XMLPayload>

(Opcional, mas consulte a linha Presença na tabela abaixo para mais informações.) Especifica a mensagem formatada em XML a partir da qual o valor da variável vai ser extraído. As cargas úteis XML são extraídas apenas quando o cabeçalho Content-Type da mensagem é 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>
Predefinição: N/A
Presença: Opcional. No entanto, tem de incluir, pelo menos, um dos seguintes elementos: <URIPath>, <QueryParam>, <Header>, <FormParam>, <JSONPayload> ou <XMLPayload>.
Tipo: N/A

Atributos

Atributo Descrição Predefinição Presença Tipo
stopPayloadProcessing

Definido como true para parar a avaliação de XPath depois de uma variável ser preenchida. Isto significa que apenas uma variável é preenchida pela política.

falso

 Opcional Booleano

<XMLPayload>/<Namespaces> element

(Opcional) Especifica o espaço de nomes a usar na avaliação do XPath. Se estiver a usar espaços de nomes nas expressões XPath, tem de declarar os espaços de nomes aqui, conforme mostrado no exemplo seguinte.

<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 não estiver a usar espaços de nomes nas suas expressões XPath, pode omitir ou comentar o elemento <Namespaces>, como mostra o exemplo seguinte:

<XMLPayload stopPayloadProcessing="false">
  <!-- <Namespaces/> -->
  <Variable name="legName" type="string">
    <XPath>/Directions/route/leg/name</XPath>
  </Variable>
</XMLPayload>
Predefinição: N/A
Presença: Opcional
Tipo: String

Atributos

Atributo Descrição Predefinição Presença Tipo
prefix

O prefixo do espaço de nomes.

N/A

 Obrigatória String

Elemento <XMLPayload>/<Variable>

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

<Variable name="name" type="boolean">
   <XPath>/test/example</XPath>
</Variable>
Predefinição: N/A
Presença: Opcional
Tipo: N/A

Atributos

Atributo Descrição Predefinição Presença Tipo
nome

Especifica o nome da variável à qual o valor extraído vai ser atribuído.

nome

 Obrigatória String
escrever Especifica o tipo de dados do valor da variável. Booleano Opcional

String. Selecione uma opção:

  • de string
  • booleano
  • número inteiro
  • longo
  • flutuante
  • dupla
  • nodeset (devolve um fragmento XML)

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

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

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

Exemplo com um espaço de nomes. Se usar espaços de nomes nas expressões XPath, tem de declarar os espaços de nomes na secção <XMLPayload><Namespaces> da política.

<Variable name="name" type="boolean">
   <XPath>/foo:test/foo:example</XPath>
</Variable>
Predefinição: N/A
Presença: Obrigatória
Tipo: String

Referência de erro

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.

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.

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

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

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

Tópicos relacionados

Referência de variáveis do fluxo