レポートエンドポイントへのアクセス

基本事項

Brightcove Interactivity は、2 つの API エンドポイントセットを通じてレポートデータへのプログラムによるアクセスを提供します。

エンゲージメントレポートのベース URL

https://interactivity-reporting.api.brightcove.com/api/reports/v2/

アナリティクスレポートのベース URL

https://interactivity.api.brightcove.com

リクエストの認証

レポート API は、クライアントクレデンシャルフローを使用した Brightcove のOAuth システムによって認証されます。これは、クライアントクレデンシャル（client_id と client_secret）を取得し、それらを使用してアクセストークンを取得し、以下のように Authorization ヘッダーに含めて送信することを意味します：

Authorization: Bearer access_token_here

アクセストークンの生成方法については、アクセストークンの取得に関する情報を参照してください。

クライアントクレデンシャルを最も簡単に取得する方法は Studio を利用することです。詳細は API クレデンシャルの管理をご覧ください。Interactivity に必要な権限は以下の通りです：

自身のレポート API キーは、Brightcove Interactivity ポータルの管理者メニュー内の「統合」タブにあります。レポート API キーはパスワードと同様に慎重に取り扱ってください。第三者がそのキーを持っていれば、あなたのアカウントのレポートデータを取得できてしまいます。

レポートリクエスト用のベース URL:

URL 構造の例

https://[base-url]/[report-name]?send_status=true&[parameters]

リクエストの例

interactivity-reporting.api.brightcove.com/api/reports/v2/project_engagement_summary_raw?send_status=true&account_id=6415650835001

APIリクエストの構築

API は、ベース API URL への GET 操作によって呼び出されます。リクエストには有効な Authorization ヘッダーを含める必要があります。特定のレポートは、ベース API URL にレポート名と有効なパラメータを追加することでリクエストされます。

結果は同期的には返されません。 レポート API の操作は非同期であり、リクエストの返答時点で結果がまだ利用できない場合があります。その場合、リクエストはキューに追加され、結果を取得するにはポーリング（定期的な再リクエスト）を行うか、後で再度リクエストする必要があります。

リクエストには常に send_status=true を含める必要があります。これにより、レポート処理中は API が HTTP 202 ステータスを返し、処理完了後に結果と共に HTTP 200 を返すようになります。

結果の取得にポーリングが必要かどうかを判断するには、API から返される HTTP ステータスコードを確認してください。「202 Accepted」の場合、レポートはまだ生成中であり、少し時間をおいて再度リクエストを行う必要があります。完了すると、HTTP 200 ステータスコードと共に結果が返されます。レポート結果が一度生成されると、その結果は 1 日間キャッシュされ、以降のリクエストには即座に返されます。

エンゲージメントレポートのエンドポイント

以下のレポートは、次のベースURLを通じてAPI経由で取得することができます: https://interactivity-reporting.api.brightcove.com/api/reports/v2/

名前	説明	エンドポイント
プロジェクト概要	プロジェクトごとに1行	project_engagement_summary_raw
ユーザー概要	ユーザーごとに1行	user_engagement_summary_raw
エクスペリエンス概要	エクスペリエンスごとに1行	experience_engagement_summary_raw
投票ウィジェット概要	投票ウィジェットのインスタンスごとに1行。`poll_widget_summary` のレスポンス値には回答数が含まれます。プロジェクトIDには、該当の投票が表示および送信されたすべてのプロジェクトのリストが含まれます。同じ投票ウィジェットが複数のプロジェクトで使用されるテンプレートに対応しています。注: プロジェクトIDのリストは重複排除されていません。	poll_widget_summary
サインインウィジェット概要	サインインウィジェットのインスタンスごとに1行。各種サインイン統計の件数を含みます。プロジェクトIDには、該当のサインインが表示および送信されたすべてのプロジェクトのリストが含まれます。同じサインインウィジェットが複数のプロジェクトで使用されるテンプレートに対応しています。注: プロジェクトIDのリストは重複排除されていません。	signin_widget_summary
ユーザーアクティビティストリーム	アクションごとに1行（ユーザーIDが判明している場合は含む） * ブックマークの表示、プレーヤーコントロール、アノテーション、ウィジェットに対するユーザーの操作を含みます。 **「Progress」イベントは含まれません。	user_stream_raw
プロジェクトアクティビティストリーム	アクションごとに1行 * ブックマークの表示、プレーヤーコントロール、アノテーション、ウィジェットに対するユーザーの操作を含みます。 **「Progress」イベントは含まれません。	project_stream_raw
エクスペリエンスストリーム	アクションごとに1行 * ブックマークの表示、プレーヤーコントロール、アノテーション、ウィジェットに対するユーザーの操作を含みます。 **「Progress」イベントは含まれません。	experience_stream_raw
投票ウィジェット詳細	投票の送信イベントごとに1行	poll_widget_detail
サインインウィジェット詳細	サインイン送信イベントごとに1行。以前の手動サインインにより自動でサインインされたイベントも含みます。	signin_widget_detail
チャプター概要レポート	チャプターアノテーションごとに1行	chapter_summary
ユーザー感情ウィジェット	プロジェクトごとに1行	widget_user_sentiment_summary

エンゲージメントレポートのパラメータ

すべてのエンゲージメントレポートエンドポイントは、以下のパラメータを受け取ります：

start

レポート結果の開始日。デフォルト値は「end」日から7日前。日付の形式は YYYY-MM-DD。すべての時間はUTCです。

end

レポート結果の終了日。デフォルト値は現在の日の終わり。例えば、今日が2021-09-23の場合、デフォルトの終了日は2021-09-23 23:59:59.999です。

format

レポート結果の出力形式。サポートされている値は: csv および json。

send_status

APIとのやり取りを簡単にするために、常に send_status=true を含めることを推奨します。これにより、レポート処理中は HTTP 202ステータスが返され、完了後に結果とともに HTTP 200が返されます。

アナリティクスレポートのエンドポイント

以下のレポートは、次のベースURLを通じてAPI経由で取得できます: https://interactivity.api.brightcove.com

レポート名	説明	エンドポイントパス
成績概要レポート（Gradebook Summary Report）	ユーザーIDごとに正解数を集計して取得します。	`/v1/accounts/{account_id}/reports/gradebook/summary`
ユーザー回答レポート（Gradebook User Answer Report）	ユーザーが送信した回答を取得します。	`/v1/accounts/{account_id}/reports/gradebook/users/answers`
クイズアクションレポート（Quiz Actions Report）	プロジェクトごとに回答された質問の件数を取得します。	`/v1/accounts/{account_id}/reports/quiz/actions`
クイズプロジェクト概要レポート（Quiz Project Summary Report）	質問および回答ごとに集計されたユニーク回答件数を取得します。	`/v1/accounts/{account_id}/reports/quiz/project/summary`

アナリティクスレポートのパラメータ

各エンドポイントの全パラメータと詳細については、Interactivity API リファレンスを参照してください。

以下は一部のエンドポイントで共通して使用されるパラメータです：

account_id

レポートを要求するアカウントの一意の識別子。

project_id

プロジェクトIDで結果をフィルタリングします。

start_time

と

end_time

レポートの時間範囲を定義します。

user_id

ユーザー別のクイズデータを取得するためのオプションフィールドです。

重要な詳細：制限事項

最大行数 - APIは出力結果を最大 500,000 行に制限しています。この制限を超えるデータは結果に含まれません。
最大期間 - APIは取得可能なデータの期間を最大6か月に制限しています。
レート制限 - デフォルトでは、レポート API は1分あたり最大4件、1時間あたり20件、1日あたり100件のレポート実行に制限されています。この制限は、レポート結果の取得やステータスの確認のためにエンドポイントへアクセスする回数ではなく、「実行可能なユニークなレポート数」に適用されます。

Pythonコードの例

以下の例は、一般的な Requests ライブラリを使用して、Python からレポートを呼び出す方法を示しています。

import requests
 import sys
 import time

 TIMEOUT = 120 # consider a report "timed out" if running > 2

 minutes = True
 processing = True
 BASE_DOMAIN= "https://interactivity-reporting.api.brightcove.com/api/reports/v2/"

 url = BASE_DOMAIN+"api/reports/v2/project_engagement_summary_raw"
 print(url)

 # Reporting endpoint url
 querystring = {
     "start": "2023-07-01",
     "end": "2024-03-31",
     "format": "csv", # csv or JSON
     "send_status":"true"
     }
 headers = {
     'Authorization': "Bearer {Brightove Access Token}",
     'cache-control': "no-cache",
     }
     
 start_time = time.time()
 while processing:
     if time.time() - start_time > TIMEOUT:
         print('Report timed-out')
         sys.exit(-1)
 response = requests.request("GET", url, headers=headers, params=querystring) 
 print('Result: {}'.format(response.status_code))
 if response.status_code == 200:
     processing = False
     print(response.text)
 elif response.status_code == 202:
     print('sleep/recheck')
     time.sleep (10)
 else:
     print('Something went wrong')
     sys.exit(-2)