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

使用 Metrics API

查看 Apigee Edge 說明文件。
前往 Apigee X說明文件。資訊

Apigee Edge 可記錄各種跨 API 流通的營運與業務資料。系統從這類資料中衍生的指標很適合用於營運監控和業務監控使用 Edge API Analytics 例如判斷哪些 API 效能較佳或較差，哪些開發人員流量最高的流量，以及哪些應用程式造成後端服務發生問題。

為協助輕鬆存取這些指標資料，Edge 提供了符合 REST 樣式的 API。你可以如果需要自動執行特定 Analytics 函式 (例如擷取指標)，請使用 Metrics API 定期透過自動化用戶端或指令碼執行這項作業您也可以使用 API 自行建立以自訂小工具的形式呈現圖表，供您嵌入入口網站或自訂應用程式。

瞭解如何在 API 中使用 Analytics Edge 管理 UI，請參閱「API 數據分析總覽」。

關於 Metrics API

Edge 提供兩項指標 API：

取得指標傳回機構和環境的指標一段時間，例如一小時、一天或一週

舉例來說，假設您希望獲得前一週的使用者：
- 政策錯誤數量
- 平均回覆時間
- 總流量
取得依維度排序的指標會傳回機構和環境在一段時間內指標，維度。

舉例來說，您前一週使用維度將指標依 API 產品、API Proxy 和開發人員電子郵件地址，以便取得：
- 「每項 API 產品」的政策錯誤數量
- 每個 API Proxy 的平均回應時間
- 個別開發人員電子郵件的總流量
取得依維度排序的指標 API 支援取得指標不支援的其他功能 API，包含：
- 排序
- 篩選
- 分頁

關於 Metrics API 配額

Edge 會對這些呼叫強制執行下列配額。配額是根據後端系統計算而得處理呼叫：

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

敬上

指定要傳回的指標

對於取得指標並取得依維度排序的指標使用 select 查詢參數，指定指標的 API 擷取與選用的匯總函式，格式如下：

?select=metric

或是：

?select=aggFunction(metric)

在此情況下：

metric 指定要傳回的資料。例如： API 要求、快取命中或政策錯誤的數量。查看指標表格，指定與 select 查詢參數搭配使用的指標名稱。
aggFunction 會指定針對指標執行的選用匯總函式。舉例來說，您可以搭配使用下列匯總函式與處理延遲時間指標：
- avg：傳回平均處理延遲時間。
- min：傳回最短處理延遲時間。
- max：傳回最長處理延遲時間。
- sum：傳回所有處理延遲時間的總和。
並非所有指標都支援所有匯總函式。 metrics：包含指定指標名稱的資料表以及指標支援的函式 (sum、avg、min、max)。

舉例來說，如要傳回平均交易次數 (亦即 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 之前的 %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。

使用分隔符號

如要在 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

apis 和 apps 維度則以 , 分隔。

注意：過去有未記錄的使用情形允許使用正斜線 (/) 做為分隔符號。系統已不支援這項機制：請使用半形逗號做為分隔符號

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 2 天內的訊息總數

在這個範例中，您會傳回所有 API Proxy 收到的要求數指標超過 75%select 查詢參數定義了指標的匯總函式 sum 選擇「apiproxy」維度的message_count。報表會傳回要求訊息的處理量適用於 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"
  } ]...
}

此回應表示一個 API Proxy 收到 1100 則訊息，其呼叫的 API 為「target-reroute」於 2018 年 6 月 20 日至 2023 年 6 月底間 2018 年 6 月 21 日。

提示：請注意時間戳記 1498003200000 位於 Unix 時間戳記格式。網路上有許多 Unix 時間戳記轉換工具方便您解碼這些時間戳記

如要取得其他維度的指標，請將其他維度指定為 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 大最慢的前 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"
    }
  ]...
}

敬上

注意：「請勿」使用 / 做為篩選器的捷徑。適用對象正確的呼叫如下：

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

在這個呼叫中，「請勿」將 apis?filter=(apis eq 'myapp')&select= 替換成快速鍵 apis/myapp?select=。

分頁結果

在實際工作環境中，有些向 Edge Analytics API 發出的要求會傳回非常龐大的資料運用 AI 開發原則審查系統如要在以 UI 為基礎的應用程式時輕鬆顯示大型資料集， API 原生支援分頁功能，

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

注意：將結果分頁時，請務必使用可預測的方式，將結果排序， sortby 查詢參數沒有排序時，系統會在無法預測的順序，因而打破分頁的目的。

sortby 值必須與 select 查詢中使用的值相同參數。舉例來說，如果 select=sum(message_count)，則 sortby=sum(message_count)。

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

針對第二個「網頁」結果使用偏移查詢參數，如下所示。請注意，限制和偏移量相同這是因為系統會將 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