概述： CMS API

API參考

另見 API參考.

一般信息

基本網址

的基本網址 CMS API 是：

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

帳戶路徑

在所有情況下，都將針對特定 Video Cloud 帳戶。 因此，您將始終添加該詞 accounts 然後是您的帳戶ID和基本URL：

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

認證

對請求的身份驗證需要一個 授權頭 :

        Authorization: Bearer {access_token}

access_token 是臨時OAuth2訪問令牌，必須從 Brightcove OAuth 服務。 有關更多詳細信息，請參見 Brightcove OAuth概述.

創建客戶端憑據的最簡單方法是通過Brightcove Studio管理頁面。 有關詳細說明，請參見 管理API身份驗證憑據

操作

當您請求客戶端憑據時，您將需要指定所需的帳戶訪問或操作類型。 以下是當前支持的操作列表 CMS API :

• 視頻數據：

  video-cloud/video/read
video-cloud/video/create
video-cloud/video/update
video-cloud/video/delete
  or
  video-cloud/video/all
video-cloud/video/assets/delete （僅在要刪除數字母版時才需要-請注意， 不能 在Studio中創建憑據時獲得此權限。 必須通過 OAuth API 或者 Brightcove學習服務創建的示例應用程序.)

• 播放清單資料：

  video-cloud/playlist/read
video-cloud/playlist/create
video-cloud/playlist/update
video-cloud/playlist/delete
  or
  video-cloud/playlist/all

• 通知：
  • video-cloud/notifications/all （為 通知)

限速

這個 CMS API 提供對數據的未緩存讀取訪問。 這對於時間敏感的發布工作流程非常重要，因為您可以使用 CMS API 并快速讀取數據以驗證是否正確。

CMS API 不適用於大規模的運行時使用（例如，訪問高流量公共網頁上的視頻）。 對於高流量應用程序，您必須使用緩存的接口，例如： Playback API , Gallery, Player或本機SDK。

為確保性能 Video Cloud 系統，最多不超過20個並發調用 CMS API 被允許每個帳戶。 訪問頻率應小於每秒10個請求。

如果多個應用程序將集成到 CMS API 對於一個帳戶，則這些應用程序應具有退避和重試邏輯，以處理達到並發限製或速率限制的實例。

如果超出速率或併發限制，則 429 - TOO_MANY_REQUESTS 錯誤將被返回。

參考編號衝突

為了確保參考ID的唯一性， CMS API 對分配給視頻的視頻進行任何操作後，最多可將ID鎖定3分鐘。 當您嘗試重試失敗太快的請求時，或者在刪除先前分配給它的視頻後不久嘗試重用參考ID時，這可能會導致返回409錯誤。 見 錯誤消息參考 更多的細節。

視頻資產限制

每個視頻最多只能有1,000個資產。 資產包括演繹，音頻軌道，文本軌道和圖像，以及數字母帶。 字幕和圖像的總資產很少會超過10-15，因此即使您擁有針對150種不同語言的單獨音軌和文本音軌，資產也仍然少於350。

使用注意事項

方法

目前，API支持以下請求類型：

• GET
• POST
• PATCH
• PUT
• DELETE

參數

請注意，所有參數都是 可選。 除另有說明外，它們適用於 GET 要求提供視頻和播放列表。

搜尋影片

Brightcove的 CMS API 提供了一種編程方式來搜索您的視頻 Video Cloud 圖書館。

要對視頻數據執行基本和復雜的搜索，您將使用 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必須包含“熊”或“水獺”）
• q=%2Bname:bears+type:EXPLICIT （名稱必須包含“熊”）

看到 搜索播放列表 更多的細節。

分頁結果

使用 limit 參數，以指定要根據請求返回的項目數-最多100。然後，您可以使用 offset 參數以瀏覽大於結果的結果集 limit。 “ offset 是要跳過的項目數。

例如，以下搜索返回總結果集中的視頻51-75，假設總結果集中至少有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 or plays_trailing_week，但這些字段未包含在結​​果中

排序播放列表結果

您可以在以下字段上對播放列表進行排序：

• name
• updated_at （默認）

所有視頻和大數據集

如果您要檢索帳戶中的所有視頻或大量視頻，則必須注意以下幾點：

1. 您可能會嘗試使用允許的最大容量 limit （100），但最好以25或更少的批次檢索視頻，以最大程度地減少API請求超時的可能性
2. 在翻閱大型數據集時，可能會在操作期間更新視頻數據，這可能會導致項目的響應發生偏移：
   • 您可能會在連續的頁面上看到重複的項目
   • 某項可能已丟失，因為它已轉移到先前的響應集

   要考慮第一種可能性，在完成視頻檢索後，您的應用應該對整個項目列表進行重複數據刪除。 要處理第二種可能性，您需要將（重複數據刪除後）檢索到的項目總數與期望的數目進行比較，然後重新運行請求，並按last_modified_date（降序）對結果進行排序-您不需要檢索多個批次以撿拾丟失的物品。

3. 您可以通過對返回的結果進行適當的排序來降低上一項目中出現這種情況的可能性。 默認排序方式 相關性 for search是基於一種複雜的算法，該算法查找關鍵字，標籤和自定義字段值的組合。 如果您要搜索基於多個關鍵字，標籤和/或自定義字段的視頻，則按相關性排序正是您想要的。 但是，如果您只是嘗試檢索全部或大量視頻，請設置 sort 參數顯式將使您可以更好地控制返回項目的順序。

視頻操作

視頻操作包括：

• 獲取視頻或搜索結果的數量
• 獲取所有視頻
• 按ID或參考ID獲取一個或多個視頻
• 創建，檢索，更新和刪除視頻
• 搜索視頻
• 獲取視頻源，圖像和數字主信息
• 獲取視頻所屬的播放列表
• 從所有播放列表中刪除視頻

有關視頻操作的詳細信息，請參見 API參考.

播放列表操作

播放列表操作包括：

• 獲取播放列表數量
• 獲取所有播放列表
• 創建，更新和刪除播放列表
• 在播放列表中獲取視頻數量
• 在播放列表中獲取視頻

播放列表操作的詳細信息可以在 API參考.

資產

資產操作使您可以管理資產，包括格式，清單，圖像和文本軌道。 要攝取資產，您必須使用 Dynamic Ingest API。 “ POST 以及 PATCH 的操作 CMS API /assets 可用於添加和更新 遠程資產. CMS API GET操作將適用於 都 提取和遠程資產。

• 添加，更新或刪除演繹
• 添加，更新或刪除數字母版的元數據
• 添加，更新或刪除分段視頻類型（例如HLS）的清單
• 添加，更新或刪除海報和縮略圖
• 添加，更新或刪除WebVTT文本軌道或DFXP字幕

資產操作的詳細信息可以在 API參考.

自定義現場操作

當前有一個自定義字段操作：

• 獲取帳戶的所有自定義字段

有關自定義字段操作的詳細信息，請參見 API參考.

文件夾操作

文件夾操作使您可以：

• 獲取文件夾列表
• 創建，更新和刪除文件夾
• 獲取文件夾中的視頻列表
• 將視頻添加到文件夾
• 從文件夾中刪除視頻

文件夾操作的詳細信息可以在 API參考.

通知

您可以在以下情況下收到通知 video_change 事件發生在您的視頻庫中。 通知將發送到您指定的URL，該URL應指向能夠處理的應用程序 HTTP POST 請求。

通知失敗

通知系統將來自客戶服務器的任何4xx或5xx返回視為可重試的故障。 失敗的回調將最多重試20次，隨後的回調之間的延遲將成倍增加。 前幾次重試將在初始回調嘗試後的幾分鐘內發生。 如果回調繼續失敗，並且我們一直進行到第20次重試，則重試延遲將是幾天。

防火牆

如果您的組織對通過防火牆的傳入流量來源有嚴格的政策，我們會允許所有AWS East地區IP。 這可能會更改，因此所有AWS IP都應列入白名單。 看到 https://docs.aws.amazon.com/general/latest/gr/aws-ip-ranges.html 了解更多信息。

通知操作

當前可用於通知的操作是：

• 創建訂閱
• 獲取一個或所有訂閱
• 刪除訂閱

通知操作的詳細信息可以在 API參考.