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 secção descreve os códigos de falha e as mensagens de erro devolvidas, bem como as variáveis de falha definidas pelo Apigee quando esta política aciona um erro. Estas informações são importantes para saber se está a desenvolver regras de falhas para tratar falhas. Para saber mais, consulte o artigo O que precisa de saber acerca dos erros de políticas e Como processar falhas.

Erros de tempo de execução

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

Código de falha Estado de HTTP Causa Corrigir
steps.extractvariables.ExecutionFailed 500

Este erro ocorre quando:

  • O payload de entrada (JSON, XML) está vazio.
  • A entrada (JSON, XML, etc.) transmitida à política é inválida ou tem um formato incorreto.
steps.extractvariables.ImmutableVariable 500 Uma variável usada na política é imutável. Não foi possível definir esta variável na política. N/A
steps.extractvariables.InvalidJSONPath 500 Este erro ocorre se for usado um caminho JSON inválido no elemento JSONPath da política. Por exemplo, se uma carga útil JSON não tiver o objeto Name, mas especificar Name como o caminho na política, ocorre este erro.
steps.extractvariables.JsonPathParsingFailure 500 Este 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, isto acontece se a variável de fluxo especificada no elemento Source não existir no fluxo atual.
steps.extractvariables.SetVariableFailed 500 Este erro ocorre se a política não conseguir definir o valor para uma variável. Geralmente, o erro ocorre se tentar atribuir valores a várias variáveis cujos nomes começam com as mesmas palavras num formato aninhado separado por pontos.
steps.extractvariables.SourceMessageNotAvailable 500 Este erro ocorre se a variável message especificada no elemento Source da política for:
  • Fora do âmbito (não disponível no fluxo específico onde a política está a ser executada) ou
  • Não é possível resolver (não está definido)
steps.extractvariables.UnableToCast 500 Este erro ocorre se a política não conseguir converter o valor extraído numa variável. Normalmente, isto acontece se tentar definir o valor de um tipo de dados para uma variável de outro tipo de dados.

Erros de implementação

Estes erros podem ocorrer quando implementa um proxy que contém esta política.

Nome do erro Causa Corrigir
NothingToExtract Se a política não tiver nenhum dos elementos URIPath, QueryParam, Header, FormParam, XMLPayload ou JSONPayload, a implementação do proxy de API falha porque não existe nada para extrair.
NONEmptyPrefixMappedToEmptyURI Este erro ocorre se a política tiver um prefixo definido no elemento Namespace no elemento XMLPayload, mas não tiver nenhum URI definido.
DuplicatePrefix Este erro ocorre se a política tiver o mesmo prefixo definido mais do que uma vez no elemento Namespace no elemento XMLPayload.
NoXPathsToEvaluate Se a política não tiver o elemento XPath no elemento XMLPayload, a implementação do proxy de API falha com este erro.
EmptyXPathExpression Se a política tiver uma expressão XPath vazia no elemento XMLPayload, a implementação do proxy de API falha.
NoJSONPathsToEvaluate Se a política não tiver o elemento JSONPath no elemento JSONPayload, a implementação do proxy de API falha com este erro.
EmptyJSONPathExpression Se a política tiver uma expressão XPath vazia no elemento XMLPayload, a implementação do proxy de API falha.
MissingName Se a política não tiver o atributo name em nenhum dos elementos da política, como QueryParam, Header, FormParam ou Variable, onde é necessário, a implementação do proxy de API falha.
PatternWithoutVariable Se a política não tiver uma variável especificada no elemento Pattern, a implementação do proxy de API falha. O elemento Pattern requer o nome da variável na qual os dados extraídos vão ser armazenados.
CannotBeConvertedToNodeset Se a política tiver uma expressão XPath em que o tipo Variable está definido como nodeset, mas a expressão não puder ser convertida em nodeset, a implementação do proxy de API falha.
JSONPathCompilationFailed Não foi possível compilar um caminho JSON especificado na política. 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 implementação do proxy de API falha.
InvalidPattern Se a definição do elemento Pattern for inválida em qualquer um dos elementos, como URIPath, QueryParam, Header, FormParam, XMLPayload ou JSONPayload na política, a implementação do proxy de API falha.

Variáveis de falha

Estas variáveis são definidas quando esta política aciona um erro no tempo de execução. Para mais informações, consulte o artigo O que precisa de saber sobre os erros de políticas.

Variáveis Onde Exemplo
fault.name="fault_name" fault_name é o nome da falha, conforme indicado na tabela Erros de tempo 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 utilizador da política que gerou 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