このページの内容は Apigee と Apigee ハイブリッドに該当します。
Apigee Edge のドキュメントを表示する
Apigee Analytics は、インタラクティブ ダッシュボード、カスタム レポート生成ツールと関連機能の豊富なセットを提供します。ただし、これらの機能はインタラクティブであることを目的としています。つまり、API または UI リクエストを送信すると、分析サーバーがレスポンスを提供するまでそのリクエストはブロックされます。
ただし、分析リクエストは、完了までに時間がかかりすぎるとタイムアウトすることがあります。クエリ リクエストが大量のデータ（例: 数百 GB）を処理する必要がある場合は、タイムアウトのために失敗する可能性があります。
非同期クエリ処理を使用すると、非常に大きいデータセットに対してクエリを実行し、その後に結果を取得できます。インタラクティブ クエリがタイムアウトすることがわかった場合は、オフライン クエリの使用を検討してください。次のような状況では、非同期クエリ処理が適切な代替手段になることがあります。
- レポートの分析と作成に長い時間がかかる場合。
- グループ化のディメンションが多いなど、クエリを複雑にする制約のあるデータを分析する場合。
- 一部のユーザーや組織のデータ量が大幅に増加したことが判明したときにクエリを管理する場合。
このドキュメントでは、API を使用して非同期クエリを開始する方法について説明します。カスタム レポートの実行で説明されているように、UI を使用することもできます。
レポート API と UI の比較
カスタム レポートの作成と管理には、Apigee UI を使用してカスタム レポートを作成して実行する方法が記載されています。これらのレポートは同期的または非同期的に実行できます。
UI を使用してカスタム レポートを生成する場合のコンセプトの大部分は、API を使用する場合に当てはまります。つまり、API を使用してカスタム レポートを作成するときに、Apigee に組み込まれている指標、ディメンション、フィルタを指定します。
API を使用して生成されたレポートと UI を使用して生成されたレポートを比較した場合の主な違いは、前者は CSV または JSON（改行区切り）ファイルに書き込まれますが、後者は UI に表示されることです。
クエリの制限時間
Apigee では非同期クエリの時間範囲には、365 日の上限が適用されます。
非同期分析クエリの作成方法
非同期分析クエリは、次の 3 つのステップで作成します。
ステップ 1. クエリを送信する
POST リクエストを Queries API に送信する必要があります。この API は、バックグラウンドでリクエストを処理するよう Apigee に指示します。クエリの送信が成功すると、API は 201 ステータスと ID を返します。この ID は、後の手順でクエリを参照するために使用します。
次に例を示します。
curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/queries" \ -X POST \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d @json-query-file
ここで、OAuth 2.0 アクセス トークンの取得で説明されているように、$TOKEN は OAuth 2.0 アクセス トークンに設定されます。この例で使用されている curl オプションの詳細については、curl の使用をご覧ください。使用される環境変数の説明については、Apigee API リクエストの環境変数の設定をご覧ください。
リクエストの本文は、クエリの 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 リクエストを Queries API に送信します。POST 呼び出しから返されたクエリ ID を指定します。次に例を示します。
curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/queries/QUERY_ID" \ -X GET \ -H "Authorization: Bearer $TOKEN"
ここで、OAuth 2.0 アクセス トークンの取得で説明されているように、$TOKEN は OAuth 2.0 アクセス トークンに設定されます。この例で使用されている curl オプションの詳細については、curl の使用をご覧ください。使用される環境変数の説明については、Apigee API リクエストの環境変数の設定をご覧ください。
サンプル レスポンス
クエリが処理中の場合は、次のようなレスポンスが返されます。ここでは、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 になったら、次の 2 つの方法でクエリ結果を取得できます。
getResulturl（推奨）: クエリ結果を表示できる URL を返す新しいメソッドです。このメソッドでは、クエリの結果のサイズに制限はありません。getResult: クエリ結果を含む zip ファイルをダウンロードするための古い方法です。この方法では、クエリの結果に 32 MB のサイズ上限が適用されます。
以下のタブでは、どちらの方法を使用してもクエリ結果を取得するための API 呼び出しを示しています。前述のとおり、クエリ ID は 9cfc0d85-0f30-46d6-ae6f-318d0cb961bd です。
getResulturl（推奨）
curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/queries/QUERY_ID/resulturl" \ -X GET \ -H "Authorization: Bearer $TOKEN"
ここで、OAuth 2.0 アクセス トークンの取得で説明されているように、$TOKEN は OAuth 2.0 アクセス トークンに設定されます。この例で使用されている curl オプションの詳細については、curl の使用をご覧ください。使用される環境変数の説明については、Apigee API リクエストの環境変数の設定をご覧ください。
次に、呼び出しに対するレスポンスの例を示します。
{
"urls": [
"uri": "https://storage.googleapis.com/example-bucket/cat.jpeg?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=example%40example-project.iam.gserviceaccount.com%2F20181026%2Fus-central1%2Fstorage%2Fgoog4_request&X-Goog-Date=20181026T181309Z&X-Goog-Expires=900&X-Goog-SignedHeaders=host&X-Goog-Signature=247a2aa45f169edf4d187d54e7cc46e4731b1e6273242c4f4c39a1d2507a0e58706e25e3a85a7dbb891d62afa8496def8e260c1db863d9ace85ff0a184b894b117fe46d1225c82f2aa19efd52cf21d3e2022b3b868dcc1aca2741951ed5bf3bb25a34f5e9316a2841e8ff4c530b22ceaa1c5ce09c7cbb5732631510c20580e61723f5594de3aea497f195456a2ff2bdd0d13bad47289d8611b6f9cfeef0c46c91a455b94e90a66924f722292d21e24d31dcfb38ce0c0f353ffa5a9756fc2a9f2b40bc2113206a81e324fc4fd6823a29163fa845c8ae7eca1fcf6e5bb48b3200983c56c5ca81fffb151cca7402beddfc4a76b133447032ea7abedc098d2eb14a7",
"md5": "23db6982caef9e9152f1a5b2589e6ca3",
"sizeBytes": 1024
]
}レスポンスには、次のフィールドを含むリスト urls[] が含まれます。
uri: レポートの JSON データの署名付き URL の文字列。レポートは URL で確認できます。md5: JSON データの MD5 ハッシュ。sizeBytes: ファイルのサイズ（バイト単位）。
JSON 形式の結果のサンプルについては、クエリ結果についてをご覧ください。
getResult
curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/queries/QUERY_ID/result" \ -X GET \ -H "Authorization: Bearer $TOKEN"
ここで、OAuth 2.0 アクセス トークンの取得で説明されているように、$TOKEN は OAuth 2.0 アクセス トークンに設定されます。この例で使用されている curl オプションの詳細については、curl の使用をご覧ください。使用される環境変数の説明については、Apigee API リクエストの環境変数の設定をご覧ください。
ダウンロードしたファイルを取得するには、ダウンロードしたファイルをシステムに保存するよう、使用するツールを構成する必要があります。次に例を示します。
- 上で示したように、cURL を使用する場合は、
-O -Jオプションを使用できます。 - Postman を使用する場合は、[Save and Download] ボタンを選択する必要があります。この場合は、
responseという名前の zip ファイルがダウンロードされます。 - Chrome ブラウザを使用している場合は、ダウンロードが自動的に受け入れられます。
リクエストが成功し、0 以外の結果セットが存在する場合は、結果が圧縮された JSON（改行区切り）ファイルとしてクライアントにダウンロードされます。ダウンロードされるファイルの名前は OfflineQueryResult- です。
例: 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_display_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 Apigee API に対して 1 時間に最大 7 回までの呼び出しが可能です。呼び出しの割り当てを超えた場合、API は HTTP 429 レスポンスを返します。 |
| アクティブ クエリの上限 | 10 | 組織 / 環境に対して最大 10 個のアクティブ クエリを使用できます。 |
| クエリ実行時間のしきい値 | 6 時間 | 6 時間以上かかるクエリは強制終了されます。 |
| クエリの時間間隔 | 説明をご覧ください。 | クエリの最大許容時間範囲は 365 日です。 |
| ディメンションと指標の上限 | 25 | クエリ ペイロードで指定可能なディメンションと指標の最大数。 |
クエリ結果について
JSON 形式の結果の例を以下に示します。結果の表示方法は、クエリ結果の取得に使用した方法によって異なります。
- メソッド
getResulturlを使用した場合は、結果のuriフィールドで指定された URL で結果を表示できます。このメソッドでは、クエリの結果のサイズに制限はありません。 getResultメソッドを使用した場合は、結果が zip ファイルでダウンロードされます。getResultメソッドでは、クエリの結果に 32 MB のサイズ上限が適用されます。結果が 32 MB を超える場合は、400 ステータス コードと「クエリ結果が 32 MB を超えています」というメッセージが返されます。この上限を回避するには、クエリ結果を取得するで説明されているように、メソッドgetReulturlを使用します。
次の例に示すように、結果は改行区切り文字で区切られた 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 "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/queries" \ -X POST \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d @last60minutes.json
ここで、OAuth 2.0 アクセス トークンの取得で説明されているように、$TOKEN は OAuth 2.0 アクセス トークンに設定されます。この例で使用されている curl オプションの詳細については、curl の使用をご覧ください。使用される環境変数の説明については、Apigee API リクエストの環境変数の設定をご覧ください。
last60minutes.json からのリクエストの本文
{
"metrics":[
{
"name":"message_count",
"function":"sum"
}
],
"dimensions":[
"apiproxy"
],
"groupByTimeUnit":"minute",
"limit":1000,
"timeRange":"last60minutes"
}
例 2: カスタム時間範囲
カスタム時間範囲を使用したクエリ。
クエリ
curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/queries" \ -X POST \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d @custom-timerange.json
ここで、OAuth 2.0 アクセス トークンの取得で説明されているように、$TOKEN は OAuth 2.0 アクセス トークンに設定されます。この例で使用されている curl オプションの詳細については、curl の使用をご覧ください。使用される環境変数の説明については、Apigee API リクエストの環境変数の設定をご覧ください。
custom-timerange.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 "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/queries" \ -X POST \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d @tpm.json
ここで、OAuth 2.0 アクセス トークンの取得で説明されているように、$TOKEN は OAuth 2.0 アクセス トークンに設定されます。この例で使用されている curl オプションの詳細については、curl の使用をご覧ください。使用される環境変数の説明については、Apigee API リクエストの環境変数の設定をご覧ください。
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 "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/queries" \ -X POST \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d @filterCombo.json
ここで、OAuth 2.0 アクセス トークンの取得で説明されているように、$TOKEN は OAuth 2.0 アクセス トークンに設定されます。この例で使用されている curl オプションの詳細については、curl の使用をご覧ください。使用される環境変数の説明については、Apigee API リクエストの環境変数の設定をご覧ください。
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 "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/queries" \ -X POST \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d @metricsExpression.json
ここで、OAuth 2.0 アクセス トークンの取得で説明されているように、$TOKEN は OAuth 2.0 アクセス トークンに設定されます。この例で使用されている curl オプションの詳細については、curl の使用をご覧ください。使用される環境変数の説明については、Apigee API リクエストの環境変数の設定をご覧ください。
metricsExpression.json からのリクエストの本文
{
"metrics":[
{
"name":"message_count",
"function":"sum",
"operator":"/",
"value":"7"
}
],
"dimensions":[
"apiproxy"
],
"groupByTimeUnit":"minute",
"limit":10,
"timeRange":"last60minutes"
}