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

Você está lendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. info

O Edge API Analytics coleta e analisa uma grande variedade de informações estatísticas de cada solicitação de API e resposta. Essas informações são coletadas automaticamente e podem ser exibidas na interface do Edge ou usando a API Metrics. Consulte métricas 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, demonstramos como usar a política StatisticsCollector para extrair dados de análise personalizados de uma solicitação de API/resposta e alimentar esses dados no Edge API Analytics. Em seguida, mostramos como visualizar os dados de análise em um relatório na interface do Edge ou usando a API Edge.

Sobre a API Google Books

Neste tópico, descrevemos como capturar dados personalizados de análise de solicitações de proxy de API para a API Google Livros. 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 Books

Antes de coletar estatísticas para a API Google Books, você precisa criar um proxy de API Edge que a chame. Depois, você invoca esse proxy de API para fazer as solicitações à API Google Books.

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 Books. Na etapa 5 do procedimento, ao criar o proxy de API, defina as seguintes propriedades para fazer referência à API Google Livros:

  • 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. 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 do interesse e grave-os em uma variável.

    Todos os dados transmitidos ao Edge API Analytics vêm de valores armazenados em variáveis. Alguns dados são armazenados automaticamente nas 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 Edge API Analytics.

    Use a política Statistics Collector para gravar dados de uma variável no Edge API Analytics. Os dados podem vir de variáveis de fluxo predefinidas do Edge , ou de variáveis criadas pela política Extract Variables.

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

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

Os dados de análises precisam ser extraídos e armazenados em uma variável, seja uma variável de fluxo predefinida pelo Edge ou uma variável personalizada que você definir, 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 da pesquisa JSON da API Google Books, 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 foi avaliado, a política Extract Variables grava 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 essa política ao seu proxy de API na interface do Edge. Se você estiver criando o proxy de 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 Statistics Collector para gravar dados no serviço de análise

Use a política StatisticsCollector para gravar dados de uma variável no Edge API Analytics. A política Statistics Collector tem o seguinte formato:

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

em que:

  • 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 pode ser uma variável personalizada criada pela política Extract Variables.

  • dataType especifica o tipo de dados das informações registradas como string, número inteiro, flutuante, longo, duplo ou booleano.

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

  • defValue opcionalmente, forneça um valor padrão para uma variável personalizada, que é enviada ao API Analytics se as variáveis não puderem ser resolvidas ou se a variável for indefinida.

No exemplo abaixo, você usa a política Statistics Collector para coletar dados das variáveis criadas pela política Extract Variables. Você também coleta o valor do parâmetro de consulta transmitido a cada chamada de API. Faça referência aos parâmetros de consulta usando a variável de fluxo predefinida flow variable:

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 seu proxy de API na interface do Edge ou, se você estiver criando o proxy da 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 de API no local apropriado. Nesse caso de uso, as políticas precisam ser executadas depois que a resposta foi recebida da API Google Books e antes do envio da resposta 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 de 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:

  • A interface do Edge é compatível com relatórios personalizados que permitem visualizar 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 com qualquer uma das métricas 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 usando a 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.

    Edge clássico (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 Análise > 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 string que você criou 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 exibição da data no canto superior direito para abrir o pop-up do Seletor de datas.

  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 Metrics do Edge para ver 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 métricas 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 período 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 Metrics 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 que você crie variáveis de análise personalizadas por meio de uma caixa de diálogo da interface de gerenciamento fácil de usar.

Leia a seção anterior Coleta de dados de análise personalizados, que explica como as políticas Extrair variáveis e Coletor de estatísticas funcionam juntas para alimentar variáveis personalizadas no Edge API Analytics. Como você verá, a interface segue esse mesmo padrão, mas é uma maneira conveniente de configurar tudo por meio da interface. 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 de API para você. As políticas extraem variáveis de interesse de solicitações ou respostas e as transmitem para o Edge API 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 seu 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 de API você quer anexar as políticas Extract Variables e 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 de API no local apropriado. É necessário anexar as políticas em um estágio do fluxo em que as variáveis que estão sendo coletadas estão no escopo (preenchido).
  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.