ディメンションとフィールド
ディメンションは、アナリティクスの主要なデータ バケットです。個々のディメンションの完全なガイドを参照するには、以下のリストでディメンション名をクリックしてください。
以下のディメンションを選択して、返されるフィールドを確認してください。これらのオプションを使用してリクエストを行うボタンをクリックしてサンプル リクエストを作成し、結果を確認することもできます。互換性のない複数のディメンションを選択すると、その旨のメッセージが表示されます。
注
- デフォルトでは、返されるフィールドは、
video_viewのみで、他のフィールドは、fieldsパラメータの値で指定されている場合にのみ返されます。 - ディメンションまたはディメンションの組み合わせでサポートされていない、フィールドを返すように指定した場合、
UNSUPPORTED_FIELD_COMBINATION_ERRORエラーが返されます。 bytes_deliveredフィールドには、ビデオデータ、画像、テキストトラック、その他のアセットなど、Video Cloudによってクライアントに配信されるすべてのデータと、プレーヤーコード自体が含まれます。このデータの一部はCDNから取得されており、最大3日間利用できない場合があります。videoディメンションに表示されるフィールドに加えて、video.custom_fields.{field_name}を返すこともできます。
リクエストの例
複数のディメンションに関するレポートを取得するための一般的な使用例として、デスクトップとモバイル デバイス間の動画視聴の内訳が知りたい場合、また、モバイル デバイスの視聴のうち、iOSとAndroidデバイスのどちらが多いか、デスクトップの視聴のうち、Mac と Windows マシンのどちらが多いかを知りたい場合があります。現在のところ、この情報を提供する Studio Analytics モジュールの標準レポートはありませんが、この 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を試してみたい場合は、いくつかの注意事項があります：
サンプル
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に置き換えれば、このリクエストは機能するはずです。なお、このサンプルアプリ を使用してアクセストークンを生成することもできます。
サポートされているディメンションの組み合わせ
簡単に参照できるように、以下の表に、サポートされているディメンションとサポートされていないディメンションの組み合わせを示します。上記のディメンションとフィールドツールは、一般的に最大 4 つのディメンジョンの組み合わせに対して正確です。
account |
browser_type |
city |
country |
date |
date_hour |
destination_domain |
destination_path |
device_os |
device_manufacturer |
device_type |
live_stream |
player |
referrer_domain |
region |
search_terms |
social_platform |
source_type |
video |
|
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
account |
n/a | ||||||||||||||||||
browser_type |
n/a | ||||||||||||||||||
city |
n/a | ||||||||||||||||||
country |
n/a | ||||||||||||||||||
date |
n/a | ||||||||||||||||||
date_hour |
n/a | ||||||||||||||||||
destination_domain |
n/a | ||||||||||||||||||
destination_path |
n/a | ||||||||||||||||||
device_os |
n/a | ||||||||||||||||||
device_manufacturer |
n/a | ||||||||||||||||||
device_type |
n/a | ||||||||||||||||||
live_stream |
n/a | ||||||||||||||||||
player |
n/a | ||||||||||||||||||
referrer_domain |
n/a | ||||||||||||||||||
region |
n/a | ||||||||||||||||||
search_terms |
n/a | ||||||||||||||||||
social_platform |
n/a | ||||||||||||||||||
source_type |
n/a | ||||||||||||||||||
video |
n/a |
URLパラメーター
Analytics API レポートは、以下のURLパラメータをサポートしています。
| パラメータ | 説明 | 必須 | 値 | デフォルト |
|---|---|---|---|---|
account |
レポートしたいアカウント | はい | カンマ区切りのリストとしての1つ以上のアカウントID | なし |
dimensions |
レポートしたいディメンション | はい | 1つまたは複数のディメンションをカンマ区切りのリストとして指定します（有効でない組み合わせもあります - 組み合わせが有効かどうかを判断するには、こちらのインタラクティブ ツールを使用して下さい。) | なし |
where |
レポートのフィルタを指定するために使用 | いいえ |
{dimension}=={value} - 1 つ以上のセミコロン区切りリスト。値は、そのディメンジョンの主なメトリックの 1 つ以上の値になります。例えば: account==account_id、country=country-code、viewer=viewer_id (最後の viewer_idの形式は、何らかのviewer_idを自分で取得して送信しているか、分析システムによって生成された値に応じて異なります）。
|
なし |
limit |
返答に含める項目の数 | いいえ | 正整数 | 10 |
offset |
スキップする項目の数 | いいえ | 正整数 | 0 |
sort |
項目を並べ替えるフィールド | いいえ | リクエストによって返されるフィールド | video_view |
fields |
返すフィールド | いいえ | 報告するディメンションによって異なる | video,video_view |
format |
結果を返すフォーマット | いいえ | json (デフォルト) | csv | xlxs | json |
reconciled |
含まれている場合、結果は履歴データまたはリアルタイム データに制限されます。分析データは複数のソースから取得されます。プレーヤーから送信されるデータもありますが、CDN や Video Cloud システムから収集されるデータもあります。可能な限り迅速にアナリティクスを提供するため、「リアルタイム」データが利用可能になるとすぐに配信を開始し、すべてのソースからのデータが収集され処理された後でアナリティクスを調整します。完全に処理されたデータは調整済みと呼ばれます。 | いいえ | true | false | true |
from |
リクエストの日付範囲の先頭 | いいえ |
以下のいずれかになります:
エンゲージメント エンドポイント、または reconciled=false の場合、過去 32 日以内の日付のみが許可されます。 |
-30d |
to |
リクエストの日付範囲の終わり | いいえ |
以下のいずれかになります:
エンゲージメント エンドポイント、または reconciled=false の場合、過去 32 日以内の日付のみが許可されます。 |
now |
アカウント
レポートが必要なVideo Cloudアカウントは、accountsパラメータを使用して指定します。例は次のとおりです。
https://analytics.api.brightcove.com/v1/data?accounts={account1_id,account2_id}
where フィルター
フィルタの一般的な構文は次のとおりです。
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は、"where video = 1234 OR 5678 AND Player= 9876"と解釈されます。
スペースと特殊文字
文字列値はURIエンコードする必要があります。特殊文字は""(ダブルクォテーション)でエスケープすることもできます。
where=search_terms==boston,%20ma
フィルタとして任意のディメンションを使用できますが、しかし、そのディメンションが、リクエストするdimensionsに含まれている場合のみに限ります。
ビデオプロパティによるフィルタリング
特別なwhere=video.q=={property}:{value}フィルタを使用すると、次のような様々なプロパティに基づいて、レポートを特定のビデオセットに制限できます。
- tags
- reference_id
- custom_fields [1]
- {a_specific_custom_field}
- created_at
注
[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のロジックがあることに注意して下さい：
- 検索語の前に +（プラス）記号を付けると、検索結果にこの用語が含まれていなければならないことを意味します。
- 検索語の前に -（マイナス）記号を付けると、検索結果にこの用語が含まれないことを意味します。
- プラス記号もマイナス記号もない場合、検索結果にこの用語が含まれることもあれば、含まれないこともあります。
次の例は、このロジックの使用法を示しています。
whereフィルター |
結果 |
|---|---|
where=video.q==tags:red%20tags:blue%tags:green |
redまたはblueまたはgreenのタグが付いた動画が検索結果として返されます。 |
where=video.q==+tags:red%20tags:blue%tags:green |
返される動画には、red タグが必要であり、blueまたはgreenのタグがついていてもよい。 |
where=video.q==+tags:red%20tags:blue%-tags:green |
返される動画には、red のタグと blue のタグが付いてなければならないが、green のタグがついてないものになります。 |
このクエリ構文の完全な説明については、 CMS APIの使用：ビデオを検索するを参照してください。
フィルターと許容値の概要
次の表に、フィルターとして使用される各ディメンションの許容値を示します。
| ディメンション フィルター | 許容値 |
|---|
日付範囲
すべての種類のレポートの from および to パラメーターで指定された日付範囲は、異なるフォーマットで表示することができます。
- テキスト値：
to=now（利用可能で、すべてのリクエストのデフォルト値）
1377047323000のようなミリ秒単位のエポックタイム値。- ISO 8601標準の国際日付形式で表された日付：
YYYY-MM-DD、例えば2013-09-12など。この形式で表現された日付の場合:- 指定された日付範囲は アカウントに設定されたタイムゾーンで解釈されます。
- 指定された日付の時刻は、アカウントに設定されたタイムゾーン 指定された日付の午前0時 (
00:00:00) として解釈されます
- 相対的な日付：
toとfromの値のいずれかを、もう一方の値と相対的に d（日）または h（時間）で表すことができます。例は次のとおりです。from=2015-01-01&to=31dfrom=-48h&to=nowfrom=-2d&to=now( 前の例と同じ結果になります)from=-365d&to=2014-12-31
負の数（-2d）は "before"（もう一方の値）として解釈され、正の数（48h）は "from"（もう一方の値）として扱われることに注意してください。
"Video" のような1日単位のディメンジョンに関するレポートを作成するには、to値とfrom値をその日付に設定します:
...&dimensions=video&from=2013-11-01&to=2013-11-01
制限とオフセット
limit は返される項目の数です（デフォルト：10）。すべての項目を返すには、limit=all を使用します。offset はスキップする項目の数です（デフォルト：0）。limit と offset を併用して、結果を順に表示するアプリを作成できます。
調整済みデータ
reconciled パラメータはブール値です。true に設定されている場合、結果は調整されたデータに限定されます。false を指定すると、結果はリアルタイム（1時間ごとの調整されていない）データに限定されます。
地理的レポート
地理分析のディメンション
country-ISO-3611-1の国コードとして。例えば：'US'region-ISO-3611-2の地域コードとして。例えば：'US-WA'city- 都市の名前。例えば：Seattle
注:国や地域が不明な場合、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
}
}