使用自訂數據分析功能分析 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_name 和 env_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 是變數的「前置字元」，而 totalitems、ratingscount、avgrating，以及「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 政策所建立的數值資料統計資料。 舉例來說，您可以選取 ratingscount 和 Sum 的「匯總函式」。

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

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

    自訂書籍報告
  6. 選取「Save」(儲存)。這份報表會顯示在所有自訂報表的清單中。

  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。

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