概述：分析 API v1

簡介

Analytics API可讓您直接取得影片雲端帳戶的分析資料。您也可以在視訊雲端工作室的分析模組中檢視內建的分析報表。以程式設計方式存取資料可提供額外的彈性。

典型用途

以下是API的一些典型用法：

建立自訂圖表和顯示
一起使用多個 API-例如，使用上週觀看CMS API次數最多的視頻獲取視頻數據
結合您的影片分析資料與其他網站分析資料
有關一些示例解決方案，請參見
- 播放列表分析
- 按國家和日期進行分析

基本網址

的基本網址Analytics API為：

  <code class =“ language-http translation =” No“> https://analytics.api.brightcove.com/v1

標頭

身份驗證（必填）

Analytics API使用 Brightcove OAuth 服務來驗證呼叫。

您首先需要取得用戶端認證 (a client_id和client_secret )。這是一次性作業，可以使用 OAuth 認證 UI 執行。您可以使用CURL、Postman或直接從 Brightcove OAuth 服務取得用戶端憑證Insomnia。

您需要具有Google讀取和視頻讀取權限才能獲得客戶端憑據：

如果您直接通過OAuth API創建憑據，則所需權限為：

  [
    "video-cloud/analytics/read"
    "video-cloud/video/read"
  ]

您還需要一個access_token，它是使用和獲得的，client_idclient_secret並與您的 API 請求一起傳入授權標頭：

  Authorization: Bearer {access_token}

五分鐘後access_token過期，因此您必須為每個請求獲取一個，或者檢查以確保您的令牌仍然有效。有關如何獲取訪問令牌（包括代碼示例）的詳細說明，請參閱獲取訪問令牌。

Accept-Encoding: gzip (optional)

傳遞此標頭將導致響應以壓縮形式返回。這可以提高大型報表的性能。

快取

出於性能原因，API響應會緩存大約5分鐘，儘管確切的時間可能會因多種因素而有所不同。對於任何Analytics API查詢，您可以從響應頭獲取有關緩存的信息：

會Cache-Control告訴您快取結果的最長時間，以秒為單位 (在上面的範例中為 24 秒)。Last-Modified和標Expires頭會告訴您當前緩存的創建時間以及何時到期。

在大多數情況下，這可能不是問題，但是，如果分析數據的新鮮度至關重要，則應該知道查詢運行的時間越長，緩存的時間就越長，並且報告僅獲取實時（每小時未對帳）數據只要獲取對帳數據的數據（僅實時數據或除實時數據外）就不會被緩存。找到實時和協調數據的完整解釋如果你喜歡;簡短的版本是Analytics API依賴於兩個數據桶：

實時或每小時未對帳數據，可立即使用並存儲32天
對帳數據已永久存儲；對實時數據進行協調以提高準確性，並每24小時將其存儲在協調的數據存儲庫中

您可以使用和解範圍。

要最小化緩存：

使用reconciled=false參數將結果限制為即時資料
使用較小的日期範圍，並確保整個範圍在過去 32 天內

超時時間

如果未完成，Analytics API會在8分鐘後請求超時。如果您看到少於8分鐘的超時，則原因是某些客戶端限制。

您最多可以退回的物品

可以退回的最大物品數為一百萬。在大多數情況下，您不太可能達到限制，但是如果您在很長時間內請求date維度的報告，則可能是可能的。如果達到百萬個項目的限制，則需要修改請求以減少返回的項目數。通常，最直接的方法是減少數據范圍（使用稍後討論的from和to參數）。

並發請求

一個帳戶一次只能限制一個請求。多個並發請求將按順序執行。

例如：

啟動API請求“ A”。
為同一帳戶啟動API請求“ B”。
在“ A”完成之前，請求“ B”將不會完成。
如果請求“ A”花費的時間太長，則請求“ A”將收到一條錯誤消息：“您的請求未決；請重試”。
如果請求“ A”花費的時間太長，則可能導致請求“ B”收到相同的錯誤。請注意，如果完成A + B的時間大於我們的超時值，則請求“ B”將收到錯誤。

如果您發出多個並發請求，則將按收到的順序一次處理一個。

最終返回“未決錯誤”的請求將完成並保存到我們的緩存中。這意味著將來對同一數據的請求將幾乎立即返回，但前提是該請求是在五分鐘緩存到期之前發出的。

您的系統應通過等待2-4分鐘並再次發出相同的請求來處理未決錯誤。

最佳實務

請求類型

Analytics API接受三種請求類型

數據（也稱為報告）

一個或多個的報告dimensions。報告請求的端點是：

  https://analytics.api.brightcove.com/v1/data?accounts={account_id(s)}&dimensions={dimensions}

參與度報告

過去32天內可使用的詳細參與度數據。有關更多詳細信息，請參閱參與部分。

視頻信息端點

一條特定的分析數據以最小的延遲提供服務。看視頻數據端點了解更多信息。

篩選條件和日期範圍可套用至報表的位置。報告要求可以包含本文件中詳細說明的其他參數。

維度和欄位

有關維度和字段的詳細信息現在位於單獨的文檔中：「標註」、「欄位」和「參數」概述。

參數

有關參數的詳細信息現在位於單獨的文檔中：「標註」、「欄位」和「參數」概述。

參與度報告

在過去32天內，可以查看詳細的參與度報告，其中顯示了視頻的第100部分的觀看次數（或帳戶或播放器所有視頻的平均值）。（對過去32天以外的日期範圍的請求將返回錯誤。）

帳戶參與度

要獲取觀看視頻的參與度平均值，請使用端點：

  
      https://analytics.api.brightcove.com/v1/engagement/accounts/:account_id

玩家參與度

要獲取播放器中觀看的所有視頻的平均值，請使用端點：

  
      https://analytics.api.brightcove.com/v1/engagement/accounts/:account_id/players/:player_id

視訊參與

要獲取特定視頻的參與度數據，請使用端點：

  
      https://analytics.api.brightcove.com/v1/engagement/accounts/:account_id/videos/:video_id

實時分析

提Analytics API供兩個端點，可依時間序列或依事件擷取 Brightcove 即時串流的分析資料。Analytics API Reference如需詳細資訊，請參閱。