概述：受眾 API

API 參考

另請參閱API參考。

基本網址

Audience API的基本URL為：

https://audience.api.brightcove.com/v1

帳號路徑

在所有情況下，我們都會針對特定的視訊雲端帳戶提出要求。您將始終需要在基本網址中添加“帳戶”一詞，然後添加您的帳戶ID：

https://audience.api.brightcove.com/v1/accounts/{account_id} 

驗證

Audience API使用Brightcove OAuth服務驗證電話。

您首先需要取得用戶端憑證 (a client_id和client_secret )。這是一次性操作，可以使用OAuth憑證使用者介面。您將需要受眾群體/閱讀操作的權限：

您可以使用以下方法直接從Brightcove OAuth服務獲取客戶端憑據：捲曲要么郵差。

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

Authorization: Bearer {access_token}

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

處理錯誤

如果發生錯誤，API將在響應正文中使用以下狀態代碼之一和相應的錯誤代碼進行響應：

以下是錯誤的示例響應正文：

[
   {
    "error_code": "UNAUTHORIZED_ERROR",
    "message": "Permission denied"
   }
]

參數

您可以將幾個參數添加到請求中，以限制和過濾檢索到的數據。這些適用於以下各節中描述的所有請求類型。

篩選結果

您可以使用where參數。過濾器的語法為：

where=field1==value1;field2==value2

例如：

where=video_id==123456789;video_name==test

逗號被視為邏輯“或”，分號被視為邏輯“與”。例如，where=video_id==1234,5678;video_name=test被解釋為“其中video_id = 1234或5678，而video_name =測試”。

選擇要返回的字段

可以在請求中指定字段列表，以將結果限制為該字段子集。字段的語法為：

fields=field1,field4

例如：

fields=video_id,video_name

在以下各節中，針對每種請求類型詳細說明了可以過濾和排序的字段。

日期範圍

日期範圍可以在from和to參數和應用於視圖事件的最後更新日期（updated_at字段）。日期範圍可以用以下格式表示：

• 文字值now代表當前時間
• 以毫秒為單位的紀元時間值，例如1377047323000
• 以ISO 8601標準國際日期格式表示的日期：YYYY-MM-DD格式，例如2013-09-12。對於以此格式表示的日期：
  • 指定的任何日期範圍將以UTC解釋
  • 給出日期的時間將被解釋為午夜（00:00:00）在指定的日期
• 相對日期：您可以表達to和from相對於另一個值d（天），h（小時），m（分鐘），或s（秒）。例如：
  • from=2015-01-01&to=31d
  • from=-48h&to=now
  • from=-2d&to=now（將給出與前面的例子相同的結果）
  • from=-365d&to=2015-12-31
  • from=-10m&to=now

分頁結果

的limit是要返回的項目數（默認：25；最大：100）。offset是要跳過的項目數（默認值：0）。您可以使用limit並offset一起建立分頁結果的應用程式。每個都包括limit，offset和count.，您可以用來設置總結果的迭代。例如，在JavaScript中，您可以像這樣獲得所需的總迭代次數：

// response is the JSON-parsed response from the first request
var totalRequests = Math.ceil(response.count / response.limit)

檢索視圖事件

要檢索帳戶中的查看事件，請執行GET對view_events資源的請求：

https://audience.api.brightcove.com/v1/accounts/{account_id}/view_events

這是cURL中的示例請求

curl -i https://audience.api.brightcove.com/v1/accounts/{account_id}/view_events?where=video_id==123&from=-5d&to=now&sort=-created_at \
  -H "Authorization: Bearer {token}"

響應將如下所示：

{
    "count": 27,
    "limit": 25,
    "offset": 0,
    "result": [
        {
            "created_at": "2016-04-25T18:30:21.651Z",
            "page_url": "http://players.brightcove.net/1486906377/V1s6NOwRx_default/index.html?videoId=4842718056001",
            "player_id": "V1s6NOwRx",
            "time_watched": 2,
            "updated_at": "2016-04-25T18:30:21.651Z",
            "video_id": "4842718056001",
            "video_name": "Horses Heading to the Track",
            "watched": 19
        },
        {
            "created_at": "2016-04-25T18:31:55.071Z",
            "page_url": "http://players.brightcove.net/1486906377/BkgFuzyhg_default/index.html?videoId=4842718056001",
            "player_id": "BkgFuzyhg",
            "time_watched": 15,
            "updated_at": "2016-04-25T18:32:00.879Z",
            "video_id": "4842718056001",
            "video_name": "Horses Heading to the Track",
            "watched": 99
        }, ...
    }
]

用於篩選和選擇的欄位

所有參數可以與view_event要求。

以下是使用參數的 cURL 中的示例請求：

curl -i https://audience.api.brightcove.com/v1/accounts/{account_id}/view_events?where=video_id==123&from=-5d&to=now&sort=-created_at \
  -H "Authorization: Bearer {token}"

支持以下字段view_event過濾時的請求where子句或在fields條款：

檢索線索

要檢索帳戶中的查看事件，請執行GET要求view_events資源：

https://audience.api.brightcove.com/v1/accounts/{account_id}/leads

範例回應：

{
    "count": 2,
    "limit": 25,
    "offset": 0,
    "result": [
        {
            "created_at": "2016-06-30T12:57:11.283Z",
            "email_address": "bbailey@brightcove.com",
            "first_name": "Bob",
            "last_name": "Bailey",
            "page_url": "http://players.brightcove.net/1486906377/Hk4TBqzL_default/index.html?videoId=4997275041001",
            "player_id": "Hk4TBqzL",
            "video_id": "4997275041001"
        },
        {
            "created_at": "2016-06-30T12:57:33.301Z",
            "email_address": "rcrooks@brightcove.com",
            "first_name": "Robert",
            "last_name": "Crooks",
            "page_url": "http://players.brightcove.net/1486906377/Hk4TBqzL_default/index.html?videoId=4997275041001",
            "player_id": "Hk4TBqzL",
            "video_id": "4997275041001"
        }
    ]
}

用於篩選和選擇的欄位

所有參數可以與leads要求。

以下是使用參數的 cURL 中的示例請求：

curl -i https://audience.api.brightcove.com/v1/accounts/{account_id}/leads?where=video_id==123&from=-5d&to=now&sort=-created_at \
  -H "Authorization: Bearer {token}"

支持以下字段leads過濾時的請求where子句或在fields條款：