一、接口總覽
| 接口名稱 | 功能描述 | 請求方式 | 授權(quán)方式 | 接口版本 |
|---|---|---|---|---|
| 查詢事件數(shù)（get_event_count） | 查詢指定設(shè)備在特定時間段內(nèi)的事件數(shù)量 | GET / POST (GraphQL) | JWT / Bearer Token 授權(quán) | v1 |
| 查詢事件列表（get_event_list） | 查詢云端事件列表，支持分頁和多條件篩選 | GET / POST (GraphQL) | JWT / Bearer Token 授權(quán) | v1 |
| 查詢過期事件（get_archieved_event_list） | 查詢已過期的云端事件列表 | GET / POST (GraphQL) | JWT / Bearer Token 授權(quán) | v1 |
| 修改事件標(biāo)簽（update_event） | 修改指定事件的標(biāo)簽信息 | GET / POST (GraphQL) | JWT / Bearer Token 授權(quán) | v1 |
| 刪除事件（remove_event） | 刪除指定事件或特定時間段內(nèi)的事件 | GET / POST (GraphQL) | JWT / Bearer Token 授權(quán) | v1 |
本章節(jié)介紹VSaaS平臺事件管理核心API接口（GraphQL版本），第三方系統(tǒng)可通過這些接口完成事件數(shù)量查詢、列表查詢、標(biāo)簽修改、事件刪除等操作，所有接口均需攜帶有效的VSaaS Token完成身份認(rèn)證。
二、查詢事件數(shù)接口（get_event_count）
用于查詢指定設(shè)備在特定時間段內(nèi)的事件數(shù)量，支持按事件ID、標(biāo)簽、是否歸檔等條件篩選，常用于分頁控制和數(shù)據(jù)統(tǒng)計。
（一）請求說明
1. 請求URL
GET: https://vsaas.kalay.us/vsaas/api/v1/be?query={get_event_count(device:String!,start_time:String!,end_time:String!,is_archieve:Boolean,event_id:Int,tags:String) Int}
POST: https://vsaas.kalay.us/vsaas/api/v1/be/
說明：支持GET和POST兩種請求方式，推薦使用POST方式避免URL參數(shù)過長問題
2. 請求頭（Header）
| 參數(shù)名 | 類型 | 必選 | 說明 |
|---|---|---|---|
Authorization | String | 是 | 授權(quán)令牌，格式：JWT {token} 或 Bearer {token} |
Content-Type | String | 是 | 固定值：application/json |
3. 請求參數(shù)
| 參數(shù)名 | 類型 | 必選 | 位置 | 說明 |
|---|---|---|---|---|
device | String | 是 | GraphQL參數(shù) QUERY | 設(shè)備端的UDID/UID（與流媒體接口的udid一致） |
start_time | String | 是 | GraphQL參數(shù) QUERY | 起始時間（時間戳格式，毫秒），需小于end_time |
end_time | String | 是 | GraphQL參數(shù) QUERY | 結(jié)束時間（時間戳格式，毫秒），需大于start_time |
is_archieve | Boolean | 否 | GraphQL參數(shù) QUERY | 是否歸檔：true（僅查歸檔事件）、false（僅查未歸檔事件），默認(rèn)查詢?nèi)?/td> |
event_id | Int | 否 | GraphQL參數(shù) QUERY | 事件ID，用于分類篩選（如1=移動偵測、2=人形偵測等，需與業(yè)務(wù)約定一致） |
tags | String | 否 | GraphQL參數(shù) QUERY | 標(biāo)簽，多個標(biāo)簽以空格分隔（如"門口 花園"），精確匹配篩選 |
4. 請求體（POST 方式專用）
{
"query": "query {get_event_count(device:\"udid\",start_time:\"1583985297000\",end_time:\"1584011301000\",is_archieve:false,event_id:1,tags:\"門口\")}"
}
（二）響應(yīng)說明
1. 響應(yīng)狀態(tài)碼
| 狀態(tài)碼 | 徽章 | 說明 |
|---|---|---|
| 200 | 成功 | 請求成功，返回事件數(shù)量 |
| 400 | 參數(shù)錯誤 | 請求參數(shù)錯誤（如GraphQL語法錯誤、必填參數(shù)缺失、時間戳格式非法） |
| 401 | 授權(quán)失敗 | 授權(quán)令牌無效或過期 |
| 500 | 服務(wù)器錯誤 | 服務(wù)器內(nèi)部異常，請重試或聯(lián)系技術(shù)支持 |
2. 響應(yīng)數(shù)據(jù)結(jié)構(gòu)
{
"data": {
"get_event_count": "Int" // 符合條件的事件數(shù)量，無匹配結(jié)果時返回0
}
}
（三）接口示例
1. 請求示例（curl）
POST方式請求（示例）
curl --location --request POST 'https://vsaas.kalay.us/vsaas/api/v1/be/' \
--header 'Authorization: Bearer LKdkjlk8873BNN' \
--header 'Content-Type: application/json' \
--data-raw '{"query": "query {get_event_count(device:\"udid\",start_time:\"1583985297000\",end_time:\"1584011301000\",is_archieve:false)}"}'
2. 響應(yīng)示例（成功）
成功響應(yīng)
{
"data": {
"get_event_count": 761
}
}
無匹配結(jié)果響應(yīng)
{
"data": {
"get_event_count": 0
}
}
參數(shù)錯誤響應(yīng)（400）
{
"errors": [
{
"message": "Field 'start_time' of required type 'String!' is not provided",
"locations": [{"line": 1, "column": 25}]
}
]
}
三、查詢事件列表接口（get_event_list）
用于查詢云端事件列表，支持按設(shè)備、時間段、事件類型等條件篩選，可通過skip和limit控制分頁。返回結(jié)果包含事件關(guān)鍵信息（如start_time_ts、thumbnail），為后續(xù)媒體操作提供必要參數(shù)。
說明：點擊事件播放或者下載請參考流媒體模塊的「回放接口（ask_media）」，需使用本接口返回的
device和start_time_ts參數(shù)。（一）請求說明
1. 請求URL
GET: https://vsaas.kalay.us/vsaas/api/v1/be?query={get_event_list(device:string!,start_time:string!,end_time:string!,is_archieve:Boolean,event_id:Int,tags:string,skip:Int,limit:Int) [Event]}
POST: https://vsaas.kalay.us/vsaas/api/v1/be/
說明：limit默認(rèn)值為50，最大值為100，超過最大值將按100返回
2. 請求頭（Header）
| 參數(shù)名 | 類型 | 必選 | 說明 |
|---|---|---|---|
Authorization | String | 是 | 授權(quán)令牌，格式：JWT {token} 或 Bearer {token} |
Content-Type | String | 是 | 固定值：application/json |
3. 請求參數(shù)
| 參數(shù)名 | 類型 | 必選 | 位置 | 說明 |
|---|---|---|---|---|
device | String | 是 | GraphQL參數(shù) QUERY | 設(shè)備端的UDID/UID（與流媒體接口的udid一致） |
start_time | String | 是 | GraphQL參數(shù) QUERY | 起始時間（時間戳格式，毫秒） |
end_time | String | 是 | GraphQL參數(shù) QUERY | 結(jié)束時間（時間戳格式，毫秒） |
is_archieve | Boolean | 否 | GraphQL參數(shù) QUERY | 是否歸檔：true（僅查歸檔事件）、false（僅查未歸檔事件），默認(rèn)查詢?nèi)?/td> |
event_id | Int | 否 | GraphQL參數(shù) QUERY | 事件ID，用于分類篩選（如1=移動偵測、2=人形偵測等） |
tags | String | 否 | GraphQL參數(shù) QUERY | 標(biāo)簽（如"門口"、"花園"），精確匹配 |
skip | Int | 否 | GraphQL參數(shù) QUERY | 跳過的事件數(shù)量（分頁用，如每次查20條，第2頁填20，第3頁填40），默認(rèn)0 |
limit | Int | 否 | GraphQL參數(shù) QUERY | 單次拉取事件數(shù)量上限，默認(rèn)50，最大100 |
4. 請求體（POST 方式專用）
{
"query": "query {get_event_list(device:\"KJKWJK\",start_time:\"1582398139849\",end_time:\"1582398239849\",skip:0,limit:100,is_archieve:false){pk,start_time,start_time_ts,thumbnail,event_id}}"
}
（二）響應(yīng)說明
1. 響應(yīng)狀態(tài)碼
| 狀態(tài)碼 | 徽章 | 說明 |
|---|---|---|
| 200 | 成功 | 請求成功，返回事件列表 |
| 400 | 參數(shù)錯誤 | 請求參數(shù)錯誤（如GraphQL語法錯誤、必填參數(shù)缺失、limit超過最大值） |
| 401 | 授權(quán)失敗 | 授權(quán)令牌無效或過期 |
| 500 | 服務(wù)器錯誤 | 服務(wù)器內(nèi)部異常，請重試或聯(lián)系技術(shù)支持 |
2. 響應(yīng)數(shù)據(jù)結(jié)構(gòu)
{
"data": {
"get_event_list": [
{
"pk": "String", // 事件唯一標(biāo)識
"created": "String", // 事件創(chuàng)建時間（YYYY-MM-DD HH:MM:SS）
"updated": "String", // 事件修改時間（YYYY-MM-DD HH:MM:SS）
"device": "String", // 設(shè)備UDID
"account": "String", // 關(guān)聯(lián)賬戶標(biāo)識
"start_time": "String", // 事件開始時間（YYYY-MM-DD HH:MM:SS）
"start_time_ts": "String", // 事件開始時間戳（毫秒）
"expires": "String", // 事件到期時間（YYYY-MM-DD HH:MM:SS）
"thumbnail": "String", // 縮略圖地址
"url": "String", // 媒體資源原始地址
"event_type": "Int", // 事件類型標(biāo)識
"contract": "String", // 關(guān)聯(lián)合約標(biāo)識
"is_archieve": "Boolean", // 是否歸檔
"event_id": "Int" // 事件分類ID
}
]
}
}
（三）接口示例
1. 請求示例（curl）
POST方式請求（示例）
curl -XPOST -H 'Authorization: Bearer LKdkjlk8873BNN' -H 'Content-Type: application/json' -d '{"query": "query {get_event_list(device:\"KJKWJK\",start_time:\"1582398139849\",end_time:\"1582398239849\",skip:0,limit:100){pk,start_time,start_time_ts,thumbnail,event_id}}"}' https://vsaas.kalay.us/vsaas/api/v1/be/
2. 響應(yīng)示例（成功）
成功響應(yīng)
{
"data": {
"get_event_list": [
{
"pk": "event123456",
"start_time": "2019-10-02 12:20:20",
"start_time_ts": "1569980420000",
"expires": "2024-10-02 12:20:20",
"thumbnail": "https://example.com/thumb.jpg",
"is_archieve": false,
"event_id": 1,
"device": "KJKWJK"
},
{
"pk": "event789012",
"start_time": "2019-10-02 12:21:30",
"start_time_ts": "1569980490000",
"expires": "2024-10-02 12:21:30",
"thumbnail": "https://example.com/thumb2.jpg",
"is_archieve": false,
"event_id": 2,
"device": "KJKWJK"
}
]
}
}
無匹配結(jié)果響應(yīng)
{
"data": {
"get_event_list": []
}
}
四、查詢過期事件接口（get_archieved_event_list）
用于查詢已經(jīng)過期的云端事件列表，按設(shè)備分組返回事件集合，無需額外篩選參數(shù)。過期事件指expires時間早于當(dāng)前時間的事件。
（一）請求說明
1. 請求URL
GET: https://vsaas.kalay.us/vsaas/api/v1/be?query={get_archieved_event_list [ArchievedEvent]}
POST: https://vsaas.kalay.us/vsaas/api/v1/be/
2. 請求頭（Header）
| 參數(shù)名 | 類型 | 必選 | 說明 |
|---|---|---|---|
Authorization | String | 是 | 授權(quán)令牌，格式：JWT {token} 或 Bearer {token} |
Content-Type | String | 是 | 固定值：application/json |
3. 請求參數(shù)
| 參數(shù)名 | 類型 | 必選 | 位置 | 說明 |
|---|---|---|---|---|
| - | - | - | - | 無額外請求參數(shù)，返回當(dāng)前賬戶下所有設(shè)備的過期事件 |
4. 請求體（POST 方式專用）
{
"query": "query {get_archieved_event_list {device,events{pk,start_time,start_time_ts,expires,thumbnail}}}"
}
（二）響應(yīng)說明
1. 響應(yīng)狀態(tài)碼
| 狀態(tài)碼 | 徽章 | 說明 |
|---|---|---|
| 200 | 成功 | 請求成功，返回過期事件列表 |
| 400 | 參數(shù)錯誤 | 請求參數(shù)錯誤（如GraphQL語法錯誤） |
| 401 | 授權(quán)失敗 | 授權(quán)令牌無效或過期 |
| 500 | 服務(wù)器錯誤 | 服務(wù)器內(nèi)部異常，請重試或聯(lián)系技術(shù)支持 |
2. 響應(yīng)數(shù)據(jù)結(jié)構(gòu)
{
"data": {
"get_archieved_event_list": [
{
"device": "String", // 設(shè)備UDID
"events": [ // 過期事件列表，結(jié)構(gòu)同get_event_list
{
"pk": "String",
"start_time": "String",
"start_time_ts": "String",
"expires": "String",
"thumbnail": "String"
}
]
}
]
}
}
（三）接口示例
1. 請求示例（curl）
POST方式請求（示例）
curl -XPOST -H 'Authorization: Bearer LKdkjlk8873BNN' -H 'Content-Type: application/json' -d '{"query": "query {get_archieved_event_list {device,events{pk,start_time,start_time_ts,expires,thumbnail}}}" }' https://vsaas.kalay.us/vsaas/api/v1/be/
2. 響應(yīng)示例（成功）
成功響應(yīng)
{
"data": {
"get_archieved_event_list": [
{
"device": "KJKWJK",
"events": [
{
"pk": "archieve123",
"start_time": "2019-10-02 12:20:20",
"start_time_ts": "1569980420000",
"expires": "2023-10-02 12:20:20",
"thumbnail": "https://example.com/archieve_thumb.jpg"
}
]
},
{
"device": "XYZ789",
"events": [
{
"pk": "archieve456",
"start_time": "2019-10-03 09:15:30",
"start_time_ts": "1570053330000",
"expires": "2023-10-03 09:15:30",
"thumbnail": "https://example.com/archieve_thumb2.jpg"
}
]
}
]
}
}
五、修改事件標(biāo)簽接口（update_event）
用于修改指定事件的標(biāo)簽信息，需傳遞事件唯一標(biāo)識pk和新的標(biāo)簽列表。標(biāo)簽修改為覆蓋操作，將替換事件原有的所有標(biāo)簽。
（一）請求說明
1. 請求URL
GET: https://vsaas.kalay.us/vsaas/api/v1/be?query=mutation {update_event(pk:string!,tags:[string]!) String}
POST: https://vsaas.kalay.us/vsaas/api/v1/be/
說明：接口名稱為update_event（原文檔update為簡寫，標(biāo)準(zhǔn)名稱含event后綴）
2. 請求頭（Header）
| 參數(shù)名 | 類型 | 必選 | 說明 |
|---|---|---|---|
Authorization | String | 是 | 授權(quán)令牌，格式：JWT {token} 或 Bearer {token} |
Content-Type | String | 是 | 固定值：application/json |
3. 請求參數(shù)
| 參數(shù)名 | 類型 | 必選 | 位置 | 說明 |
|---|---|---|---|---|
pk | String | 是 | GraphQL參數(shù) MUTATION | 事件唯一標(biāo)識（通過get_event_list接口獲?。?/td> |
tags | Array[String] | 是 | GraphQL參數(shù) MUTATION | 標(biāo)簽列表（如["home","family"]），支持空數(shù)組 |
4. 請求體（POST 方式專用）
設(shè)置標(biāo)簽
{
"query": "mutation {update_event(pk:\"8dfaksjk2jkjkdjkjckjed3354\",tags:[\"home\",\"family\",\"門口\"])}"
}
清空標(biāo)簽
{
"query": "mutation {update_event(pk:\"8dfaksjk2jkjkdjkjckjed3354\",tags:[])}"
}
（二）響應(yīng)說明
1. 響應(yīng)狀態(tài)碼
| 狀態(tài)碼 | 徽章 | 說明 |
|---|---|---|
| 200 | 成功 | 請求成功，標(biāo)簽修改完成 |
| 400 | 參數(shù)錯誤 | 請求參數(shù)錯誤（如GraphQL語法錯誤、pk無效、標(biāo)簽格式非法） |
| 401 | 授權(quán)失敗 | 授權(quán)令牌無效或過期 |
| 404 | 事件不存在 | 指定pk的事件不存在或已被刪除 |
| 500 | 服務(wù)器錯誤 | 服務(wù)器內(nèi)部異常，請重試或聯(lián)系技術(shù)支持 |
2. 響應(yīng)數(shù)據(jù)結(jié)構(gòu)
{
"data": {
"update_event": "String" // 操作結(jié)果（Update event finish./失敗原因）
}
}
（三）接口示例
1. 請求示例（curl）
設(shè)置標(biāo)簽
curl -XPOST -H 'Authorization: Bearer LKdkjlk8873BNN' -H 'Content-Type: application/json' -d '{"query": "mutation {update_event(pk:\"8dfaksjk2jkjkdjkjckjed3354\",tags:[\"home\",\"family\",\"門口\"])}"}' https://vsaas.kalay.us/vsaas/api/v1/be/
清空標(biāo)簽
curl -XPOST -H 'Authorization: Bearer LKdkjlk8873BNN' -H 'Content-Type: application/json' -d '{"query": "mutation {update_event(pk:\"8dfaksjk2jkjkdjkjckjed3354\",tags:[])}"}' https://vsaas.kalay.us/vsaas/api/v1/be/
2. 響應(yīng)示例（成功）
成功響應(yīng)
{
"data": {
"update_event": "Update event finish."
}
}
六、刪除事件接口（remove_event）
用于刪除云端指定事件或特定時間段內(nèi)的事件：pk不為空時刪除指定事件（多個pk以空格分隔）；pk為空時刪除指定時間段內(nèi)的所有事件。
（一）請求說明
1. 請求URL
GET: https://vsaas.kalay.us/vsaas/api/v1/be?query=mutation {remove_event(pk:string,device:string!,start_time:string,end_time:string) String}
POST: https://vsaas.kalay.us/vsaas/api/v1/be/
說明：pk與start_time/end_time二選一；pk為空時必須傳device+start_time+end_time
2. 請求頭（Header）
| 參數(shù)名 | 類型 | 必選 | 說明 |
|---|---|---|---|
Authorization | String | 是 | 授權(quán)令牌，格式：JWT {token} 或 Bearer {token} |
Content-Type | String | 是 | 固定值：application/json |
3. 請求參數(shù)
| 參數(shù)名 | 類型 | 必選 | 位置 | 說明 |
|---|---|---|---|---|
pk | String | 否 | GraphQL參數(shù) MUTATION | 事件唯一標(biāo)識，多個pk以空格分隔（如"pk1 pk2 pk3"） |
device | String | 是 | GraphQL參數(shù) MUTATION | 設(shè)備UDID/UID（與流媒體接口的udid一致） |
start_time | String | 否 | GraphQL參數(shù) MUTATION | 起始時間戳（毫秒），pk為空時必填 |
end_time | String | 否 | GraphQL參數(shù) MUTATION | 結(jié)束時間戳（毫秒），pk為空時必填 |
4. 請求體（POST 方式專用）
刪除指定事件
{
"query": "mutation {remove_event(pk:\"8dfaksjk2jkjkdjkjckjed3354 event789012\",device:\"KJKWJK\")}"
}
刪除指定時間段事件
{
"query": "mutation {remove_event(device:\"KJKWJK\",start_time:\"1582398139849\",end_time:\"1582398239849\")}"
}
（二）響應(yīng)說明
1. 響應(yīng)狀態(tài)碼
| 狀態(tài)碼 | 徽章 | 說明 |
|---|---|---|
| 200 | 成功 | 請求成功，事件已刪除 |
| 400 | 參數(shù)錯誤 | 請求參數(shù)錯誤（如pk和時間段都為空/都傳、GraphQL語法錯誤） |
| 401 | 授權(quán)失敗 | 授權(quán)令牌無效或過期 |
