使用 Metrics API

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

Apigee Edge 會記錄跨 API 的多種作業與業務資料。從這項資料衍生的指標可以用於作業監控和業務監控。舉例來說,您可以透過 Edge API Analytics 判斷哪些 API 的執行成效良好或不佳、哪些開發人員帶來最高價值流量,以及哪些應用程式造成後端服務的問題最多。

為協助您輕鬆存取這些指標資料,Edge 提供符合 REST 樣式的 API。如果需要自動處理特定 Analytics (分析) 函式 (例如透過自動化用戶端或指令碼定期擷取指標),您可以使用 Metrics API。此外,這個 API 也能用來建構自己的視覺化圖表,並嵌入入口網站或自訂應用程式中。

如要瞭解如何在 API Edge 管理 UI 中使用 Analytics (分析),請參閱「API 數據分析總覽」一文。

關於 Metrics API

Edge 提供兩項指標 API:

  • 取得指標會傳回機構和環境在一段時間內 (例如一小時、一天或一週) 的指標。

    例如,若要取得上週的資料:

    • 政策錯誤數量
    • 平均回覆時間
    • 總流量
  • 取得依維度整理的指標:系統會傳回一段時間內的指標,方便您維度分組的機構和環境。

    舉例來說,就上週的資料使用維度按 API 產品、API Proxy 和開發人員電子郵件地址分組指標,即可取得下列資料:

    • 每個 API 產品的政策錯誤數量
    • 每個 API Proxy 的平均回應時間
    • 每位開發人員電子郵件地址的總流量

    取得按維度分類的指標」 API 支援 取得指標 API 不支援的其他功能,包括:

關於 Metrics API 配額

邊緣會針對這些呼叫強制執行下列配額。配額是以處理呼叫的後端系統為基礎:

  • Postgres:每分鐘 40 次呼叫
  • BigQuery:每分鐘 12 次呼叫

檢查回應物件,找出處理呼叫的後端系統。每個回應物件都包含 metaData 屬性,該屬性會列出在 Source 屬性中處理呼叫的服務。例如 Postgres:

{
  ...
  "metaData": {
    "errors": [],
    "notices": [
      "Source:Postgres",
      "Table used: xxxxxx.yyyyy",
      "query served by:111-222-333"
    ]
  }
}

如果是 BigQuery,Source 屬性為:

"Source:Big Query"

如果您超過呼叫配額,API 會傳回 HTTP 429 回應。

使用 Management API 取得指標

這兩個 API 的主要差異在於,「取得指標」會傳回整個機構組織和環境的原始指標;而「依維度取得指標」則可讓您依不同實體類型 (例如 API 產品、開發人員和應用程式) 將指標分組。

取得指標 API 的要求網址如下:

https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats

如要使用依維度整理指標 API,您可以在 /stats 後方加入額外資源,指定所需的維度

https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/dimension

例如,如要取得依 API Proxy 分組的指標,可以使用下列網址呼叫 Management API:

https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/apiproxy

指定要傳回的指標

對於取得指標取得依維度分類的指標 API,您可以使用 select 查詢參數,指定要擷取的metrics和選用的匯總函式,格式如下:

?select=metric

或是:

?select=aggFunction(metric)

在此情況下:

  • metric 會指定您要傳回的資料。例如 API 要求數量、快取命中或政策錯誤。請參閱metrics,瞭解指定將指標名稱與 select 查詢參數搭配使用的指標名稱。
  • aggFunction 會指定對指標執行的選用匯總函式。舉例來說,您可以搭配使用下列匯總函式與處理延遲時間指標:

    • avg:傳回平均處理延遲時間。
    • min:傳回最短處理延遲時間。
    • max:傳回最大處理延遲時間。
    • sum:傳回所有處理延遲時間的總和。

    並非所有指標都支援所有匯總函式。metrics說明文件包含指定指標名稱的資料表,以及指標支援的函式 (sumavgminmax)。

舉例來說,如要傳回平均交易次數 (亦即 API Proxy 要求),您可以:

?select=tps

請注意,這個範例不需要匯總函式。下一個範例使用匯總函式傳回快取命中的總和:

?select=sum(cache_hit)

您可以針對單一 API 呼叫傳回多個指標。如要取得政策錯誤總和和平均要求大小的指標,請使用以逗號分隔的指標清單設定 select 查詢參數:

?select=sum(policy_error),avg(request_size)

指定時間範圍

Metrics API 會在指定期間內傳回資料。請使用 timeRange 查詢參數來指定時間範圍,格式如下:

?timeRange=MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM

請留意 HH:MM 之前的 %20timeRange 參數需要 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。

使用分隔符號

如要在 API 呼叫中分隔多個維度,請使用半形逗號 (,) 做為分隔符號。例如,在 API 呼叫中

curl https://api.enterprise.apigee.com/v1/o/myorg/e/prod/stats/apis,apps?select=sum(message_count)&timeRange=9/24/2018%2000:00~10/25/2018%2000:00&timeUnit=day

維度 apisapps 之間以 , 分隔。

API 呼叫範例

本節提供使用「取得指標」和「依維度分類指標」的範例 API。如需其他範例,請參閱 Metrics API 範例

傳回一個月內對 API 發出的呼叫總數

如要查看貴機構中在一個月內對所有 API 發出的呼叫總數,請使用 取得指標 API:

curl -v "https://api.enterprise.apigee.com/v1/o/{org}/e/{env}/stats/?select=sum(message_count)&timeRange=03/01/2018%2000:00~03/31/2018%2023:59" \
-u email:password

回應範例:

{
  "environments": [
    {
      "metrics": [
        {
          "name": "sum(message_count)",
          "values": [
            "7.44944088E8"
          ]
        }
      ],
      "name": "prod"
    }
  ],
...
}

傳回每個 API Proxy 兩天內每個 API Proxy 的訊息總數

在這個範例中,您要傳回所有 API Proxy 在兩天內接收的要求數量指標。select 查詢參數會針對維度「apiproxy」中的指標 message_count 定義匯總函式 sum。這份報表會針對從世界標準時間 2018 年 6 月 20 日開始到 2018 年 6 月 21 日結束前收到的所有 API 傳回要求訊息處理量:

curl  https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59" \
-u email:password

回應範例:

{
  "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 則訊息。

如要取得其他維度的指標,請指定其他維度做為 URI 參數。舉例來說,您可以指定 developer_app 維度來擷取開發人員應用程式的指標。下列 API 呼叫會傳回指定時間間隔內來自所有應用程式的處理量 (收到的訊息):

curl  https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/developer_app?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59&timeUnit=day" \
-u email:password

回應範例:

{
  "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://api.enterprise.apigee.com/v1/o/{org_name}/e/{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" \
  -u email:password
{
  "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://api.enterprise.apigee.com/v1/o/{org_name}/e/{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" \
-u email:password

回應範例

{
  "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://api.enterprise.apigee.com/v1/o/{org_name}/e/{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')" \
-u email:password

回應範例:

{
  "environments" : [
    {
      "dimensions" : [
        {
          "metrics" : [
            {
              "name" : "sum(is_error)",
              "values" : [
                {
                  "timestamp" : 1519516800000,
                  "value" : "1.0"
                }
              ]
          }
        ],
        "name" : "testCache"
        }
      ],
      "name" : "test"
    }
  ]...
}

將結果分頁

在實際工作環境中,某些傳送至 Edge Analytics API 的要求會傳回非常大的資料集。為了輕鬆地在使用者介面式應用程式中顯示大型資料集,該 API 原生支援分頁功能。

如要為結果分頁,請使用 offsetlimit 查詢參數,搭配 sortby 排序參數,確保項目順序一致。

舉例來說,下列要求可能會傳回大型資料集,因為這項功能會擷取產品環境中所有 API 中上週所有錯誤的指標。

curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)" \
-u email:password

如果以 UI 為基礎的應用程式可以在每頁合理顯示 50 筆結果,您可以將限制設為 50。由於 0 會計為第一個項目,因此以下呼叫會以遞減順序傳回 0-49 的項目 (sort=DESC 為預設值)。

curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{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" \
-u email:password

針對第二個「網頁」,請使用 offset 查詢參數,如下所示。請注意,上限和偏移值相同。這是因為 0 計為第一個項目。上限為 50 且偏移值 0,會傳回 0 到 49 的項目。如果偏移量為 50,則傳回項目 50-99。

curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{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" \
-u email:password