概要：Audience API

API リファレンス

「 API リファレンス」も参照してください。

ベース URL

Audience API のベース URL は次のとおりです。

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

アカウントパス

いずれの場合も、特定の Video Cloud アカウントに対してリクエストが行われます。ベース URL には、常に「アカウント」という語句の後にアカウント ID を追加する必要があります。

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

認証

Audience API は、Brightcove OAuth サービスを使用して呼び出しを認証します。

まず、クライアントの資格情報（a client_idとclient_secret）を取得する必要があります。これは、 OAuth 認証情報 UI を使用して実行できる 1 回限りの操作です。Audience/Read オペレーションの権限が必要です。

cURL または Postman を使用して、Brightcove OAuth サービスから直接クライアント認証情報を取得できます。

また、が必要です。これはaccess_token、client_idclient_secretおよびを使用して取得され、API リクエストで Authorization ヘッダーで渡されます。

Authorization: Bearer {access_token}

は 5 access_token分後に有効期限が切れるため、リクエストごとに 1 つ取得するか、トークンがまだ有効であることを確認する必要があります。アクセストークンの取得方法の詳細については、「アクセストークンの取得」を参照してください (コードサンプルを含む)。

エラー処理

エラーが発生した場合、API は次のいずれかのステータスコードと、応答本文に対応するエラーコードを使用して応答します。

以下は、エラーに対するレスポンスボディの例です。

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

パラメーター

取得するデータを制限およびフィルタリングするために、リクエストに追加できるパラメータがいくつかあります。これらは、以降のセクションで説明するすべてのリクエストタイプに適用されます。

結果のフィルタリング

whereパラメータを使用して結果をフィルタリングできます。フィルタの構文は次のとおりです。

where=field1==value1;field2==value2

例は次のとおりです。

where=video_id==123456789;video_name==test

カンマは論理 OR として扱われ、セミコロンは論理 AND として扱われます。たとえば、where=video_id==1234,5678;video_name=testは「video_id = 1234 または 5678、および video_name = テスト」と解釈されます。

返すフィールドの選択

リクエストでフィールドのリストを指定して、結果をそのフィールドのサブセットに限定することができます。フィールドの構文は次のとおりです。

fields=field1,field4

例は次のとおりです。

fields=video_id,video_name

フィルタリングおよび並べ替えが可能なフィールドは、次のセクションの各リクエストタイプについて詳しく説明します。

日付範囲

日付範囲は、fromtoおよびパラメータで指定でき、ビューイベントが最後に更新された日付 (updated_at フィールド) に適用されます。日付の範囲は、次の形式で示すことができます。

• now現在の時刻を表すテキスト値
• エポック時間値 (ミリ秒単位)。1377047323000
• ISO 8601 標準の国際日付形式: YYYY-MM-DD形式 (など) で表される日付2013-09-12。この形式で表現された日付の場合:
  • 指定された日付範囲は UTC で解釈されます
  • 日付を与える時間は、指定された日付の午前 0 時 ( 00:00:00 ) として解釈されます
• 相対日付: tofromその他の値との相対値のいずれかを表すことができます。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

ページングの結果

NS limit返されるアイテムの数です（デフォルト：25、最大：200）。offsetスキップするアイテムの数です（デフォルト：0）。limitoffsetとを併用して、結果をページスルーするアプリを作成できます。各にはlimit、offset、count.、およびが含まれ、これらを使用して、合計結果に対する反復を設定できます。たとえば、JavaScript では、次のように必要な反復の合計を取得できます。

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

ビューイベントを取得しています

アカウント内のビューイベントを取得するには、view_events GETリソースへのリクエストを実行します。

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

リードの取得

アカウントでビューイベントを取得するには、GETview_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句：