ApsaraVideo 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配置回調地址。

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

  • 控制台

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

  • API

    介面	描述	參考文檔
    SetLiveStreamsNotifyUrlConfig	設定推流回調配置。	設定直播推流回調配置
    DescribeLiveStreamsNotifyUrlConfig	查詢推流回調配置。	查詢直播推流回調配置
    DeleteLiveStreamsNotifyUrlConfig	刪除推流回調配置。	刪除直播推流回調配置

• 直播推流狀態回調

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

  • 直播推流狀態回調中開播（publish）狀態回調邏輯

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

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

    說明

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

    • 當10秒內（包含十秒）沒有流資料推送到直播中心時，直播服務就會自動斷開推流。

  • 直播推流狀態回調參數

    參數	描述
    action	事件。 publish：推流。 publish_done：斷流。
    ip	推流的用戶端IP。
    id	推流流名稱。
    app	推流網域名稱。預設為自訂的推流網域名稱，如果未綁定推流網域名稱即為播流網域名稱。
    appname	推流應用程式名稱。
    time	Unix時間戳記。單位：秒。
    usrargs	使用者推流的參數。
    node	CDN接受流的節點或者機器名。
    height	解析度的高。單位：像素。 說明 解析度資訊（height和width）僅在首次回調時產生。
    width	解析度的寬。單位：像素。

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

    http://1.1.X.X?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.X.X?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-TIMESTAMP和 ALI-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個參數），來詢問使用者是否需要錄製這路流。

• 請求參數

  參數	類型	描述
  domain	String	主播流網域名稱。
  app	String	播流所屬應用程式名稱。
  stream	String	播流名稱。
  codec	String	編碼方式。取值： h264 h265
  vbitrate	String	視頻碼率。單位：kbps。

• 返回參數

  參數	類型	是否必選	描述
  ApiVersion	String	否	API版本。預設為1.0版本。
  NeedRecord	Bool	是	是否需要錄製。
  Interval	JSONObject	否	具體格式的錄製周期變化。取值範圍：5~21600。單位：秒。
  Format	JSONArray	否	錄製格式。支援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配置回調地址。

• 視頻審核回調設定方式

  • 控制台

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

    說明

    目前僅部分直播中心支援直播智能審核，具體支援該功能的直播中心，請參見服務地區。

  • API

    介面	描述	參考文檔
    AddLiveDetectNotifyConfig	添加直播視頻審核回調配置。	添加直播審核回調配置
    DescribeLiveAudioAuditNotifyConfig	查詢直播視頻審核回調配置。	查詢直播審核回調配置
    UpdateLiveDetectNotifyConfig	更新直播視頻審核回調配置。	更新直播審核回調配置
    DeleteLiveDetectNotifyConfig	刪除直播視頻審核回調配置。	刪除直播審核回調配置

• 視頻審核回調

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

  • 視頻審核回調參數

    參數	類型	描述
    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": {}}
             ]
         }
     ]
    }
                        

• 語音審核回調設定方式

  • 控制台

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

  • API

    介面	描述	參考文檔
    AddLiveAudioAuditNotifyConfig	添加直播語音審核回調配置。 重要 直播語音審核回調返回為JSON字串。	添加直播語音審核回調配置
    DeleteLiveAudioAuditNotifyConfig	刪除直播語音審核回調配置。	刪除直播語音審核回調配置
    UpdateLiveAudioAuditNotifyConfig	更新直播語音審核回調配置。	更新直播語音審核回調配置
    DescribeLiveAudioAuditNotifyConfig	查詢直播語音審核回調配置。	查詢直播語音審核回調配置

• 語音審核回調

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

  • 語音審核回調參數

    參數	類型	描述
    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"
                    }
                ]
            }
        ]
    }