Эта страница переведена с помощью Cloud Translation API.

Используйте API метрик

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

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

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

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

О API метрик

Edge предоставляет два API для работы с метриками:

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

О квотах API метрик

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

PostgreSQL : 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.

Получение метрик с помощью API управления

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

URL-адрес запроса для API получения метрик :

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

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

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

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

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

Указание метрик для возврата

Для получения метрик как в API Get metrics , так и в API Get metrics organized by dimensions используется параметр запроса select для указания метрик , которые необходимо получить, а также необязательная функция агрегирования в следующем формате:

?select=metric

или:

?select=aggFunction(metric)

Где:

Параметр metric указывает данные, которые вы хотите получить. Например, количество запросов к API, попаданий в кэш или ошибок политик. См. раздел metrics для получения таблицы, в которой указано имя метрики, используемой с параметром запроса 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 требует наличия закодированного в URL-формате пробела перед HH:MM или символа + , например: 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 «Получить метрики» и « Получить метрики, организованные по измерениям» . Дополнительные примеры см. в разделе «Примеры использования API метрик» .

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

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

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.06.2018 по конец 21.06.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.06.2018 по 21.06.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 Analytics возвращают очень большие наборы данных. Чтобы упростить отображение больших наборов данных в контексте приложения с пользовательским интерфейсом, 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 считается первым элементом. При limit равном 50 и offset равном 0 возвращаются элементы 0-49. При offset равном 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