媒體分享

在本主題中，您將學習如何使用 CMS API 將影片從一個視訊雲端帳戶分享到另一個帳戶。

簡介

媒體共享是Video Cloud的一項功能，該功能使發布者可以與其他發布者共享視頻，從而使您可以更輕鬆地管理多個帳戶中的視頻。例如，發布者可以保留視頻內容的主帳戶，然後將視頻共享給組織的其他部門或子公司。

請注意，所有媒體共享操作也可以在Studio中執行。看到管理媒體共享設置。

共享媒體和計費

有關共享媒體計費方式的信息，請參閱使用媒體模塊進行媒體共享。

術語

在媒體共享中，主帳戶（共享視頻）與一個或多個關聯帳戶（接收共享視頻）之間存在關聯：

媒體分享術語
帳戶 描述
主 創建原始視頻的帳戶。

主人擁有該內容，並負責設置，管理和提供內容給關係企業。
合作夥伴 正在接收視頻的帳戶。

聯盟可以接受從主人分享給它的內容。
頻道 從主機共享內容到任意數量的會員的管道。啟用媒體共享後，default頻道將在您的帳戶中創建。
關係 描述管理員與會員之間的互動。

關係由共享內容的主設備，共享內容的渠道，接受內容的合同和接收內容的關聯公司組成。
合約 描述了母版和會員之間的共享關係。

合同由主合同創建，然後必須接受才能啟用共享。關聯公司還可以指定共享視頻是自動接受還是必須逐一批准。

基本網址

至於全部CMS API請求，下面討論的操作的基本URL是：

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

發出請求時，下面討論的所有端點都將附加到基本URL。

驗證

請求的身份驗證需要一個授權標頭：

          Authorization: Bearer {access_token}

這access_token是一個臨時的 OAuth2 訪問令牌，必須從布萊特灣 OAuth 服務獲得。如需有關如何取得用戶端認證並使用它們來擷取存取權杖的詳細資訊，請參閱 Brightcove OAuth 概觀。

請注意，周圍的所有操作關係所需的新權限：

      video-cloud/video/all
      video-cloud/sharing-relationships/read
      video-cloud/sharing-relationships/create
      video-cloud/sharing-relationships/update
      video-cloud/sharing-relationships/delete

或者，您可以只使用：

      video-cloud/sharing-relationships/all

在Studio API身份驗證管理頁面中，顯示了兩個權限：

  • 分享閱讀（相當於video-cloud/sharing-relationships/read）
  • 共享讀/寫（相當於video-cloud/sharing-relationships/all）

共享限制

默認情況下，所有視頻都可以共享。但是，您可以在以下情況下阻止共享：

  • 聯盟帳戶沒有一個自定義字段，該字段在主帳戶中的視頻上設置了一個值
  • 主帳戶已啟用地理過濾，但會員帳戶未啟用

自訂欄位比對

您可以為頻道強制執行自定義字段匹配，這意味著視頻共享將失敗如果視頻具有會員帳戶中不存在的自定義字段的值。如果視頻沒有任何不匹配的自定義字段的值，視頻仍將成功共享

默認情況下，自定義字段匹配為不強制執行。

如果視頻共享由於自定義字段不匹配而失敗，您將在響應中看到以下錯誤：

      {
        "video_id": "5691312273001",
        "affiliate_id": "47509719001",
        "affiliate_video_id": null,
        "status": "PROCESSING",
        "error_message": [{"error_code":"MISSING_CUSTOM_FIELDS","error_message":"Affiliate account is missing custom fields: [subject]"}],
        "shared_at": "2018-01-03T16:29:19.080Z",
        "updated_at": "2018-01-03T16:29:19.080Z"
      }

地理過濾匹配

如果為頻道啟用了地理過濾匹配，則在主帳戶已啟用地理過濾而會員帳戶未啟用地理過濾的情況下，無法共享視頻。

默認情況下，地理過濾匹配是強制執行。

該錯誤將如下所示：

      {
        "video_id": "5691312273001",
        "affiliate_id": "47509719001",
        "affiliate_video_id": null,
        "status": "PROCESSING",
        "error_message": [{"error_code":"CONFLICT","error_message":"Affiliate account is not configured for geo restriction."}],
        "shared_at": "2018-01-03T16:29:19.080Z",
        "updated_at": "2018-01-03T16:29:19.080Z"

看到更新頻道下面介紹瞭如何更新渠道以實施自定義字段和/或地理位置過濾匹配。

共享什麼？

本部分說明共享的內容以及如何處理視頻的後續更改。

共享視頻時

共享視頻時，大多數視頻元數據字段都會從主服務器複製到會員帳戶。值得注意的例外是：

  • id -該視頻將在會員帳戶中擁有自己的唯一ID
  • 日期字段，例如created_at和updated_at

會員帳戶使用所有視頻資產（租借，圖像，text_tracks等）進行播放。

分享視頻後

共享視頻後，會員帳戶會自動繼承主帳戶中視頻的某些更改，而某些更改則不會。

視頻資產

圖片除外，對視頻資產的主更改是總是由會員繼承。會員關係無法更改資產例如演繹，清單，文本軌道或數字母版。

會員對圖片的更改由會員繼承除非會員更換了圖片。會員更改圖像後，該圖像將不再從主服務器繼承。

視頻元數據

會員可以修改任何視頻元數據（例如名稱，描述和參考ID），並且在主視頻上所做的更改是不由會員繼承。

轉貼影片

但是請注意，如果重新分享視頻（只能通過CMS API來完成，而不能在Studio中完成），所有資產和元數據（數據/時間字段除外）都將共享給會員，覆蓋會員所做的任何更改。

媒體共享步驟概述

建立關係

以下是建立關係的操作摘要（單擊操作名稱可了解更多詳細信息）：

設置操作
主操作
操作 方法/端點 描述
列出頻道 GET /accounts/ master_account_id/channels 獲取帳戶的渠道列表
獲取頻道詳細信息 GET/accounts/ master_account_id/channels/ channel_name [2-1] 獲取頻道的詳細信息
更新頻道 POST /accounts/ master_account_id/channels/ channel_name 更新頻道設置
列出頻道會員 GET /accounts/ master_account_id/channels/default/members 獲取頻道的會員
添加會員 PUT /accounts/ master_account_id/channels/default/members 將會員添加到頻道
刪除會員 DELETE /accounts/ master_account_id/channels/default/members/ affiliate_account_id 從頻道中刪除會員
聯盟營運
操作 方法/端點 描述
列出可用合同 GET /accounts/ affiliate_account_id/contracts 獲取該帳戶可用的所有合同
獲取特定帳戶的合同 GET /accounts/ affiliate_account_id/contracts/ master_account_id 從特定帳戶獲取合同（如果有）
批准合同 PATCH /accounts/ affiliate_account_id/contracts/ master_account_id 接受並配置合同的接受條件

注意事項

  • [2-1]目前只有一個頻道名為default

分享影片

視頻共享操作由主帳戶執行。會員帳戶可以接受共享（如果auto_accept被設置為false），並可以使用標準更新共享的視頻元數據和圖像更新影片操作。

建立關係後，可以執行以下共享操作（單擊操作名稱以獲取更多詳細信息）：

共享操作
主操作
操作 方法/端點 描述
列出現有股份 GET /accounts/ master_account_id/videos/ video_id/shares 獲取視頻的現有共享列表-這是重要由於的後果重新分享視頻當它已經被共享時
分享影片 POST /accounts/ master_account_id/videos/ video_id/shares 與一個或多個會員共享視頻-請注意，如果視頻已經共享，則此操作將重新分享 -那可能是不你想做什麼
取消共享會員視頻 DELETE /accounts/ master_account_id/videos/ video_id/shares 取消共享特定會員的視頻-請注意，取消共享和重新共享將導致共享視頻在會員帳戶中具有新的視頻ID
聯盟營運
操作 方法/端點 描述
接受共享的視頻 PATCH /accounts/ affiliate_account_id/videos/ video_id 接受共享視頻（如果auto_accept已關閉）

注意：要識別等待被接受的共享視頻，請搜索具有state:pending :

https://cms.api.brightcove.com/v1/accounts/{account_id}/videos?q=state:pending

或

https://cms.api.brightcove.com/v1/accounts/{account_id}/videos?query=state:PENDING

CMS API請求-設置

本節列出了CMS API設置媒體共享所涉及的操作。

主操作

列出頻道

列出通道
方法 GET
端點 /accounts/ master_account_id/channels
要求主體  
範例回應 
      [
        {
          "account_id": "57838016001",
          "name": "default",
          "enforce_custom_fields": false,
          "enforce_geo": false,
          "account_name": "BrightcoveLearning",
          "created_at": "2017-08-23T17:11:18.474Z",
          "updated_at": "2017-08-23T17:11:18.474Z"
        }
      ]

獲取頻道詳細信息

獲取頻道詳細信息
方法 GET
端點 https://cms.api.brightcove.com/v1/accounts/ master_account_id/channels/ channel_name [5-1]
要求主體  
範例回應 
      {
        "account_id": "57838016001",
        "name": "default",
        "enforce_custom_fields": false,
        "enforce_geo": false,
        "account_name": "BrightcoveLearning",
        "created_at": "2017-08-23T17:11:18.474Z",
        "updated_at": "2017-08-23T17:11:18.474Z"
      }
注意事項
  • [5-1]目前只有一個頻道名為default

更新頻道

建立頻道
方法 PATCH
端點 /accounts/ master_account_id/channels/ channel_name [6-1]
要求主體 
      {
        "enforce_custom_fields" : true,
        "enforce_geo" : true
      }
範例回應 
      {
        "account_id": "57838016001",
        "name": "default",
        "enforce_custom_fields": true,
        "enforce_geo": true,
        "account_name": "BrightcoveLearning",
        "created_at": "2017-08-23T17:11:18.474Z",
        "updated_at": "2017-12-30T15:06:27.015Z"
      }
注意事項
  • [6-1]目前只有一個頻道名為default

列出頻道的會員

列出渠道會員
方法 GET
端點 /accounts/ master_account_id/channels/default/members
要求主體  
範例回應 
      [
        {
          "account_id": "20318290001",
          "approved": false,
          "account_name": "Brightcove Training"
        },
        {
          "account_id": "1485884786001",
          "approved": true,
          "account_name": "Brightcove Learning Doc Samples"
        },
        {
          "account_id": "1752604059001",
          "approved": true,
          "account_name": "BC Training Videos"
        }
      ]

的價值approved字段指示關聯公司是否已批准合同。

將會員添加到頻道

新增聯盟
方法 PUT
端點 /accounts/ master_account_id/channels/default/members/ affiliate_account_id
要求主體 
      {
        "account_id":"affiliate_account_id"
      }
範例回應 
      {
        "account_id": "1485884786001"
      }

從頻道中刪除會員

刪除會員
方法 DELETE
端點 /accounts/ master_account_id/channels/default/members/ affiliate_account_id
要求主體  
範例回應 204 NO CONTENT（空響應正文）

聯盟營運

列出可用合同

列出合約
方法 GET
端點 /accounts/ affiliate_account_id/contracts
要求主體  
範例回應 
      [
        {
          "account_id": "1485884786001",
          "channel": {
            "account_id": "57838016001",
            "name": "default"
          },
          "approved": false,
          "auto_accept": false,
          "approved_at": null,
          "updated_at": "2017-08-23T17:45:41.556Z",
          "created_at": "2017-08-23T17:45:41.556Z"
        }
      ]

響應中的兩個基本字段是：

  • approved -設為true時，聯盟會員接受合同
  • auto-accept -設為true時，通過此合同共享的視頻將被會員自動接受；否則，必須一一批准

我們將在下面查看如何更新合同。

獲取特定帳戶的合同

取得合約
方法 GET
端點 /accounts/ affiliate_account_id/contracts/ master_account_id
要求主體  
範例回應 
      {
        "account_id": "1485884786001",
        "channel": {
          "account_id": "57838016001",
          "name": "default"
        },
        "approved": false,
        "auto_accept": false,
        "approved_at": null,
        "created_at": "2017-08-23T17:45:41.556Z",
        "updated_at": "2017-08-23T17:45:41.556Z"
      }

批准合同

批准合同
方法 PATCH
端點 /accounts/ affiliate_account_id/contracts/ master_account_id
要求主體 
      {
        "approved": true,
        "auto_accept": true
      }
範例回應 
      {
        "account_id": "1485884786001",
        "channel": {
          "account_id": "57838016001",
          "name": "default"
        },
          "approved": true,
        "auto_accept": true,
        "approved_at": "2017-08-27T12:27:21.582Z",
        "created_at": "2017-08-23T17:45:41.556Z",
        "updated_at": "2017-08-27T12:27:21.582Z"
      }

如果僅包括"approved":true，每個視頻都必須分別獲得批准。

CMS API請求-共享

本節詳細介紹CMS API共享視頻中使用的請求。媒體共享操作由主帳戶執行。會員帳戶可以接受股票，如果auto_accept已關閉。

主操作

列出現有股份

要確定視頻是否已經與其他帳戶共享，可以使用以下請求。

列出股份
方法 GET
端點 /accounts/ master_account_id/videos/ video_id/shares
要求主體  
範例回應 
      [
        {
          "video_id": "5553744346001",
          "affiliate_id": "1752604059001",
          "affiliate_video_id": "5553754248001",
          "status": "COMPLETE",
          "shared_at": "2017-08-27T14:35:01.890Z",
          "updated_at": "2017-08-27T14:35:25.630Z"
        },
        {
          "video_id": "5553744346001",
          "affiliate_id": "1485884786001",
          "affiliate_video_id": "5553758415001",
          "status": "COMPLETE",
          "shared_at": "2017-08-27T14:34:34.919Z",
          "updated_at": "2017-08-27T14:35:25.212Z"
        }
      ]

分享（或轉播）視頻

以下描述的請求將視頻共享給一個或多個會員帳戶。

分享視訊
方法 POST
端點 /accounts/ master_account_id/videos/ video_id/shares
要求主體 
      [
        { "id": "affiliate_account_id_1" },
        { "id": "affiliate_account_id_2" }
      ]
範例回應

成功回應

      [
        {
          "video_id": "5553744346001",
          "affiliate_id": "1485884786001",
          "affiliate_video_id": null,
          "status": "PROCESSING",
          "shared_at": "2017-08-27T14:25:55.710Z",
          "updated_at": "2017-08-27T14:25:55.710Z"
        }
      ]

失敗回應

      {
      "video_id": "5553744346001",
      "affiliate_id": "1485884786001",
      "affiliate_video_id": null,
      "status": "ERROR",
      "error_message": "[{\"error_code\":\"MISSING_CUSTOM_FIELDS\",\"error_message\":\"Affiliate account is missing custom fields: [myfieldname]\"}]",
      "shared_at": "2017-10-23T15:21:38.541Z",
      "updated_at": "2017-10-23T15:22:58.519Z"
      }

分享將在會員帳戶中創建一個新視頻。的state的視頻份額將是PROCESSING直到共享完成和該視頻是在會員帳戶中創建的。關聯企業可能仍需要接受視頻（如果auto_accept被設置為false關於會員的合同-請參閱上一節“設置共享”。

取消共享會員視頻

取消分享視頻
方法 DELETE
端點 /accounts/ master_account_id/videos/ video_id/shares/ affiliate_account_id
要求主體  
範例回應 202 ACCEPTED（空響應正文）-響應表明請求已被接受進行處理，但操作可能會在幾分鐘內完成

聯盟營運

接受分享的視頻

要接受共享視頻，會員會更新共享視頻，並將其設置為state至ACTIVE。（設置state至INACTIVE拒絕分享。）

接受共享視頻
方法 PATCH
端點 /accounts/ affiliate_account_id/videos/ affiliate_video_id
要求主體 
      
        {
          "state": "ACTIVE"
        }
範例回應 
      {
        "id": "5557656136001",
        "account_id": "1485884786001",
        "ad_keys": null,
        "clip_source_video_id": null,
        "complete": true,
        "created_at": "2017-08-30T13:35:51.796Z",
        "cue_points": [
        ],
        "custom_fields": {
        },
        "delivery_type": "dynamic_origin",
        "description": null,
        "digital_master_id": "4728546275001",
        "duration": 11111,
        "economics": "AD_SUPPORTED",
        "folder_id": null,
        "geo": null,
        "has_digital_master": true,
        "images": {
          "thumbnail": {
            "asset_id": "5473683978001",
            "remote": false,
            "src": "https://brightcove.vo.llnwd.net/e1/pd/57838016001/57838016001_5473683978001_4728519374001-th.jpg?pubId=1485884786001&videoId=5557656136001",
            "sources": [
              {
                "src": "https://brightcove.vo.llnwd.net/e1/pd/57838016001/57838016001_5473683978001_4728519374001-th.jpg?pubId=1485884786001&videoId=5557656136001",
                "height": 90,
                "width": 160
              },
              {
                "src": "https://brightcove.hs.llnwd.net/e1/pd/57838016001/57838016001_5473683978001_4728519374001-th.jpg?pubId=1485884786001&videoId=5557656136001",
                "height": 90,
                "width": 160
              }
            ]
          },
          "poster": {
            "asset_id": "5473684427001",
            "remote": false,
            "src": "https://brightcove.vo.llnwd.net/e1/pd/57838016001/57838016001_5473684427001_4728519374001-vs.jpg?pubId=1485884786001&videoId=5557656136001",
            "sources": [
              {
                "src": "https://brightcove.vo.llnwd.net/e1/pd/57838016001/57838016001_5473684427001_4728519374001-vs.jpg?pubId=1485884786001&videoId=5557656136001",
                "height": 720,
                "width": 1280
              },
              {
                "src": "https://brightcove.hs.llnwd.net/e1/pd/57838016001/57838016001_5473684427001_4728519374001-vs.jpg?pubId=1485884786001&videoId=5557656136001",
                "height": 720,
                "width": 1280
              }
            ]
          }
        },
        "link": null,
        "long_description": null,
        "name": "oystercatcher.mp4",
        "original_filename": "57838016001_4728546275001_4728519374001.mp4",
        "projection": null,
        "published_at": "2017-08-30T13:41:13.974Z",
        "reference_id": "2016-01-29T21:41:33.225Z-screencast-1280",
        "schedule": null,
        "sharing": {
          "by_external_acct": true,
          "by_id": "57838016001",
          "source_id": "4728519374001",
          "to_external_acct": false,
          "by_reference": true
        },
        "state": "ACTIVE",
        "tags": [
          "newtag",
          "foo"
        ],
        "text_tracks": [
        ],
        "updated_at": "2017-08-30T13:41:14.075Z"
      }

設置state至INACTIVE拒絕分享。

請注意，沒有特殊通知指示已將視頻共享到您的帳戶。但是，如果你搜索視頻對於state:pending，它將找到任何不可接受的份額。或者，您可以使用Studio Media模塊中的“待處理的共享”列表來查看和接受/拒絕待處理的共享：

待處理股份
待處理股份

錯誤

媒體共用錯誤不會傳回為 API 要求的個別錯誤回應，而是在正常回應的error_message欄位中傳回：

      [
        {
          "video_id" : "1239817239128",
          "affiliate_id" : "32871239",
          "affiliate_video_id" : "30308254055202",
          "status" : "COMPLETE",
          "shared_at" : "2017-12-11T17:57:45.530Z",
          "updated_at" : "2017-12-11T18:03:32.789Z",
          "error_message" : "[{"error_code":"MISSING_CUSTOM_FIELDS","error_message":"Affiliate account is missing custom fields: [whisky]"}]"
        }
      ]

看到的CMS API錯誤參考更多細節。

限制

當前，媒體共享具有以下限制：

  • DRM：通過CMS API當前不支持啟用DRM的帳戶。支援將未啟用 DRM 的帳戶中的影片分享給已啟用 DRM 的帳戶，但共用的影片將不會封裝給 DRM。

  • 如果主帳戶定義的渠道已設置enforce_custom_fields至true，然後共享一個具有自定義字段且其關聯會員帳戶不允許使用該值的視頻，則共享嘗試將失敗。共享狀態將更新，並顯示以下錯誤消息：

          [{"error_code": "ILLEGAL_CUSTOM_FIELD_VALUE", "error_message": "Illegal value for custom fields: [topic]"}]

    如果主帳戶定義的渠道已設置enforce_custom_fields至false，然後共享具有自定義字段且其會員帳戶所不允許的值的視頻，則共享嘗試將起作用，但是具有錯誤值的字段將不會包含在該視頻的會員副本中。

  • 使用 SSAI 播放共用的視訊時，SSAI 巨集取代將使用父視訊中的中繼資料，而不是子視訊。如果上層影片標示為，即使子視訊標示為Advertising='Free'，SSAI 也會略過廣告查閱Ad Supported。