Política ExtractVariables

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X.
informações

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.

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.
Extrair variáveis do parâmetro de consulta (versão clássica do Edge) Extraia variáveis de um parâmetro de consulta usando a interface clássica do Edge.
Extrair variáveis do payload XML ou JSON (versão clássica do Edge) Extraia variáveis de um payload XML ou JSON usando a interface clássica do Edge.

Amostras

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

GitHub

Esses links direcionam para amostras funcionais de proxy de API que podem ser implantadas e executadas no Edge. Elas usam ExtractVariables e estão localizadas no repositório api-platform-samples no GitHub. Os READMEs explicam como ExtractVariables é usado em cada caso e como implantar e executar cada amostra.

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://org1-test.apigee.net/svc1/accounts/12797282

Suponha que o caminho base para o proxy da API seja /svc1. Quando o Apigee Edge aplica o código de política ExtractVariables acima dessa solicitação recebida, ele definirá a variável urirequest.id para 12797282. Depois que o Apigee Edge executar a política, o código ou as políticas subsequentes no fluxo de processamento podem se referir à variável urirequest.id para receber o valor de string 12797282.

Por exemplo, a seguinte política AssignMessage 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://org1-test.apigee.net/accounts/12797282?code=DBN88271

Quando a Apigee Edge aplicar o código de política ExtractVariables acima a essa solicitação recebida, ele define a variável queryinfo.dbncode como 88271. Após a Apigee Edge executa a política, as políticas ou o código subsequentes no fluxo de processamento podem se referir ao variável chamada queryinfo.dbncode para receber o valor de string 88271.

Agora, é possível acessar a variável queryinfo.dbncode no seu proxy. Por exemplo, a seguinte política AssignMessage copia-a 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 essa política para extrair o valor de várias instâncias do parâmetro de consulta "w". Para fazer referência a 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, terceiro, índice 3 etc.

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

GET http://org1-test.apigee.net/weather?w=Boston&w=Chicago

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

Agora é possível acessar a variável queryinfo.firstWeather e queryinfo.secondWeather 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>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 o Apigee Edge aplicar o código de política ExtractVariables acima a esse cabeçalho, defina 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>
<JSONPayload>$

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 Edge aplica o código de política ExtractVariables acima a essa 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>
<XMLPayload>

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 Edge aplica o código de política ExtractVariables acima a essa mensagem XML, define três variáveis: directionsresponse.travelmode, directionsresponse.duration e directionsresponse.timeunit. Todas as variáveis usam o mesmo prefixo de variável de directionsresponse. O sufixo dessas variáveis é especificado explicitamente pelo atributo name do elemento <Variable>.

A variável directionsresponse.travelmode recebe o valor DRIVING. A variável directionsresponse.duration recebe o valor 19. A variável directionsresponse.timeunit recebe o valor minutes.

Agora, é possível acessar a variável directionresponse.travelmode no seu proxy. Por exemplo, a seguinte política AssignMessage 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>

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 análise da API Edge.

Para ver como o ExtractVariables pode ser usado na criação de relatórios do Analytics orientados por conteúdo, consulte Analisar Conteúdo de mensagens da API usando análises personalizadas.

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 de geração de registros de mensagens)
  • Fluxos de erro
.

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 é definida como qualquer valor no proxy.pathsuffix após "/a/". Por exemplo, suponha que o caminho base para o 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 marcadores para correspondência, correspondentes 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 faz nada, e as variáveis não são criadas.
  • Se houver mais de um padrão, o padrão com segmentos de caminho 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 da API fique da seguinte forma:

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

Neste exemplo, o primeiro padrão corresponde ao URI e a variável urirequest.pathSeg está 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, insira 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 é definida como "b" e a variável urirequest.pathSeg2 é 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>, conforme 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, você especifica 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) para as informações extraídas.

Todas as tags <Variable> na política são avaliadas para que você preencha várias 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>Extract Variables 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.

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.

true Opcional
async

Esse atributo está obsoleto.

falso Obsoleto

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á-lo para extrair informações de uma entidade criada pela política AccessEntity, com base em dados retornados pelo serviço política de chamada ou extrair informações de um objeto XML ou JSON.

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

<Source clearPayload="true|false">request</Source>
Padrão: message
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 necessária depois que ExtractVariables for executado. Definir como true libera a memória usada pela mensagem.

falso

Opcional Booleanos

Elemento <VariablePrefix>

(Opcional) O nome completo da variável é criado juntando-se o <VariablePrefix>, um ponto e o nome definido em {curly braces} no elemento <Pattern> ou <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

Se uma referência XPath não for resolvida em uma <XMLPayload>, a política vai gerar o seguinte erro:

{
   "fault":{
      "faultstring":"Unresolved xpath path in policy policy_name.",
      "detail":{
         "errorcode":"steps.extractvariables.InvalidXPath"
      }
   }
}

Elemento <URIPath>

(Opcional, mas veja a linha de presença na tabela abaixo para saber mais.) Extrai um valor do proxy.pathsuffix de uma mensagem de origem 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 com 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 Booleanos

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 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. 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/D

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

Obrigatório String

Elemento <JSONPayload>

(Opcional, mas veja a linha de presença na tabela abaixo para saber mais.) Especifica a mensagem formatada em JSON da qual o valor da variável será extraído. JSON é executada apenas quando o cabeçalho Content-Type da mensagem é 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/D

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/D Opcional

String. Selecione uma destas opções:

  • string
  • boolean
  • integer
  • 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.

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

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. Booleanos Opcional

String. Selecione uma destas opções:

  • string
  • boolean
  • integer
  • 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.

<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

Referência de erros

Nesta seção, descrevemos os códigos e as mensagens de erro retornados e as variáveis de falha definidas pelo Edge quando a 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.
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 essa 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.
InstantiationFailed Não foi possível instanciar a política.
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

Temas relacionados

Analise o conteúdo da mensagem da API usando análises personalizadas

Referência de variáveis