首頁 > 文檔中心 > 云端服務(wù) > 云端存儲(chǔ) > 設(shè)備端接入

通過https的方式實(shí)作云存推流

VSaaS 設(shè)備端推流相關(guān) API 文檔 | TUTK SDK 開發(fā)手冊

一、概述

本文檔將說明設(shè)備端通過https的方式，推流到VSaaS相關(guān)參數(shù)，包括獲取上傳地址、推流（視頻上傳）、更新事件標(biāo)簽三個(gè)關(guān)鍵操作。設(shè)備端需先通過VSaaS Token認(rèn)證，再依次完成推流地址獲取、視頻分片上傳、事件標(biāo)簽補(bǔ)充等流程，最終實(shí)現(xiàn)視頻數(shù)據(jù)的云端存儲(chǔ)與管理。

前置條件：設(shè)備端已從第三方APP獲取有效的VSaaS Info（具體請參考：通過AVAPIs實(shí)作云存儲(chǔ)中的配置變更回調(diào)部分代碼）。后續(xù)的操作，將使用到VSaaS Info里面的url信息。

二、API接口

（一）獲取上傳地址

設(shè)備端通過此接口獲取視頻推流地址，用于將事件視頻或?qū)崟r(shí)視頻流上傳至VSaaS云端，推流前需優(yōu)先調(diào)用此接口。

1. 請求說明

項(xiàng)	說明
HTTP請求方式	GET
請求URL	https://vsaas-domain/vsaas/api/v1/stream/stream_url/{UDID}?stoken={stoken}&starttime={timestamp}&protocol=upload&event_id={event_id}[&event_file={event_file}][&media_type={media_type}][&tags={tag}]
請求頭（Header）	無額外要求，參數(shù)通過URL拼接傳遞

2. 請求參數(shù)

參數(shù)名	類型	必選	說明
UDID	String	是	設(shè)備唯一標(biāo)識(shí)（設(shè)備UID）
stoken	String	是	推流用Token，從APP端獲取
event_id	String	是	事件類型ID
starttime	String	是	事件觸發(fā)時(shí)間戳（秒級(jí)）
protocol	String	是	固定值：upload
event_file	String	否	關(guān)聯(lián)的事件文件名稱（可選）
media_type	Int	是	媒體類型：0=hls，1=krf，4=mp4（默認(rèn)按系統(tǒng)配置）
tags	String	否	事件標(biāo)簽，多個(gè)標(biāo)簽用逗號(hào)分隔（如"門口,花園"）

3. 響應(yīng)說明

3.1 響應(yīng)參數(shù)

參數(shù)名	類型	說明
contract_type	String	存儲(chǔ)類型："event"（事件存儲(chǔ)）或 "fulltime"（全時(shí)存儲(chǔ)）
url	String	推流地址（含OTP臨時(shí)授權(quán)碼）
recording_max_kbps	Int	最大推流碼率（kbps）
video_max_fps	Int	最大幀率（fps）
video_max_height	Int	視頻最大高度（像素）
video_max_width	Int	視頻最大寬度（像素）
message	String	錯(cuò)誤信息（成功時(shí)為空）
code	Int	錯(cuò)誤碼：1=成功；-1001=參數(shù)無效；-1002=設(shè)備無效；-1003=綁定記錄無效；-1004=合約無效；-1005=開始時(shí)間無效；-1006=開始時(shí)間格式錯(cuò)誤；-3001=合約未找到

3.2 響應(yīng)狀態(tài)碼

狀態(tài)碼	徽章	說明
200	成功	請求成功，返回推流地址及配置信息
400	參數(shù)錯(cuò)誤	必填參數(shù)缺失或格式錯(cuò)誤

4. 接口示例

請求示例（curl）

curl -vvv "https://idc-stg-be-docker.kalay.us:8864/vsaas/api/v1/stream/stream_url/TC021LBP010000000001AAAAAAAAAAAAAAAAAAAA?stoken=dEmhotTRI7FG4ceJfZ1R7b6NwuJXhpclrGlm2LvkOguM4nPCjnZRN5zrltts-sPp0E5kdK_T6D9pJN5axFgnkX0QmiWfOm3-ybLmQy5Guwk=&protocol=upload&event_id=999&starttime=1562048846&media_type=0"

響應(yīng)示例（成功）

{ "result": { "url": "https://idc-stg-stream01.kalay.us:8080/post_stream/v1/TC021LBP010000000001AAAAAAAAAAAAAAAAAAAA?OTP=202E457ED959CA934F3A&stoken=dEmhotTRI7FG4ceJfZ1R7b6NwuJXhpclrGlm2LvkOguM4nPCjnZRN5zrltts-sPp0E5kdK_T6D9pJN5axFgnkX0QmiWfOm3-ybLmQy5Guwk=&event_id=999&starttime=1562048846", "contract_type": "event", "recording_max_kbps": 10, "video_max_fps": 15, "event_recording_max_length": 10, "video_max_height": 360, "video_max_width": 480 }, "message": "", "code": 1 }

（二）推流（視頻上傳）

設(shè)備端使用「獲取上傳地址」接口返回的推流地址，以multipart/form-data格式將視頻流（支持分片）上傳至VSaaS云端，支持TS/MP4/JPG格式文件。

1. 請求說明

項(xiàng)	說明
HTTP請求方式	POST
請求URL	從「獲取上傳地址」接口返回的url（含OTP臨時(shí)授權(quán)碼）
請求頭（Header）	Content-Type: multipart/form-data; boundary={自定義邊界值}（邊界值需與請求體中一致）

2. 請求參數(shù)

參數(shù)類型	參數(shù)名	類型	必選	說明
URL參數(shù)	OTP	String	是	臨時(shí)授權(quán)碼，來自推流地址（每次推流唯一）
	stoken	String	是	推流用Token，與「獲取上傳地址」時(shí)一致
	event_id	String	是	事件類型ID，與「獲取上傳地址」時(shí)一致
	starttime	String	是	事件觸發(fā)時(shí)間戳（秒級(jí)），與「獲取上傳地址」時(shí)一致
	UDID	String	是	設(shè)備唯一標(biāo)識(shí)，與「獲取上傳地址」時(shí)一致
	tags	String	否	事件標(biāo)簽，多個(gè)標(biāo)簽用逗號(hào)分隔（可選補(bǔ)充）
Form-Data參數(shù)（media_file）	file_start_time	String	是	文件開始時(shí)間戳（毫秒級(jí)），需等于starttime*1000
	file_duration	String	是	文件時(shí)長（毫秒級(jí)）；JPG格式填0
	event_end	String	是	事件結(jié)束標(biāo)識(shí)：1=最后一個(gè)文件，0=后續(xù)還有文件
	filename	String	否	格式：{13位毫秒時(shí)間戳}_D{毫秒時(shí)長}[E].(ts/mp4/jpg)；E標(biāo)識(shí)最后一個(gè)文件；優(yōu)先級(jí)低于前三個(gè)參數(shù)(file_start_time、file_duration、event_end)
	Content-Type	String	是	文件類型：video/MP2T（TS）、video/mp4（MP4）、image/jpg（JPG）
請求體	-	Binary	是	視頻/圖片二進(jìn)制數(shù)據(jù)；多文件需重復(fù)media_file字段分片上傳

2.1 多文件上傳說明

1. 分片視頻（如TS文件）需為每個(gè)分片重復(fù)media_file字段，最后一個(gè)分片event_end設(shè)為1；
2. 已填寫file_start_time、file_duration、event_end時(shí)，可省略filename，系統(tǒng)自動(dòng)生成；
3. 分片時(shí)長建議一致（如5秒/片），便于后續(xù)回放和下載。

3. 響應(yīng)狀態(tài)碼

狀態(tài)碼	徽章	說明
200	成功	文件上傳成功
400	參數(shù)錯(cuò)誤	Form-Data參數(shù)缺失或格式錯(cuò)誤
403	授權(quán)失敗	OTP過期、stoken無效或推流地址失效

4. 接口示例

請求示例（curl）

curl -X POST \ "http://localhost:55550/post_stream/v1/DRUUA974YFRC9MPGU1XJ?stoken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9&starttime=1570237012&event_id=999&OTP=hahahaha" \ -H "Content-Type: multipart/form-data; boundary=cf58a91e1d88633dfb10e1c64ef494b9c69ecddc8ef903055835a73413ac" \ -F "media_file=@1570237012000_D5000.ts;type=video/mp2t;file_start_time=1570237012000;file_duration=5000;event_end=0" \ -F "media_file=@1570237017000_D5000E.ts;type=video/mp2t;file_start_time=1570237017000;file_duration=5000;event_end=1"

請求體示例（Form-Data）

--cf58a91e1d88633dfb10e1c64ef494b9c69ecddc8ef903055835a73413ac Content-Disposition: form-data; name="media_file";file_start_time="1570011960000";file_duration="5000";event_end="0" Content-Type: video/MP2T [TS文件二進(jìn)制數(shù)據(jù)] --cf58a91e1d88633dfb10e1c64ef494b9c69ecddc8ef903055835a73413ac Content-Disposition: form-data; name="media_file";file_start_time="1570011965000";file_duration="5000";event_end="1" Content-Type: video/MP2T [TS文件二進(jìn)制數(shù)據(jù)] --cf58a91e1d88633dfb10e1c64ef494b9c69ecddc8ef903055835a73413ac--

（三）更新事件標(biāo)簽

為已上傳的事件視頻添加標(biāo)簽，支持多個(gè)標(biāo)簽以逗號(hào)分隔，標(biāo)簽用于后續(xù)事件篩選和查詢。

1. 請求說明

項(xiàng)	說明
HTTP請求方式	GET
請求URL	https://vsaas-domain/vsaas/api/v1/stream/stream_event/{UDID}?stoken={stoken}&tags=a,b,c,d&starttime={timestamp}
請求頭（Header）	無額外要求，參數(shù)通過URL拼接傳遞

2. 請求參數(shù)

參數(shù)名	類型	必選	說明
UDID	String	是	設(shè)備唯一標(biāo)識(shí)（與上傳視頻時(shí)一致）
stoken	String	是	推流用Token，與上傳視頻時(shí)一致
starttime	String	是	事件觸發(fā)時(shí)間戳（秒級(jí)），與上傳視頻時(shí)一致（唯一標(biāo)識(shí)事件）
tags	String	否	事件標(biāo)簽，多個(gè)標(biāo)簽用逗號(hào)分隔（如"門口,花園,異常"）；為空則清空標(biāo)簽

3. 響應(yīng)狀態(tài)碼

狀態(tài)碼	徽章	說明
200	成功	標(biāo)簽更新成功
400	參數(shù)錯(cuò)誤	UDID、stoken、starttime缺失或格式錯(cuò)誤

4. 接口示例

請求示例（curl）

curl -vvv "https://vsaas-stg.kalay.us/vsaas/api/v1/stream/stream_event/TC021LBP010000000001AAAAAAAAAAAAAAAAAAAA?stoken=dEmhotTRI7FG4ceJfZ1R7b6NwuJXhpclrGlm2LvkOguM4nPCjnZRN5zrltts-sPp0E5kdK_T6D9pJN5axFgnkX0QmiWfOm3-ybLmQy5Guwk=&tags=a,b,c,d&starttime=1562048846"