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

    概要: Analytics API v1

    このトピックでは、分析 API の概要を説明します。
     

    はじめに

    ザ・Analytics API VideoCloudアカウントの分析データを直接取得できます。また、Video Cloud Studio の分析モジュールで組み込みの分析レポートを表示することもできます。プログラムでデータにアクセスすると、柔軟性が向上します。

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

    一般的な用途

    APIの一般的な使用法は次のとおりです。

    • カスタムチャートと表示の作成
    • 複数の API を一緒に操作する-たとえば、CMS API前週で最も視聴回数が多い動画の「」を使用してビデオデータを取得する
    • 動画分析データを他のサイト分析データと組み合わせる
    • いくつかのサンプルソリューションについては、を参照してください。

    ベース URL

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

      <code class = "language-http translate =" No "> https://analytics.api.brightcove.com/v1

    ヘッダー

    認証（必須）

    ザ・Analytics APIBrightcove を使用OAuthサービス通話を認証します。

    まず、クライアントの資格情報（a client_idとclient_secret）を取得する必要があります。これは、 OAuth 認証情報 UI を使用して実行できる 1 回限りの操作です。を使用して、BrightcoveOAuthサービスから直接クライアント資格情報を取得できます。CURL、Postman、またはInsomnia。

    クライアント資格情報には、Analytics読み取りとビデオ読み取りの両方のアクセス許可が必要です。

    <img class = "bcls-image" alt = "<span translate =" No ">アナリティクスAPIの権限資格情報 "src =" / assets / images / analysis / getting-started / analytics-permissions.png "/>
    の権限Analytics API資格情報

    OAuth APIを介して直接認証情報を作成する場合、必要な権限は次のとおりです。

      [
    "video-cloud/analytics/read"
    "video-cloud/video/read"
  ]

    また、access_token、を使用して取得されますclient_idそしてclient_secret APIリクエストとともにAuthorizationヘッダーを渡します。

      Authorization: Bearer {access_token}

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

    Accept-Encoding: gzip (optional)

    このヘッダーを渡すと、応答が圧縮された形式で返されます。これにより、大きなレポートのパフォーマンスが向上する場合があります。

    キャッシュ

    パフォーマンス上の理由から、API応答は約5分間キャッシュされますが、正確な時間はいくつかの要因によって異なる場合があります。どんな場合でもAnalytics APIクエリでは、応答ヘッダーからキャッシュに関する情報を取得できます。

    キャッシュ制御ヘッダー
    キャッシュ制御ヘッダー

    ザ・Cache-Control結果がキャッシュされる最大時間を秒単位で示します（上記の例では24秒）。ザ・Last-ModifiedそしてExpiresヘッダーは、現在のキャッシュがいつ作成され、いつ期限切れになるかを示します。

    ほとんどの場合、これはおそらく問題ではありませんが、分析データの鮮度が非常に重要である場合は、クエリの実行時間が長くなるほど、キャッシュされる時間が長くなり、リアルタイム（調整されていない1時間ごと）のデータのみをフェッチするレポートが作成されることを知っておく必要があります。調整されたデータをフェッチするもの（リアルタイムデータのみ、またはリアルタイムデータに加えて）である限り、キャッシュされません。見つけるリアルタイムおよび調整済みデータの完全な説明もし良かったら;短いバージョンはAnalytics API 2つのデータバケットに依存しています。

    • リアルタイム、または1時間ごとの調整されていないデータ。すぐに利用可能になり、32日間保存されます。
    • 永続的に保存される調整済みデータ。リアルタイムデータは精度を向上させるために調整され、24時間ごとに調整されたデータリポジトリに保存されます

    を使用して、結果を調整済みデータまたはリアルタイムデータに制限できます。和解パラメータ。

    キャッシュを最小限に抑えるには：

    • 使用reconciled=false結果をリアルタイムデータに制限するパラメータ
    • 小さいものを使用する日付範囲、および範囲全体が過去32日以内であることを確認してください

    タイムアウト

    Analytics APIは、完了していない場合、8分後にタイムアウトを要求します。8分未満でタイムアウトが発生する場合、原因はクライアント側の制限です。

    返品できるアイテムの最大数

    返品できる商品の最大数は100万個です。ほとんどの場合、制限に達する可能性は低いですが、レポートを要求している場合はdateたとえば、長期間にわたる寸法は可能です。百万アイテムの制限に達した場合は、リクエストを変更して、返されるアイテムの数を減らす必要があります。一般に、これを行う最も簡単な方法は、データ範囲を縮小することです（fromそしてto後で説明するパラメータ）。

    同時リクエスト

    1つのアカウントは、一度に1つのリクエストに制限されています。複数の同時リクエストが連続して実行されます。

    例は次のとおりです。

    1. APIリクエスト「A」を開始します。
    2. 同じアカウントのAPIリクエスト「B」を開始します。
    3. リクエスト「B」は「A」が完了するまで完了しません。
    4. リクエスト「A」に時間がかかりすぎると、リクエスト「A」は「リクエストは保留中です。再試行してください」というエラーを受け取ります。
    5. リクエスト「A」に時間がかかりすぎると、リクエスト「B」が同じエラーを受け取る可能性があります。A + Bを完了する時間がタイムアウト値よりも大きい場合、リクエスト「B」はエラーを受け取ることに注意してください。

    複数の同時リクエストを行う場合、それらは受信した順序で一度に1つずつ処理されます。

    「保留中のエラー」で返されるリクエストは、最終的に完了し、キャッシュに保存されます。これは、同じデータに対する今後のリクエストがほぼ瞬時に返されることを意味しますが、5分間のキャッシュが期限切れになる前にリクエストが行われた場合に限ります。

    システムは、2〜4分待ってから同じ要求を再度行うことにより、保留中のエラーを処理する必要があります。

    ベストプラクティス

    リクエストタイプ

    ザ・Analytics API 3つのリクエストタイプを受け入れます

    データ（レポートとも呼ばれます）
    1つ以上のレポートdimensions。レポートリクエストのエンドポイントは次のとおりです。 
      https://analytics.api.brightcove.com/v1/data?accounts={account_id(s)}&dimensions={dimensions}
    エンゲージメントレポート
    過去32日以内の期間に利用可能な詳細なエンゲージメントデータ。見るエンゲージメントセクション詳細については。
    ビデオ情報エンドポイント
    最小限のレイテンシで提供される特定の分析データ。見るビデオデータエンドポイント詳細については。

    フィルターをかける場所そして日付範囲レポートに適用できます。レポートリクエストには、このドキュメント。

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

    ディメンションとフィールドの詳細情報は、別のドキュメントにあります。ディメンション、フィールド、パラメータの概要。

    パラメーター

    パラメータの詳細情報は、別のドキュメントにあります。ディメンション、フィールド、パラメータの概要。

    エンゲージメントレポート

    動画の100番目の部分ごとの視聴回数（またはアカウントまたはプレーヤーのすべての動画の平均）を示す詳細なエンゲージメントレポートは、過去32日以内の期間で利用できます。（過去32日以外の日付範囲をリクエストすると、エラーが返されます。）

    アカウントエンゲージメント

    視聴した動画のエンゲージメントの平均値を取得するには、エンドポイントを使用します。

      
      https://analytics.api.brightcove.com/v1/engagement/accounts/:account_id

    プレーヤーの関与

    プレーヤーで視聴されたすべての動画の平均値を取得するには、エンドポイントを使用します。

      
      https://analytics.api.brightcove.com/v1/engagement/accounts/:account_id/players/:player_id

    動画エンゲージメント

    特定の動画のエンゲージメントデータを取得するには、エンドポイントを使用します。

      
      https://analytics.api.brightcove.com/v1/engagement/accounts/:account_id/videos/:video_id

    ライブ分析

    ザ・Analytics API時系列またはイベントのいずれかによって、Brightcoveライブストリームの分析を取得するための2つのエンドポイントを提供します。を参照してくださいAnalytics API Reference詳細については。