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

使用 Metrics API (tf.metrics)

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

查看 Apigee Edge 說明文件。

Apigee 會記錄各個 API 的運作與業務資料。從這類資料得出的指標有助於監控作業和業務。舉例來說，您可以透過 Apigee Analytics 判斷哪些 API 的運作效能良好或不佳、哪些開發人員帶來的流量價值最高，以及哪些應用程式造成後端服務的問題最多。

如要輕鬆存取這項指標資料，請在需要自動執行特定分析功能時使用指標 API，例如使用自動化用戶端或指令碼定期擷取指標。您也可以使用 API 建立自己的視覺化內容，以自訂小工具的形式嵌入入口網站或自訂應用程式。

如要瞭解如何在 Apigee UI 中使用 Analytics，請參閱「Apigee Analytics 總覽」。

關於 Metrics API

您可以使用指標 API 的方式有兩種：

取得機構和環境在一段時間內的指標，例如一小時、一天或一週。這個方法會傳回整個機構和環境的原始指標。
舉例來說，您想取得上週的資料：
- 政策錯誤數
- 平均回覆時間
- 總流量
取得一段時間內，依機構和環境維度整理的指標。

舉例來說，您可以針對上週使用維度，依據 API 產品、API Proxy 和開發人員電子郵件地址 (也可以是 AppGroup ID) 將指標分組，以取得：
- 每個 API 產品的政策錯誤數
- 每個 API Proxy 的平均回應時間
- 每個開發人員電子郵件地址的總流量
如要管理傳回的結果，指標 API 支援下列功能：
詳情請參閱指標 API 參考資料。

開始使用指標 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 個百分位數，使用 percentile(latency_metric,50)&aggTable=agg_percentile 計算。
  - p95：傳回使用 percentile(latency_metric,95)&aggTable=agg_percentile 計算的處理延遲時間第 95 個百分位數。
  - p99：傳回使用 percentile(latency_metric,99)&aggTable=agg_percentile 計算的處理延遲時間第 99 個百分位數。
  latency_metric 可以是：
  - total_response_time
  - target_response_time
  - response_processing_latency
  - request_processing_latency
  並非所有指標都支援所有匯總函式。指標說明文件包含一個表格，其中會指定指標名稱和指標支援的函式 (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。

注意：如要瞭解資料保留時間長度，請參閱 Apigee 方案頁面。

呼叫 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 日初至 2018 年 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 日到 2018 年 6 月 21 日之間，名為「target-reroute」的 API Proxy 在測試環境中收到 1100 則訊息。

提示：請注意，時間戳記 1498003200000 採用 Unix 時間戳記格式。網路上有許多 Unix 時間戳記轉換工具，可用來解碼這些時間戳記。

如要取得其他維度的指標，請將其他維度指定為 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 名」的結果，例如「前 10 個最慢的 API」、「前 10 個最活躍的應用程式」。如要這麼做，請在要求中加入 topk 查詢參數。

舉例來說，您可能想知道以輸送量為準，哪些開發人員的表現最出色，或是哪些開發人員的表現最差 (也就是「延遲時間最長」目標 API。

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 要求設定環境變數。

注意：篩選器文字必須以單引號括住，例如 'POST'。請勿使用雙引號。

以下是回應範例：
```
{
  "environments" : [
    {
      "dimensions" : [
        {
          "metrics" : [
            {
              "name" : "sum(is_error)",
              "values" : [
                {
                  "timestamp" : 1519516800000,
                  "value" : "1.0"
                }
              ]
          }
        ],
        "name" : "testCache"
        }
      ],
      "name" : "test"
    }
  ]...
}
```
結果分頁

在實際工作環境中，部分對 Apigee 數據分析 API 的要求會傳回非常大的資料集。為了方便在以 UI 為基礎的應用程式中顯示大型資料集，這個 API 原生支援分頁功能。

如要將結果分頁，請使用 offset 和 limit 查詢參數，以及 sortby 排序參數，確保項目排序一致。

注意：分頁顯示結果時，請務必使用 sortby 查詢參數，以可預測的方式排序結果。如果沒有排序，結果會以無法預測的順序傳回，這會失去分頁的意義。
sortby 值必須與 select 查詢參數中使用的值相同。舉例來說，如果 select=sum(message_count)，則為 sortby=sum(message_count)。

舉例來說，下列要求可能會傳回大型資料集，因為這項要求會擷取產品環境中所有 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"
```

使用 Metrics API (tf.metrics) 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

關於 Metrics API

開始使用指標 API

指定要傳回的指標

指定時間範圍

呼叫 Metrics API 的範例

依相對排名排序結果

篩選結果

結果分頁

使用 Metrics API (tf.metrics)