Edge Analytics は、インタラクティブ ダッシュボード、カスタム レポート ジェネレータ、および関連機能の豊富なセットを提供します。ただし、これらの機能は双方向性を意図して設計されているため、API または UI リクエストを送信すると、分析サーバーがレスポンスを提供するまでそのリクエストはブロックされます。
分析リクエストは、完了までに時間がかかりすぎるとタイムアウトする可能性があります。クエリ リクエストが大量のデータ（数百 GB など）を処理する必要がある場合は、タイムアウトのために失敗する可能性があります。
非同期クエリ処理を使用すれば、大量のデータセットに対してクエリを実行しておいて、後から結果を受け取ることができます。インタラクティブ クエリがタイムアウトすることがわかった場合は、オフライン クエリの使用を検討してください。次のように、非同期クエリ処理が適切な代替手段になる場合があります。
- レポートの分析と作成に時間がかかる場合。
- グループ化ディメンションが多いなどのクエリを複雑にする制約を伴うデータを分析する場合。
- 一部のユーザーまたは組織のデータ量が大幅に増加したことがわかってからクエリを管理する場合。
このドキュメントでは、API を使用して非同期クエリを開始する方法について説明します。カスタム レポートの実行で説明されているように、UI を使用することもできます。
レポート API と UI の比較
カスタム レポートの作成と管理に、Edge UI を使用してカスタム レポートを作成して実行する方法が記載されています。これらのレポートは同期的または非同期的に実行できます。
UI を使用してカスタム レポートを生成する場合のコンセプトのほとんどが、API の使用に適用されます。つまり、API を使用してカスタム レポートを作成するときは、Edge に組み込まれた指標、ディメンション、フィルタと、StatisticsCollector ポリシーを使用して作成したカスタム指標を指定します。
UI と API で生成されるレポートの主な違いは、API を使用して生成されたレポートが UI に表示される視覚的なレポートではなく、CSV または JSON（改行区切り）ファイルに書き込まれることです。
Apigee ハイブリッドの制限
Apigee ハイブリッドでは、結果データセットに 30 MB のサイズ上限が適用されます。
非同期分析クエリを作成する方法
非同期分析クエリは、次の 3 つのステップで作成します。
ステップ 1. クエリを送信する
POST リクエストを /queries Management API に送信する必要があります。この API は、バックグラウンドでリクエストを処理するように Edge に指示します。クエリの送信が成功すると、API は 201 ステータスと、後のステップでクエリを参照するために使用する ID を返します。
例:
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)"
}
リクエスト本文の構文の詳細については、後述するリクエスト本文についてをご覧ください。
レスポンスの例:
クエリ ID 9cfc0d85-0f30-46d6-ae6f-318d0cb961bd がレスポンスに含まれていることに注意してください。HTTP ステータス 201 に加えて、enqueued の state が、リクエストが成功したことを示しています。
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 呼び出しから返されたクエリ ID を指定します。次に例を示します。
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 になったら、get results API を使用して、結果を回収できます。ここでは、クエリ ID が再び 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 を使用する場合は、[Save and Download] ボタンを選択する必要があります。この場合は、
responseという名前の zip ファイルがダウンロードされます。Chrome ブラウザを使用している場合は、ダウンロードが自動的に受け入れられます。
リクエストが成功し、0 以外の結果セットが存在する場合は、結果が圧縮された 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
|
指標の配列。各指標が含まれる 1 つのクエリに対して、1 つ以上の指標を指定できます。指標名のみが必須です。
"metrics":[
{
"name":"response_processing_latency",
"function":"avg",
"alias":"average_response_time_in_seconds",
"operator":"/",
"value":"1000"
}
]詳細については、アナリティクス指標、ディメンション、フィルタのリファレンスをご覧ください。 |
× |
dimensions
|
指標をグループ化するディメンションの配列。詳細については、サポートされているディメンションのリストをご覧ください。複数のディメンションを指定できます。 | × |
timeRange
|
クエリの時間範囲。
次の事前に定義された文字列を使用して、時間範囲を指定できます。
または、開始タイムスタンプと終了タイムスタンプを ISO 形式で記述した構造 "timeRange": {
"start": "2018-07-29T00:13:00Z",
"end": "2018-08-01T00:18:00Z"
} |
○ |
limit
|
結果で返される最大行数。 | × |
filter
|
データのフィルタ処理に使用されるブール式。フィルタ式は、AND / OR 用語を使用して組み合わせることができ、曖昧さを避けるために全体を括弧で囲む必要があります。フィルタ処理に使用可能なフィールドの詳細については、アナリティクス指標、ディメンション、フィルタのリファレンスをご覧ください。フィルタ式の作成に使用されるトークンの詳細については、フィルタ式の構文をご覧ください。 | × |
groupByTimeUnit
|
結果セットのグループ化に使用される時間単位。有効な値は、second、minute、hour、day、week、month です。
クエリに |
× |
outputFormat
|
出力形式。有効な値は、csv と json です。デフォルトは、改行区切りの JSON に対応する json です。
注: |
× |
csvDelimiter
|
outputFormat が csv に設定されている場合に、CSV ファイルで使用される区切り文字。デフォルトで ,（カンマ）文字に設定されます。サポートされている区切り文字には、カンマ（,）、パイプ（|）、タブ（\t）があります。 |
× |
フィルタ式の構文
このリファレンス セクションでは、リクエスト本文でフィルタ式を作成するために使用可能なトークンについて説明します。たとえば、次の式では「ge」トークン（以上）が使用されています。
"filter":"(message_count ge 0)"
| トークン | 説明 | 例 |
|---|---|---|
in
|
リストに含む | (apiproxy in 'ethorapi','weather-api') (apiproxy in 'ethorapi') (apiproxy in 'Search','ViewItem') (response_status_code in 400,401,500,501) 注: 文字列を引用符で囲む必要があります。 |
notin
|
リストから除外する | (response_status_code notin 400,401,500,501) |
eq
|
次に等しい（==)
|
(response_status_code eq 504) (apiproxy eq 'non-prod') |
ne
|
等しくない（(!=)
|
(response_status_code ne 500) (apiproxy ne 'non-prod') |
gt
|
より大きい（>)
|
(response_status_code gt 500) |
lt
|
より小さい（<)
|
(response_status_code lt 500) |
ge
|
以上（>=)
|
(target_response_code ge 400) |
le
|
以下（<=)
|
(target_response_code le 300) |
like
|
文字列パターンが指定したパターンに一致する場合に true を返します。
右の例は次のように一致します。 - 「buy」という単語を含む値 - 「item」で終わる値 - 「Prod」で始まる値 - 4 で始まる値、response_status_code は数値であることに注意
|
(apiproxy like '%buy%') (apiproxy like '%item') (apiproxy like 'Prod%') |
not like
|
文字列パターンが指定したパターンに一致する場合に false を返します。 | (apiproxy not like '%buy%') (apiproxy not like '%item') (apiproxy not like 'Prod%') |
and
|
「and」ロジックを使用して複数のフィルタ式を含めることができます。フィルタには、すべての条件を満たすデータが含まれます。 | (target_response_code gt 399) and (response_status_code ge 400) |
or
|
「or」ロジックを使用して、考えられるさまざまなフィルタ式を評価できます。フィルタには、少なくとも 1 つの条件を満たすデータが含まれます。 | (response_size ge 1000) or (response_status_code eq 500) |
制約とデフォルト
非同期クエリ処理機能の制約とデフォルトのリストを以下に示します。
| 制約 | デフォルト | 説明 |
|---|---|---|
| クエリ呼び出しの上限 | 説明を参照 | 非同期レポートを開始するために、/queries Management API を 1 時間あたり最大 7 回呼び出すことができます。呼び出しの割り当てを超えた場合、API は HTTP 429 レスポンスを返します。 |
| アクティブ クエリの上限 | 10 | 組織 / 環境に対して最大 10 個のアクティブ クエリを使用できます。 |
| クエリ実行時間のしきい値 | 6 時間 | 6 時間以上かかるクエリは強制終了されます。 |
| クエリ時間の範囲 | 説明を参照 | クエリの最大許容時間範囲は 365 日です。 |
| ディメンションと指標の上限 | 25 | クエリ ペイロードで指定可能なディメンションと指標の最大数。 |
クエリ結果について
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: 1 分あたりのトランザクション
1 分あたりのトランザクション（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: 指標パラメータで式を渡す
指標パラメータの一部として渡される式を使用したクエリ。単純な 1 演算子式のみを使用できます。
クエリ
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）クエリ結果を回収するという 3 つのステップで非同期収益化レポートクエリを作成します。
クエリを送信するステップ 1 については後述します。
ステップ 2 と 3 は、非同期分析クエリの場合とまったく同じです。詳細については、非同期分析クエリを作成する方法をご覧ください。
非同期収益化レポートに対するクエリを送信するには、/mint/organizations/org_id/async-reports に POST リクエストを発行します。
オプションで、environment クエリ パラメータを渡すことで環境を指定できます。指定しなかった場合は、クエリ パラメータがデフォルトで prod に設定されます。次に例を示します。
/mint/organizations/org_id/async-reports?environment=prod
リクエスト本文で、次の検索条件を指定します。
| 名前 | 説明 | デフォルト | 必須 |
appCriteria |
レポートに含まれる特定のアプリケーションの ID と組織。このプロパティが指定されなかった場合は、すべてのアプリケーションがレポートに含まれます。 | なし | × |
billingMonth |
7 月などのレポートの請求月。 | なし | ○ |
billingYear |
2015 年などのレポートの請求年。 | なし | ○ |
currencyOption |
レポートの通貨。有効な値は次のとおりです。
EUR、GBP、または USD を選択した場合は、レポートに、取引日に有効な為替レートに基づいて、その単一通貨を使用するすべてのトランザクションが表示されます。 |
なし | × |
devCriteria
|
レポートに含まれる特定のデベロッパーのデベロッパー ID またはメールアドレスと組織名。このプロパティが指定されなかった場合は、すべてのデベロッパーがレポートに含まれます。 例: "devCriteria":[{
"id":"RtHAeZ6LtkSbEH56",
"orgId":"my_org"}
] |
なし | × |
fromDate
|
UTC でのレポートの開始日。 | なし | ○ |
monetizationPakageIds |
レポートに含める 1 つ以上の API パッケージの ID。このプロパティが指定されなかった場合は、すべての API パッケージがレポートに含まれます。 | なし | × |
productIds
|
レポートに含める 1 つ以上の API プロダクトの ID。このプロパティが指定されなかった場合は、すべての API プロダクトがレポートに含まれます。 | なし | × |
ratePlanLevels |
レポートに含める料金プランのタイプ。有効な値は次のとおりです。
このプロパティが指定されなかった場合は、デベロッパー固有の料金プランと標準料金プランの両方がレポートに含まれます。 |
なし | × |
toDate
|
UTC でのレポートの終了日。 | なし | ○ |
たとえば、次のリクエストは、指定された API プロダクトとデベロッパー ID の 2017 年 6 月の非同期収益化レポートを生成します。レポートの 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