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

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X.
informações

O Edge API Analytics coleta e analisa uma grande variedade de informações estatísticas de cada solicitação e resposta da API. Essas informações são coletadas automaticamente e podem ser exibidas na interface do Edge ou usando a API de métricas. Consulte metrics e dimensão para mais informações sobre essas estatísticas.

Talvez você também queira coletar dados de análise personalizados específicos para seus proxies, aplicativos, produtos ou desenvolvedores de API. Por exemplo, talvez você queira coletar dados de parâmetros de consulta, cabeçalhos de solicitação, corpos de solicitação e resposta ou variáveis definidas nas suas APIs.

Neste tópico, mostramos como usar a política Statisticscollector para extrair dados de análise personalizados de uma solicitação/resposta de API e alimentar esses dados para o Analytics da API Edge. Em seguida, ele mostra como visualizar seus dados de análise em um relatório na interface do Edge ou usando a API Edge.

Sobre a API Google Book

Neste tópico, descrevemos como capturar dados personalizados de análises de solicitações de proxy da API para a API Google Books. A API Google Books permite que você pesquise livros por título, assunto, autor e outras características.

Por exemplo, faça solicitações ao endpoint /volumes para realizar uma pesquisa por título do livro. Transmita um único parâmetro de consulta à API Books que contém o título do livro:

curl https://www.googleapis.com/books/v1/volumes?q=davinci%20code

A chamada retorna uma matriz JSON de itens encontrados que correspondem aos critérios de pesquisa. Veja abaixo o primeiro elemento da matriz na resposta. Observe que parte do conteúdo foi omitida para simplificar:

{
 "kind": "books#volumes",
 "totalItems": 1799,
 "items": [
  {
   "kind": "books#volume",
   "id": "ohZ1wcYifLsC",
   "etag": "4rzIsMdBMYM",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/ohZ1wcYifLsC",
   "volumeInfo": {
    "title": "The Da Vinci Code",
    "subtitle": "Featuring Robert Langdon",
    "authors": [
     "Dan Brown"
    ],
    "publisher": "Anchor",
    "publishedDate": "2003-03-18",
    "description": "MORE THAN 80 MILLION COPIES SOLD ....",
    "industryIdentifiers": [
     {
      "type": "ISBN_10",
      "identifier": "0385504217"
     },
     {
      "type": "ISBN_13",
      "identifier": "9780385504218"
     }
    ],
    "readingModes": {
     "text": true,
     "image": true
    },
    "pageCount": 400,
    "printType": "BOOK",
    "categories": [
     "Fiction"
    ],
    "averageRating": 4.0,
    "ratingsCount": 710,
    "maturityRating": "NOT_MATURE",
    "allowAnonLogging": true,
    "contentVersion": "0.18.13.0.preview.3",
    "panelizationSummary": {
     "containsEpubBubbles": false,
     "containsImageBubbles": false
    },
...
   "accessInfo": {
    "country": "US",
    "viewability": "PARTIAL",
    "embeddable": true,
    "publicDomain": false,
    "textToSpeechPermission": "ALLOWED_FOR_ACCESSIBILITY",
    "epub": {
     "isAvailable": true,
     "acsTokenLink": "link"
    },
    "pdf": {
     "isAvailable": true,
     "acsTokenLink": "link"
    },
...
   }
  }

Veja que várias áreas da resposta foram destacadas:

  • Número de resultados da pesquisa
  • Classificação média dos livros
  • Número de avaliações
  • Disponibilidade de versões em PDF do livro

As seções a seguir descrevem como coletar estatísticas para essas áreas da resposta e também para o parâmetro de consulta, q, que contém os critérios de pesquisa.

Criar um proxy de API para a API Google Book

Antes de coletar estatísticas para a API Google Book, crie um proxy da API Edge para a chamar. Depois, você invoca esse proxy de API para fazer solicitações à API Google Book.

A Etapa 2: criar um proxy de API do tutorial sobre como criar um proxy de API descreve como criar um proxy que chama a API https://mocktarget.apigee.net. Observe que o proxy descrito nesse tutorial não requer uma chave de API para chamá-lo.

Use o mesmo procedimento para criar um proxy de API para o endpoint /volumes da API Google Book. Na etapa 5 do procedimento, ao criar o proxy da API, defina as seguintes propriedades para fazer referência à API Google Books:

  • Nome do proxy: "mybooksearch"
  • Caminho base do proxy: "/mybooksearch"
  • API existente: "https://www.googleapis.com/books/v1/volumes"

Depois de criar e implantar o proxy, você poderá chamá-lo usando um comando curl no formulário:

curl http://org_name-env_name.apigee.net/mybooksearch?q=davinci%20code

em que org_name e env_name especificam a organização e o ambiente em que você implantou o proxy. Por exemplo:

curl http://myorg-test.apigee.net/mybooksearch?q=davinci%20code

Colete dados de análise personalizados

A coleta de dados de análise de uma solicitação de API é um procedimento de duas etapas:

  1. Extraia os dados de interesse e grave-os em uma variável.

    Todos os dados transmitidos para o Analytics da API Edge vêm de valores armazenados em variáveis. Alguns dados são armazenados automaticamente em variáveis de fluxo predefinidas do Edge, como os valores dos parâmetros de consulta transmitidos ao proxy de API. Consulte a Visão geral das variáveis de fluxo para saber mais sobre elas.

    Use a política Extract Variables para extrair o conteúdo personalizado de uma solicitação ou resposta e gravar esses dados em uma variável.

  2. Gravar dados de uma variável no Analytics da API Edge.

    Use a política do Coletor de estatísticas para gravar dados de uma variável no Analytics da API Edge. Os dados podem vir de variáveis de fluxo predefinidas do Edge ou variáveis criadas pela política "Extrair variáveis".

Depois de coletar os dados estatísticos, use a API ou a IU de gerenciamento do Edge para recuperar e filtrar as estatísticas. Por exemplo, você pode gerar um relatório personalizado que mostra a classificação média de cada título de livro, em que o título corresponde ao valor do parâmetro de consulta transmitido à API.

Use a política Extract Variables para extrair dados de análise

Os dados do Google Analytics precisam ser extraídos e armazenados para uma variável, seja uma variável de fluxo predefinida pelo Edge ou variáveis personalizadas definidas por você, antes de serem transmitidas para a API Analytics. Para gravar dados em uma variável, use a política Extract Variables.

Essa política pode analisar payloads de mensagens com expressões JSONPath ou XPath. Para extrair as informações dos resultados de pesquisa JSON da API Google Book, use uma expressão JSONPath. Por exemplo, para extrair o valor de averageRating do primeiro item na matriz de resultados JSON, a expressão JSONPath é:

$.items[0].volumeInfo.averageRating

Depois que o JSONPath for avaliado, a política "Extract Variables" vai gravar o valor extraído em uma variável.

Neste exemplo, essa política é usada para criar quatro variáveis:

  • responsejson.totalitems
  • responsejson.ratingscount
  • responsejson.avgrating
  • responsejson.pdf

Para essas variáveis, responsejson é a variável prefix e totalitems, ratingscount, avgrating e pdf são a variável names.

A política Extract Variables abaixo mostra como extrair dados da resposta JSON e gravá-los em variáveis personalizadas. Cada elemento <Variable> usa o atributo name que especifica o nome das variáveis personalizadas e a expressão JSONPath associada. O elemento <VariablePrefix> especifica o prefixo da variável.

Adicione esta política ao proxy de API na interface do Edge. Se você estiver criando o proxy da API em XML, adicione a política a um arquivo em /apiproxy/policies chamado ExtractVars.xml:

<ExtractVariables name="ExtractVars">
    <Source>response</Source>
    <JSONPayload>
        <Variable name="totalitems">
            <JSONPath>$.totalItems</JSONPath>
        </Variable>
        <Variable name="ratingscount">
            <JSONPath>$.items[0].volumeInfo.ratingsCount</JSONPath>
        </Variable>
        <Variable name="avgrating">
            <JSONPath>$.items[0].volumeInfo.averageRating</JSONPath>
        </Variable>
        <Variable name="pdf">
            <JSONPath>$.items[0].accessInfo.pdf.isAvailable</JSONPath>
        </Variable>
    </JSONPayload>
    <VariablePrefix>responsejson</VariablePrefix>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Usar a política de coletor de estatísticas para gravar dados no serviço de análise

Use a política do Coletor de estatísticas para gravar dados de uma variável no Analytics da API Edge. A política de coletor de estatísticas tem a seguinte forma:

<StatisticsCollector>
<DisplayName>Statistics Collector-1</DisplayName>
    <Statistics>
        <Statistic name="statName" ref="varName" type="dataType">defVal</Statistic>
       …
    </Statistics>
</StatisticsCollector>

onde:

  • statName especifica o nome usado para referenciar os dados estatísticos em um relatório personalizado.
  • varName especifica o nome da variável que contém os dados de análise a serem coletados. Essa variável pode ser integrada ao Edge ou ser uma variável personalizada criada pela política "Extrair variáveis".
  • dataType especifica o tipo dos dados gravados como string, número inteiro, flutuante, longo, duplo ou booleano.

    Para dados do tipo string, faça referência aos dados estatísticos como uma dimensão em um relatório personalizado. Para tipos de dados numéricos (número inteiro/flutuante/longo/duplo), você faz referência aos dados estatísticos como uma dimensão ou uma métrica em um relatório personalizado.

  • defValue também fornece um valor padrão para uma variável personalizada, que será enviada ao API Analytics se não for possível resolver as variáveis ou se a variável estiver indefinida.

No exemplo abaixo, você usa a política do coletor de estatísticas para coletar dados das variáveis criadas pela política de extração de variáveis. Você também coleta o valor do parâmetro de consulta transmitido para cada chamada de API. Consulte os parâmetros de consulta usando a variável de fluxo predefinida:

request.queryparam.queryParamName

Para o parâmetro de consulta chamado "q", faça referência a ele como:

request.queryparam.q

Adicione essa política ao proxy de API na interface do Edge ou, se você estiver criando o proxy de API em XML, adicione um arquivo em /apiproxy/policies chamado AnalyzeBookResults.xml, com o seguinte conteúdo:

<StatisticsCollector name="AnalyzeBookResults">
 <Statistics>
        <Statistic name="totalitems" ref="responsejson.totalitems" type="integer">0</Statistic>
        <Statistic name="ratingscount" ref="responsejson.ratingscount" type="integer">0</Statistic>
        <Statistic name="avgrating" ref="responsejson.avgrating" type="float">0.0</Statistic>
        <Statistic name="pdf" ref="responsejson.pdf" type="boolean">true</Statistic>
        <Statistic name="booktitle" ref="request.queryparam.q" type="string">none</Statistic>
 </Statistics>
</StatisticsCollector>

Anexe políticas ao fluxo de resposta ProxyEndpoint

Para que tudo funcione corretamente, as políticas devem ser anexadas ao fluxo do proxy da API no local apropriado. Nesse caso de uso, as políticas precisam ser executadas depois que a resposta for recebida da API Google Book e antes que a resposta seja enviada ao cliente solicitante. Portanto, anexe as políticas à resposta ProxyEndpoint de PreFlow.

A configuração do ProxyEndpoint de exemplo abaixo executa primeiro a política chamada ExtractVars para analisar a mensagem de resposta. Em seguida, a política chamada AnalyzeBookResults encaminha esses valores para a análise da API:

<ProxyEndpoint name="default">
    ><PreFlow name="PreFlow">
        <Request/>
        <Response>
            <Step>
                <Name>Extract-Vars</Name>
            </Step>
            <Step>
                <Name>AnalyzeBookResults</Name>
            </Step>
        </Response>
    </PreFlow>
 <HTTPProxyConnection>
  <!-- Base path used to route inbound requests to this API proxy -->
  <BasePath>/mybooksearch</BasePath>
  <!-- The named virtual host that defines the base URL for requests to this proxy -->
  <VirtualHost>default</VirtualHost>
 </HTTPProxyConnection>
 <RouteRule name="default">
 <!-- Connects the proxy to the target defined under /targets -->
  <TargetEndpoint>default</TargetEndpoint>
 </RouteRule>
</ProxyEndpoint>

Implante o proxy de API

Depois de fazer essas alterações, será necessário implantar o proxy da API que você configurou.

Preencher dados de análise

Depois de implantar o proxy de API, chame-o para preencher os dados nas análises da API. Para fazer isso, execute os seguintes comandos, cada um com um título de livro diferente:

Mobey Dick:

curl https://org_name-env_name.apigee.net/mybooksearch?q=mobey%20dick

O código Da Vinci:

curl https://org_name-env_name.apigee.net/mybooksearch?q=davinci%20code 

Garota Exemplar:

curl https://org_name-env_name.apigee.net/mybooksearch?q=gone%20girl  

Game of Thrones:

curl https://org_name-env_name.apigee.net/mybooksearch?q=game%20of%20thrones   

Ver dados de análise

O Edge oferece duas maneiras de visualizar seus dados de análise personalizados:

  • Na interface do Edge, você pode gerar relatórios personalizados que permitem ver os dados em um gráfico.
  • A API Metrics permite recuperar dados de análise fazendo chamadas REST para a API Edge. É possível usar a API para criar suas próprias visualizações na forma de widgets personalizados que você pode incorporar em portais ou aplicativos personalizados.

Gerar um relatório de estatísticas usando a interface do Edge

Os relatórios personalizados permitem que você detalhe estatísticas específicas da API para visualizar os dados exatos que quer ver. É possível criar um relatório personalizado usando qualquer uma das metrics e dimensões integradas ao Edge. Além disso, é possível usar qualquer um dos dados de análise extraídos com a política StatisticsCollector.

Ao criar uma política Statistics Collector, você especifica o tipo de dados das informações coletadas. Para o tipo de dados de string, faça referência aos dados estatísticos como uma dimensão em um relatório personalizado. Para tipos de dados numéricos (inteiro/flutuante/longo/duplo), referencie os dados estatísticos de um relatório personalizado como uma dimensão ou métrica. Consulte Gerenciar relatórios personalizados para saber mais.

Como gerar um relatório personalizado usando a interface do Edge:

  1. Acesse a página "Relatórios personalizados", conforme descrito abaixo.

    Edge

    Para acessar a página "Relatórios personalizados" pela interface do Edge:

    1. Faça login em apigee.com/edge.
    2. Selecione Analisar > Relatórios personalizados > Relatórios na barra de navegação à esquerda.

    Borda clássica (nuvem privada)

    Para acessar a página "Relatórios personalizados" usando a interface clássica do Edge:

    1. Faça login em http://ms-ip:9000, em que ms-ip é o endereço IP ou o nome DNS do nó do servidor de gerenciamento.
    2. Selecione Analytics > Relatórios na barra de navegação superior.

  2. Na página "Relatórios personalizados", clique em + Relatório personalizado.
  3. Especifique um Nome do relatório, como mybookreport.
  4. Selecione uma Métrica integrada, como Tráfego, e uma Função de agregação, como Soma.

    Ou então, selecione uma das estatísticas de dados numéricos que você criou usando a política StatisticsCollector. Por exemplo, selecione ratingscount e uma Função de agregação de Soma.

  5. Selecione uma Dimensão integrada, como Proxy de API, ou qualquer uma das estatísticas numéricas ou de strings criadas usando a política Statisticscollector.

    Por exemplo, selecione booktitle. Agora seu relatório exibirá a soma de ratingscount por booktitle:

    relatório de livros personalizado
  6. Selecione Salvar. O relatório aparece na lista de todos os relatórios personalizados.
  7. Para gerar o relatório, selecione o nome dele. Por padrão, o relatório mostra dados da última hora.

  8. Para definir o período, selecione a data no canto superior direito e abra o pop-up Seletor de data.
  9. Selecione Últimos 7 dias. O relatório é atualizado para mostrar a soma das avaliações por título do livro:

    Gráfico do relatório de livros

Receber estatísticas usando a API Edge

Use a API de métricas do Edge para gerar estatísticas sobre seus dados de análise personalizados. No exemplo de solicitação abaixo:

  • O recurso para o URL após /stats especifica a dimensão desejada. Neste exemplo, você recebe dados para a dimensão booktitle.
  • O parâmetro de consulta select para especificar as metrics a serem recuperadas. Essa solicitação retorna análises com base na soma do ratingscount.
  • O parâmetro timeRange especifica o intervalo de tempo para os dados retornados. O intervalo de tempo está no formato:

    MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM

A chamada de API completa é:

curl -X GET "https://api.enterprise.apigee.com/v1/organizations/org_name/environments/env_name/stats/booktitle?select=sum(ratingscount)&timeRange=04/21/2019&2014:00:00~04/22/2019&2014:00:00" /
-u email:password

Você verá uma resposta no formato:

{
  "environments": [
    {
      "dimensions": [
        {
          "metrics": [
            {
              "name": "sum(ratingscount)",
              "values": [
                "5352.0"
              ]
            }
          ],
          "name": "gone girl"
        },
        {
          "metrics": [
            {
              "name": "sum(ratingscount)",
              "values": [
                "4260.0"
              ]
            }
          ],
          "name": "davinci code"
        },
        {
          "metrics": [
            {
              "name": "sum(ratingscount)",
              "values": [
                "1836.0"
              ]
            }
          ],
          "name": "game of thrones"
        },
        {
          "metrics": [
            {
              "name": "sum(ratingscount)",
              "values": [
                "1812.0"
              ]
            }
          ],
          "name": "mobey dick"
        }
      ],
      "name": "prod"
    }
  ],
  "metaData": {
    "errors": [],
    "notices": [
      "query served by:9b372dd0-ed30-4502-8753-73a6b09cc028",
      "Table used: uap-prod-gcp-us-west1.edge.edge_api_raxgroup021_fact",
      "Source:Big Query"
    ]
  }
}

A API de métricas do Edge tem muitas opções. Por exemplo, você pode classificar os resultados em ordem crescente ou decrescente. No exemplo a seguir, a ordem crescente é usada:

curl -X GET "https://api.enterprise.apigee.com/v1/organizations/org_name/environments/env_name/stats/booktitle?select=sum(ratingscount)&timeRange=04/21/2019&2014:00:00~04/22/2019&2014:00:00&sort=ASC" /
-u email:password

Os resultados também podem ser filtrados especificando os valores das dimensões de interesse. No exemplo abaixo, o relatório é filtrado por resultados para "Garota exemplar" e "O código Da Vinci":

$ curl -X GET "https://api.enterprise.apigee.com/v1/organizations/org_name/environments/env_name/stats/booktitle?select=sum(ratingscount)&timeRange=04/21/2019&2014:00:00~04/22/2019&2014:00:00&filter=(booktitle%20in%20'gone%20girl'%2C%20'davinci%20code')" /
-u email:password

Como criar variáveis de análise personalizadas com o Solution Builder

O Solution Builder permite criar variáveis de análise personalizadas por meio de uma caixa de diálogo da interface de gerenciamento fácil de usar.

Confira a seção anterior Coletar dados personalizados de análise, que explica como as políticas de extração de variáveis e o coletor de estatísticas funcionam lado a lado para alimentar as variáveis personalizadas com a API Edge. Como você verá, a IU segue esse mesmo padrão, mas é uma maneira conveniente de configurar tudo por meio da IU. Se você quiser, teste o exemplo da API Google Books usando a IU em vez de editar e anexar políticas manualmente.

A caixa de diálogo do Solution Builder permite que você configure variáveis de análise diretamente na IU. Essa ferramenta gera políticas e as anexa ao proxy da API para você. As políticas extraem variáveis de interesse de solicitações ou respostas e transmitem as variáveis extraídas para a API Edge Analytics.

O Solution Builder cria novas políticas de Extract Variables e Statistics Collector e atribui nomes exclusivos a elas. O Solution Builder não permite que você volte e altere essas políticas após a criação em uma determinada revisão de proxy. Para fazer alterações, edite as políticas geradas diretamente no editor.

  1. Acesse a página "Visão geral" do proxy na interface do Edge.
  2. Clique em Desenvolver.
  3. Na página "Desenvolver", selecione Conjunto de análises personalizadas no menu "Ferramentas". A caixa de diálogo "Solution Builder" é exibida.
  4. Na caixa de diálogo do Solution Builder, primeiro configure duas políticas: Extract Variables e Statistics Collector. Depois, configure onde anexar essas políticas.
  5. Especifique os dados que você quer extrair:
    • Tipo de local: selecione o tipo de dado que você quer coletar e de onde coletar. Você pode selecionar dados do lado da solicitação ou da resposta. Por exemplo, Solicitação: Parâmetro de consulta ou resposta: corpo XML.
    • Origem do local: identifique os dados que você quer coletar. Por exemplo, o nome do parâmetro de consulta ou o XPath para dados XML no corpo da resposta.
  6. Especifique um nome (e tipo) de variável que a política Statistics Collector usará para identificar os dados extraídos. Veja as restrições de nomenclatura neste tópico.

    O nome usado aparecerá no menu suspenso de Dimensões ou Métricas na IU do Criador de relatórios personalizados.
  7. Escolha em que fluxo do proxy da API você quer anexar as políticas Extract Variables and Statistics Collector geradas. Para orientações, consulte "Anexar políticas ao fluxo de resposta ProxyEndpoint". Para que tudo funcione corretamente, as políticas devem ser anexadas ao fluxo do proxy da API no local apropriado. É necessário anexar as políticas em uma etapa do fluxo em que as variáveis que você está armazenando estejam no escopo (preenchidas).
  8. Clique em + Coletor para adicionar mais variáveis personalizadas.
  9. Quando terminar, clique em Criar solução.

  10. Salve e implante o proxy.

Agora, você pode gerar um relatório personalizado para os dados conforme descrito acima.