概要: オーディエンス API

API リファレンス

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

ベース URL

オーディエンス API のベース URL は次のとおりです。

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

アカウントパス

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

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

[認証]

オーディエンス API は、ブライトコーブ OAuthサービスを使用して呼び出しを認証します。

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

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

また、が必要です。これはaccess_token、client_idおよびを使用して取得されます。client_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 で解釈されます
  • 日付が与えられる時間は、指定された日付の真夜中 ( 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

ページングの結果

limitは、返すアイテムの数です（デフォルト:25、最大:100）。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句: