非同期カスタム レポート API を使用する

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. クエリを送信します。

2. クエリ ステータスを取得します。

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":[
  {
    "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: 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

リクエスト本文で、次の検索条件を指定します。

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

たとえば、次のリクエストは、指定された 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