Usar a API de métricas

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

O Apigee regista uma grande variedade de dados operacionais e empresariais que fluem nas APIs. As métricas derivadas destes dados são úteis para a monitorização operacional e a monitorização da empresa. Com o Apigee Analytics, pode, por exemplo, determinar que APIs estão a ter um bom ou mau desempenho, que programadores estão a gerar o tráfego de maior valor e que apps estão a causar mais problemas aos seus serviços de back-end.

Para ajudar a aceder facilmente a estes dados de métricas, use a API de métricas quando precisar de automatizar determinadas funções de estatísticas, como obter métricas periodicamente através de um script ou um cliente de automatização. Também pode usar a API para criar as suas próprias visualizações sob a forma de widgets personalizados que pode incorporar em portais ou apps personalizadas.

Para saber como usar o Analytics na IU do Apigee, consulte o artigo Vista geral do Apigee Analytics.

Acerca da API Metrics

Existem duas formas de usar a API de métricas:

  • Obtenha métricas para uma organização e um ambiente durante um período, como uma hora, um dia ou uma semana. Este método devolve métricas não processadas para toda a organização e ambiente.

    Por exemplo, para a semana anterior, quer obter:

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

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

    Por exemplo, para a semana anterior, pode usar dimensões para agrupar métricas por produto da API, proxy da API e email do programador (que também pode ser um ID do grupo de apps) para obter:

    • Número de erros de política por produto da API
    • Tempo de resposta médio por proxy de API
    • Tráfego total por email de programador

    Para gerir o resultado devolvido, a API Metrics suporta as seguintes funcionalidades:

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

    Começar a usar a API Metrics

    O URL do pedido da 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 o seguinte URL para chamar a API 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 devolver métricas não processadas para toda a organização e ambiente durante o período especificado:

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

    Especificar as métricas a devolver

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

    ?select=metric

    ou:

    ?select=aggFunction(metric)

    Onde:

    • metric especifica os dados que quer devolver. Por exemplo, o número de pedidos de API, resultados da cache ou erros de políticas. Consulte as métricas para ver uma tabela que especifica o nome da métrica a usar com o parâmetro de consulta select.

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

      • avg: devolve a latência de processamento média.
      • min: devolve a latência de processamento mínima.
      • max: devolve a latência de processamento máxima.
      • sum: devolve a soma de todas as latências de processamento.
      • p50: devolve o percentil 50 para latências de processamento, calculado através de percentile(latency_metric,50)&aggTable=agg_percentile.
      • p95: devolve o percentil 95 para as latências de processamento, calculado através de percentile(latency_metric,95)&aggTable=agg_percentile.
      • p99: devolve o percentil 99 das latências de processamento, calculado através de percentile(latency_metric,99)&aggTable=agg_percentile.

      O latency_metric pode ser:

      • total_response_time
      • target_response_time
      • response_processing_latency
      • request_processing_latency

      Nem todas as métricas suportam todas as funções de agregação. A documentação sobre as 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 devolver o número médio de transações, ou seja, pedidos de proxy da API, por segundo: 

    ?select=tps

    Repare que este exemplo não requer uma função de agregação. O exemplo seguinte usa uma função de agregação para devolver a soma dos acertos da cache:

    ?select=sum(cache_hit)

    Pode devolver várias métricas para uma única chamada API. Para obter métricas para a soma dos erros de políticas e o tamanho médio do pedido, defina o parâmetro de consulta select usando uma lista de métricas separadas por vírgulas:

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

    Especificar o período

    A API Metrics devolve dados relativos a um período especificado. 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

    Repare no %20 antes de HH:MM. O parâmetro timeRange requer um caráter de espaço com codificação URL antes de HH:MM ou um caráter +, 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 hora, porque é convertida em 00:00. Em alternativa, use 23:59.

    Exemplos de chamadas à API Metrics

    Esta secção fornece exemplos de utilização da API Metrics. Consulte exemplos da API Metrics para ver exemplos adicionais.

    Devolva o número total de chamadas feitas às suas APIs durante um mês

    Para devolver o número total de chamadas feitas a todas as APIs na sua organização e ambiente durante 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 está definido como a sua chave de acesso OAuth 2.0, conforme descrito em Obter uma chave de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte a secção Usar o curl. Para uma descrição das variáveis de ambiente que pode usar, consulte o artigo Definir variáveis de ambiente para pedidos de API Apigee.

    Segue-se um exemplo da resposta:

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

    Devolver a contagem total de mensagens por proxy de API durante dois dias

    Neste exemplo, devolve métricas para o número de pedidos recebidos por todos os proxies de API durante 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 devolve a taxa de transferência de mensagens de pedidos para todas as APIs para o tráfego recebido entre o início de 20/06/2018 e o fim de 21/06/2018, na hora 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 está definido como a sua chave de acesso OAuth 2.0, conforme descrito em Obter uma chave de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte a secção Usar o curl. Para uma descrição das variáveis de ambiente que pode usar, consulte o artigo Definir variáveis de ambiente para pedidos de API Apigee.

    Segue-se 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 foram recebidas 1100 mensagens por um proxy de API denominado "target-reroute" em execução no ambiente de teste entre o início de 20/06/2018 e o fim de 21/06/2018.

    Para obter métricas para outras dimensões, especifique uma dimensão diferente como o parâmetro URI. Por exemplo, pode especificar a dimensão developer_app para obter métricas para apps de programadores. A seguinte chamada API devolve o débito total (mensagens recebidas) de quaisquer apps para o 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"

    Segue-se 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"
        }
  ]...
}

    Ordenar resultados por classificação relativa

    Muitas vezes, quando obtém métricas, só quer obter resultados para um subconjunto do conjunto total de dados. Normalmente, tem de obter os resultados dos "10 principais", por exemplo, as "10 APIs mais lentas" ou as "10 apps mais ativas". Pode fazê-lo através do parâmetro de consulta topk como parte do pedido.

    Por exemplo, pode ter interesse em saber quem são os seus principais programadores, medidos pelo débito, ou quais são os seus recursos com pior desempenho (ou seja, "Mais lentas") são as APIs de destino por latência.

    A função topk (que significa "principais k" entidades) permite criar relatórios sobre as entidades associadas ao valor mais elevado para uma determinada métrica. Isto permite-lhe filtrar métricas para uma lista de entidades que exemplificam uma condição específica.

    Por exemplo, para saber qual o URL de destino que foi mais propenso a erros na última semana, o parâmetro topk é anexado ao pedido 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 está definido como a sua chave de acesso OAuth 2.0, conforme descrito em Obter uma chave de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte a secção Usar o curl. Para uma descrição das variáveis de ambiente que pode usar, consulte o artigo Definir variáveis de ambiente para pedidos de API Apigee.

    Segue-se um exemplo da resposta:

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

    O resultado deste pedido é um conjunto de métricas que mostra que o URL de destino com mais erros é http://api.company.com.

    Também pode usar o parâmetro topk para ordenar as APIs que estão a ter o débito mais elevado. O exemplo seguinte obtém métricas sobre a API com a classificação mais elevada, definida pelo débito mais elevado 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"

    Segue-se 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"
    }
  ]...
}

    A filtrar resultados

    Para uma maior granularidade, pode filtrar os resultados para limitar os dados devolvidos. Quando usar filtros, tem de usar dimensões como propriedades de filtro.

    Por exemplo, suponhamos que precisa de obter uma contagem de erros dos serviços de back-end filtrados pelo verbo HTTP do pedido. O seu objetivo é saber quantos pedidos POST e PUT estão a gerar erros por serviço de back-end. Para o fazer, usa 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 está definido como a sua chave de acesso OAuth 2.0, conforme descrito em Obter uma chave de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte a secção Usar o curl. Para uma descrição das variáveis de ambiente que pode usar, consulte o artigo Definir variáveis de ambiente para pedidos de API Apigee.

    Segue-se um exemplo da resposta:

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

    Paginar resultados

    Em ambientes de produção, alguns pedidos à API Apigee Analytics devolvem conjuntos de dados muito grandes. Para facilitar a apresentação de grandes conjuntos de dados no contexto de uma aplicação baseada na IU, a API suporta nativamente a paginação.

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

    Por exemplo, é provável que o seguinte pedido devolva um grande conjunto de dados, uma vez que obtém métricas para todos os erros em todas as APIs no ambiente do produto durante a ú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 está definido como a sua chave de acesso OAuth 2.0, conforme descrito em Obter uma chave de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte a secção Usar o curl. Para uma descrição das variáveis de ambiente que pode usar, consulte o artigo Definir variáveis de ambiente para pedidos de API Apigee.

    Se a sua aplicação baseada na IU puder apresentar razoavelmente 50 resultados por página, pode definir o limite como 50. Uma vez que 0 conta como o primeiro item, a seguinte chamada devolve os itens 0 a 49 por ordem descendente (sort=DESC é a predefiniçã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 de deslocamento, da seguinte forma. Tenha em atenção que o limite e o desvio são idênticos. Isto acontece porque 0 conta como o primeiro item. Com um limite de 50 e um deslocamento de 0, são devolvidos os itens 0 a 49. Com um desvio de 50, são devolvidos os itens 50 a 99.

    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"