Esta é a documentação do Apigee Edge.
Acesse
Documentação da Apigee X. informações
![](https://docs.apigee.com/static/api-platform/images/icon_policy_extract-variable.jpg?authuser=0000&hl=pt)
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 Opcionalmente, use o elemento |
N/A | Obrigatório |
continueOnError |
Defina como Defina como |
falso | Opcional |
enabled |
Defina como Defina como |
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 |
---|---|
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. |
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 chamadauser
. - Se
<VariablePrefix>
for especificado como myprefix, os valores extraídos serão atribuídos a uma variável chamadamyprefix.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:
|
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 |
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:
|
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:
|
build |
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á. |
build |
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. |
build |
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. | build |
steps.extractvariables.SourceMessageNotAvailable |
500 | Esse erro ocorrerá se a variável message
especificada no elemento Source da política
for:
|
build |
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. | build |
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. |
build |
NONEmptyPrefixMappedToEmptyURI |
Esse erro ocorre se a política tiver um prefixo definido no elemento
Namespace no elemento XMLPayload , mas nenhum URI será
definido. |
build |
DuplicatePrefix |
Esse erro ocorre se a política tiver o mesmo prefixo definido mais de
uma vez no elemento Namespace no elemento XMLPayload . |
build |
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.
|
build |
EmptyXPathExpression |
Se a política tiver uma expressão XPath vazia no elemento XMLPayload ,
a implantação do proxy da API falhará. |
build |
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. |
build |
EmptyJSONPathExpression |
Se a política tiver uma expressão XPath vazia no
elemento XMLPayload , a implantação do proxy da API falhará. |
build |
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á. |
build |
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. |
build |
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á. |
build |
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á. |
build |
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á.
|
build |
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