本頁面由 Cloud Translation API 翻譯而成。

使用非同步自訂報表 API

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

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

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

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

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

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

比較報表 API 和 UI

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

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

使用 API 產生的報表與使用 UI 產生的報表的主要差異在於，前者會寫入 CSV 或 JSON (以換行符號分隔) 檔案，而後者則會顯示在 UI 中。

查詢時間限制

Apigee 會將非同步查詢的時間範圍限制在 365 天內。

如何建立非同步的數據分析查詢

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

提交查詢。
取得查詢狀態。
擷取查詢結果。

步驟 1：提交查詢

您必須將 POST 要求傳送至查詢 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

其中 $TOKEN 會設為您的 OAuth 2.0 存取權憑證，如取得 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：取得查詢狀態

如要要求查詢的狀態，請向查詢 API 傳送 GET 要求。您必須提供 POST 呼叫傳回的查詢 ID。例如：

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/queries/QUERY_ID" \
  -X GET \
  -H "Authorization: Bearer $TOKEN"

其中 $TOKEN 會設為您的 OAuth 2.0 存取權憑證，如取得 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 後，您可以使用兩種方法擷取查詢結果：

getResulturl (建議)：這是較新的做法，可傳回網址，讓您查看查詢結果。此方法對查詢結果的大小沒有限制。
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"

以下是呼叫的回應範例：

{
  "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 資料的已簽署網址。你可以透過以下網址查看這份報表。
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"

如要擷取已下載的檔案，您必須設定所用工具，讓該工具將已下載的檔案儲存到系統。例如：

如果您使用 cURL，可以使用 -O -J 選項，如上方所示。
如果您使用 Postman，請選取「Save and Download」按鈕。在本例中，系統會下載名為 response 的 ZIP 檔案。
如果您使用 Chrome 瀏覽器，系統會自動接受下載要求。

如果要求成功，且結果集不為零，結果會以壓縮的 JSON (以換行符號分隔) 檔案格式下載至用戶端。下載的檔案名稱會是 OfflineQueryResult-.zip。

例如 OfflineQueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.zip。

注意： 系統會下載 ZIP 檔案，因為 Apigee 需要花費很長的時間才能將結果合併。因此，基於效能考量，Apigee 會傳回包含結果部分的 ZIP 檔案。為避免這種情況，請改用 getResulturl 方法。

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_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`	指標陣列。您可以為查詢指定一或多個指標，每個指標都包含以下項目：只需要提供指標名稱： `name`：(必要) metrics 表格中定義的指標名稱。 `function`：(選用) 匯總函式，如 `avg`、`min`、`max` 或 `sum`。並非所有指標都支援所有匯總函式。指標說明文件包含一張表格，其中會指定指標名稱和指標支援的函式 (`avg`、`min`、`max`、`sum`)。 `alias`：(選用) 在輸出內容中包含成效資料的屬性名稱。如果省略，則預設為指標名稱與匯總函式名稱的組合。 `operator`：(選用) 在計算指標值後，要對指標執行的作業。可搭配 `value` 屬性使用。支援的作業包括：`+ - / % *`。 `value`：(選用) 指定 `operator` 時，套用至計算指標的值。 `operator` 和 `value` 屬性定義對指標執行的後置處理作業。舉例來說，如果您指定指標 `response_processing_latency`，該指標會傳回平均回應處理延遲時間，單位為毫秒。如要將單位轉換為秒，請將 `operator` 設為 `"/"`，並將 `value` 設為 `”1000.0“`： "metrics":[ { "name":"response_processing_latency", "function":"avg", "alias":"average_response_time_in_seconds", "operator":"/", "value":"1000" } ] 詳情請參閱「Analytics 指標、維度和篩選器參考資料」。	是
`dimensions`	用於將指標分組的維度陣列。詳情請參閱支援的維度清單。您可以指定多個維度。	是
`timeRange`	查詢的時間範圍。您可以使用下列預先定義字串指定時間範圍： `last60minutes` `last24hours` `last7days` 或者，您也可以將 `timeRange` 指定為結構，以 ISO 格式描述開始和結束時間戳記：`yyyy-mm-ddThh:mm:ssZ`。例如： "timeRange": { "start": "2018-07-29T00:13:00Z", "end": "2018-08-01T00:18:00Z" }	是
`limit`	結果中可傳回的列數上限。	否
`filter`	可用於篩選資料的布林值運算式。篩選器運算式可使用 AND/OR 運算子組合，且應加上完整的括號，以免造成歧義。如要進一步瞭解可用於篩選的欄位，請參閱「Analytics 指標、維度和篩選器參考資料」一文。如要進一步瞭解用於建構篩選運算式的符記，請參閱「篩選運算式語法」。	否
`groupByTimeUnit`	用於將結果集分組的時間單位。有效值包括：`second`、`minute`、`hour`、`day`、`week` 或 `month`。如果查詢包含 `groupByTimeUnit`，則結果會是根據指定的時間單位進行匯總，且產生的時間戳記不含毫秒精確度。如果查詢省略 `groupByTimeUnit`，則產生的時間戳記會包含毫秒精確度。	否
`outputFormat`	輸出格式。有效值包括：`csv` 或 `json`。預設為 `json`，對應於以換行符號分隔的 JSON。注意：請使用 `csvDelimiter` 屬性設定 CSV 輸出的分隔符號。	否
`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」邏輯來評估不同的可能篩選運算式。篩選器會納入至少符合一項條件的資料。	(response_size ge 1000) or (response_status_code eq 500)

限制和預設值

以下是非同步查詢處理功能的限制和預設值清單。

限制	預設	說明
查詢呼叫限制	請參閱說明	您每小時最多可以向 /queries Apigee API 發出七次呼叫，以啟動非同步報表。如果您超出呼叫配額，API 會傳回 HTTP 429 回應。
執行中查詢限制	10	一個機構/環境最多可有 10 個有效查詢。
查詢執行時間門檻	6 小時	執行時間超過 6 小時的查詢會遭到終止。
查詢時間範圍	請參閱說明	查詢的時間範圍上限為 365 天。
維度和指標限制	25	您可以在查詢酬載中指定的維度和指標數量上限。

關於查詢結果

以下是 JSON 格式的結果範例。您查看結果的方式取決於您用來擷取查詢結果的方法：

如果您使用 getResulturl 方法，可以透過結果的 uri 欄位提供的網址查看結果。此方法對查詢結果的大小沒有限制。
如果您使用 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"}    
…

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

範例

範例 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

來自 last60minutes.json 的 Request Body

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

自訂時間範圍.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 "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/queries" \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @tpm.json

來自 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

來自 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 "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/queries" \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @metricsExpression.json

metricsExpression.json 中的要求主體

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