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

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

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

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

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

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

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

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

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

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

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

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

Гибрид Apigee устанавливает ограничение размера результирующего набора данных в 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

Тело запроса из Last60MINUT.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

Тело запроса из Last60MINUT.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: Транзакций в минуту

Запрос по метрике транзакций в минуту (tpm).

Запрос

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