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

O Apigee 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 IU da Apigee 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 StatisticsCollect para extrair dados de análise personalizados de uma solicitação/resposta de API e alimentar esses dados no Apigee Analytics. Em seguida, mostramos como visualizar os dados de análise em um relatório na IU da Apigee ou usando a API Apigee.

Sobre a API Google Books

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.

Crie 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 Apigee 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 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. 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 Apigee Analytics vêm de valores armazenados em variáveis. Alguns dados são armazenados automaticamente nas variáveis de fluxo predefinidas da Apigee, como os valores dos parâmetros de consulta transmitidos ao proxy da 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 Apigee Analytics.

    Use a política StatisticsCollector para gravar dados de uma variável no Apigee Analytics. Os dados podem vir de variáveis de fluxo predefinidas da Apigee ou de variáveis criadas pela política Extract Variables.

Depois de coletar os dados estatísticos, use a IU ou a API da Apigee 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 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 de análises precisam ser extraídos e armazenados em uma variável, seja uma variável de fluxo predefinida pela Apigee 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 IU da Apigee. 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>

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

Visualizar dados de análise

A Apigee oferece duas maneiras de visualizar os dados de análise personalizados:

  • A IU da Apigee é 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 Apigee. É 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 IU da Apigee

Os relatórios personalizados permitem que você detalhe estatísticas específicas da API para visualizar os dados exatos que quer ver. Os relatórios personalizados podem incluir qualquer uma das métricas e dimensões incorporadas à Apigee. 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 IU da Apigee:

Para acessar a página de relatórios personalizados usando a IU do Apigee:

  1. Faça login na IU da Apigee.
  2. Selecione Analisar > Relatórios personalizados > Relatórios na barra de navegação à esquerda.
  3. Na página "Relatórios personalizados", clique em + Relatório personalizado.
  4. Especifique um Nome do relatório, como mybookreport.
  5. 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.

  6. 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
  7. Selecione Salvar. O relatório aparece na lista de todos os relatórios personalizados.
  8. Para gerar o relatório, selecione o nome dele. Por padrão, o relatório mostra dados da última hora.

  9. Para definir o período, selecione a exibição da data no canto superior direito para abrir o pop-up do Seletor de datas.
  10. 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 Apigee

Use a API Metrics da Apigee 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 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:BigQuery"
    ]
  }
}

A API Metrics da Apigee 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 IU da Apigee fácil de usar.

Leia a seção anterior Colete dados de análises personalizados, que explica como as políticas Extract Variables e Statistics Collector funcionam juntas para fornecer as variáveis personalizadas ao Apigee Analytics. 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 as transmitem para o Apigee 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 IU da Apigee.
  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 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.