全部產品
Search
文件中心

ApsaraVideo Live:回調管理

更新時間:Jul 31, 2024

ApsaraVideo for Live提供直播推流狀態、直播錄製、按需錄製、直播截圖和智能審核的事件回調,本文介紹這些回調的設定方式、回調參數和樣本。

回調簡介

當直播過程中某些事件被觸發時,阿里雲將主動發送請求到客戶服務器,客戶服務器負責應答請求,驗證通過後,您可接收到事件回調資訊的JSON資料包。

ApsaraVideo for Live支援回調如下事件的資訊:

回調方式

ApsaraVideo for Live服務目前支援HTTP回調(相容HTTPS)方式擷取事件通知。您需要部署一個HTTP服務來接收回調訊息,並在控制台或通過API配置回調地址。

  • 當推流或斷流事件產生時,直播服務端會向該地址發起HTTP GET請求,具體內容將通過URL參數送達。

  • 當其他事件產生時,直播服務端會向該地址發起HTTP POST請求,具體內容將通過JSON Body送達。

注意事項

回調地址URL無需標識,只需可正常訪問,URL的應答有如下要求:如果訪問逾時,會重試URL,目前逾時時間是5秒,重試次數5次,稍候再試1秒。

直播推流狀態回調

通知當前網域名稱推流狀態,包括推流成功、斷流狀態,支援通過控制台或API配置回調地址。

  • 直播推流狀態回調設定方式

  • 直播推流狀態回調

    推斷流狀態回調會將參數封裝在MultiDict內。

    • 直播推流狀態回調中開播(publish)狀態回調邏輯

      1. RTMP推流在阿里雲直播服務收到On Publish訊息後2秒內,如果推流端不主動斷開,阿里雲直播服務就會發推流成功回調。

      2. 假設您有推流網域名稱A和播流網域名稱B,如果您的網域名稱B使用拉流直播(固定拉流和觸發回源拉流)需要回調,請在網域名稱A配置推流回調。配置後網域名稱B的拉流回調邏輯與上一條一致,建聯後預設2秒無主動斷開即認為拉流成功。

      說明

      建議業務方不僅根據回調通知判斷推流、拉流接入正常,同時配合查詢網域名稱線上流列表介面查詢推流正常後,再下發直播流播放地址。

    • 直播推流狀態回調參數

      參數

      描述

      action

      事件。

      • publish:推流。

      • publish_done:斷流。

      ip

      推流的用戶端IP。

      id

      推流流名稱。

      app

      推流網域名稱。預設為自訂的推流網域名稱,如果未綁定推流網域名稱即為播流網域名稱。

      appname

      推流應用程式名稱。

      time

      Unix時間戳記。單位:秒。

      usrargs

      使用者推流的參數。

      node

      CDN接受流的節點或者機器名。

      height

      解析度的高。單位:像素。

      說明

      解析度資訊(height和width)僅在首次回調時產生。

      width

      解析度的寬。單位:像素。

    • 推流狀態回調參數樣本:

      http://1.1.1.1?action=publish&ip=192.168.0.1&id=world&app=example.aliyundoc.com&appname=liveApp****&time=1609220385&usrargs={使用者參數}&
      node=cdnvideocenter01020711****.cm3&height=720&width=1280
    • 斷流狀態回調參數樣本:

      http://1.1.1.1?action=publish_done&ip=192.168.0.0&id=world&app=example.aliyundoc.com&appname=liveApp****&time=1609220385&usrargs={使用者參數}&
      node=cdnvideocenter01020711****.cm3&height=720&width=1280
    • 直播推流狀態回調鑒權

      推流回調鑒權功能預設關閉,使用者可在配置推流回調地址時啟用鑒權。啟用功能後,鑒權邏輯如下:

      1. 阿里雲ApsaraVideo for Live發起回調請求時在HTTP(S)要求標頭中帶上ALI-LIVE-TIMESTAMPALI-LIVE-SIGNATURE 欄位,供回調訊息接收服務端進行簽名認證。其中,ALI-LIVE-SIGNATURE的值由如下計算而得:

        ALI-LIVE-SIGNATURE=MD5SUM(MD5CONTENT)

        MD5CONTENT=推流網域名稱|ALI-LIVE-TIMESTAMP取值|鑒權KEY

        說明

        回調網域名稱指配置回調URL的推流網域名稱。鑒權Key指使用者為推流回調URL配置的鑒權Key。

      2. 回調訊息接收服務端接收回調訊息時,將回調網域名稱、ALI-LIVE-TIMESTAMP取值、鑒權Key進行拼接後計算MD5值,得到加密字串,再將計算出的加密字串與ApsaraVideo for Live發起的HTTP(S)要求標頭中的ALI-LIVE-SIGNATURE欄位值進行對比。如果不一致,則請求非法。

直播錄製回調

直播錄製回調包括錄製狀態回調、檔案產生回調,支援通過控制台和API進行配置。

  • 錄製狀態回調:在檔案開始錄製與結束錄製時發出,主要表示檔案已經開始和結束錄製。

  • 檔案產生回調:在檔案產生時發出,主要包括檔案名稱,開始結束時間與時間長度資訊。

  • 直播錄製回調設定方式

    • 控制台

      進入ApsaraVideo for Live控制台頁面,選擇左側導覽列功能管理 > 事件回調進入事件回調頁面,選擇需要開啟的網域名稱,在回調設定頁簽下,開啟錄製回調開關,添加或修改推流回調地址。具體操作請參見錄製回調

    • API

      介面

      描述

      參考文檔

      AddLiveRecordNotifyConfig

      添加網域名稱層級錄製回調配置。

      若需要開啟錄製任務狀態回調,請將NeedStatusNotify參數值設定為true。

      添加直播錄製回調配置

      DescribeLiveRecordNotifyConfig

      查詢網域名稱層級錄製回調配置。

      查詢直播錄製回調配置

      DeleteLiveRecordNotifyConfig

      刪除網域名稱層級錄製回調配置。

      刪除直播錄製回調配置

  • 錄製狀態回調

    • 錄製狀態回調參數

      參數

      描述

      domain

      錄製的播流網域名稱。

      app

      應用程式名稱。

      stream

      流名。

      event

      事件名。

      • record_started:錄製已經成功開始。

      • record_paused:錄製已經成功暫停。

      • record_resumed:錄製已經成功恢複繼續錄製。

    • 錄製狀態回調參數樣本

      {
      "domain": "demo.aliyundoc.com",
      "app": "liveApp****",
      "stream": "liveStream****",
      "event": "record_started"
      }
  • 檔案產生回調

    • 檔案產生回調參數

      參數

      描述

      domain

      錄製的播流網域名稱。

      app

      應用程式名稱。

      stream

      流名。

      uri

      目標錄製檔案在使用者錄製OSS Bucket下的路徑。

      duration

      目標錄製檔案錄製內容時間長度,單位:秒。

      start_time

      錄製開始時間。Unix時間戳記,單位:秒。

      stop_time

      錄製結束時間。Unix時間戳記,單位:秒。

      push_args

      推流參數中以callback_為首碼的參數,如callback_arg1、callback_myid等。

      說明

      同一個參數名只能有一個參數值,如果傳入多個值,回調僅包含第一個值。如推流參數包含callback_args1=value1&callback_args1=value2,回調中仍為"callback_args1": "value1"

    • 檔案產生回調參數樣本

      推流URL為:

      rtmp://demo.aliyundoc.com/liveApp****/liveStream****?callback_args1=value1&callback_myid=1231389741

      則回調內容為:

      {
        "domain": "demo.aliyundoc.com",
        "app": "liveApp****",
        "stream": "liveStream****",
        "uri": "liveApp****/liveStream****/0_2017-03-08-23:09:46_2017-03-08-23:10:40.flv",
        "duration": 69.403,
        "start_time": 1488985786,
        "stop_time": 1488985840,
        "push_args": {
          "callback_args1": "value1",
          "callback_myid": "1231389741"
        }
      }
      說明

      以上回調樣本,適用於所有沒有定製回調模板的客戶。

按需錄製回調

按需錄製回調是錄製之前通過回調的方式,傳遞直播流的相關參數給使用者,由使用者判斷是否需要錄製的功能。

使用者指定一個回調地址,並設定一個domain、app或stream層級的錄製為按需錄製。當錄製服務收到匹配domain、app或stream名稱的流時,向使用者的回調地址發送請求(請求包含5個參數),來詢問使用者是否需要錄製這路流。

  • 請求參數

    參數類型描述
    domainString主播流網域名稱。
    appString播流所屬應用程式名稱。
    streamString播流名稱。
    codecString編碼方式。取值:
    • h264
    • h265
    vbitrateString視頻碼率。單位:kbps。
  • 返回參數

    參數類型是否必選描述
    ApiVersionString

    API版本。預設為1.0版本。

    NeedRecordBool是否需要錄製。
    IntervalJSONObject具體格式的錄製周期變化。取值範圍:5~21600。單位:秒。
    FormatJSONArray錄製格式。支援MP4、FLV、M3U8。
  • 請求樣本

    GET /?app=seq_all&domain=demo.aliyundoc.com&stream=ondemand8&vbitrate=2000&codec=h264 HTTP/1.1
    Host: pull.aliyundoc.com
    User-Agent: Go-http-client/1.1
    Accept-Encoding: gzip
  • 返回樣本

    {
        "ApiVersion" : "1.0",
        "NeedRecord" : true,
        "Interval" : {
            "Mp4": 300,
            "Flv": 120,
            "M3U8": 180
        },
        "Format" : ["mp4","flv"]
    }
  • 返回參數處理

    錄製服務會對使用者返回的參數配置和既有配置進行覆蓋。例如,顯示指定了Interval,那麼錄製服務會覆蓋資料庫中的錄製配置裡面的Interval,Format會和資料庫中的配置取交集。如果使用者指定的格式全不在既有配置之中,則不會錄製這路直播流。

    說明
    • 所有非200 http status code,都會被認為是調用使用者介面失敗。

    • 對於範圍body長度有限制,超過2048會被截斷,以防惡意攻擊。

直播截圖回調

ApsaraVideo for Live支援直播截圖結果回調,您可以在控制台或通過API配置回調地址。

  • 截圖回調設定方式

    • 控制台

      進入ApsaraVideo for Live控制台頁面,選擇左側導覽列功能管理 > 事件回調進入事件回調頁面,選擇需要開啟的網域名稱,在回調設定頁簽下,開啟截圖回調開關,添加或修改推流回調地址。具體操作請參見截圖回調

    • API

      介面

      描述

      參考文檔

      AddLiveSnapshotNotifyConfig

      添加截圖回調配置。

      添加截圖回調配置

      UpdateLiveSnapshotNotifyConfig

      修改截圖回調配置。

      修改截圖回調配置

      DescribeLiveSnapshotNotifyConfig

      擷取截圖回調配置。

      擷取截圖回調配置

      DeleteLiveSnapshotNotifyConfig

      刪除截圖回調配置。

      刪除截圖回調配置

    • 截圖檔案回調參數

      參數

      描述

      Event

      事件。

      DomainName

      截圖的播流網域名稱。

      AppName

      應用程式名稱。

      StreamName

      流名。

      OssBucket

      儲存截圖的Bucket名。

      OssEndpoint

      儲存截圖的OSS。

      OssObject

      截圖的檔案名稱。

      CreateTime

      截圖時間。

      SnapshotUrl

      截圖檔案在使用者錄製OSS Bucket下的路徑。

      Size

      圖片大小。

      Width

      圖片寬。單位:像素。

      Height

      圖片高。單位:像素。

    • 截圖檔案回調參數樣本

      {
          "Event":"Snapshot",
          "DomainName":"demo.aliyundoc.com",
          "AppName":"liveApp****",
          "StreamName":"liveStream****",
          "OssBucket":"liveBucket****",
          "OssEndpoint":"oss-cn-shan****.aliyuncs.com",
          "OssObject":"1****.jpg",
          "CreateTime":"2015-12-01T17:36:00Z",
          "SnapshotUrl":"http://liveBucket****.oss-cn-shan****.aliyuncs.com/1****.jpg",
          "Size":"36291",
          "Width":"1280",
          "Height":"720"
      }
    • 直播截圖支援截圖回調鑒權配置。詳細資料請參見設定截圖回調鑒權配置截圖回調鑒權說明

智能審核回調

ApsaraVideo for Live可使用視訊審核和語音審核的結果回調,您可以在控制台或通過API配置回調地址。

  • 視頻審核回調設定方式

  • 視頻審核回調

    只會對於有問題的視頻內容進行回調通知,通知內容包含問題視頻截圖的審核資訊和儲存資訊。

    • 視頻審核回調參數

      參數

      類型

      描述

      DomainName

      String

      播流網域名稱。

      AppName

      String

      應用程式名稱。

      StreamName

      String

      流名稱。

      OssEndpoint

      String

      儲存物件Endpoint。

      OssBucket

      String

      儲存物件的Bucket。

      OssObject

      String

      儲存物件的檔案名稱。

      Result

      JSONArray

      檢測結果。請參見Result

      表 1. Result

      參數

      類型

      描述

      BizType

      String

      業務類型。可用於選擇模型,預設值為網域名稱。

      Scene

      String

      檢測情境

      • porn:鑒黃。

      • terrorism:暴恐涉政。

      • ad:圖文違規。

      • live:不良情境。

      • logo:圖片logo。

      Label

      String

      檢測結果的分類。不同檢測情境的結果分類不同,具體如下:

      • 圖片智能鑒黃(porn)結果分類:

        • normal:正常。

        • sexy:性感。

        • porn:色情。

      • 圖片暴恐涉政(terrorism)結果分類:

        • normal:正常。

        • bloody:血腥。

        • explosion:爆炸煙光。

        • outfit:特殊裝束。

        • logo:特殊標識。

        • weapon:武器。

        • politics:涉政。

        • violence :打鬥。

        • crowd:聚眾。

        • parade:遊行。

        • carcrash:車禍現場。

        • flag:旗幟。

        • location:地標。

        • others:其他。

      • 圖文違規(ad)結果分類:

        • normal:正常。

        • ad:其他廣告。

        • npx:牛皮癬廣告。

        • qrcode:含二維碼。

        • programCode:含小程式碼。

      • 不良情境(live)結果分類:

        • normal:正常。

        • meaningless:圖片中無內容(例如,黑屏、白屏)。

        • PIP:畫中畫。

        • smoking:吸煙。

        • drivelive:車內直播。

      • 圖片logo(logo)結果分類:

        • normal:正常。

        • TV:含受管控的logo。

        • trademark:含商標。

      Rate

      Float

      信賴度分數。取值範圍:0(表示信賴度最低)~100(表示信賴度最高)。

      說明

      該值僅作為參考,強烈建議您不要在業務中使用。建議您參考Label結果用於內容違規判定。

      Extent

      String

      預留欄位。

      說明

      預設新使用者將使用此版本,老使用者維持不變,如需使用此版本,請您提交工單。關於如何提交工單,請參見聯絡我們

    • 視頻審核回調參數樣本

      {
       "DomainName": "demo.aliyundoc.com",
       "AppName": "liveApp****",
       "StreamName": "liveStream****",
       "OssEndpoint": "oss-cn-hang****.aliyuncs.com",
       "OssBucket": "liveBucket****",
       "OssObject": "example.jpg",
       "Result": [
           {
               "BizType": "demo.aliyundoc.com",
               "Result": [
                   {"Label": "Porn", "Rate":11, "Suggestion": "review", "Scene":"porn", "Extent": {}},
                   {"Label": "Ad", "Rate":11, "Suggestion": "review", "Scene":"ad", "Extent": {}}
               ]
           }
       ]
      }
                          
  • 語音審核回調設定方式

  • 語音審核回調

    只會對於有問題的音頻內容進行回調通知,通知內容包含問題語音的文本資訊以及最近一分鐘內的上下文資訊。

    • 語音審核回調參數

      參數

      類型

      描述

      domain

      String

      播流網域名稱。

      app

      String

      應用程式名稱。

      stream

      String

      流名稱。

      timestamp

      Int

      回調時間戳記。單位:秒。

      result

      JSONArray

      檢測結果。請參見Result

      表 2. Result

      參數

      類型

      描述

      scene

      String

      檢測情境。

      label

      String

      檢測結果的分類。取值:

      • normal:正常文本

      • spam:含垃圾資訊

      • ad:廣告

      • politics:涉政

      • terrorism:暴恐

      • abuse:辱罵

      • porn:色情

      • flood:灌水

      • contraband:違禁

      • meaningless:無意義

      suggestion

      String

      處理建議。取值:

      • pass:結果正常,無需進行其餘操作。

      • review:結果不確定,需要進行人工審核。

      • block:結果違規,建議直接刪除或者限制公開。

      rate

      Float

      信賴度分數。取值範圍:0(表示信賴度最低)~100(表示信賴度最高)。

      說明

      該值僅作為參考,強烈建議您不要在業務中使用。建議您參考Label結果用於內容違規判定。

      details

      JSONArray

      語音對應的文本詳情,每一句文本對應一個元素,可以包含一個或者多個元素。關於每個元素的結構描述,請參見Detail

      表 3. Detail

      參數

      類型

      描述

      startTime

      Int

      句子開始的時間戳記,單位:秒。

      endTime

      Int

      句子結束的時間戳記,單位:秒。

      text

      String

      問題語音轉換成文本的結果。

      label

      String

      檢測結果的分類。取值:

      • normal:正常文本

      • spam:含垃圾資訊

      • ad:廣告

      • politics:涉政

      • terrorism:暴恐

      • abuse:辱罵

      • porn:色情

      • flood:灌水

      • contraband:違禁

      • meaningless:無意義

    • 語音審核回調參數樣本

      {
          "domain": "example.aliyundoc.com",
          "app": "liveApp****",
          "stream": "5d9747eba39b44769852d276f9ff****",
          "timestamp": 1572248095,
          "result": [
              {
                  "scene": "antispam",
                  "label": "ad",
                  "suggestion": "block",
                  "rate": 99.91,
                  "details": [
                      {
                          "startTime": 1572248023,
                          "endTime": 1572248040,
                          "text": "麗江隴川等酒店免費居住權120天居住權可與親友共用來雲棲社國際燒酒店接待中心地址芒市團結大街96號鄧朝ktv旁諮詢熱線2285699",
                          "label": "ad"
                      },
                      {
                          "startTime": 1572248040,
                          "endTime": 1572248070,
                          "text": "典藏經典別墅尊享隆多溫泉、梁河金塔、溫泉旅遊小鎮二期濱江苑地區11月2號盛大開盤天然龍窩、溫泉水入戶戶型多樣,設計經典價位超值,值得您擁有開盤當天還有超值優惠,歡迎您前來品鑒,憑藉地址,然和縣遮島鎮先鋒路229號分享熱線0692695577769***
      ",
                          "label": "normal"
                      },
                      {
                          "startTime": 1572248072,
                          "endTime": 1572248077,
                          "text": "快樂的時光,有你相伴愜意的日子,格外輕鬆。",
                          "label": "normal"
                      },
                      {
                          "startTime": 1572248078,
                          "endTime": 1572248086,
                          "text": "fme043忙裡偷閒音樂時光有歌曲溫暖,有你想念影院。",
                          "label": "normal"
                      }
                  ]
              }
          ]
      }