Как использовать API асинхронных специальных отчетов

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

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

Однако время ожидания запросов к аналитике может истечь, если они выполняются слишком долго. Если запрос требует обработки большого объема данных (например, сотен гигабайт), он может завершиться с ошибкой из-за превышения времени ожидания.

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

• Анализ и создание отчетов за большие периоды времени.
• Анализ данных с использованием различных параметров группировки и других ограничений, которые усложняют запрос.
• Управление запросами, если вы обнаружили, что объем данных значительно увеличился для некоторых пользователей или организаций.

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

Сравнение API отчетов с интерфейсом

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

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

Основное отличие между отчетами, созданными в интерфейсе и с помощью API, заключается в том, что отчеты, созданные с помощью API, записываются в файлы CSV или JSON (с разделителями строк), а не в визуальные отчеты, отображаемые в интерфейсе.

Ограничения в Apigee Hybrid

В Apigee hybrid действует ограничение на размер набора данных результатов в 30 МБ.

Как создать асинхронный запрос к аналитике

Асинхронные запросы к аналитическим данным выполняются в три этапа:

1. Нажмите Отправить.

2. Получить статус запроса.

3. Получите результаты запроса.

Шаг 1. Отправка запроса

Вам нужно отправить запрос POST к API /queries. Этот API позволяет Edge обрабатывать ваш запрос в фоновом режиме. Если запрос отправлен успешно, API возвращает статус 201 и идентификатор, который вы будете использовать для ссылки на запрос на последующих этапах.

Пример:

curl -X POST -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries -d @json-query-file
-u orgAdminEmail:password

Тело запроса представляет собой описание запроса в формате JSON. В теле JSON-запроса укажите показатели, параметры и фильтры, которые определяют отчет.

Ниже приведен пример файла json-query-file:

{ 
   "metrics":  [
     {
         "name": "message_count",
         "function": "sum",
         "alias": "sum_txn"
    }
        ],
    "dimensions": ["apiproxy"],
    "timeRange": "last24hours",
    "limit": 14400,
    "filter":"(message_count ge 0)"         
}

Полное описание синтаксиса тела запроса приведено в разделе О теле запроса ниже.

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

Обратите внимание, что в ответе есть идентификатор запроса 9cfc0d85-0f30-46d6-ae6f-318d0cb961bd. Помимо кода статуса HTTP 201, успешное выполнение запроса подтверждает значение state в enqueued.

HTTP/1.1 201 Created

{  
  "self":"/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd",
  "created":"2018-05-10T07:11:10Z",
  "state":"enqueued",
  "error":"false",
}

Шаг 2. Как узнать статус запроса

Чтобы запросить статус запроса, выполните вызов GET. Вы указываете идентификатор запроса, возвращенный вызовом POST. Пример:

curl -X GET -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd
-u email:password

Примеры ответов:

Если запрос ещё выполняется, вы получите ответ, в котором state будет заменено на running:

{
    "self": "/organizations/myorg/environments/myenv/queries/1577884c-4f48-4735-9728-5da4b05876ab",
    "state": "running",
    "created": "2018-02-23T14:07:27Z",
    "updated": "2018-02-23T14:07:54Z"
}

После успешного выполнения запроса вы увидите ответ, в котором для параметра state задано значение completed:

{
      "self": "/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd",
      "state": "completed",
      "result": {
        "self": "/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd/result",
        "expires": "2017-05-22T14:56:31Z"
      },
      "resultRows": 1,
      "resultFileSize": "922KB",
      "executionTime": "11 sec",
      "created": "2018-05-10T07:11:10Z",
      "updated": "2018-05-10T07:13:22Z"
}

Шаг 3. Как получить результаты запроса

Когда статус запроса изменится на completed, вы сможете получить результаты с помощью API get results, где идентификатор запроса снова будет 9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.

curl -X GET -H "Content-Type:application/json" -O -J https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd/result
-u email:password

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

• Если вы используете cURL, то можете использовать параметры -O -J, как показано выше.

• Если вы используете Postman, нажмите кнопку Сохранить и скачать. В этом случае будет скачан ZIP-файл с названием response.

• Если вы используете браузер Chrome, скачивание начнется автоматически.

Если запрос выполнен успешно и набор результатов не пуст, результат скачивается на клиент в виде ZIP-архива с JSON-файлом (с символом перевода строки в качестве разделителя). Название скачанного файла будет выглядеть следующим образом:

OfflineQueryResult-<query-id>.zip

Пример:

OfflineQueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.zip

ZIP-файл содержит архив JSON-результатов в формате GZ. Чтобы получить доступ к файлу JSON, распакуйте скачанный файл, а затем используйте команду gzip, чтобы извлечь файл JSON:

unzip OfflineQueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.zip
gzip -d QueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd-000000000000.json.gz

О теле запроса

В этом разделе описаны параметры, которые можно использовать в теле запроса JSON для запроса. Подробнее о показателях и параметрах, которые можно использовать в запросе, рассказывается в справочнике по Аналитике.

{  
   "metrics":[  
      {  
        "name":"metric_name",
        "function":"aggregation_function",
        "alias":"metric_dispaly_name_in_results",
        "operator":"post_processing_operator",
        "value":"post_processing_operand"
      },
   ...
   ],
   "dimensions":[  
      "dimension_name",
      ...
   ],
   "timeRange":"time_range",
   "limit":results_limit,
   "filter":"filter",
   "groupByTimeUnit": "grouping",
   "outputFormat": "format",
   "csvDelimiter": "delimiter"
}

"metrics":[  
  {  
    "name":"response_processing_latency",
    "function":"avg",
    "alias":"average_response_time_in_seconds",
    "operator":"/",
    "value":"1000"
  }
]

"timeRange": {
    "start": "2018-07-29T00:13:00Z",
    "end": "2018-08-01T00:18:00Z"
}

Синтаксис выражений фильтра

В этом справочном разделе описаны токены, которые можно использовать для создания выражений фильтра в теле запроса. Например, в следующем выражении используется токен "ge" (больше или равно):

"filter":"(message_count ge 0)"

(apiproxy in 'ethorapi','weather-api')

(apiproxy in 'ethorapi')

(apiproxy in 'Search','ViewItem')

(response_status_code in 400,401,500,501)

(response_status_code notin 400,401,500,501)

(response_status_code eq 504)

(apiproxy eq 'non-prod')

(response_status_code ne 500)

(apiproxy ne 'non-prod')

(response_status_code gt 500)

(response_status_code lt 500)

(target_response_code ge 400)

(target_response_code le 300)

(apiproxy like '%buy%')

(apiproxy like '%item')

(apiproxy like 'Prod%')

(apiproxy not like '%buy%')

(apiproxy not like '%item')

(apiproxy not like 'Prod%')

(target_response_code gt 399) and (response_status_code ge 400)

(response_size ge 1000) or (response_status_code eq 500)

Ограничения и значения по умолчанию

Ниже приведены ограничения и значения по умолчанию для функции асинхронной обработки запросов.

О результатах запроса

Ниже приведен пример результата в формате JSON. Выходные данные состоят из строк JSON, разделенных символом новой строки:

{"message_count":"10209","apiproxy":"guest-auth-v3","hour":"2018-08-07 19:26:00 UTC"}
{"message_count":"2462","apiproxy":"carts-v2","hour":"2018-08-06 13:16:00 UTC"}    
…

Вы можете получать результаты по URL, пока не истечет срок хранения данных в репозитории. Подробнее об ограничениях и значениях по умолчанию…

Примеры

Пример 1. Сумма количества сообщений

Запрос на получение суммы количества сообщений за последние 60 минут.

Запрос

curl -X POST -H "Content-Type: application/json" -H "Accept: application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries"
-d @last60minutes.json
-u orgAdminEmail:password

Тело запроса из файла last60minutes.json

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":"last60minutes"
}

Пример 2. Специальный диапазон дат

Запрос с использованием специального диапазона дат.

Запрос

curl -X POST -H "Content-Type: application/json" -H "Accept: application/json"
https://api.enterprise.apigee.com/v1 /organizations/myorg/environments/test/queries"
-d @last60minutes.json
-u orgAdminEmail:password

Тело запроса из файла last60minutes.json

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum"
      },
      {  
         "name":"total_response_time",
         "function":"avg",
         "alias":"average_response_time"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":{  
      "start":"2018-11-01T11:00:00Z",
      "end":"2018-11-30T11:00:00Z"
   }
}

Пример 3. Транзакции в минуту

Запрос показателя "Транзакции в минуту".

Запрос

curl -X POST -H "Content-Type: application/json" -H "Accept: application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries"
-d @tpm.json
-u orgAdminEmail:password

Тело запроса из файла tpm.json

{  
   "metrics":[  
      {  
         "name":"tpm"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":{  
      "start":"2018-07-01T11:00:00Z",
      "end":"2018-07-30T11:00:00Z"
   }
}

Пример результата

Выдержка из файла результатов:

{"tpm":149995.0,"apiproxy":"proxy_1","minute":"2018-07-06 12:16:00 UTC"}
{"tpm":149998.0,"apiproxy":"proxy_1","minute":"2018-07-09 15:12:00 UTC"}
{"tpm":3.0,"apiproxy":"proxy_2","minute":"2018-07-11 16:18:00 UTC"}
{"tpm":148916.0,"apiproxy":"proxy_1","minute":"2018-07-15 17:14:00 UTC"}
{"tpm":150002.0,"apiproxy":"proxy_1","minute":"2018-07-18 18:11:00 UTC"}
...

Пример 4. Использование выражения фильтра

Запрос с выражением фильтра, в котором используется логический оператор.

Запрос

curl -X POST -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries"
-d @filterCombo.json
-u orgAdminEmail:password

Тело запроса из файла filterCombo.json

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum"
      },
      {  
         "name":"total_response_time",
         "function":"avg",
         "alias":"average_response_time"
      }
   ],
   "filter":"(apiproxy ne \u0027proxy_1\u0027) and (apiproxy ne \u0027proxy_2\u0027)",
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":{  
      "start":"2018-11-01T11:00:00Z",
      "end":"2018-11-30T11:00:00Z"
   }
}

Пример 5. Передача выражения в параметре metrics

Запрос с выражением, которое передается как часть параметра metrics. Можно использовать только простые выражения с одним оператором.

Запрос

curl -X POST -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries" 
-d @metricsExpression.json
-u orgAdminEmail:password

Тело запроса из файла metricsExpression.json

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum",
         "operator":"/",
         "value":"7"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":10,
   "timeRange":"last60minutes"
}

Как создать асинхронный запрос для отчета о монетизации

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

Как и в случае с асинхронными запросами аналитики, асинхронные запросы отчетов о монетизации выполняются в три этапа: 1) отправка запроса, 2) получение статуса запроса и 3) получение результатов запроса.

Шаг 1 – отправка запроса – описан ниже.

Шаги 2 и 3 точно такие же, как и для асинхронных аналитических запросов. Подробнее о том, как создать асинхронный аналитический запрос…

Чтобы отправить запрос на асинхронный отчет о монетизации, отправьте POST-запрос на адрес /mint/organizations/org_id/async-reports.

При необходимости вы можете указать среду, передав параметр запроса environment. Если параметр не указан, по умолчанию используется значение prod. Пример:

/mint/organizations/org_id/async-reports?environment=prod

В теле запроса укажите следующие критерии поиска:

"devCriteria":[{
    "id":"RtHAeZ6LtkSbEH56",
    "orgId":"my_org"}
]

Например, следующий запрос создает асинхронный отчет о монетизации за июнь 2017 г. для указанного продукта API и идентификатора разработчика. Даты и время в отчетах fromDate и toDate указаны по всемирному координированному времени (UTC/GMT) и могут включать время.

curl -H "Content-Type:application/json" -X POST -d \
'{
      "fromDate":"2017-06-01 00:00:00",
      "toDate":"2017-06-30 00:00:00",    
     "productIds": [
        "a_product"
    ],
    "devCriteria": [{
        "id": "AbstTzpnZZMEDwjc",
        "orgId": "myorg"
    }]

 }' \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/async-reports?environment=prod" \
-u orgAdminEmail:password