使用自訂數據分析功能分析 API 訊息內容

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

Edge API Analytics 會從每個 API 要求和回應收集並分析多種統計資訊。系統會自動收集這項資訊,然後透過 Edge UI 或使用 Metrics API 顯示這項資訊。如要進一步瞭解這些統計資料,請參閱metrics維度

您也可以收集 API Proxy、應用程式、產品或開發人員專屬的自訂分析資料。舉例來說,建議您從查詢參數、要求標頭、要求和回應主體,或您在 API 中定義的變數收集資料。

本主題說明如何使用 StatisticsCollector 政策從 API 要求/回應中擷取自訂數據分析資料,並將該資料動態饋給至 Edge API Analytics。接著說明如何透過 Edge UI 或 Edge API 查看報表中的分析資料。

關於 Google Book API

本主題說明如何從 API Proxy 要求擷取自訂分析資料至 Google Books API。Google Books API 可讓您依照書名、主題、作者和其他特性搜尋書籍。

舉例來說,您可以向 /volumes 端點發出要求,以便依書名進行搜尋。 將單一查詢參數傳遞至包含書名的 Books API:

curl https://www.googleapis.com/books/v1/volumes?q=davinci%20code

呼叫會傳回符合搜尋條件的項目 JSON 陣列。以下顯示回應中的第一個陣列元素 (請注意,為了方便起見,系統已省略某些內容):

{
 "kind": "books#volumes",
 "totalItems": 1799,
 "items": [
  {
   "kind": "books#volume",
   "id": "ohZ1wcYifLsC",
   "etag": "4rzIsMdBMYM",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/ohZ1wcYifLsC",
   "volumeInfo": {
    "title": "The Da Vinci Code",
    "subtitle": "Featuring Robert Langdon",
    "authors": [
     "Dan Brown"
    ],
    "publisher": "Anchor",
    "publishedDate": "2003-03-18",
    "description": "MORE THAN 80 MILLION COPIES SOLD ....",
    "industryIdentifiers": [
     {
      "type": "ISBN_10",
      "identifier": "0385504217"
     },
     {
      "type": "ISBN_13",
      "identifier": "9780385504218"
     }
    ],
    "readingModes": {
     "text": true,
     "image": true
    },
    "pageCount": 400,
    "printType": "BOOK",
    "categories": [
     "Fiction"
    ],
    "averageRating": 4.0,
    "ratingsCount": 710,
    "maturityRating": "NOT_MATURE",
    "allowAnonLogging": true,
    "contentVersion": "0.18.13.0.preview.3",
    "panelizationSummary": {
     "containsEpubBubbles": false,
     "containsImageBubbles": false
    },
...
   "accessInfo": {
    "country": "US",
    "viewability": "PARTIAL",
    "embeddable": true,
    "publicDomain": false,
    "textToSpeechPermission": "ALLOWED_FOR_ACCESSIBILITY",
    "epub": {
     "isAvailable": true,
     "acsTokenLink": "link"
    },
    "pdf": {
     "isAvailable": true,
     "acsTokenLink": "link"
    },
...
   }
  }

請注意,回應的部分區域已醒目顯示:

  • 搜尋結果數量
  • 書籍平均評分
  • 評分次數
  • 書籍的 PDF 版本供應情形

以下各節說明如何針對包含搜尋條件的查詢參數 q 收集這些回應區域的統計資料。

為 Google Book API 建立 API Proxy

您必須先建立用於呼叫 Google Book API 的 Edge API Proxy,才能收集該 API 的統計資料。然後叫用該 API Proxy 即可向 Google Book API 提出要求。

步驟 2:建立 API Proxy 教學課程中的建立 API Proxy 說明如何建立呼叫 https://mocktarget.apigee.net API。請注意,該教學課程中所述的 Proxy 不需要 API 金鑰來呼叫。

按照相同的程序為 Google Book API 的 /volumes 端點建立 API Proxy。在程序的步驟 5 中,當您建立 API Proxy 時,請將下列屬性設為參照 Google Books API:

  • Proxy 名稱:「mybooksearch」
  • Proxy 基本路徑:「/mybooksearch」
  • 現有 API:「https://www.googleapis.com/books/v1/Volumes」

建立及部署 Proxy 後,您應該就能以下列格式使用 curl 指令呼叫 Proxy:

curl http://org_name-env_name.apigee.net/mybooksearch?q=davinci%20code

其中 org_nameenv_name 指定您部署 Proxy 的機構和環境。例如:

curl http://myorg-test.apigee.net/mybooksearch?q=davinci%20code

收集自訂數據分析資料

透過 API 要求收集數據分析資料包含兩個步驟:

  1. 擷取所需資料並寫入變數。

    傳送至 Edge API Analytics (分析) 的所有資料都來自變數中儲存的值。 部分資料會自動儲存在預先定義的 Edge flow 變數中,例如傳送至 API Proxy 的查詢參數值。如要進一步瞭解預先定義的流程變數,請參閱流程變數總覽

    使用「擷取變數」政策,從要求或回應擷取自訂內容,然後將該資料寫入變數。

  2. 將變數中的資料寫入 Edge API Analytics。

    使用統計資料收集器政策,將變數中的資料寫入 Edge API 數據分析。資料可能來自預先定義的邊緣流程變數,或由「擷取變數」政策建立的變數。

收集到統計資料後,您可以使用 Edge Management UI 或 API 擷取及篩選統計資料。舉例來說,您可以產生自訂報表,顯示每個書名的平均評分,其中書名會對應到傳送至 API 的查詢參數值。

使用「擷取變數」政策 擷取分析資料

Analytics (分析) 資料必須擷取並儲存至變數 (這可以是 Edge 預先定義的流程變數或您定義的自訂變數),然後才能將其傳送至 API Analytics (分析)。如要將資料寫入變數,請使用擷取變數政策

「擷取變數」政策可以使用 JSONPath 或 XPath 運算式剖析訊息酬載。 如要從 Google Book API 的 JSON 搜尋結果中擷取資訊,請使用 JSONPath 運算式。舉例來說,如要從 JSON 結果陣列中的第一個項目擷取 averageRating 的值,JSONPath 運算式會是:

$.items[0].volumeInfo.averageRating

JSONPath 經過評估後,「擷取變數」政策會將擷取的值寫入變數。

在這個範例中,您使用「擷取變數」政策建立四個變數:

  • responsejson.totalitems
  • responsejson.ratingscount
  • responsejson.avgrating
  • responsejson.pdf

對這些變數來說,responsejson 是變數的「前置字元」,而 totalitemsratingscountavgrating,以及「pdf」是變數名稱

下方的「擷取變數」政策說明如何從 JSON 回應擷取資料,並將其寫入自訂變數。每個 <Variable> 元素都會使用 name 屬性指定自訂變數名稱和相關聯的 JSONPath 運算式。<VariablePrefix> 元素會指定變數前置字元。

將這項政策新增至 Edge UI 中的 API Proxy。如要在 XML 中建構 API Proxy,請將政策新增至名為 ExtractVars.xml/apiproxy/policies 檔案:

<ExtractVariables name="ExtractVars">
    <Source>response</Source>
    <JSONPayload>
        <Variable name="totalitems">
            <JSONPath>$.totalItems</JSONPath>
        </Variable>
        <Variable name="ratingscount">
            <JSONPath>$.items[0].volumeInfo.ratingsCount</JSONPath>
        </Variable>
        <Variable name="avgrating">
            <JSONPath>$.items[0].volumeInfo.averageRating</JSONPath>
        </Variable>
        <Variable name="pdf">
            <JSONPath>$.items[0].accessInfo.pdf.isAvailable</JSONPath>
        </Variable>
    </JSONPayload>
    <VariablePrefix>responsejson</VariablePrefix>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

使用統計資料收集器政策,將資料寫入 Analytics (分析) 服務

使用統計資料收集器政策,將變數中的資料寫入 Edge API Analytics。統計資料收集政策的格式如下:

<StatisticsCollector>
<DisplayName>Statistics Collector-1</DisplayName>
    <Statistics>
        <Statistic name="statName" ref="varName" type="dataType">defVal</Statistic>
       …
    </Statistics>
</StatisticsCollector>

其中:

  • statName 會指定自訂報表中參照統計資料的名稱。
  • varName 會指定包含要收集數據分析資料的變數名稱。這個變數可內建於 Edge,也可以是透過「擷取變數」政策建立的自訂變數。
  • dataType 會將記錄資料的資料類型指定為字串、整數、浮點值、長整數、雙精度浮點值或布林值。

    對於類型字串的資料,您可以在自訂報表中以維度參照統計資料。對於數值資料類型 (整數/浮點/長/雙精度浮點數),您可以在自訂報表中以維度指標的形式參照統計資料。

  • defValue 可選擇提供自訂變數的預設值;如果無法解析變數或變數未定義,系統就會將該值傳送至 API Analytics (分析)。

在以下範例中,您會使用統計資料收集器政策,為由「擷取變數」政策建立的變數收集資料。您也可以收集傳送至每個 API 呼叫的查詢參數值。使用預先定義的流程變數參照查詢參數:

request.queryparam.queryParamName

對於名為「q」的查詢參數,此參數會參照如下:

request.queryparam.q

請在 Edge UI 中將這項政策新增至 API Proxy;如要以 XML 建構 API Proxy,請在 /apiproxy/policies 下新增名為 AnalyzeBookResults.xml, 的檔案,其中含有下列內容:

<StatisticsCollector name="AnalyzeBookResults">
 <Statistics>
        <Statistic name="totalitems" ref="responsejson.totalitems" type="integer">0</Statistic>
        <Statistic name="ratingscount" ref="responsejson.ratingscount" type="integer">0</Statistic>
        <Statistic name="avgrating" ref="responsejson.avgrating" type="float">0.0</Statistic>
        <Statistic name="pdf" ref="responsejson.pdf" type="boolean">true</Statistic>
        <Statistic name="booktitle" ref="request.queryparam.q" type="string">none</Statistic>
 </Statistics>
</StatisticsCollector>

將政策附加至 ProxyEndpoint 回應流程

為了讓政策正常運作,您必須將政策附加至 API Proxy 流程的適當位置。在這個用途中,政策必須在從 Google Book API 收到回應後,以及將回應傳送至提出要求的用戶端之前執行。因此,請將政策附加至 ProxyEndpoint 回應 PreFlow

下方的 ProxyEndpoint 設定範例會先執行名為 ExtractVars 的政策,以剖析回應訊息。接著,名為 AnalyzeBookResults 的政策會將這些值轉送至 API Analytics (分析):

<ProxyEndpoint name="default">
    ><PreFlow name="PreFlow">
        <Request/>
        <Response>
            <Step>
                <Name>Extract-Vars</Name>
            </Step>
            <Step>
                <Name>AnalyzeBookResults</Name>
            </Step>
        </Response>
    </PreFlow>
 <HTTPProxyConnection>
  <!-- Base path used to route inbound requests to this API proxy -->
  <BasePath>/mybooksearch</BasePath>
  <!-- The named virtual host that defines the base URL for requests to this proxy -->
  <VirtualHost>default</VirtualHost>
 </HTTPProxyConnection>
 <RouteRule name="default">
 <!-- Connects the proxy to the target defined under /targets -->
  <TargetEndpoint>default</TargetEndpoint>
 </RouteRule>
</ProxyEndpoint>

部署 API Proxy

完成這些變更後,您必須部署已設定的 API Proxy。

填入數據分析資料

部署 API Proxy 後,請呼叫 Proxy 以在 API Analytics (分析) 中填入資料。如要達到這個目的,請執行下列指令,每個指令都會使用不同的書名:

Mobey Dick:

curl https://org_name-env_name.apigee.net/mybooksearch?q=mobey%20dick

達文西密碼:

curl https://org_name-env_name.apigee.net/mybooksearch?q=davinci%20code 

Gone Girl:

curl https://org_name-env_name.apigee.net/mybooksearch?q=gone%20girl  

《權力遊戲》:

curl https://org_name-env_name.apigee.net/mybooksearch?q=game%20of%20thrones   

查看分析資料

Edge 提供兩種查看自訂數據分析資料的方式:

  • Edge UI 支援自訂報表,可讓您透過圖形圖表查看資料。
  • Metrics API 可讓您對 Edge API 發出 REST 呼叫,藉此擷取數據分析資料。您可以使用這個 API 打造自己的視覺化圖表,並嵌入入口網站或自訂應用程式中。

使用 Edge UI 產生統計資料報告

自訂報表可讓您細查特定 API 統計資料,查看要查看的確切資料。您可以使用 Edge 內建的任何metrics維度建立自訂報表。此外,您也可以使用 StatisticsCollector 政策所擷取的任何數據分析資料。

建立統計資料收集器政策時,您會指定收集的資料類型。 在自訂報表中,將統計資料做為維度來參照字串資料類型。如為以數值表示的資料類型 (整數/浮點數/長/雙精度浮點數),請在自訂報表中以維度或指標的形式參照統計資料日期。詳情請參閱「管理自訂報表」一文。

使用 Edge UI 產生自訂報表:

  1. 按照下方說明存取「自訂報表」頁面。

    邊緣

    如何透過 Edge UI 存取「自訂報表」頁面:

    1. 登入 apigee.com/edge
    2. 在左側導覽列中,依序選取「分析」>「自訂報表」>「報表」

    傳統邊緣 (Private Cloud)

    如何透過傳統版 Edge UI 存取「自訂報表」頁面:

    1. 登入 http://ms-ip:9000,其中 ms-ip 是管理伺服器節點的 IP 位址或 DNS 名稱。
    2. 在頂端的導覽列中,依序選取「數據分析」>「報表」

  2. 在「自訂報表」頁面中,按一下「+ 自訂報表」
  3. 指定「報表名稱」,例如 mybookreport
  4. 選取內建的指標 (例如「Traffic」) 和「匯總函式」,例如「Sum」。

    或者,選取使用 StatisticsCollector 政策所建立的數值資料統計資料。 舉例來說,您可以選取 ratingscountSum 的「匯總函式」

  5. 選取內建的維度 (例如「API Proxy」),或是使用 StatisticsCollector 政策建立的任何字串或數值統計資料。

    例如「booktitle」。您的報告現在會顯示 booktitleratingscount 總和:

    自訂書籍報告
  6. 選取「儲存」。這份報表會顯示在所有自訂報表的清單中。
  7. 如要執行報表,請選取報表名稱。根據預設,報表會顯示過去 1 小時的資料。

  8. 如要設定時間範圍,請選取右上角的日期,開啟「日期選取器」彈出式視窗。
  9. 選取「過去 7 天」。這份報告會更新並顯示每個書名的評分總和:

    讀書報告

使用 Edge API 取得統計資料

使用 Edge 指標 API 取得自訂分析資料的統計資料。在下方的要求範例中:

  • /stats 之後的網址資源會指定所需的維度。在本例中,您會取得維度「booktitle」的資料。
  • select 查詢參數,用於指定要擷取的metrics。這項要求會根據 ratingscount 的總和傳回數據分析。
  • timeRange 參數會指定傳回資料的時間間隔。時間範圍的格式如下:

    MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM

完整的 API 呼叫如下:

curl -X GET "https://api.enterprise.apigee.com/v1/organizations/org_name/environments/env_name/stats/booktitle?select=sum(ratingscount)&timeRange=04/21/2019&2014:00:00~04/22/2019&2014:00:00" /
-u email:password

您應該會在以下表單中看到回應:

{
  "environments": [
    {
      "dimensions": [
        {
          "metrics": [
            {
              "name": "sum(ratingscount)",
              "values": [
                "5352.0"
              ]
            }
          ],
          "name": "gone girl"
        },
        {
          "metrics": [
            {
              "name": "sum(ratingscount)",
              "values": [
                "4260.0"
              ]
            }
          ],
          "name": "davinci code"
        },
        {
          "metrics": [
            {
              "name": "sum(ratingscount)",
              "values": [
                "1836.0"
              ]
            }
          ],
          "name": "game of thrones"
        },
        {
          "metrics": [
            {
              "name": "sum(ratingscount)",
              "values": [
                "1812.0"
              ]
            }
          ],
          "name": "mobey dick"
        }
      ],
      "name": "prod"
    }
  ],
  "metaData": {
    "errors": [],
    "notices": [
      "query served by:9b372dd0-ed30-4502-8753-73a6b09cc028",
      "Table used: uap-prod-gcp-us-west1.edge.edge_api_raxgroup021_fact",
      "Source:Big Query"
    ]
  }
}

Edge 指標 API 有許多選項。舉例來說,您可以遞增或遞減排序結果。 在以下範例中,您將使用遞增順序:

curl -X GET "https://api.enterprise.apigee.com/v1/organizations/org_name/environments/env_name/stats/booktitle?select=sum(ratingscount)&timeRange=04/21/2019&2014:00:00~04/22/2019&2014:00:00&sort=ASC" /
-u email:password

此外,您也可以指定所需維度的值來篩選結果。在下方範例中,報表是依「Gone Girl」和「The Da Vinci Code」篩選出的結果:

$ curl -X GET "https://api.enterprise.apigee.com/v1/organizations/org_name/environments/env_name/stats/booktitle?select=sum(ratingscount)&timeRange=04/21/2019&2014:00:00~04/22/2019&2014:00:00&filter=(booktitle%20in%20'gone%20girl'%2C%20'davinci%20code')" /
-u email:password

使用解決方案建構工具建立自訂數據分析變數

在解決方案建構工具中,您可以透過簡單易用的管理 UI 對話方塊建立自訂數據分析變數。

建議您參閱前一節「收集自訂數據分析資料」一節,瞭解「擷取變數和統計資料收集器」政策如何協助您將自訂變數提供給 Edge API Analytics。如您所見,UI 採用同樣的模式,但可讓您輕鬆透過 UI 完全進行設定。如有需要,您也可以嘗試使用 Google Books API 範例,而不要手動編輯及附加政策。

「解決方案建構工具」對話方塊可讓您直接在使用者介面中設定數據分析變數。這項工具會產生政策,並為您連結至 API Proxy。這項政策會從要求或回應中擷取感興趣的變數,並將擷取的變數傳遞至 Edge API Analytics。

解決方案建構工具會建立新的「擷取變數」和「統計資料收集器」政策,並為其命名。這些政策建立在特定 Proxy 修訂版本中之後,解決方案建構工具就無法讓您返回並變更政策。如要進行變更,請直接透過政策編輯器編輯系統產生的政策。

  1. 在 Edge UI 中前往 Proxy 的總覽頁面。
  2. 按一下「開發」
  3. 在「開發」頁面中,選取「工具」選單中的「自訂數據分析集合」。畫面上會顯示「Solution Builder」對話方塊。
  4. 在「解決方案建構工具」對話方塊中,您必須先設定兩項政策:擷取變數和統計資料收集器。然後設定這些政策的附加位置。
  5. 指定要擷取的資料:
    • 位置類型:選取想要收集的資料類型和收集位置。您可以從要求或回應端選取資料。例如「要求:查詢參數」或「回應:XML 主體」。
    • 位置來源:找出要收集的資料。例如,查詢參數的名稱或回應主體中 XML 資料的 XPath。
  6. 指定統計資料收集器政策的名稱 (和類型),用來識別擷取的資料。請參閱本主題中的命名限制。

    這個名稱會顯示在「自訂報表製作工具」使用者介面的「維度」或「指標」下拉式選單中。
  7. 選擇要在 API Proxy 流程中附加系統產生的政策「擷取變數和統計資料收集器」。如需指引,請參閱「將政策附加至 ProxyEndpoint 回應流程」。如要讓政策正常運作,您必須將政策附加至 API Proxy 流程的適當位置。您需要在流程的某個階段中附加政策,也就是您要處理的變數位於範圍內 (已填入值)。
  8. 按一下「+收集器」新增更多自訂變數。
  9. 完成後,按一下「Build Solution」

  10. 儲存及部署 Proxy。

您現在可以按照上述方式產生資料的自訂報表。