您正在查看 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 要求收集數據分析資料包含兩個步驟:
擷取所需資料並寫入變數。
傳送至 Edge API Analytics (分析) 的所有資料都來自變數中儲存的值。 部分資料會自動儲存在預先定義的 Edge flow 變數中,例如傳送至 API Proxy 的查詢參數值。如要進一步瞭解預先定義的流程變數,請參閱流程變數總覽。
使用「擷取變數」政策,從要求或回應擷取自訂內容,然後將該資料寫入變數。
將變數中的資料寫入 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 產生自訂報表:
- 按照下方說明存取「自訂報表」頁面。
邊緣
如何透過 Edge UI 存取「自訂報表」頁面:
- 登入 apigee.com/edge。
- 在左側導覽列中,依序選取「分析」>「自訂報表」>「報表」。
傳統邊緣 (Private Cloud)
如何透過傳統版 Edge UI 存取「自訂報表」頁面:
- 登入
http://ms-ip:9000
,其中 ms-ip 是管理伺服器節點的 IP 位址或 DNS 名稱。 在頂端的導覽列中,依序選取「數據分析」>「報表」。
- 在「自訂報表」頁面中,按一下「+ 自訂報表」。
- 指定「報表名稱」,例如 mybookreport。
選取內建的指標 (例如「Traffic」) 和「匯總函式」,例如「Sum」。
或者,選取使用 StatisticsCollector 政策所建立的數值資料統計資料。 舉例來說,您可以選取 ratingscount 和 Sum 的「匯總函式」。
選取內建的維度 (例如「API Proxy」),或是使用 StatisticsCollector 政策建立的任何字串或數值統計資料。
例如「booktitle」。您的報告現在會顯示 booktitle 的 ratingscount 總和:
- 選取「Save」(儲存)。這份報表會顯示在所有自訂報表的清單中。
如要執行報表,請選取報表名稱。根據預設,報表會顯示過去 1 小時的資料。
- 如要設定時間範圍,請選取右上角的日期,開啟「日期選取器」彈出式視窗。
選取「過去 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 修訂版本中之後,解決方案建構工具就無法讓您返回並變更政策。如要進行變更,請直接透過政策編輯器編輯系統產生的政策。
- 在 Edge UI 中前往 Proxy 的總覽頁面。
- 按一下「開發」。
- 在「開發」頁面中,選取「工具」選單中的「自訂數據分析集合」。畫面上會顯示「Solution Builder」對話方塊。
- 在「解決方案建構工具」對話方塊中,您必須先設定兩項政策:擷取變數和統計資料收集器。然後設定這些政策的附加位置。
- 指定要擷取的資料:
- 位置類型:選取想要收集的資料類型和收集位置。您可以從要求或回應端選取資料。例如「要求:查詢參數」或「回應:XML 主體」。
- 位置來源:找出要收集的資料。例如,查詢參數的名稱或回應主體中 XML 資料的 XPath。
- 指定統計資料收集器政策的名稱 (和類型),用來識別擷取的資料。請參閱本主題中的命名限制。
這個名稱會顯示在「自訂報表製作工具」使用者介面的「維度」或「指標」下拉式選單中。 - 選擇要在 API Proxy 流程中附加系統產生的政策「擷取變數和統計資料收集器」。如需指引,請參閱「將政策附加至 ProxyEndpoint 回應流程」。如要讓政策正常運作,您必須將政策附加至 API Proxy 流程的適當位置。您必須在流程的切入變數位於範圍內 (已填入) 的階段中附加政策。
- 按一下「+收集器」新增更多自訂變數。
完成後,按一下「Build Solution」。
- 儲存及部署 Proxy。
您現在可以按照上述方式產生資料的自訂報表。