使用非同步自訂報表 API

您正在查看 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

Edge Analytics 提供豐富的互動式資訊主頁、自訂報表產生器和相關功能。不過，這些功能的設計目的是提供互動功能：您提交 API 或 UI 要求後，系統會將要求封鎖，直到數據分析伺服器提供回應為止。

不過，如果數據分析要求耗時過長，就可能會逾時。如果查詢要求需要處理大量資料 (例如 100 GB)，可能會因逾時而失敗。

非同步查詢處理功能可讓您查詢非常大型的資料集，並在稍後擷取結果。如果發現互動式查詢逾時，您可以考慮使用離線查詢。以下是一些非同步查詢處理作業可能較佳的替代方案：

• 分析並建立跨越長時間間隔的報表。
• 使用各種分組維度和其他限制來分析資料，這會使查詢變得複雜。
• 當您發現部分使用者或機構的資料量大幅增加時，請管理查詢。

本文說明如何使用 API 啟動非同步查詢。您也可以使用 UI，如「執行自訂報表」一節所述。

比較報表 API 和 UI

「建立及管理自訂報表」一文說明如何使用 Edge UI 建立及執行自訂報表。您可以同步或非同步執行這些報表。

使用 UI 產生自訂報表時，大部分的概念也適用於使用 API。也就是說，使用 API 建立自訂報表時，您可以指定指標、維度和 Edge 內建的篩選器，以及使用StatisticsCollector 政策建立的任何自訂指標。

在使用者介面和 API 中產生的報表之間，主要的差異在於，使用 API 產生的報表會寫入 CSV 或 JSON (以換行符號分隔) 檔案，而不是在使用者介面中顯示的視覺報表。

Apigee Hybrid 的限制

Apigee hybrid 對結果資料集強制規定 30 MB 的大小限制。

如何提出非同步數據分析查詢

您可以透過三個步驟建立非同步的數據分析查詢：

1. 提交查詢。

2. 取得查詢狀態。

3. 擷取查詢結果。

步驟 1：提交查詢

您必須向 /queries API 傳送 POST 要求。這個 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 瀏覽器，系統會自動接受下載要求。

如果要求成功，且結果集不為零，結果會以壓縮 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 要求主體中用於查詢的各個參數。如要進一步瞭解可在查詢中使用的指標和維度，請參閱「Analytics 參考資料」。

{  
   "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"}    
…

您可以從網址擷取結果，直到存放區中的資料到期為止。請參閱「限制和預設值」。

範例

範例 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 的 Request Body

{  
   "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：每分鐘交易數

查詢每分鐘交易數 (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 與非同步 Analytics 查詢完全相同。詳情請參閱「如何建立非同步 Analytics 查詢」一文。

如要提交非同步營利報表的查詢，請向 /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 日期和時間以世界標準時間/格林威治標準時間為準，且可能包含時間。

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