使用非同步自訂報表 API

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊

Edge Analytics 提供豐富的互動式資訊主頁、自訂報表產生器和相關功能。然而，這些功能的目的在於互動：您提交 API 或 UI 要求，但會在分析伺服器提供回應之前封鎖要求。

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

非同步查詢處理功能可讓您查詢非常龐大的資料集，並於日後擷取結果。如果互動式查詢逾時，您可以考慮使用離線查詢。非同步查詢處理作業在某些情況下，可能是不錯的替代方案：

• 分析及建立橫跨大量時間間隔的報表。
• 使用各種分組維度和其他限制來分析資料，增加查詢的複雜度。
• 當您發現某些使用者或機構的資料量大幅增加時，就可以管理查詢。

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

比較報表 API 與使用者介面

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

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

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

Apigee Hybrid 的限制

Apigee Hybrid 對結果資料集強制執行 30 MB 的大小限制。

如何建立非同步分析查詢

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

1. 提交查詢。

2. 取得查詢狀態。

3. 擷取查詢結果。

步驟 1：提交查詢

您必須傳送 POST 要求至 /queries 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 主體中，指定定義報表的metrics、維度和篩選器。

以下為 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，則必須選取「儲存並下載」按鈕。此時，系統會下載名為 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 的要求主體

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

來自 metricExpression.json 的要求主體

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum",
         "operator":"/",
         "value":"7"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":10,
   "timeRange":"last60minutes"
}

如何建立非同步營利報表查詢

你可以按照本節所述的步驟，擷取特定時間範圍內在某組條件內成功的所有營利交易。

與非同步分析查詢一樣，您可以透過三個步驟執行非同步營利報表查詢：(1) 提交查詢、(2) 取得查詢狀態，以及 (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