サポート問い合わせ先| システムステータス
ページコンテンツ

    概要:ディメンション、フィールド および パラメーター

    ディメンションは、 Analytics API データレポートの主要なデータ分類です。このトピックでは、ディメンションとその他について説明します。また、レポートでどのディメンションを組み合わせられるか、およびさまざまな組み合わせで使用できるフィールドを示します。

    ディメンションとフィールド

    ディメンションは、アナリティクスの主要なデータ バケットです。個々のディメンションの完全なガイドを参照するには、以下のリストでディメンション名をクリックしてください。

     
     

    以下のディメンションを選択して、返されるフィールドを確認してください。これらのオプションを使用してリクエストを行うボタンをクリックしてサンプル リクエストを作成し、結果を確認することもできます。互換性のない複数のディメンションを選択すると、その旨のメッセージが表示されます。

    入力

    レポートするディメンションを選択します。

     
     

    返すフィールド:

     
     

    (サンプルのBrightcoveアカウントを使用)

    出力

    このディメンションの組み合わせで最も古い日付: から

     

    サンプルAPIリクエスト:

    応答データ

      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 モジュールの標準レポートはありませんが、この 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に置き換えれば、このリクエストは機能するはずです。なお、このサンプルアプリ を使用してアクセストークンを生成することもできます。

    サポートされているディメンションの組み合わせ

    簡単に参照できるように、以下の表に、サポートされているディメンションとサポートされていないディメンションの組み合わせを示します。上記のディメンションとフィールドツールは、一般的に最大 4 つのディメンジョンの組み合わせに対して正確です。

    Supported Dimension Combinations
      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パラメータをサポートしています。

    URL Parameters
    パラメータ 説明 必須 デフォルト
    account レポートしたいアカウント はい カンマ区切りのリストとしての1つ以上のアカウントID なし
    dimensions レポートしたいディメンション はい 1つまたは複数のディメンションをカンマ区切りのリストとして指定します(有効でない組み合わせもあります  - 組み合わせが有効かどうかを判断するには、こちらのインタラクティブ ツールを使用して下さい。) なし
    where レポートのフィルタを指定するために使用 いいえ {dimension}=={value} - 1 つ以上のセミコロン区切りリスト。値は、そのディメンジョンの主なメトリックの 1 つ以上の値になります。例えば: account==account_idcountry=country-codeviewer=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 リクエストの日付範囲の先頭 いいえ 以下のいずれかになります:
    • ISO 8601 の日付 (YYYY-MM-DD)
    • ミリ秒単位のエポック時間 (例: 1659641316719 [= Thursday, August 4, 2022 7:28:36.719 PM GMT]). Epoch 時間コンバーターを参照して下さい。
    • 文字列: from=alltime
    • 日(d)、週(w)、月(m) での+/- 相対日付 - 例:from=-6m&to=%2B2w (6 ヶ月前から 2 週間後までの期間。+ 記号は%2Bとして URI エンコードする必要があることに注意して下さい)。

    エンゲージメント エンドポイント、または reconciled=false の場合、過去 32 日以内の日付のみが許可されます。

    -30d
    to リクエストの日付範囲の終わり いいえ 以下のいずれかになります:
    • ISO 8601 の日付 (YYYY-MM-DD)
    • ミリ秒単位のエポック時間 (例: 1659641316719 [= Thursday, August 4, 2022 7:28:36.719 PM GMT]). Epoch 時間コンバーターを参照して下さい。
    • 文字列: to=now
    • 日(d)、週(w)、月(m) での+/- 相対日付 - 例:from=-6m&to=%2B2w (6 ヶ月前から 2 週間後までの期間。+ 記号は%2Bとして URI エンコードする必要があることに注意して下さい)。

    エンゲージメント エンドポイント、または 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の値と一致)します。特定のカスタムフィールドを検索する場合は、表示名ではなく内部名で検索する必要があることに注意してください:

    Internal Name vs Display Name
    内部名と表示名

    正しい名前を使用しているかどうかを簡単に確認します: 内部名はすべて小文字で、スペースは含まれません

    ここでは、タグとカスタムフィールドを検索するための 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 の検索機能には、次のようなANDORそして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 ) として解釈されます
    • 相対的な日付: tofrom の値のいずれかを、もう一方の値と相対的に d(日)または h(時間)で表すことができます。例は次のとおりです。
      • from=2015-01-01&to=31d
      • from=-48h&to=now
      • from=-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)。limitoffset を併用して、結果を順に表示するアプリを作成できます。

    調整済みデータ

    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
      }
    }

    ページの最終更新日22 Sep 2021