本頁適用於 Apigee 和 Apigee Hybrid。
查看
Apigee Edge 說明文件。
Apigee 會記錄各式各樣的 API 運作和業務資料。從這類資料衍生的指標可用於作業監控和業務監控。舉例來說，您可以使用 Apigee Analytics 判斷哪些 API 的運作效能良好或不佳、哪些開發人員帶來最高價值流量，以及哪些應用程式會對後端服務造成最多問題。
為了方便存取這類指標資料，請在需要自動執行特定分析功能 (例如使用自動化用戶端或指令碼定期擷取指標) 時，使用指標 API。您也可以使用 API 以自訂小工具的形式建立自己的圖表，並嵌入入口網站或自訂應用程式。
如要瞭解如何在 Apigee UI 中使用 Analytics，請參閱「Apigee Analytics 簡介」。
關於 Metrics API
您可以透過兩種方式使用 Metrics API：
- 取得機構和環境在一段時間內 (例如 1 小時、1 天或 1 週) 的各種指標。這個方法會針對整個機構和環境傳回原始指標。
例如，您想取得上週的以下資料：
- 政策錯誤數
- 平均回覆時間
- 總流量
取得機構和環境在一段時間內按維度分類的指標。
舉例來說，您可以使用維度將指標依 API 產品、API Proxy 和開發人員電子郵件 (也可以是 AppGroup ID) 分組，以便取得以下資訊：
- 每項 API 產品的政策錯誤數
- 每個 API Proxy 的平均回應時間
- 每封開發人員電子郵件的總流量
為了管理傳回的結果，Metrics API 支援下列功能：
詳情請參閱 指標 API 參考資料。
開始使用 Metrics API
指標 API 的要求網址如下：
https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats[dimension]
舉例來說，如要取得按 API proxy 分組的指標，請使用下列網址呼叫 Apigee API：
https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?timeRange=07/21/2018+00:00:00~08/23/2018+00:00:00
省略維度，即可針對指定時間範圍內的整個機構和環境傳回原始指標：
https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats?timeRange=07/21/2019+00:00:00~08/23/2018+00:00:00
指定要傳回的指標
使用
select查詢參數，指定要擷取的指標和選用的匯總函式，格式如下：?select=metric
或：
?select=aggFunction(metric)
其中：
- metric 會指定要傳回的資料。例如 API 要求、快取命中或政策錯誤的數量。請參閱指標，瞭解如何使用
select查詢參數指定指標名稱。 aggFunction 會指定針對指標執行的選用匯總函式。舉例來說，您可以使用下列匯總函式搭配處理延遲時間指標：
avg：傳回平均處理延遲時間。min：傳回最短的處理延遲時間。max：傳回處理的最大延遲時間。-
sum：傳回所有處理延遲時間的總和。 -
p50：傳回處理延遲時間的第 50 個百分位數。 -
p95：傳回處理延遲時間的第 95 個百分位數。 -
p99：傳回處理延遲時間的第 99 個百分位數。
並非所有指標都支援所有匯總函式。指標說明文件包含一張表格，其中會指定指標名稱和指標支援的函式 (
sum、avg、min、max)。
例如，如要傳回每秒的平均交易數 (即 API Proxy 要求)：
?select=tps
請注意，這個範例不需要匯總函式。以下範例使用匯總函式傳回快取命中次數的總和：
?select=sum(cache_hit)
您可以為單一 API 呼叫傳回多個指標。如要取得政策錯誤總數和平均要求大小的指標，請使用以半形逗號分隔的指標清單設定
select查詢參數：?select=sum(policy_error),avg(request_size)
指定時間範圍
指標 API 會傳回指定時間範圍內的資料。使用
timeRange(最多 6 個月) 查詢參數指定時間範圍，格式如下：?timeRange=MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM
請留意
HH:MM前面的%20。timeRange參數需要在HH:MM之前加上經過網址編碼的空格字元，或+字元，例如：MM/DD/YYYY+HH:MM~MM/DD/YYYY+HH:MM。例如：
?timeRange=03/01/2018%2000:00~03/30/2018%2023:59
請勿使用 24:00 做為時間，因為這會回繞到 00:00。請改用 23:59。
呼叫 Metrics API 的範例
本節提供使用指標 API 的範例。如需其他範例，請參閱「Metrics API 範例」。
傳回一個月內對 API 發出的呼叫總數
如要傳回機構和環境中所有 API 在一個月內的呼叫總數，請使用類似下方的呼叫：
curl -v "https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/?select=sum(message_count)&timeRange=03/01/2018%2000:00~03/31/2018%2023:59" \ -H "Authorization: Bearer $TOKEN"
其中
$TOKEN會設為您的 OAuth 2.0 存取權憑證，如取得 OAuth 2.0 存取權憑證一文所述。如要瞭解本範例中使用的curl選項，請參閱「使用 curl」。如要瞭解所使用的環境變數，請參閱「為 Apigee API 要求設定環境變數」。以下提供回應範例：
{ "environments": [ { "metrics": [ { "name": "sum(message_count)", "values": [ "7.44944088E8" ] } ], "name": "prod" } ], ... }傳回兩天內每個 API Proxy 的訊息總數
在這個範例中，您會傳回兩天期間內所有 API Proxy 收到的要求數量指標。
select查詢參數會為維度apiproxy上的指標message_count定義匯總函式sum。這份報表會以世界標準時間，針對 2018 年 6 月 20 日至 6 月 21 日期間收到的流量，針對所有 API 傳回要求訊息傳送量：curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59" \ -H "Authorization: Bearer $TOKEN"
其中
$TOKEN會設為您的 OAuth 2.0 存取權憑證，如取得 OAuth 2.0 存取權憑證一文所述。如要瞭解本範例中使用的curl選項，請參閱「使用 curl」。如要瞭解所使用的環境變數，請參閱「為 Apigee API 要求設定環境變數」。以下提供回應範例：
{ "environments" : [ { "dimensions" : [ { "metrics" : [ { "name" : "sum(message_count)", "values" : [ { "timestamp" : 1498003200000, "value" : "1100.0" } ] } ], "name" : "target-reroute" } ], "name" : "test" } ]... }這個回應表示，在 2018 年 6 月 20 日開始至 6 月 21 日結束期間，在測試環境中執行的一個名為「target-reroute」的 API 代理程式收到了 1100 則訊息。
如要取得其他維度的指標，請將其他維度指定為 URI 參數。舉例來說，您可以指定
developer_app維度，擷取開發人員應用程式的指標。以下 API 呼叫會傳回指定時間間隔內，任何應用程式傳送的總傳輸量 (已收到的訊息)：curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/developer_app?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59&timeUnit=day" \ -H "Authorization: Bearer $TOKEN"
以下提供回應範例：
{ "environments": [ { "dimensions": [ { "metrics": [ { "name": "sum(message_count)", "values": [ { "timestamp": 1498003200000, "value": "886.0" } ] } ], "name": "Test-App" }, { "metrics": [ { "name": "sum(message_count)", "values": [ { "timestamp": 1498003200000, "value": "6645.0" } ] } ], "name": "johndoe_app" }, { "metrics": [ { "name": "sum(message_count)", "values": [ { "timestamp": 1498003200000, "value": "1109.0" } ] } ], "name": "marys_app" } ]... }依據相對排名排序結果
在取得指標時，您通常只想取得總資料集的子集結果。通常您需要取得「前 10 名」的結果，例如「速度最慢的 API 前 10 名」、「最活躍的應用程式前 10 名」。您可以使用
topk查詢參數做為要求的一部分來執行這項操作。舉例來說，您可能想知道哪些開發人員是效能最高的 (以吞吐量為準)，或是哪些開發人員的效能最差 (目標 API 的「最慢」(「top slowest」) 是根據延遲時間排序。
topk(意指「前 k 名」實體) 可針對特定指標最高值相關聯的實體產生報表。這可讓您針對列出特定條件的實體清單篩選指標。舉例來說，如要找出過去一週內哪個目標網址最容易發生錯誤，請將
topk參數附加至要求，並將1設為值：curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/target_url?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&topk=1" \ -H "Authorization: Bearer $TOKEN"
其中
$TOKEN會設為您的 OAuth 2.0 存取權憑證，如取得 OAuth 2.0 存取權憑證一文所述。如要瞭解本範例中使用的curl選項，請參閱「使用 curl」。如要瞭解所使用的環境變數，請參閱「為 Apigee API 要求設定環境變數」。以下提供回應範例：
{ "environments": [ { "dimensions": [ { "metrics": [ { "name": "sum(is_error)", "values": [ { "timestamp": 1494201600000, "value": "12077.0" } ] } ], "name": "http://api.company.com" } ]... }這項要求的結果是一組指標，顯示最容易發生錯誤的目標網址為
http://api.company.com。您也可以使用
topk參數，為傳輸量最高的 API 進行排序。以下範例會根據上週最高的總處理量，擷取排名前幾名的 API 指標：curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV}/stats/apiproxy?"select=sum(message_count)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=day&sortby=sum(message_count)&sort=DESC&topk=1" \ -H "Authorization: Bearer $TOKEN"
以下提供回應範例：
{ "environments": [ { "dimensions": [ { "metrics": [ { "name": "sum(message_count)", "values": [ { "timestamp": 1494720000000, "value": "5750.0" }, { "timestamp": 1494633600000, "value": "5752.0" }, { "timestamp": 1494547200000, "value": "5747.0" }, { "timestamp": 1494460800000, "value": "5751.0" }, { "timestamp": 1494374400000, "value": "5753.0" }, { "timestamp": 1494288000000, "value": "5751.0" }, { "timestamp": 1494201600000, "value": "5752.0" } ] } ], "name": "testCache" } ], "name": "test" } ]... }篩選結果
如要取得更精細的資料，您可以篩選結果，限制傳回的資料。使用篩選器時，您必須使用維度做為篩選器屬性。
舉例來說，假設您需要從後端服務中擷取錯誤數量，並根據要求的 HTTP 動詞進行篩選。您的目標是找出每項後端服務產生多少個 POST 和 PUT 要求錯誤。如要這麼做，請使用維度
target_url搭配篩選器request_verb：curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/target_url?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&filter=(request_verb%20in%20'POST','PUT')" \ -H "Authorization: Bearer $TOKEN"
其中
$TOKEN會設為您的 OAuth 2.0 存取權憑證，如取得 OAuth 2.0 存取權憑證一文所述。如要瞭解本範例中使用的curl選項，請參閱「使用 curl」。如要瞭解所使用的環境變數，請參閱「為 Apigee API 要求設定環境變數」。以下提供回應範例：
{ "environments" : [ { "dimensions" : [ { "metrics" : [ { "name" : "sum(is_error)", "values" : [ { "timestamp" : 1519516800000, "value" : "1.0" } ] } ], "name" : "testCache" } ], "name" : "test" } ]... }分頁顯示結果
在實際工作環境中，對 Apigee Analytics API 提出的部分要求會傳回非常大的資料集。為在以 UI 為基礎的應用程式中輕鬆顯示大型資料集，API 原生支援分頁功能。
如要分頁顯示結果，請使用
offset和limit查詢參數，並搭配sortby排序參數，確保項目的排序一致。舉例來說，下列要求可能會傳回大型資料集，因為它會擷取產品環境中上週所有 API 的所有錯誤指標。
curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)" \ -H "Authorization: Bearer $TOKEN"
其中
$TOKEN會設為您的 OAuth 2.0 存取權憑證，如取得 OAuth 2.0 存取權憑證一文所述。如要瞭解本範例中使用的curl選項，請參閱「使用 curl」。如要瞭解所使用的環境變數，請參閱「為 Apigee API 要求設定環境變數」。如果您的 UI 應用程式可合理地在每個網頁上顯示 50 個結果，您可以將限制設為 50。由於 0 會計為第一個項目，因此下列呼叫會以遞減順序傳回 0 到 49 的項目 (
sort=DESC是預設值)。curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&limit=50&offset=0" \ -H "Authorization: Bearer $TOKEN"
如要取得第二個「頁面」的結果，請使用 offset 查詢參數，如下所示。請注意，限制和偏移值相同。這是因為 0 會計為第一個項目。上限為 50，偏移量為 0，會傳回 0 到 49 的項目。偏移量為 50 時，系統會傳回 50 到 99 的項目。
curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&limit=50&offset=50" \ -H "Authorization: Bearer $TOKEN"