Используйте API асинхронных пользовательских отчетов

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

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

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

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

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

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

Сравнение API отчетов с пользовательским интерфейсом.

В разделе «Создание и управление пользовательскими отчетами» описывается, как использовать пользовательский интерфейс Edge для создания и запуска пользовательских отчетов. Вы можете запускать эти отчеты синхронно или асинхронно.

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

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

Ограничения в гибриде Apigee

В 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 получения результатов, где идентификатор запроса снова будет 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, загрузка будет принята автоматически.

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

OfflineQueryResult-<query-id>.zip

Например:

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

ZIP-архив содержит файл .gz с результатами в формате JSON. Чтобы получить доступ к файлу 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: Передача выражения в параметре метрики.

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

Запрос

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