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

    概要：CMS API

    このトピックでは、CMS APIの概要を説明します。NS CMS APIデータへのキャッシュされていない読み取りアクセスを提供します。を使用して動画や再生リストに変更を加えるため、これは時間に敏感な公開ワークフローにとって重要です。 CMS APIデータをすばやく読み取って、それが正しいことを確認します。

    API リファレンス

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

    一般情報

    ベース URL

    のベースURL CMS APIは：

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

    アカウントパス

    いずれの場合も、特定のリクエストが行われますビデオクラウドアカウント。したがって、accountsあなたは常にベースURLにアカウントIDが続く用語を追加します：

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

    認証

    リクエストの認証には、承認ヘッダー：

            Authorization: Bearer {access_token}

    NS access_tokenから取得する必要がある一時的なOAuth2アクセストークンです。ブライトコーブOAuthサービス。詳細については、を参照してください。 BrightcoveOAuthの概要。

    クライアント資格情報を作成する最も簡単な方法は、BrightcoveStudio管理ページを使用することです。詳細な手順については、を参照してください。 API認証資格情報の管理

    オペレーション

    クライアントの資格情報を要求するときは、必要なアカウントアクセスの種類または操作を指定する必要があります。以下は、現在サポートされている操作のリストです。 CMS API：

    • ビデオデータ：

      video-cloud/video/read
      video-cloud/video/create
      video-cloud/video/update
      video-cloud/video/delete
      または
      video-cloud/video/all
      video-cloud/video/assets/delete（デジタルマスターを削除する場合にのみ必要です- できません Studioでクレデンシャルを作成するときに、この権限を取得します。これは、OAuthAPIまたはBrightcove LearningServicesによって作成されたサンプルアプリ。）

    • プレイリストデータ：

      video-cloud/playlist/read
      video-cloud/playlist/create
      video-cloud/playlist/update
      video-cloud/playlist/delete
      または
      video-cloud/playlist/all

    • 通知：
      • video-cloud/notifications/all（にとって通知）

    レート制限

    このCMS APIデータへのキャッシュされていない読み取りアクセスを提供します。を使用して動画や再生リストに変更を加えるため、これは時間に敏感な公開ワークフローにとって重要です。 CMS APIデータをすばやく読み取って、それが正しいことを確認します。

    NS CMS API大規模なランタイムの使用（トラフィックの多い公開Webページのビデオへのアクセスなど）には適していません。トラフィックの多いアプリケーションの場合、次のようなキャッシュされたインターフェイスを使用する必要があります。Playback API、ギャラリー、プレーヤー、またはネイティブSDK。

    のパフォーマンスを確保するにはビデオクラウドシステム、20以下の同時呼び出しCMS APIアカウントごとに許可されます。アクセス頻度は、1秒あたり10リクエスト未満である必要があります。

    複数のアプリケーションがに統合される場合CMS APIアカウントの場合、これらのアプリケーションには、同時実行制限またはレート制限に達したインスタンスを処理するためのバックオフおよび再試行ロジックが必要です。

    レートまたは同時実行の制限を超えた場合、429 - TOO_MANY_REQUESTSエラーが返されます。

    参照 ID の競合

    参照IDの一意性を保証するために、 CMS API割り当てられたビデオの操作後、最大3分間IDをロックします。これにより、リクエストの失敗が早すぎる場合、または以前に割り当てられた動画を削除してからすぐに参照 ID を再利用しようとすると、409 エラーが返される可能性があります。詳細については、エラーメッセージリファレンスを参照してください。

    ビデオアセットの制限

    動画ごとに1,000アセットの制限があります。アセットには、レンディション、オーディオトラック、テキストトラック、画像、およびデジタルマスターが含まれます。レンディションと画像の合計が10〜15を超えることはめったにないため、150の異なる言語用に別々のオーディオトラックとテキストトラックがある場合でも、アセットは350未満になります。

    使用上の注意

    メソッド

    現在、APIは次のリクエストタイプをサポートしています。

    • GET
    • POST
    • PATCH
    • PUT
    • DELETE

    パラメーター

    すべてのパラメータはオプションであることに注意してください。特に記載のない限り、GET動画と再生リストのリクエスト。

    GETリクエストパラメータ
    パラメーター 説明
    q 検索用のクエリ文字列-を参照してください検索構文詳細については
    limit 返す動画数-1 ～ 100 の整数を指定してください。デフォルト： 20
    offset スキップする動画の数（ページング結果用）。正の整数である必要があります。デフォルト： 0
    sort 並べ替えの基準となるフィールドを指定するストリング。皮切りに-降順で並べ替えます。の値がqが指定されている場合、デフォルトの並べ替えは「スコア」（検索結果と元のクエリの関連性）によるものです。の値がない場合qが提供されている場合、デフォルトのソートはupdated_at降順。次のフィールドは並べ替えに有効です。name、reference_id、created_at、published_at、updated_at、schedule_starts_at、schedule_ends_at、state、plays_total、およびplays_trailing_week

    ブライトコーブのCMS APIあなたのビデオを検索するためのプログラム的な方法を提供しますビデオクラウド図書館。

    動画データの基本検索および複雑な検索を実行するには、qパラメーターを使用します。

            https://cms.api.brightcove.com/v1/accounts/921483702001/videos?q={search terms}

    動画を検索する方法については、「ビデオの検索」ドキュメントを参照してください。

    プレイリストの場合、検索文字列でサポートされる値はさらに制限されます。現在、で検索できますtype、name、description、およびreference_id。有効な検索の例を次に示します。

    • q=type:EXPLICIT
    • q=type:ACTIVATED_OLDEST_TO_NEWEST
    • q=type:ALPHABETICAL
    • q=bears+otters（名前、説明、または参照IDには、「bears」または「otters」のいずれかが含まれている必要があります）
    • q=%2Bname:bears+type:EXPLICIT（名前には「クマ」が含まれている必要があります）

    見るプレイリストを検索詳細については。

    ページングの結果

    使用 limit リクエストで返すアイテムの数を指定するパラメータ（最大100）。その後、を使用することができます offset より大きい結果セットをページスルーするパラメータlimit。offsetはスキップする項目の数です。

    たとえば、次の検索では、結果セットの合計に少なくとも 75 本の動画が含まれていると仮定して、結果セット全体の 51 ～ 75 の動画が返されます。

            /videos?q=updated_at:2014-01-01..2014-06-30&limit=25&offset=50

    ザ・limitそしてoffsetパラメータは、動画と再生リストの両方に使用できます。

    ページングのベストプラクティス

    CMS APIで同時に変更操作が行われている可能性があるため、結果セットをページングするときは、次の手順に従うことをお勧めします。

    1. 作る count 結果セット内の動画の総数を取得するようにリクエストします。 
            /accounts/578380111111/counts/videos?q=tags:nature
    2. 使用 limit そして offset 結果セットからデータのグループを返すパラメータ。 
            /accounts/578380111111/videos?q=tags:nature&limit=20&offset=50
    3. 一部のページには20本未満のビデオがある場合があることに注意してください。最初の動画と同じ数の動画をリクエストすると、結果セットの最後に到達したことがわかります。countリクエスト。

    要約すると、元の動画数と同じになるまでページを取得し続けますcountこの数は過大評価の側で誤りを犯すはずなので、要求してください。求める：

          count / page-size + 1 page

    ビデオ結果のソート

    パラメータを使用するsort=field_name結果の並べ替え方法を指定するには、ビデオとプレイリストの両方を並べ替えることができます。次のビデオフィールドで並べ替えることができます。 [1-1]

    • name
    • reference_id
    • created_at
    • published_at
    • updated_at
    • schedule_starts_at（注：これはソートフィールド- 検索フィールドはschedule.starts_at）
    • schedule_ends_at（注：これはソートフィールド- 検索フィールドはschedule.ends_at）
    • state
    • plays_total [1-2]
    • plays_trailing_week [1-2]

    備考

    • [1-1] ビデオ検索呼び出しに並べ替え値を指定しない場合、結果は関連性によって並べ替えられます。GETビデオ呼び出しの並べ替え値を指定しない場合、updated_at結果は降順でソートされます。
    • [1-2] 並べ替えることができますplays_totalまたplays_trailing_week、ただし、これらのフィールドは結果に含まれません

    プレイリストの結果を並べ替える

    次のフィールドでプレイリストを並べ替えることができます。

    • name
    • updated_at（デフォルト）

    すべてのビデオと大きなデータセット

    アカウント内のすべての動画、または多数の動画を取得する場合は、以下の点に注意する必要があります。

    1. 許可されている最大のlimit（100）を使いたくなるかもしれませんが、API リクエストがタイムアウトする可能性を最小限に抑えるには、25 以下のバッチで動画を取得することをお勧めします。
    2. 大きなデータセットをページングすると、操作中にビデオデータが更新され、アイテムが応答にシフトする可能性があります。
      • 連続したページで項目が繰り返し表示されることがあります
      • 以前のレスポンスセットに移行したため、アイテムが見逃される可能性がある

      最初の可能性を考慮するには、動画の取得が完了したら、アプリは項目リスト全体を重複排除する必要があります。2番目の可能性を処理するには、（重複除外後）取得されたアイテムの合計数を期待していた数と比較し、要求を再実行し、結果をlast_modified_date（降順）でソートする必要があります。欠落したアイテムをピックアップするために、複数のバッチを取得する必要はありません。

    3. 返された結果を適切に並べ替えることにより、前の項目のシナリオの可能性を減らすことができます。検索の関連性によるデフォルトの並べ替えは、キーワード、タグ、およびカスタムフィールド値の組み合わせを検索する複雑なアルゴリズムに基づいています。複数のキーワード、タグ、カスタムフィールドに基づいて動画を検索する場合は、関連性で並べ替える必要があります。ただし、すべての動画または大規模な動画セットを取得する場合は、sortパラメーターを明示的に設定することで、返されるアイテムの順序をより詳細に制御できます。

    ビデオ操作

    ビデオ操作には次のものが含まれます。

    • ビデオまたは検索結果の数を取得します
    • Get all videos
    • IDまたは参照IDで1つ以上の動画を取得する
    • 動画の作成、取得、更新、削除
    • ビデオを検索する
    • ビデオソース、画像、およびデジタルマスター情報を取得します
    • 動画が属する再生リストを取得する
    • すべての再生リストから動画を削除します

    ビデオ操作の詳細は、 APIリファレンス。

    プレイリストの操作

    プレイリストの操作は次のとおりです。

    • プレイリストの数を取得する
    • すべてのプレイリストを取得する
    • プレイリストの作成、更新、削除
    • 再生リスト内の動画の数を取得する
    • 再生リストで動画を取得する

    プレイリスト操作の詳細は、 APIリファレンス。

    アセット

    アセット操作を使用すると、レンディション、マニフェスト、画像、テキストトラックなどのアセットを管理できます。アセットを取り込むには、を使用する必要がありますDynamic Ingest API。NS POSTとPATCHの操作CMS API /assets追加と更新に使用できますリモート資産。CMS API GET操作はどちらも取り込んだ資産とリモート資産。

    • レンディションを追加、更新、または削除します
    • デジタルマスターのメタデータを追加、更新、または削除します
    • HLSなどのセグメント化されたビデオタイプのマニフェストを追加、更新、または削除します
    • ポスターとサムネイル画像を追加、更新、または削除する
    • WebVTTテキストトラックまたはDFXPキャプションを追加、更新、または削除します

    資産運用の詳細は、 APIリファレンス。

    カスタムフィールド操作

    現在、1つのカスタムフィールド操作があります。

    • アカウントのすべてのカスタムフィールドを取得する

    カスタムフィールド操作の詳細は、 APIリファレンス。

    フォルダ操作

    フォルダ操作により、次のことが可能になります。

    • フォルダのリストを取得する
    • フォルダを作成、更新、および削除します
    • フォルダ内のビデオのリストを取得します
    • フォルダにビデオを追加する
    • フォルダから動画を削除する

    フォルダ操作の詳細は、 APIリファレンス。

    通知

    通知を受け取ることができるのはvideo_changeイベントはビデオライブラリで発生します。指定したURLに通知が送信されます。このURLは、処理可能なアプリケーションを指している必要があります。HTTP POSTリクエスト。

    通知の失敗

    通知システムは、カスタマーサーバーからの4xxまたは5xxのリターンを再試行可能な障害として扱います。失敗したコールバックは 20 回まで再試行され、後続のコールバック間の遅延は急激に増加します。最初の数回の再試行は、最初のコールバック試行から数分以内に行われます。コールバックが失敗し続け、20 回目の再試行まで続く場合、再試行遅延は数日になります。

    ファイアウォール

    組織がファイアウォールを通過する着信トラフィックのソースに関して厳格なポリシーを持っている場合、すべてのAWSEastリージョンIPを許可します。これは変更される可能性があるため、すべての AWS IP をホワイトリストに登録する必要があります。見るhttps://docs.aws.amazon.com/general/latest/gr/aws-ip-ranges.html詳細については。

    通知操作

    現在通知に使用できる操作は次のとおりです。

    • サブスクリプションを作成する
    • 1つまたはすべてのサブスクリプションを取得する
    • サブスクリプションを削除する

    通知操作の詳細は、 APIリファレンス。

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