Usando a API de métricas

Esta página se aplica ao Apigee e ao Apigee híbrido .

Veja a documentação do Apigee Edge .

A Apigee registra uma ampla variedade de dados operacionais e comerciais que fluem entre APIs. As métricas derivadas desses dados são úteis para monitoramento operacional e comercial. Usando o Apigee Analytics, você pode, por exemplo, determinar quais APIs estão com bom ou mau desempenho, quais desenvolvedores estão entregando o tráfego de maior valor e quais aplicativos estão causando mais problemas para seus serviços de back-end.

Para facilitar o acesso a esses dados de métricas, use a API de métricas quando precisar automatizar determinadas funções analíticas, como recuperar métricas periodicamente usando um cliente ou script de automação. Você também pode usar a API para criar suas próprias visualizações na forma de widgets personalizados que podem ser incorporados em portais ou aplicativos personalizados.

Para saber como usar o Analytics na interface do usuário do Apigee, consulte Visão geral do Apigee Analytics .

Sobre a API de métricas

Há duas maneiras de usar a API de métricas:

  • Obtenha métricas para uma organização e ambiente ao longo de um período, como uma hora, um dia ou uma semana. Este método retorna métricas brutas para toda a organização e ambiente.

    Por exemplo, para a semana anterior você deseja obter:

    • Número de erros de política
    • Tempo médio de resposta
    • Tráfego total

  • Obtenha métricas organizadas por dimensão ao longo de um período de tempo para uma organização e ambiente.

    Por exemplo, na semana anterior, você pode usar dimensões para agrupar métricas por produto de API, proxy de API e e-mail do desenvolvedor (que também pode ser um ID do AppGroup) para obter:

    • Número de erros de política por produto de API
    • Tempo médio de resposta por proxy de API
    • Tráfego total por e-mail do desenvolvedor

    Para gerenciar o resultado retornado, a API de métricas oferece suporte aos seguintes recursos:

    Para obter mais informações, consulte a referência da API de métricas .

    Introdução ao uso da API de métricas

    O URL de solicitação para a API de métricas é:

    https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats[dimension]

    Por exemplo, para obter métricas agrupadas por proxy de API, use a seguinte URL para chamar a API da Apigee:

    https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?timeRange=07/21/2018+00:00:00~08/23/2018+00:00:00

    Omita a dimensão para retornar métricas brutas para toda a organização e ambiente para o período de tempo especificado:

    https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats?timeRange=07/21/2019+00:00:00~08/23/2018+00:00:00

    Especificando as métricas a serem retornadas

    Use o parâmetro de consulta select para especificar as métricas a serem recuperadas e uma função de agregação opcional, no formato:

    ?select=metric

    ou:

    ?select=aggFunction(metric)

    Onde:

    • metric especifica os dados que você deseja retornar. Por exemplo, o número de solicitações de API, ocorrências de cache ou erros de política. Consulte métricas para obter uma tabela que especifica o nome da métrica a ser usada com o parâmetro de consulta select .

    • aggFunction especifica a função de agregação opcional executada em relação à métrica. Por exemplo, você pode usar as seguintes funções de agregação com a métrica de latência de processamento:

      • avg : Retorna a latência média de processamento.
      • min : Retorna a latência mínima de processamento.
      • max : Retorna a latência máxima de processamento.
      • sum : Retorna a soma de todas as latências de processamento.
      • p50 : Retorna o 50º percentil para latências de processamento.
      • p95 : Retorna o 95º percentil para latências de processamento.
      • p99 : Retorna o 99º percentil para latências de processamento.

      Nem todas as métricas suportam todas as funções de agregação. A documentação sobre métricas contém uma tabela que especifica o nome da métrica e a função ( sum , avg , min , max ) suportada pela métrica.

    Por exemplo, para retornar o número médio de transações, ou seja, solicitações de proxy de API, por segundo:

    ?select=tps

    Observe que este exemplo não requer uma função de agregação. O próximo exemplo usa uma função de agregação para retornar a soma dos acessos ao cache:

    ?select=sum(cache_hit)

    Você pode retornar várias métricas para uma única chamada de API. Para obter métricas para a soma de erros de política e o tamanho médio da solicitação, defina o parâmetro de consulta select usando uma lista de métricas separadas por vírgulas:

    ?select=sum(policy_error),avg(request_size)

    Especificando o período de tempo

    A API de métricas retorna dados referentes a um período específico. Use o parâmetro de consulta timeRange (máximo de 6 meses) para especificar o período, no formato:

    ?timeRange=MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM

    Observe o %20 antes de HH:MM . O parâmetro timeRange requer um caractere de espaço codificado em URL antes de HH:MM , ou um caractere + , como em: MM/DD/YYYY+HH:MM~MM/DD/YYYY+HH:MM .

    Por exemplo: 

    ?timeRange=03/01/2018%2000:00~03/30/2018%2023:59

    Não use 24:00 como horário, pois ele se aproxima de 00:00. Em vez disso, use 23:59.

    Exemplos de chamada da API de métricas

    Esta seção fornece exemplos usando a API de métricas. Consulte Exemplos da API de métricas para obter mais exemplos.

    Retorna o número total de chamadas feitas para suas APIs em um mês

    Para retornar o número total de chamadas feitas para todas as APIs em sua organização e ambiente por um mês, use uma chamada semelhante à seguinte: 

    curl -v "https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/?select=sum(message_count)&timeRange=03/01/2018%2000:00~03/31/2018%2023:59" \
  -H "Authorization: Bearer $TOKEN"

    Onde $TOKEN é definido como seu token de acesso OAuth 2.0, conforme descrito em Como obter um token de acesso OAuth 2.0 . Para obter informações sobre as opções curl usadas neste exemplo, consulte Usando curl . Para obter uma descrição das variáveis ​​de ambiente usadas, consulte Definindo variáveis ​​de ambiente para solicitações da API da Apigee .

    A seguir, um exemplo da resposta: 

    {
  "environments": [
    {
      "metrics": [
        {
          "name": "sum(message_count)",
          "values": [
            "7.44944088E8"
          ]
        }
      ],
      "name": "prod"
    }
  ],
...
}

    Retorna a contagem total de mensagens por proxy de API por dois dias

    Neste exemplo, você retorna métricas para o número de solicitações recebidas por todos os proxies de API em um período de dois dias. O parâmetro de consulta select define a função de agregação sum para a métrica message_count na dimensão apiproxy . O relatório retorna a taxa de transferência de mensagens de solicitação para todas as APIs para o tráfego recebido entre o início de 20/06/2018 e o final de 21/06/2018, no horário UTC: 

    curl  https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59" \
  -H "Authorization: Bearer $TOKEN"

    Onde $TOKEN é definido como seu token de acesso OAuth 2.0, conforme descrito em Como obter um token de acesso OAuth 2.0 . Para obter informações sobre as opções curl usadas neste exemplo, consulte Usando curl . Para obter uma descrição das variáveis ​​de ambiente usadas, consulte Definindo variáveis ​​de ambiente para solicitações da API da Apigee .

    A seguir, um exemplo da resposta: 

    {
  "environments" : [ {
    "dimensions" : [ {
      "metrics" : [ {
        "name" : "sum(message_count)",
        "values" : [ {
          "timestamp" : 1498003200000,
          "value" : "1100.0"
        } ]
      } ],
      "name" : "target-reroute"
    } ],
    "name" : "test"
  } ]...
}

    Esta resposta indica que 1100 mensagens foram recebidas por um proxy de API chamado 'target-reroute' em execução no ambiente de teste entre o início de 20/06/2018 e o final de 21/06/2018.

    Para obter métricas para outras dimensões, especifique uma dimensão diferente como parâmetro de URI. Por exemplo, você pode especificar a dimensão developer_app para recuperar métricas para aplicativos de desenvolvedor. A seguinte chamada de API retorna a taxa de transferência total (mensagens recebidas) de qualquer aplicativo no intervalo de tempo especificado: 

    curl  https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/developer_app?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59&timeUnit=day" \
  -H "Authorization: Bearer $TOKEN"

    A seguir, um exemplo da resposta: 

    {
  "environments": [
    {
      "dimensions": [
        {
          "metrics": [
            {
              "name": "sum(message_count)",
              "values": [
                {
                  "timestamp": 1498003200000,
                  "value": "886.0"
                }
              ]
            }
          ],
          "name": "Test-App"
        },
        {
          "metrics": [
            {
              "name": "sum(message_count)",
              "values": [
                {
                  "timestamp": 1498003200000,
                  "value": "6645.0"
                }
              ]
            }
          ],
          "name": "johndoe_app"
        },
        {
          "metrics": [
            {
              "name": "sum(message_count)",
              "values": [
                {
                  "timestamp": 1498003200000,
                  "value": "1109.0"
                }
              ]
            }
          ],
          "name": "marys_app"
        }
  ]...
}

    Classificando resultados por classificação relativa

    Muitas vezes, ao obter métricas, você deseja obter resultados apenas para um subconjunto do conjunto total de dados. Normalmente, você precisa obter os resultados para o "top 10", por exemplo, as "10 APIs mais lentas" e os "10 aplicativos mais ativos". Você pode fazer isso usando o parâmetro de consulta topk como parte da solicitação.

    Por exemplo, você pode estar interessado em saber quem são seus principais desenvolvedores, medidos pela taxa de transferência, ou quais são suas APIs de destino com pior desempenho (ou seja, "mais lentas") por latência.

    O topk (que significa "top k" entidades) permite gerar relatórios sobre as entidades associadas ao maior valor para uma determinada métrica. Isso permite filtrar métricas para uma lista de entidades que exemplificam uma condição específica.

    Por exemplo, para descobrir qual URL de destino foi mais propensa a erros na última semana, o parâmetro topk é anexado à solicitação, com um valor de 1 : 

    curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/target_url?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&topk=1" \
  -H "Authorization: Bearer $TOKEN"

    Onde $TOKEN é definido como seu token de acesso OAuth 2.0, conforme descrito em Como obter um token de acesso OAuth 2.0 . Para obter informações sobre as opções curl usadas neste exemplo, consulte Usando curl . Para obter uma descrição das variáveis ​​de ambiente usadas, consulte Definindo variáveis ​​de ambiente para solicitações da API da Apigee .

    A seguir, um exemplo da resposta: 

    {
  "environments": [
    {
      "dimensions": [
        {
          "metrics": [
            {
              "name": "sum(is_error)",
              "values": [
                {
                  "timestamp": 1494201600000,
                  "value": "12077.0"
                }
              ]
            }
          ],
          "name": "http://api.company.com"
        }
      ]...
}

    O resultado dessa solicitação é um conjunto de métricas que mostra que o URL de destino com mais bugs é http://api.company.com .

    Você também pode usar o parâmetro topk para classificar as APIs com maior taxa de transferência. O exemplo a seguir recupera métricas da API com melhor classificação, definida pela maior taxa de transferência na última semana: 

    curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV}/stats/apiproxy?"select=sum(message_count)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=day&sortby=sum(message_count)&sort=DESC&topk=1" \
  -H "Authorization: Bearer $TOKEN"

    A seguir, um exemplo da resposta: 

    {
  "environments": [
    {
      "dimensions": [
        {
          "metrics": [
            {
              "name": "sum(message_count)",
              "values": [
                {
                  "timestamp": 1494720000000,
                  "value": "5750.0"
                },
                {
                  "timestamp": 1494633600000,
                  "value": "5752.0"
                },
                {
                  "timestamp": 1494547200000,
                  "value": "5747.0"
                },
                {
                  "timestamp": 1494460800000,
                  "value": "5751.0"
                },
                {
                  "timestamp": 1494374400000,
                  "value": "5753.0"
                },
                {
                  "timestamp": 1494288000000,
                  "value": "5751.0"
                },
                {
                  "timestamp": 1494201600000,
                  "value": "5752.0"
                }
              ]
            }
          ],
          "name": "testCache"
        }
      ],
      "name": "test"
    }
  ]...
}

    Filtrando resultados

    Para maior granularidade, você pode filtrar os resultados para limitar os dados retornados. Ao usar filtros, você deve usar dimensões como propriedades do filtro.

    Por exemplo, suponha que você precise recuperar uma contagem de erros de serviços de back-end filtrados pelo verbo HTTP da solicitação. Seu objetivo é descobrir quantas solicitações POST e PUT estão gerando erros por serviço de back-end. Para isso, use a dimensão target_url juntamente com o filtro request_verb : 

    curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/target_url?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&filter=(request_verb%20in%20'POST','PUT')" \
  -H "Authorization: Bearer $TOKEN"

    Onde $TOKEN é definido como seu token de acesso OAuth 2.0, conforme descrito em Como obter um token de acesso OAuth 2.0 . Para obter informações sobre as opções curl usadas neste exemplo, consulte Usando curl . Para obter uma descrição das variáveis ​​de ambiente usadas, consulte Definindo variáveis ​​de ambiente para solicitações da API da Apigee .

    A seguir, um exemplo da resposta: 

    {
  "environments" : [
    {
      "dimensions" : [
        {
          "metrics" : [
            {
              "name" : "sum(is_error)",
              "values" : [
                {
                  "timestamp" : 1519516800000,
                  "value" : "1.0"
                }
              ]
          }
        ],
        "name" : "testCache"
        }
      ],
      "name" : "test"
    }
  ]...
}

    Resultados de paginação

    Em ambientes de produção, algumas solicitações à API de análise da Apigee retornam conjuntos de dados muito grandes. Para facilitar a exibição de grandes conjuntos de dados no contexto de um aplicativo baseado em IU, a API oferece suporte nativo à paginação.

    Para paginar os resultados, use os parâmetros de consulta offset e limit , juntamente com o parâmetro de classificação sortby para garantir uma ordenação consistente dos itens.

    Por exemplo, a solicitação a seguir provavelmente retornaria um grande conjunto de dados, pois recupera métricas para todos os erros em todas as APIs no ambiente do produto na última semana. 

    curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)" \
  -H "Authorization: Bearer $TOKEN"

    Onde $TOKEN é definido como seu token de acesso OAuth 2.0, conforme descrito em Como obter um token de acesso OAuth 2.0 . Para obter informações sobre as opções curl usadas neste exemplo, consulte Usando curl . Para obter uma descrição das variáveis ​​de ambiente usadas, consulte Definindo variáveis ​​de ambiente para solicitações da API da Apigee .

    Se seu aplicativo baseado em interface de usuário puder exibir razoavelmente 50 resultados por página, você poderá definir o limite para 50. Como 0 conta como o primeiro item, a chamada a seguir retorna os itens de 0 a 49 em ordem decrescente ( sort=DESC é o padrão). 

    curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&limit=50&offset=0" \
  -H "Authorization: Bearer $TOKEN"

    Para a segunda "página" de resultados, use o parâmetro de consulta offset, conforme a seguir. Observe que o limite e o deslocamento são idênticos. Isso ocorre porque 0 conta como o primeiro item. Com um limite de 50 e um deslocamento de 0, os itens de 0 a 49 são retornados. Com um deslocamento de 50, os itens de 50 a 99 são retornados. 

    curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&limit=50&offset=50" \
  -H "Authorization: Bearer $TOKEN"