Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

Как использовать API показателей

Вы просматриваете документацию по Apigee Edge.
Перейдите к документации по Apigee X. Информация

Apigee Edge регистрирует самые разные операционные и бизнес-данные, передаваемые через API. Показатели, полученные на основе этих данных, полезны для оперативного и бизнес-мониторинга. С помощью Edge API Analytics можно, например, определить, какие API работают хорошо, а какие – плохо, какие разработчики создают наиболее ценный трафик и какие приложения вызывают больше всего проблем в работе ваших внутренних сервисов.

Чтобы упростить доступ к этим данным, Edge предоставляет RESTful API. API показателей можно использовать, когда вам нужно автоматизировать определенные функции Аналитики, например периодически получать показатели с помощью клиента автоматизации или скрипта. Вы также можете использовать API для создания собственных визуализаций в виде специальных виджетов, которые можно встраивать в порталы или специальные приложения.

Чтобы узнать, как использовать Аналитику в интерфейсе управления API Edge, ознакомьтесь с обзором API Analytics.

API показателей

Edge предоставляет два API для показателей:

Get metrics возвращает показатели для организации и среды за определенный период времени, например час, день или неделю.

Например, за предыдущую неделю вам нужно получить:
- Количество нарушений правил.
- Среднее время ответа
- Общий трафик
Получение показателей, упорядоченных по параметрам возвращает показатели за определенный период времени для организации и среды, сгруппированные по параметру.

Например, за предыдущую неделю вы используете параметры, чтобы сгруппировать показатели по продукту API, прокси-серверу API и адресу электронной почты разработчика и получить следующие данные:
- Количество ошибок, связанных с правилами, для каждого продукта API.
- Среднее время ответа для каждого прокси-сервера API.
- Общий трафик на адрес электронной почты разработчика.
API Get metrics organized by dimensions (Получение показателей, упорядоченных по параметрам) поддерживает дополнительные функции, недоступные в API Get metrics (Получение показателей):

Квоты для API показателей

Edge применяет к этим вызовам следующие квоты. Квота зависит от внутренней системы, которая обрабатывает звонок:

Postgres: 40 вызовов в минуту.
BigQuery: 12 вызовов в минуту.

Определите, какая система обработки вызовов используется, изучив объект ответа. Каждый объект ответа содержит свойство metaData, в котором указан сервис, обработавший вызов, в свойстве Source. Например, для Postgres:

{
  ...
  "metaData": {
    "errors": [],
    "notices": [
      "Source:Postgres",
      "Table used: xxxxxx.yyyyy",
      "query served by:111-222-333"
    ]
  }
}

Для BigQuery свойство Source:

"Source:Big Query"

Если вы превысите квоту на вызовы, API вернет HTTP-ответ 429.

Как получать показатели с помощью Management API

Основное различие между этими двумя API заключается в том, что Get metrics возвращает необработанные показатели для всей организации и среды, а Get metrics organized by dimensions позволяет группировать показатели по различным типам объектов, таким как продукт API, разработчик и приложение.

URL запроса для API Get metrics:

https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats

В API Get metrics organized by dimensions (Получение показателей, упорядоченных по параметрам) после /stats в URL добавляется дополнительный ресурс, который указывает на нужный параметр:

https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/dimension

Например, чтобы получить показатели, сгруппированные по прокси-серверу API, вызовите Management API, используя следующий URL:

https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/apiproxy

Как указать, какие показатели нужно вернуть

В API Получить показатели и Получить показатели, сгруппированные по параметрам для указания показателей, которые нужно получить, и необязательной функции агрегирования используется параметр запроса select в следующем формате:

?select=metric

Или:

?select=aggFunction(metric)

Где:

Показатель – это данные, которые вы хотите получить. Например, количество запросов API, попаданий в кеш или ошибок правил. В таблице в разделе показателей указаны названия показателей, которые можно использовать с параметром запроса select.
aggFunction – необязательная агрегатная функция, применяемая к показателю. Например, с показателем задержки обработки можно использовать следующие функции агрегирования:
- avg: возвращает среднюю задержку обработки.
- min – возвращает минимальную задержку при обработке.
- max – возвращает максимальную задержку обработки.
- sum – возвращает сумму всех задержек обработки.
Не все показатели поддерживают все функции агрегирования. В документации по показателям есть таблица, в которой указаны названия показателей и функции (sum, avg, min, max), поддерживаемые каждым из них.

Например, чтобы получить среднее количество транзакций (запросов к прокси-серверу API) в секунду, выполните следующие действия:

?select=tps

Обратите внимание, что в этом примере не требуется агрегатная функция. В следующем примере используется агрегатная функция, чтобы вернуть сумму попаданий в кеш:

?select=sum(cache_hit)

Вы можете получить несколько показателей за один вызов API. Чтобы получить показатели для суммы ошибок правил и среднего размера запроса, задайте параметр запроса select, используя список показателей, разделенных запятыми:

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

Как указать период времени

API показателей возвращает данные за определенный период времени. Чтобы указать период времени, используйте параметр запроса timeRange в следующем формате:

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

Обратите внимание на %20 до HH:MM. Параметр timeRange требует, чтобы перед HH:MM был закодированный для URL пробел или символ +, как в примере: MM/DD/YYYY+HH:MM~MM/DD/YYYY+HH:MM.

Пример:

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

Не используйте значение 24:00, поскольку оно будет преобразовано в 00:00. Используйте 23:59.

Как использовать разделитель

Чтобы разделить несколько параметров в вызове API, используйте запятую (,). Например, в вызове API

curl https://api.enterprise.apigee.com/v1/o/myorg/e/prod/stats/apis,apps?select=sum(message_count)&timeRange=9/24/2018%2000:00~10/25/2018%2000:00&timeUnit=day

Параметры apis и apps разделены символом ,.

Примечание. Ранее в качестве разделителя можно было использовать косую черту (/), но это не было указано в документации. Теперь это не поддерживается. Используйте запятую в качестве разделителя.

Примеры вызовов API

В этом разделе приведены примеры использования API Получение показателей и Получение показателей, сгруппированных по параметрам. Другие примеры можно найти в разделе Примеры использования Metrics API.

Возвращает общее количество вызовов API за месяц

Чтобы посмотреть общее количество вызовов, сделанных ко всем API в вашей организации и среде за один месяц, используйте API Get metrics:

curl -v "https://api.enterprise.apigee.com/v1/o/{org}/e/{env}/stats/?select=sum(message_count)&timeRange=03/01/2018%2000:00~03/31/2018%2023:59" \
-u email:password

Пример ответа

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

Как получить общее количество сообщений для каждого прокси-сервера API за два дня

В этом примере вы возвращаете показатели для количества запросов, полученных всеми прокси API за двухдневный период. Параметр запроса select определяет агрегированную функцию sum для показателя message_count по параметру apiproxy. В отчете возвращается пропускная способность сообщений запросов для всех API для трафика, полученного в период с начала 20 июня 2018 г. до конца 21 июня 2018 г. по времени UTC:

curl  https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59" \
-u email:password

Пример ответа

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

Этот ответ означает, что с начала 20 июня 2018 г. до конца 21 июня 2018 г. прокси-сервер API target-reroute, работающий в тестовой среде, получил 1100 сообщений.

Совет. Обратите внимание, что временная метка 1498003200000 указана в формате Unix-времени. В интернете можно найти множество инструментов для преобразования временных меток Unix, которые помогут вам декодировать эти метки.

Чтобы получить показатели для других параметров, укажите другой параметр в качестве параметра URI. Например, можно указать параметр developer_app, чтобы получить показатели для приложений разработчика. Следующий вызов API возвращает общую пропускную способность (полученные сообщения) от любых приложений за указанный временной интервал:

curl  https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/developer_app?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59&timeUnit=day" \
-u email:password

Пример ответа

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

Сортировка результатов по относительному рангу

Часто при получении показателей вам нужны результаты только для части набора данных. Обычно вам нужно получить результаты для "топ-10", например "топ-10 самых медленных API" или "топ-10 самых активных приложений". Для этого можно использовать параметр запроса topk.

Например, вы можете узнать, какие разработчики обеспечивают наибольшую производительность или какие из них работают хуже всего (то есть целевые API (например, "самые медленные") сортируются по задержке.

Символ topk (топ-k объектов) позволяет создавать отчеты об объектах, связанных с наибольшим значением определенного показателя. Это позволяет фильтровать показатели по списку объектов, которые соответствуют определенному условию. Например, чтобы узнать, какой целевой URL чаще всего вызывал ошибки на прошлой неделе, к запросу добавляется параметр topk со значением 1:

curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{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" \
  -u email:password

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

В результате этого запроса будет получен набор показателей, из которых следует, что URL с наибольшим количеством ошибок – http://api.company.com.

Вы также можете использовать параметр topk, чтобы отсортировать API по пропускной способности. В следующем примере извлекаются показатели для API с самым высоким рейтингом, который определяется по максимальной пропускной способности за последнюю неделю:

curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{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" \
-u email:password

Пример ответа

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

Применение фильтров…

Чтобы получить более точные результаты, можно отфильтровать данные. При использовании фильтров в качестве их свойств необходимо указывать параметры.

Предположим, вам нужно получить количество ошибок от внутренних сервисов, отфильтрованных по HTTP-методу запроса. Ваша цель – узнать, сколько запросов POST и PUT генерируют ошибки для каждой бэкенд-службы. Для этого используйте параметр target_url вместе с фильтром request_verb:

curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{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')" \
-u email:password

Пример ответа

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

Примечание. Не используйте / в качестве сочетания клавиш для фильтров. Например, вот так выглядит правильный вызов:

curl https://api.enterprise.apigee.com/v1/o/myorg/e/prod/stats/apis?filter=(apis eq 'myapp')&select=sum(message_count)&timeRange=9/24/2018%2000:00~10/25/2018%2000:00&timeUnit=day

В этом вызове не заменяйте apis?filter=(apis eq 'myapp')&select= ярлыком apis/myapp?select=.

Как разбивать результаты на страницы

В рабочих средах некоторые запросы к API аналитики Edge возвращают очень большие наборы данных. Чтобы упростить отображение больших наборов данных в контексте приложения на основе интерфейса, API изначально поддерживает разбиение на страницы.

Чтобы разбить результаты на страницы, используйте параметры запроса offset и limit, а также параметр сортировки sortby, чтобы обеспечить согласованное упорядочение элементов.

Примечание. При разбиении результатов на страницы важно сортировать их предсказуемым образом, используя параметр запроса sortby. Без сортировки результаты возвращаются в непредсказуемом порядке, что противоречит цели разбивки на страницы.

Значение sortby должно совпадать со значением, указанным в параметре запроса select. Например, если select=sum(message_count), то sortby=sum(message_count).

Например, следующий запрос, скорее всего, вернет большой набор данных, поскольку он извлекает показатели для всех ошибок во всех API в среде продукта за последнюю неделю.

curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)" \
-u email:password

Если ваше приложение с графическим интерфейсом может без проблем показывать 50 результатов на странице, установите ограничение на уровне 50. Поскольку 0 считается первым элементом, следующий вызов возвращает элементы 0–49 в порядке убывания (sort=DESC – значение по умолчанию).

curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{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" \
-u email:password

Чтобы получить вторую страницу результатов, используйте параметр запроса offset, как показано ниже. Обратите внимание, что значения limit и offset одинаковы. Потому что 0 считается первым элементом. Если задать лимит 50 и смещение 0, будут возвращены объекты 0–49. При смещении 50 возвращаются объекты 50–99.

curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{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" \
-u email:password