StatsCollector 政策

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

優勢

可讓您收集訊息中資料的統計資料,例如產品 ID、價格、REST 動作、用戶端和目標網址,以及訊息長度。資料可能來自 Apigee 預先定義的流程變數,或是您定義的自訂變數。

統計資料會傳送至分析伺服器,然後分析統計資料並產生報表。您可以使用 Edge Management UI 或 Edge API 查看報表。

範例

基本範例

<StatisticsCollector name="publishPurchaseDetails">
  <Statistics>
    <Statistic name="productID" ref="product.id" type="string">999999</Statistic>
    <Statistic name="price" ref="product.price" type="string">0</Statistic>
  </Statistics>
</StatisticsCollector>

在這個範例中,您會收集兩個自訂變數的統計資訊:product.idproduct.price。針對每個要求,統計資料收集器政策會將這兩個變數的值寫入分析伺服器。

另外,本例也會為每個變數設定選用的預設值,其中 product.id 的預設值為 999999,預設的 product.price 為 0。如果未定義變數且未指定預設值,系統就不會記錄該變數的資料。如果指定預設值,系統會在變數未定義時記錄預設值。

收集統計資料後,您可以使用 Edge 管理 UI 或 API 擷取統計資料。擷取統計資料時,您會分別將收集到的資料當做 productIDprice 來參照。

存取統計資料

在本範例中,您會使用 Edge Management API 查看名為 productID 集合的統計資料。這項要求會根據每天為每個產品 ID 提交的訊息數量總和,建構產品 ID 的自訂報表。將變數 {org_name} 換成貴機構名稱,並將 email:password 替換為 Apigee Edge 上的帳戶和密碼。

設定 timeRange 參數,加入收集資料的時間間隔。根據預設,系統無法存取 6 個月前的資料。如果您要存取超過六個月的資料,請與 Apigee Edge 支援團隊聯絡。

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/test/stats/productID?"select=sum(message_count)&timeRange=1/19/2015%2000:00~6/21/2015%2000:00&timeUnit=day"
-u email:password

在回應中,name 欄位包含產品 ID,值則顯示每天的要求數量:

{
  "environments" : [ {
    "dimensions" : [ {
      "metrics" : [ {
        "name" : "sum(message_count)",
        "values" : [ {
          "timestamp" : 1353369600000,
          "value" : "4.0"
        } ]
      } ],
      "name" : "52"
    }, {
      "metrics" : [ {
        "name" : "sum(message_count)",
        "values" : [ {
          "timestamp" : 1353369600000,
          "value" : "19.0"
        } ]
      } ],
      "name" : "14"
    }, ...
  } ],
  "metaData" : {
    "samplingRate" : "100"
  }
}

擷取要收集的資料

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ExtractVariables async="false" continueOnError="false" enabled="true" name="GetWeatherData">
    <VariablePrefix>weather</VariablePrefix>
    <XMLPayload>
       <Namespaces>
          <Namespace prefix="yweather">http://xml.weather.yahoo.com/ns/rss/1.0</Namespace>
       </Namespaces>
       <Variable name="location" type="string">
          <XPath>/rss/channel/yweather:location/@city</XPath>
       </Variable>
       <Variable name="condition" type="string">
          <XPath>/rss/channel/item/yweather:condition/@text</XPath>
       </Variable>
    </XMLPayload>
</ExtractVariables>

根據統計資料收集器政策規定,收集到的資料必須儲存在變數中。 這些變數可以由 Apigee 或您定義的自訂變數預先定義。

在此範例中,您使用「擷取變數」政策,從包含天氣資訊的 XML 酬載擷取資料。這項政策可以:

  • 擷取城市名稱,並將其寫入名為 weather.location 的變數。
  • 擷取目前條件並寫入名為 weather.condition 的變數

接著,您可以使用統計資料收集器政策收集變數相關資訊,如下所示:

<StatisticsCollector name="publishPurchaseDetails">
  <Statistics>
    <Statistic name="weatherLocation" ref="weather.location" type="string"></Statistic>
    <Statistic name="weatherCondition" ref="weather.condition" type="string"></Statistic>
  </Statistics>
</StatisticsCollector>

如需查看統計資料收集器政策 XML 酬載資料的完整教學課程,請參閱「使用自訂數據分析分析 API 訊息內容」。


關於統計資料收集器政策

執行時,統計資料收集器政策會記錄一或多個變數目前的值。這些變數可以是 Apigee 預先定義的資料流變數,或您定義的自訂變數。這項資料會寫入 Edge 分析伺服器。

如要存取政策收集的統計資料,請使用 Edge API 或 Edge 管理 UI。舉例來說,您可以使用 Edge 管理 UI 建立自訂報表,以多種格式顯示收集到的資料。

如需使用統計資料收集器政策的完整教學課程,請參閱使用自訂數據分析分析 API 訊息內容

政策的位置

您可以在 API Proxy 的要求或回應流程中加入統計資料收集器政策。然而,如果您將多個統計資料收集器政策放入 Proxy,則最後一個執行規則會決定寫入分析伺服器的資料,且先前所有統計資料收集器政策寫入的資料都會遺失。

一個情況中,你可能在 API Proxy 中有多個統計資料收集器政策,即要求或回應流程中有其中一項政策,而另一個則在錯誤處理常式中。如果 API Proxy 中發生錯誤,錯誤處理常式中的統計資料收集器會決定要收集的資料。您可以使用統計資料收集器來記錄故障的相關資訊,或記錄您認為的任何其他必要資訊。無論要求/回應中的統計資料收集器是否已執行,錯誤處理常式中的統計資料收集器都會決定要收集的資料。

詳情請參閱「處理錯誤」。

元素參照

元素參考資料說明統計資料收集器政策的元素和屬性。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<StatisticsCollector async="false" continueOnError="false" enabled="true" name="Statistics-Collector-1">
    <DisplayName>Statistics Collector 1</DisplayName>
    <Statistics>
        <Statistic name="statName" ref="varName" type="refDataType">defaultStatValue</Statistic>
    </Statistics>
</StatisticsCollector>

<StatisticsCollector> 屬性

<StatisticsCollector async="false" continueOnError="false" enabled="true" name="Stats-1">

下表說明所有政策父項元素的通用屬性:

屬性 說明 預設 存在必要性
name

政策的內部名稱。name 屬性的值可以包含英文字母、數字、空格、連字號、底線和半形句號。這個值不得超過 255 個半形字元。

您也可以選擇使用 <DisplayName> 元素,在管理 UI Proxy 編輯器中使用不同的自然語言名稱為政策加上標籤。

不適用 需要
continueOnError

如果設為 false,即可在政策失敗時傳回錯誤。大部分政策都是預期中的行為。

設為 true,即可在政策失敗後繼續執行資料流。

false 選用
enabled

如要強制執行政策,請設為 true

設為 false 即可停用這項政策。即使政策仍附加在流程中,系統也不會強制執行政策。

true 選用
async

此屬性已淘汰。

false 已淘汰

<DisplayName> 元素

除了 name 屬性外,您還可以使用不同的自然語言名稱,在管理 UI Proxy 編輯器中為政策加上標籤。

<DisplayName>Policy Display Name</DisplayName>
預設

不適用

如果省略這個元素,系統會使用政策的 name 屬性值。

存在必要性 選用
類型 字串

<Statistics>/<Statistic> 元素

<Statistics>
    <Statistic name="statName" ref="varName" type="refDataType">defaultStatValue</Statistic>
</Statistics>
屬性 說明 預設 存在必要性
名稱

這個名稱可用來參照收集到的指定變數資料。查看數據分析資料時,請使用這個名稱來參照系統收集的 ref 屬性指定變數相關資料。

如果在要求或回應中未定義 ref 指定的變數,則 defaultStatValue 會指定為變數收集的值。如果省略預設值,在未定義變數時,系統就不會收集任何變數資料。

命名限制

下列命名限制適用於自訂 Analytics (分析) 變數:

不適用 需要
參考資料

您要收集統計資料的流程變數。這個變數可以是 Apigee 預先定義的流程變數,或是您在 API Proxy 中定義的自訂變數。

ref 屬性通常會參照由「擷取變數」政策定義的自訂變數。詳情請參閱「擷取變數政策」。

不適用 需要
類型

指定 ref 屬性指定變數的資料類型。有效值為:string/integer/float/long/double/boolean。

針對類型字串的資料,請在自訂報表中將統計資料做為維度參照。如果是數值資料類型 (整數/浮點/長/雙精度浮點數),請在自訂報表中參照統計資料,做為「維度」或「指標」。詳情請參閱「管理自訂報表」一文。

只有在 ref 參照預先定義的 Apigee 流程變數,或是在「擷取變數」政策的 XML 酬載中宣告類型時,才能省略 type 的值。

字串 選用

錯誤參考資料

本節說明這項政策觸發錯誤時設定的錯誤訊息和流程變數。如果您正在開發 Proxy 的錯誤規則,請務必瞭解這項資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。

執行階段錯誤

無。

部署錯誤

錯誤名稱 原因 修正
UnsupportedDatatype 如果統計資料收集器政策的 <Statistic> 元素中的 ref 屬性指定變數類型,則 API Proxy 部署作業會失敗。支援的資料類型為 stringintegerfloatlongdoubleboolean
InvalidName 如果名稱用於參照在統計資料收集器政策 <Statistic> 元素中定義的指定變數收集的資料,則與系統定義的變數發生衝突,API Proxy 部署作業就會失敗。部分已知的系統定義的變數為 organizationenvironment
DatatypeMissing 如果缺少統計資料收集器政策的 <Statistic> 元素中 ref 屬性指定的變數類型,則 API Proxy 部署作業會失敗。

錯誤變數

無。

結構定義

每個政策類型都是由 XML 結構定義 (.xsd) 定義。如需參考,GitHub 提供政策結構定義

相關主題

詳情請參閱: