Política DataCapture

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

Confira a documentação da Apigee Edge.

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:

• O elemento <DataCollector>, que especifica um recurso REST do coletor de dados. Neste caso, o recurso é chamado de dc_data_collector.
• O elemento <Collect>, que especifica os meios de captura dos dados.

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:

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

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

<DataCollector>

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

<DataCollector>dc_data_collector</DataCollector>

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

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

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

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

Atributos

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

Atributos

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

Atributos

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

Atributos

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

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

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

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

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

Atributos

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

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

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

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

• Política ExtractVariables