使用非同步自訂報表 API

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

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

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

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

  • 分析及建立涵蓋長時間間隔的報表。
  • 使用各種分組維度和其他限制條件分析資料，導致查詢變得複雜。
  • 如果發現部分使用者或機構的資料量大幅增加，請管理查詢。

本文說明如何使用 API 啟動非同步查詢。您也可以按照「執行自訂報表」一文的說明，使用使用者介面。

比較 Reports API 與使用者介面

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

使用 API 生成自訂報表時，大部分概念都與使用 UI 相同。 也就是說，使用 API 建立自訂報表時，您會指定 Apigee 內建的指標、維度和篩選器。

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

查詢時間限制

Apigee 會強制執行非同步查詢的時間範圍上限 (365 天)。

如何提出非同步分析查詢

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

  1. 提交查詢。

  2. 取得查詢狀態。

  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

其中 $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 之外，state 的 enqueued 也表示要求成功。

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"

其中 $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。

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

其中 $TOKEN 會設為您的 OAuth 2.0 存取權杖，如「取得 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 資料的已簽署網址。您可以在該網址查看報表。
  • 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"

其中 $TOKEN 會設為您的 OAuth 2.0 存取權杖，如「取得 OAuth 2.0 存取權杖」一文所述。如要瞭解本範例使用的 curl 選項，請參閱「使用 curl」。如要瞭解可使用的環境變數，請參閱為 Apigee API 要求設定環境變數。

如要擷取下載的檔案，您需要設定使用的工具，讓工具將下載的檔案儲存到系統中。例如：

  • 如果您使用 cURL，可以如上所示使用 -O -J 選項。
  • 如果你使用 Postman，請選取「Save and Download」(儲存並下載) 按鈕。在這種情況下，系統會下載名為 response 的 ZIP 檔案。
  • 如果您使用 Chrome 瀏覽器，系統會自動接受下載。

如果要求成功，且結果集不為零，系統會將結果下載至用戶端，並以換行符號分隔的 JSON 檔案壓縮。下載的檔案名稱為 OfflineQueryResult-.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_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：(必要) 指標名稱，如指標表格所定義。

  • 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"
  }
]

詳情請參閱「數據分析指標、維度和篩選器參考資料」。

 是
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 字詞組合，且應完全以半形括號括住，以免產生模稜兩可的結果。如要進一步瞭解可供篩選的欄位，請參閱「數據分析指標、維度和篩選器參考資料」。如要進一步瞭解用於建構篩選運算式的權杖，請參閱「篩選運算式語法」。 否
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。

右側範例的相符情形如下：

- 含有「購買」一詞的任何值

- 任何以「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 可使用「或」邏輯評估不同的可能篩選運算式。篩選器會納入符合至少一項條件的資料。 
(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 狀態碼，並顯示「query result is larger than 32 MB」(查詢結果大於 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

其中 $TOKEN 會設為您的 OAuth 2.0 存取權杖，如「取得 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

其中 $TOKEN 會設為您的 OAuth 2.0 存取權杖，如「取得 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：每分鐘交易數

查詢每分鐘交易數 (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

其中 $TOKEN 會設為您的 OAuth 2.0 存取權杖，如「取得 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

其中 $TOKEN 會設為您的 OAuth 2.0 存取權杖，如「取得 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：在指標參數中傳遞運算式

使用運算式查詢，該運算式會做為指標參數的一部分傳入。您只能使用簡單的單一運算子運算式。

查詢

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

其中 $TOKEN 會設為您的 OAuth 2.0 存取權杖，如「取得 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"
}