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配置回調地址。
直播推流狀態回調設定方式
控制台
進入ApsaraVideo for Live控制台頁面,選擇左側導覽列 進入事件回調頁面,選擇需要開啟的網域名稱,在回調設定頁簽下,開啟推流回調開關,添加或修改推流回調地址。具體操作請參見推流回調
API
介面
描述
參考文檔
SetLiveStreamsNotifyUrlConfig
設定推流回調配置。
DescribeLiveStreamsNotifyUrlConfig
查詢推流回調配置。
DeleteLiveStreamsNotifyUrlConfig
刪除推流回調配置。
直播推流狀態回調
推斷流狀態回調會將參數封裝在MultiDict內。
直播推流狀態回調中開播(publish)狀態回調邏輯
RTMP推流在阿里雲直播服務收到On Publish訊息後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
直播推流狀態回調鑒權
推流回調鑒權功能預設關閉,使用者可在配置推流回調地址時啟用鑒權。啟用功能後,鑒權邏輯如下:
阿里雲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。
回調訊息接收服務端接收回調訊息時,將回調網域名稱、
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" } ] } ] }