Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

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

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

Edge API Analytics 會收集及分析每個 API 要求和回應的各種統計資訊。系統會自動收集這項資訊，然後在 Edge UI 中顯示，或透過指標 API 顯示。如要進一步瞭解這些統計資料，請參閱指標和維度。

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

本主題將示範如何使用 StatisticsCollector 政策，從 API 要求/回應中擷取自訂 Analytics 資料，並將該資料提供給 Edge API Analytics。接著，說明如何透過 Edge 使用者介面或 Edge API，在報表中查看 Analytics 資料。

關於 Google Book API

本主題說明如何從 API Proxy 要求擷取自訂 Analytics 資料，傳送至 Google 圖書 API。Google 圖書 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 的統計資料，必須先建立呼叫該 API 的 Edge API Proxy。接著，您會叫用該 API Proxy，向 Google Books API 發出要求。

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

請使用相同程序，為 Google Book API 的 /volumes 端點建立 API Proxy。在程序步驟 5 中建立 API Proxy 時，請設定下列屬性來參照 Google 圖書 API：

Proxy Name：「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 要求收集 Analytics 資料的程序有兩個步驟：

擷取感興趣的資料，並寫入變數。

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

使用「擷取變數」政策，從要求或回應中擷取自訂內容，並將該資料寫入變數。
將變數中的資料寫入 Edge API Analytics。

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

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

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

您必須先擷取 Analytics 資料並儲存至變數 (Edge 預先定義的流程變數或您定義的自訂變數)，才能將資料傳遞至 API Analytics。如要將資料寫入變數，請使用「擷取變數」政策。

擷取變數政策可使用 JSONPath 或 XPath 運算式剖析訊息酬載。如要從 Google Books 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，請將政策新增至 /apiproxy/policies 底下名為 ExtractVars.xml 的檔案：

<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>

使用 Statistics Collector 政策將資料寫入 Analytics 服務

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

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

其中：

statName：指定您在自訂報表中參照統計資料時使用的名稱。
varName 指定包含要收集的 Analytics 資料的變數名稱。這個變數可以內建於 Edge，也可以是 Extract Variables 政策建立的自訂變數。
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 圖書 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 中填入資料。您可以執行下列指令來完成這項操作，每個指令都會使用不同的書名：

白鯨記：

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 使用者介面支援自訂報表，可讓您以圖表形式查看資料。
指標 API 可讓您透過對 Edge API 進行 REST 呼叫，擷取 Analytics 資料。您可以使用 API，以自訂小工具的形式建立自己的圖表，並嵌入入口網站或自訂應用程式。

使用 Edge UI 生成統計資料報表

自訂報表可讓您深入瞭解特定 API 統計資料，查看所需確切資料。您可以使用 Edge 內建的任何指標和維度，建立自訂報表。此外，您也可以使用透過 StatisticsCollector 政策擷取的任何分析資料。

建立 Statistics Collector 政策時，請指定所收集資料的資料類型。如果是字串資料類型，請在自訂報表中將統計資料參照為維度。如果是數值型資料類型 (整數/浮點數/長整數/雙精度浮點數)，請在自訂報表中將統計資料參照為維度或指標。詳情請參閱「管理自訂報表」一文。

使用 Edge 使用者介面產生自訂報表：

按照下列步驟前往「自訂報表」頁面。
Edge

如要使用 Edge UI 存取「自訂報表」頁面，請按照下列步驟操作：
1. 登入 apigee.com/edge。
2. 在左側導覽列中，依序選取「分析」>「自訂報表」>「報表」。
Classic Edge (Private Cloud)

注意：只有 Edge for Private Cloud 支援 Classic Edge UI。

如要使用傳統 Edge 使用者介面存取「自訂報表」頁面，請按照下列步驟操作：
1. 登入 http://ms-ip:9000，其中 ms-ip 是管理伺服器節點的 IP 位址或 DNS 名稱。
2. 選取頂端導覽列中的「Analytics」>「報表」。
在「自訂報表」頁面中，按一下「+ 自訂報表」。
指定報表名稱，例如 mybookreport。
選取內建的「指標」，例如「流量」，以及「匯總函式」，例如「總和」。

或者，選取您使用 StatisticsCollector 政策建立的其中一個數字資料統計資料。舉例來說，選取「ratingscount」和「Sum」的「Aggregate function」(匯總函式)。
選取內建的「維度」，例如「API Proxy」，或使用 StatisticsCollector 政策建立的任何字串或數值統計資料。

例如選取「booktitle」。報表現在會顯示依 booktitle 分組的 ratingscount 總和：
選取「儲存」。報表會顯示在所有自訂報表的清單中。
如要執行報表，請選取報表名稱。根據預設，這份報表會顯示過去一小時的資料。
如要設定時間範圍，請選取右上角的日期顯示畫面，開啟「日期選取器」彈出式視窗。
選取「過去 7 天」。報表會更新，顯示每個書名的評分總和：

使用 Edge API 取得統計資料

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

/stats 後的資源會指定所需的維度。在本範例中，您會取得維度 booktitle 的資料。
select 查詢參數，用於指定要擷取的指標。這項要求會根據 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

您也可以指定感興趣的維度值，篩選結果。在下方範例中，報表會篩選出「控制」和「達文西密碼」的結果：

$ 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

使用解決方案建構工具建立自訂 Analytics 變數

您可以使用 Solution Builder，透過簡單易用的管理 UI 對話方塊建立自訂 Analytics 變數。

建議您先閱讀上一節「收集自訂 Analytics 資料」，瞭解「擷取變數」和「統計資料收集器」政策如何攜手運作，將自訂變數提供給 Edge API Analytics。如您所見，UI 遵循相同的模式，但提供便利的方式，讓您完全透過 UI 設定項目。如要使用 Google 圖書 API 範例，請透過 UI 進行，不必手動編輯及附加政策。

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

解決方案建構工具會建立新的「擷取變數」和「統計資料收集器」政策，並為這些政策命名。在特定 Proxy 修訂版本中建立這些政策後，解決方案建構工具就不允許您返回並變更政策。如要變更政策，請直接在政策編輯器中編輯產生的政策。

在 Edge UI 中，前往 Proxy 的「Overview」頁面。
按一下「開發」。
在「開發」頁面中，從「工具」選單選取「自訂數據分析收集」。系統隨即會顯示「解決方案建立工具」對話方塊。
在「解決方案建構工具」對話方塊中，請先設定兩項政策：「擷取變數」和「統計資料收集器」。接著，設定要附加這些政策的位置。
指定要擷取的資料：
- 位置類型：選取要收集的資料類型，以及要從何處收集資料。您可以選取要求或回應端的資料。舉例來說，要求：查詢參數或回應：XML 主體。
- 位置來源：找出要收集的資料。例如查詢參數名稱，或是回應主體中 XML 資料的 XPath。
指定變數名稱 (和類型)，統計資料收集器政策會使用這些名稱來識別擷取的資料。請參閱本主題中的命名限制。

您使用的名稱會顯示在自訂報表建立工具 UI 的「維度」或「指標」下拉式選單中。
在 API Proxy 流程中，選擇要附加產生的政策「擷取變數」和「統計資料收集器」的位置。如需相關指引，請參閱「將政策附加至 ProxyEndpoint 回應流程」。如要確保政策正常運作，必須將政策附加至 API Proxy Flow 的適當位置。您需要在流程中附加政策，且政策附加的階段必須在您擷取的變數範圍內 (已填入)。
按一下「+ 收集器」，即可新增更多自訂變數。
完成後，請按一下「Build Solution」(建構解決方案)。
儲存並部署 Proxy。

現在可以如上所述，為資料產生自訂報表。