Esta página foi traduzida pela API Cloud Translation.

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

Esta é a documentação do Apigee Edge.
Acesse 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 no 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.

Este tópico demonstra como usar a política StatisticsCollector para extrair dados de análise personalizados de uma solicitação/resposta de API e enviar esses dados à análise da API Edge. Em seguida, ele mostra como visualizar os dados de análise em um relatório na IU 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.

Crie um proxy de API para a API Google Book

Antes de coletar estatísticas para a API Google Book, é preciso criar um proxy da API Edge que o chama. Em seguida, você invoca esse proxy de API para fazer suas 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 a 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. 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:

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

Todos os dados transmitidos à API Edge API Analytics vêm de valores armazenados em variáveis. Alguns dados são armazenados automaticamente em variáveis flow predefinidas do Edge, como as valores dos parâmetros de consulta passados para o 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.
Gravar dados de uma variável na análise da API Edge.

Usar a política do Coletor de estatísticas para gravar dados de uma variável na análise da API Edge. Os dados podem vir de bancos de dados predefinidos, Variáveis de fluxo de borda, ou variáveis criadas pela política "Extrair variáveis".

Depois de coletar os dados estatísticos, use a interface ou a API de gerenciamento de borda 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 do Google Analytics precisam ser extraídos e armazenados para uma variável, uma variável de fluxo predefinida por Variáveis personalizadas ou de borda que você define 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 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 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 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 do Coletor de estatísticas para gravar dados no serviço do Analytics

Usar a política do Coletor de estatísticas para gravar dados de uma variável na análise da API Edge. A política de coletor de estatísticas 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 que você usa para fazer referência aos 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 personalizada criada pela política "Extrair variáveis".
dataType especifica o tipo dos dados registrados 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 (inteiro/flutuante/longo/duplo), faça referência ao dados estatísticos como uma dimensão ou uma métrica em um relatório personalizado.
defValue opcionalmente fornece um valor padrão para uma variável personalizada, que é enviada para API Analytics se as variáveis não puderem ser resolvidas ou se a variável estiver indefinida.

No exemplo abaixo, você usa a política do Coletor de estatísticas para coletar dados para as variáveis criada pela política "Extrair variáveis". Você também coleta o valor do parâmetro de consulta transmitido para cada chamada de API. Faça referência aos parâmetros de consulta usando o variável de fluxo:

request.queryparam.queryParamName

Para o parâmetro de consulta chamado "q" referencie-o 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 dados de análise personalizados:

A interface do Edge é compatível com relatórios personalizados que permitem visualizar seus dados em um gráfico.
A API Metrics permite recuperar dados de análise fazendo chamadas REST para o 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.

Observação:

Leva cerca de 30 minutos para que uma nova dimensão personalizada seja adicionada ao banco de dados depois que a política Statistics Collector é invocada pela primeira vez, para cada ambiente. Por exemplo, se um proxy do coletor de estatísticas for invocado no ambiente test , os dados dessa dimensão personalizada começarão a ser disponibilizados no ambiente test 30 minutos depois, e a dimensão personalizada aparecerá na lista suspensa Dimensões de relatórios personalizados.

Se esse proxy de Statistics Collector for chamado a partir do ambiente prod, levará cerca de 30 minutos para que os dados dessa dimensão personalizada comecem a ser disponibilizados no ambiente prod. A partir desse momento, os dados estarão disponíveis depois do mesmo intervalo de tempo que outras dimensões.

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 métricas e dimensão 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.

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

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)

Observação:a interface clássica do Edge está disponível apenas com o Edge para 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 Analtyics > Relatórios na barra de navegação superior.
Na página "Relatórios personalizados", clique em + Relatório personalizado.
Especifique um Nome do relatório, como mybookreport.
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.
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:
Selecione Salvar. O relatório aparece na lista de todos os relatórios personalizados.
Para gerar o relatório, selecione o nome dele. Por padrão, o relatório mostra dados da última hora.
Para definir o período, selecione a exibição da data no canto superior direito para abrir o pop-up do Seletor de datas.
Selecione Últimos 7 dias. O relatório é atualizado para mostrar a soma das avaliações por título do livro:

Receber estatísticas usando a API Edge

use a API Edge Metrics às estatísticas dos 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:Big Query"
    ]
  }
}

A API Edge Metrics 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 Criador de soluções permite criar variáveis de análise personalizadas por meio de uma solução da interface de gerenciamento.

Leia a seção anterior, Coletar dados de análise personalizados. que explica como as políticas do coletor de estatísticas e de variáveis de extração funcionam para fornecer variáveis personalizadas à análise da 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ê. A extração de políticas variáveis de interesse de solicitações ou respostas e transmitir as variáveis extraídas para o Edge Análise de APIs.

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.

Acesse a página "Visão geral" do seu proxy na interface do Edge.
Clique em Desenvolver.
Na página "Desenvolver", selecione Conjunto de análises personalizadas no menu "Ferramentas". A caixa de diálogo "Solution Builder" é exibida.
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.
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.
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.
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. Você precisa anexar o políticas em uma fase do fluxo em que as variáveis que você está capturando estão no escopo (preenchido).
Clique em + Coletor para adicionar mais variáveis personalizadas.
Quando terminar, clique em Criar solução.
Salve e implante o proxy.

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

OBSERVAÇÃO

Leva cerca de 30 minutos para que uma nova dimensão personalizada seja adicionada ao banco de dados depois que a política Statistics Collector é invocada pela primeira vez, para cada ambiente. Por exemplo, se um proxy do coletor de estatísticas for invocado no ambiente test, os dados dessa dimensão personalizada começarão a ser disponibilizados no ambiente test 30 minutos depois, e a dimensão personalizada aparecerá na lista suspensa Dimensões de relatórios personalizados.

Se esse proxy de Statistics Collector for chamado a partir do ambiente prod, levará cerca de 30 minutos para que os dados dessa dimensão personalizada comecem a ser disponibilizados no ambiente prod. A partir desse momento, os dados estarão disponíveis depois do mesmo intervalo de tempo que outras dimensões.