概述：標註、欄位和參數

維度和欄位

維度是用於分析的主要數據桶。要查看各個尺寸的完整指南，請在下面的列表中單擊尺寸名稱。

選擇下面的維度以查看可以為其返回的字段。您也可以按一下 [提出要求]按鈕，提出範例要求並查看結果。如果您選擇了多個不兼容的尺寸，則會看到一條消息，說明該效果。

  Response will appear here...

注意事項

1. 默認情況下，video_view是返回的唯一字段-只有在fields參數的值中指定了其他字段才會返回。
2. 如果指定要傳回的維度或維度組合不支援的欄位，則會傳回UNSUPPORTED_FIELD_COMBINATION_ERROR錯誤。
3. 該bytes_delivered欄位包括 Video Cloud 傳送給用戶端的所有資料，包括視訊資料、影像、文字軌跡和其他資產，以及播放器程式碼本身。其中一些數據是從CDN獲得的，可能長達3天都無法使用。
4. 除了為video維度顯示的欄位外，您也可以傳回video.custom_fields.{field_name}

範例要求

獲取多個維度的報告的典型用例：您想要細分台式機和移動設備之間的視頻觀看次數，還想知道iOS和Android設備上分別有多少個移動設備觀看次數，以及有多少台式機在Mac和Windows機器上查看。目前，Studio 分析模組中沒有提供此資訊的標準報表，但您可以透過此Analytics API呼叫取得：

  https://analytics.api.brightcove.com/v1/data?accounts=57838016001&dimensions=video,device_type,device_os&from=2014-01-01&to=2014-04-01&fields=video_view

（在這種情況下，我們要求在 2014 年 1 月 1 日至 4 月 1 日期間的視頻觀看。）

使用cURL的示例

如果您想使用 cURL 嘗試 API，以下是幾個注意事項：

• 您首先需要獲取訪問令牌
• 由於請求的 URL 將始終包含 URL 參數，因此您需要將其括在引號中（單或雙引號）

範例

這是一個示例cURL命令：

  curl -s --header "Authorization: Bearer $ACCESS_TOKEN" \
  "https://analytics.api.brightcove.com/v1/data?accounts={account_id}&dimensions=video&from=2017-04-04&limit=100"

如果$ACCESS_TOKEN用有效的訪問令牌替換並{account_id}用您的帳戶 ID 替換，則此請求應該可以正常工作。請注意，您可以使用此示例應用程序生成訪問令牌。

支持的尺寸組合

為了快速參考，下表顯示了受支持的尺寸組合。請注意，在某些情況下可以使用兩個以上的尺寸。您可以使用上面的尺寸和字段工具來解決這些問題。

網址參數

分析 API 報表支援下列 URL 參數。

帳戶

您要建立報告的視訊雲帳戶是使用accounts參數指定的。例如：

  https://analytics.api.brightcove.com/v1/data?accounts={account1_id,account2_id}

哪裡過濾

過濾器的一般語法為：

where=dimension1==value1;dimension2==value2

例如：

https://analytics.api.brightcove.com/v1?accounts=account_id(s)&dimensions=device_type&where=video==video_id;device_type==tablet

逗號被視為邏輯“或”，分號被視為邏輯“與”。例如，where=video==1234,5678;player==9876被解釋為「其中視頻 = 1234 或 5678 和播放器 = 9876」

空格和特殊字符

字符串值應為URI編碼。您也可以使用“”轉義特殊字符：

where=search_terms==boston,%20ma

您可以使用任何維度作為篩選器，但前提是該維度也包含在dimensions您要求的維度中。

按視頻屬性過濾

使用特殊where=video.q=={property}:{value}篩選器，您可以根據各種屬性，將報告限制為特定的一組影片，包括：

• 標籤
• 參照 _ 識別碼
• 自訂欄位^[1]
• {a_specific_custom_field}
• 建立

注意事項

^[1] 基本語法是where=video.q==custom_fields:value（與任何自定義字段中的值匹配）或where=video.q==myfield:value（與特定自定義字段中的值匹配myfield）。如果您要搜尋特定的自訂欄位，請注意，您必須搜尋「內部名稱」，而不是「顯示名稱」：

快速檢查您是否使用正確的名稱：內部名稱將全部為小寫字母，不包含空格。

範例

以下是一些用於搜索標籤和自定義字段的where過濾器示例：

單標籤

where=video.q==tags:foo

多個標籤：

where=video.q==tags:foo,bar

自訂欄位

where=video.q==custom_fields:foo

標籤和自定義字段

where=video.q==tags:foo,bar+custom_fields:fish

請注意，video.q搜索功能包括AND , OR和NOT邏輯如下：

• 搜索詞前的 + （加號）表示結果 必須 包含該詞。
• 搜索詞前的 - （減號）表示結果 不得 包含該詞。
• 如果既沒有加號也沒有減號，則結果可能包含也可能不包含此項。

以下示例說明了此邏輯的用法。

如需此查詢語法的完整說明，請參閱使用 CMS API：搜索視頻。

過濾器和允許值的摘要

下表顯示了用作過濾器的每個維度的允許值：

日期範圍

在中指定的日期範圍from和所有類型報表的to參數可以用不同的格式表示：

• 文字值：
  • to=now（可用且所有請求的默認值）
• 紀元時間值 (以毫秒為單位)，例如1377047323000
• 以 ISO 8601 標準國際日期格式表示的日期：YYYY-MM-DD格式，例如2013-09-12。對於以此格式表示的日期：
  • 指定的任何日期範圍都將在帳戶設定的時區中解釋
  • 日期給出的時間將被解釋為午夜 ( 00:00:00 ) 在指明的日期在為帳戶設置的時區
• 相對日期：您可以在 d（天）或 h（小時）中表示與另一個相對的to和from值之一。例如：
  • from=2015-01-01&to=31d
  • from=-48h&to=now
  • from=-2d&to=now（將給出與前面的示例相同的結果）
  • from=-365d&to=2014-12-31

  請注意，負數（-2d）解釋為“在”之前（另一個值），正數（48h）被解釋為“從”（另一個值）

要在某一天生成諸如“視頻”之類的維度的報告，請將該日期的to和from值設置為：

...&dimensions=video&from=2013-11-01&to=2013-11-01

限制和偏移

limit是要傳回的項目數目 (預設值：10)。若要退回所有項目，請使用limit=all。offset是要略過的項目數目 (預設值：0)。您可以使用limit並offset一起創建一個頁面瀏覽結果的應用程序。

對帳數據

該reconciled參數是一個布爾值。如果設定為true，則結果將限制為協調資料。如果false，結果將限制為即時 (每小時未調和) 資料。

地理報告

地理分析的維度

• country -作為ISO-3611-1國家/地區代碼。例如：'我們'
• region -作為ISO-3611-2區域代碼。例如：'US-WA'
• city - 城市名稱。例如：西雅圖

注意：對於未知的國家或地區，API返回“ ZZ”作為代碼（根據ISO-3611-alpha2）。

字段和排序

使用fields參數來指定您要傳回的欄位。依預設，video_view會傳回並傳回與您要報告之維度相對應的欄位 (例如destination_domain )。看維度和字段更多細節。

使用sort參數可指定用來排序傳回項目的量度欄位，例如：sort=video_view。您可以通過否定排序字段來反轉排序順序： sort= -video_view .

計算字段

您可以使用以下語法將計算出的字段添加到您的API請求中：

fields=calulated_field_name:expression

您可以使用計算字段來根據現有指標創建自己的自定義字段，也可以重命名現有字段。

計算字段的名稱可以是任何與URI兼容的字符串。該表達式可以包含常規字段名稱和以下算術運算符：

• + （加法）
• - (減法)
• * （乘法）
• / (除法)
• ^ （指數）
• () (括號)

範例

fields=avg_seconds_viewed:video_seconds_viewed/video_view,video.name

fields=avg_incomplete_ads:(ad_mode_begin-ad_mode_complete)/video_view,video.name

fields=Video%20Views:video_view,video.name

樣本請求

樣本響應（針對以上請求）

{
  "item_count": 110,
  "items": [
    {
      "avg_seconds_viewed": 2152.2519913106444,
      "video.name": "Flamingos",
      "video_seconds_viewed": 2972260,
      "video": "4825279519001",
      "video_view": 1381
    },
    {
      "avg_seconds_viewed": 14.016225448334756,
      "video.name": "Tiger",
      "video_seconds_viewed": 16413,
      "video": "4093643993001",
      "video_view": 1171
    },
    {
      "avg_seconds_viewed": 12.06,
      "video.name": "Zebra",
      "video_seconds_viewed": 9045,
      "video": "3851389913001",
      "video_view": 750
    },
    {
      "avg_seconds_viewed": 23.343065693430656,
      "video.name": "Sea-SeaTurtle",
      "video_seconds_viewed": 15990,
      "video": "1754276205001",
      "video_view": 685
    }
  ],
  "summary": {
    "avg_seconds_viewed": 274.27374399301004,
    "video_seconds_viewed": 3139063,
    "video_view": 11445
  }
}