Política DataCapture

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Ícone do DataCapture

Visão geral

A política do DataCapture captura os dados, como payload, cabeçalhos HTTP e parâmetros de caminho ou consulta, de um proxy de API para uso no Analytics. É possível usar os dados capturados nos relatórios personalizados do Analytics e implementar as regras de monetização e monitoramento.

Esta é uma Política extensível. O uso dela pode ter implicações no custo ou na utilização, dependendo da sua licença da Apigee. Para informações sobre tipos de política e implicações de uso, consulte Tipos de política.

Recurso Coletor de dados

Para usar a política DataCapture, crie primeiro um recurso REST do Coletor de dados. Para ver as etapas de criação de um recurso coletor de dados usando a IU da Apigee e a API Apigee, consulte Como criar um coletor de dados.

<DataCapture>

O elemento <DataCapture> define uma política DataCapture.

<DataCapture async="true" continueOnError="true" enabled="true" name="DC">

Aqui está um exemplo de uma política DataCapture:

<DataCapture name="DC-1">
    <Capture>
        <DataCollector>dc_data_collector</DataCollector>
        <Collect ref="my_data_variable" />
    </Capture>
</DataCapture>

O principal elemento da política DataCapture é o elemento <Capture>, que especifica os meios de captura dos dados. Ela tem dois elementos filhos obrigatórios:

Neste exemplo simples, os dados são extraídos de uma variável chamada my_data_variable, que foi criada em outro lugar no proxy. A variável é especificada pelo atributo ref.

O elemento <Collect> também fornece outras maneiras de capturar dados de várias fontes por meio dos elementos filhos. Consulte os Exemplos para ver mais maneiras de como capturar dados com a política DataCapture.

O elemento DataCapture tem a seguinte sintaxe.

<DataCapture name="capturepayment" continueOnError="false" enabled="true"> 
  <DisplayName>Data-Capture-Policy-1</DisplayName>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <ThrowExceptionOnLimit>false</ThrowExceptionOnLimit>

  <!-- Existing Variable -->
  <Capture>
    <Collect ref="existing-variable" default="0"></Collect>
    <DataCollector>dc_1</DataCollector>
  </Capture>

  <!-- JSONPayload -->
  <Capture>
    <DataCollector>dc_2</DataCollector>
    <Collect default="0">
      <Source>request</Source>
      <JSONPayload>
        <JSONPath>result.var</JSONPath>
      </JSONPayload>
    </Collect>
  </Capture>

  <!-- URIPath -->
  <Capture>
    <DataCollector>dc_3</DataCollector>
    <Collect default="0">
      <URIPath>
        <!-- All patterns must specify a single variable to extract named $ -->
        <Pattern ignoreCase="false">/foo/{$}</Pattern>
        <Pattern ignoreCase="false">/foo/bar/{$}</Pattern>
      </URIPath>
    </Collect>
  </Capture>
</DataCapture>

Este elemento tem os seguintes atributos comuns a todas as políticas:

Atributo Padrão Obrigatório? Descrição
name N/A Valor

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.
continueOnError falso Opcional Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado para a maioria das políticas. Defina como true para que a execução do fluxo continue, mesmo depois que uma política falhar. Consulte também:
enabled true Opcional Defina como true para aplicar a política. Defina como false para desativar a política. A política não será aplicada mesmo que permaneça vinculada a um fluxo.
async   falso Obsoleto Esse atributo está obsoleto.

A tabela a seguir fornece uma descrição de alto nível dos elementos filhos de <DataCapture>.

Elemento filho Obrigatório Descrição
<Capture> Obrigatório Captura os dados de uma variável especificada.

Exemplos

Os exemplos a seguir ilustram várias maneiras de usar a política DataCapture.

Como capturar dados para uma variável incorporada

O exemplo de código abaixo ilustra como capturar dados para uma variável incorporada, message.content, que contém o conteúdo da solicitação, da resposta ou da mensagem de erro. Consulte Variáveis de fluxo para obter mais informações sobre variáveis incorporadas.

<DataCapture name="DC-FullMessage">
    <Capture>
        <DataCollector>dc_data_collector</DataCollector>
        <Collect ref="message.content" />
    </Capture>
</DataCapture>

No código acima, o atributo ref do elemento </Collect> especifica a variável a ser capturada, que, neste exemplo, é chamada de "message.content".

A amostra captura os dados com um elemento <Capture>, que também contém um elemento <DataCollector> que especifica o nome do recurso do coletor de dados.

Como capturar dados in-line

O próximo exemplo mostra como capturar dados in-line usando <JSONPayload>, um elemento filho do elemento <Collect>.

<DataCapture name="DC-Currency">
    <Capture>
        <DataCollector>dc_data_collector<DataCollector>
        <Collect>
            <JSONPayload>
                <JSONPath>$.results[0].currency</JSONPath>
            </JSONPayload>
        </Collect>
    </Capture>
</DataCapture>

No código acima:

  • O elemento <JSONPayload> especifica a mensagem formatada em JSON da qual o valor da variável será extraído.
  • O elemento <JSONPath> especifica o caminho JSON usado para extrair o valor da mensagem, que neste caso é $.results[0].currency.

Para ilustrar, suponha que o valor extraído quando a mensagem foi recebida tenha sido 1120. Desse modo, a entrada resultante enviada ao Analytics seria

{
    "dc_data_collector": "1120"
}

<Capture>

O elemento <Capture> especifica os meios de captura dos dados.

<Capture />

A tabela a seguir fornece uma descrição de alto nível dos elementos filhos de <Capture>.

Elemento filho Obrigatório? Descrição
<DataCollector> Obrigatório Especifica o recurso Coletor de dados.
<Collect> Obrigatório Especifica os meios de captura dos dados.

<DataCollector>

O elemento <DataCollector> especifica o recurso coletor de dados.

<DataCollector>dc_data_collector</DataCollector>
 A tabela a seguir descreve os atributos do elemento <DataCollector>.
Atributo Descrição Padrão Obrigatório? Tipo
escopo

Especifique esse atributo e defina o valor como monetization se quiser capturar as variáveis de monetização. Para mais informações sobre as variáveis de monetização que você pode capturar, consulte Como capturar dados de monetização.

 N/A Opcional String

O corpo do elemento <DataCollector> contém o nome do recurso Coletor de dados.

<Collect>

O elemento <Collect> especifica os meios de captura dos dados.

<Collect ref="existing-variable" default="0"/>

A tabela a seguir descreve os atributos do elemento <Collect>.

Atributo Descrição Padrão Obrigatório? Tipo
ref

A variável para que você está capturando os dados.

 N/A Opcional: se ref for omitido, exatamente um dos itens a seguir precisa ser especificado: QueryParam, Header, FormParam e URIPath, JSONPayload ou XMLPayload. String
padrão Especifica o valor que será enviado ao Analytics caso o valor da variável não seja preenchido no ambiente de execução. Por exemplo, se você definir default="0", o valor enviado ao Analytics será 0. Se você não especificar o valor de default e o valor da variável não for preenchido no ambiente de execução, o valor enviado ao Analytics será null para uma variável numérica ou "Not set" para uma variável de string. Obrigatório String

É possível capturar os dados de uma variável atual usando o atributo ref ou pelos elementos filhos <Collect>.

Elementos filhos de <Collect>

A tabela a seguir fornece uma descrição de alto nível dos elementos filhos de <Collect>:

Elemento filho Obrigatório? Descrição
<Source> Opcional Especifica a variável a ser analisada.
<URIPath> Opcional Extrai um valor de proxy.pathsuffix de uma mensagem de origem request.
<QueryParam> Opcional Extrai um valor do parâmetro de consulta especificado de uma mensagem de origem request.
<Header> Opcional Extrai um valor do cabeçalho HTTP especificado da mensagem request ou response especificada.
<FormParam> Opcional Extrai um valor do parâmetro de formulário especificado da mensagem request ou response especificada.
<JSONPayload> Opcional Especifica a mensagem formatada em JSON da qual o valor da variável será extraído.
<XMLPayload> Opcional Especifica a mensagem em formato XML da qual o valor da variável será extraído.

<Source>

Especifica uma variável que nomeia a mensagem 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.

Se a variável especificada em <Source> não puder ser resolvida ou se for resolvida para um tipo que não seja de mensagem, a política não vai responder.

Valor padrão N/A
Obrigatório? Opcional
Tipo String
Elemento pai <Collect>
Elemento filho N/A 
<Source >request</Source>

<URIPath>

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 caminho base para o proxy de API. Se a mensagem de origem for resolvida como um tipo de mensagem de response, o elemento não fará nada.

Valor padrão N/A
Obrigatório? Opcional
Tipo Complexo
Elemento pai <Collect>
Elemento filho <pattern>

Atributos

Atributo Descrição Padrão Obrigatório? Tipo
ignoreCase Especifica para ignorar a correspondência de maiúsculas e minúsculas.

falso

 Opcional Booleano 
<Collect>
    <URIPath>
        <Pattern ignoreCase="false">/foo/{$}</Pattern>
    </URIPath>
</Collect>

É possível usar vários elementos <Pattern>:

<URIPath>
   <Pattern ignoreCase="false">/foo/{$}</Pattern>
   <Pattern ignoreCase="false">/foo/bar/{$}</Pattern>
</URIPath>

<QueryParam>

Extrai um valor do parâmetro de consulta especificado de uma mensagem de origem de request. Se a mensagem de origem for resolvida como um tipo de mensagem de response, o elemento não fará nada.

Valor padrão N/A
Obrigatório? Opcional
Tipo Complexo
Elemento pai <Collect>
Elemento filho <pattern>

Atributos

Atributo Descrição Padrão Obrigatório? 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 
<Collect>
    <QueryParam name="code">
        <Pattern ignoreCase="true">{$}</Pattern>
    </QueryParam>
</Collect>

Se vários parâmetros de consulta tiverem o mesmo nome, use índices para referenciar os parâmetros:

<Collect>
    <QueryParam name="code.2">
        <Pattern ignoreCase="true">{$}</Pattern>
    </QueryParam>
</Collect>

Observação: é necessário especificar uma única variável chamada {$}. Pode haver vários elementos Pattern exclusivos, mas o primeiro padrão correspondente será resolvido para uma solicitação específica.

<Header>

Extrai um valor do cabeçalho HTTP especificado da mensagem request ou response especificada. Se vários cabeçalhos tiverem o mesmo nome, os valores serão armazenados em uma matriz.

Valor padrão N/A
Obrigatório? Opcional
Tipo Complexo
Elemento pai <Collect>
Elemento filho <pattern>

Atributos

Atributo Descrição Padrão Obrigatório? 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 
<Collect>
    <Header name="my_header">
        <Pattern ignoreCase="false">Bearer {$}</Pattern>
    </Header>
</Collect>

Se vários cabeçalhos tiverem o mesmo nome, use índices para referenciar cabeçalhos individuais na matriz:

<Collect>
    <Header name="my_header.2">
        <Pattern ignoreCase="true">{$}</Pattern>
    </Header>
</Collect>

Ou o seguinte para listar todos os cabeçalhos na matriz:

<Collect>
    <Header name="my_header.values">
        <Pattern ignoreCase="true">{$}</Pattern>
    </Header>
</Collect>

<FormParam>

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.

Valor padrão N/A
Obrigatório? Opcional
Tipo Complexo
Elemento pai <Collect>
Elemento filho <pattern>

Atributos

Atributo Descrição Padrão Obrigatório? Tipo
name O nome do parâmetro de formulário do quem você extrai o valor.

N/A

 Opcional String 
<Collect>
    <FormParam name="greeting">
        <Pattern>hello {$}</Pattern>
    </FormParam>
</Collect>

<JSONPayload>

Especifica a mensagem formatada em JSON da qual o valor da variável será extraído. A extração de JSON é realizada somente quando o cabeçalho Content-Type da mensagem for application/json.

Valor padrão N/A
Obrigatório? Opcional
Tipo Complexo
Elemento pai <Collect>
Elemento filho <JSONPath> 
<Collect>
    <JSONPayload>
        <JSONPath>$.results[0].currency</JSONPath>
    </JSONPayload>
</Collect>

<JSONPath>

Elemento filho obrigatório do elemento <JSONPayload>. Especifica o caminho JSON usado para extrair um valor de uma mensagem formatada em JSON.

Valor padrão N/A
Obrigatório? Obrigatório
Tipo String
Elemento pai <JSONPayload>
Elemento filho N/A 
<JSONPath>$.rss.channel.title</JSONPath>

<XMLPayload>

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.

Valor padrão N/A
Obrigatório? Opcional
Tipo Complexo
Elemento pai <Collect>
Elemento filho <Namespaces>
<XPath>

A tabela a seguir fornece uma descrição de alto nível dos elementos filhos de <XMLPayload>.

Elemento filho Obrigatório? Descrição
<Namespaces> Opcional Especifica zero ou mais namespaces a serem usados na avaliação de XPath.
<XPath> Obrigatório Especifica o XPath definido para a variável. 
<Collect>
    <XMLPayload>
        <Namespaces>
            <Namespace prefix="soap">http://schemas.xmlsoap.org/soap/envelope/</Namespace>
            <Namespace prefix="ns1">http://ns1.example.com/operations</Namespace>
        </Namespaces>
        <!-- get the local name of the SOAP operation -->
        <XPath>local-name(/soap:Envelope/soap:Body/ns1:*[1])</XPath>
    </XMLPayload>
</Collect>

<Namespaces>

Especifica o conjunto de namespaces que podem ser usados na expressão XPath. Por exemplo:

<Collect>
    <XMLPayload>
        <Namespaces>
            <Namespace prefix="maps">http://maps.example.com</Namespace>
            <Namespace prefix="places">http://places.example.com</Namespace>
        </Namespaces>
        <XPath>/maps:Directions/maps:route/maps:leg/maps:endpoint/places:name</XPath>
    </XMLPayload>
</Collect>

Se você não estiver usando namespaces nas expressões XPath, omita ou comente o elemento <Namespaces>, como no exemplo a seguir:

<Collect>
    <XMLPayload>
        <!-- <Namespaces/> -->
        <XPath>/Directions/route/leg/name</XPath>
    </XMLPayload>
</Collect>

<Namespace>

Especifica um namespace e um prefixo correspondente para uso dentro da expressão XPath. Por exemplo:

Valor padrão N/A
Obrigatório? Opcional
Tipo String
Elemento pai <Namespaces>
Elemento filho N/A

Atributos

Atributo Descrição Padrão Obrigatório? Tipo
prefix

O prefixo que você usa para se referir ao namespace na expressão xpath. Ele não precisa ser o mesmo prefixo usado no documento XML original.

N/A

 Obrigatório String 
<Collect>
    <XMLPayload>
        <Namespaces>
            <Namespace prefix="maps">http://maps.example.com</Namespace>
        </Namespaces>
        <XPath>/maps:Directions/maps:route/maps:leg/maps:endpoint</XPath>
    </XMLPayload>
</Collect>

<XPath>

Elemento filho obrigatório do elemento XMLPayload. Especifica o XPath definido para a variável. Somente expressões XPath 1.0 são compatíveis.

Valor padrão N/A
Obrigatório? Obrigatório
Tipo String
Elemento pai <XMLPayload>
Elemento filho N/A 
   <XPath>/test/example</XPath>

Observação: se você usar namespaces nas suas expressões XPath, declare os namespaces na seção <XMLPayload><Namespaces>da política.

<ThrowExceptionOnLimit>

O elemento <ThrowExceptionOnLimit> especifica o que acontece quando os limites de captura sobre o número de variáveis ou o tamanho máximo de uma variável são atingidos. Consulte Como aplicar limites de captura.

O valor de <ThrowExceptionOnLimit> pode ser um dos seguintes:

  • false: os dados das variáveis são enviados ao Google Analytics.
  • true: uma mensagem de erro é retornada, e os dados não são enviados ao Google Analytics.

Referência de erros

Erros de execução

A tabela abaixo descreve os erros no ambiente de execução, que podem ocorrer ao executar a política.

Código de falha Causa
DataCollectorTypeMismatch

O valor a ser capturado não corresponde ao tipo DataCollector.
ExtractionFailure Falha na extração de dados.
UnresolvedVariable A variável não existe.
VariableCountLimitExceeded O número de variáveis capturadas excedeu o limite de 100 variáveis.
VariableValueLimitExceeded O tamanho de um valor capturado excedeu o limite de 400 bytes.
MsgContentParsingFailed Não foi possível analisar o conteúdo da mensagem em XML ou JSON.
InvalidMsgContentType O tipo de conteúdo da mensagem não corresponde ao tipo de conteúdo esperado na cláusula de captura de políticas.
NonMsgVariable O valor do elemento <Source> não fazia referência a uma variável de mensagem.
JSONPathQueryFailed A consulta JSONPath falhou na resolução de um valor.
PrivateVariableAccess Falha ao tentar acessar uma variável particular.
XPathEvaluationFailed Falha na resolução de um valor para XPath.

Os erros no ambiente de execução são retornados de duas maneiras:

  • Resposta de erro para o cliente (continueOnError=false)

    Se o atributo continueOnError da política estiver definido como false, os erros que ocorrerem durante a execução da política cancelarão o processamento da mensagem e retornarão uma mensagem de erro descritiva. A política tentará capturar todos os erros relevantes na política de captura de dados antes de retornar a mensagem.

  • DataCapture campo de análise de erros

    O campo dataCapturePolicyErrors contém uma lista de todos os erros que ocorreram. Veja abaixo um exemplo de como isso apareceria no mapa de dados do Analytics:

    # Example payload
[
     {
         errorType: TypeMismatch,
         policyName: MyDataCapturePolicy-1,
         dataCollector: purchaseValue
     },
     {
         errorType: MaxValueSizeLimitReached,
         policyName: MyDataCapturePolicy-1,
         dataCollector: purchasedItems
     },
]

Este campo está sujeito ao limite de tamanho da variável de 400 bytes.

Erros na implantação

Código de falha Causa
DeploymentAssertionError O DataCollector referido na política não foi encontrado na organização durante a implantação.
JsonPathCompilationFailed Falha ao compilar com o JSONPath especificado.
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á.
PatternCompilationFailed Falha na compilação do padrão.

Como encontrar erros DataCapture na ferramenta de depuração

A variável dataCapturePolicyErrors está disponível na ferramenta de depuração. Essa é uma ferramenta adicional que pode ser usada para identificar erros sem acessar o Analytics. Por exemplo, é possível capturar um erro que ocorre quando você faz upgrade da versão do ambiente de execução híbrido e interrompe inadvertidamente o Analytics em um proxy já implantado.

Como aplicar limites de captura

A Apigee aplica os seguintes limites às variáveis nos dados capturados:

  • O número permitido de variáveis é 100.
  • O tamanho máximo de cada variável (incluindo valores de lista) é de 400 bytes.

Quando a execução da política de captura de dados, antes de um valor ser adicionado ao mapa de captura de dados no contexto da mensagem:

  • Se o limite de número de variáveis for atingido, a nova variável será descartada.
  • Se o limite de tamanho das variáveis for atingido, o valor será cortado para se ajustar aos limites desejados.

Nos dois casos:

  • Uma mensagem de depuração será exibida no registro do processador de mensagens.
  • Uma mensagem de erro limit reached será anexada ao arquivo dataCapturePolicyErrors, disponível no Analytics e no Debug. Observação: somente uma mensagem de erro será atingida se o número máximo de variáveis permitidas for anexado.
  • Se <ThrowExceptionOnLimit> for true, os dados não serão enviados ao Google Analytics e, em vez disso, um erro será retornado ao cliente.

Temas relacionados