一、接口总览
| 接口名称 | 功能描述 | 请求方式 | 授权方式 | 接口版本 |
|---|---|---|---|---|
| 查询事件数（get_event_count） | 查询指定设备在特定时间段内的事件数量 | GET / POST (GraphQL) | JWT / Bearer Token 授权 | v1 |
| 查询事件列表（get_event_list） | 查询云端事件列表，支持分页和多条件筛选 | GET / POST (GraphQL) | JWT / Bearer Token 授权 | v1 |
| 查询过期事件（get_archieved_event_list） | 查询已过期的云端事件列表 | GET / POST (GraphQL) | JWT / Bearer Token 授权 | v1 |
| 修改事件标签（update_event） | 修改指定事件的标签信息 | GET / POST (GraphQL) | JWT / Bearer Token 授权 | v1 |
| 删除事件（remove_event） | 删除指定事件或特定时间段内的事件 | GET / POST (GraphQL) | JWT / Bearer Token 授权 | v1 |
本章节介绍VSaaS平台事件管理核心API接口（GraphQL版本），第三方系统可通过这些接口完成事件数量查询、列表查询、标签修改、事件删除等操作，所有接口均需携带有效的VSaaS Token完成身份认证。
二、查询事件数接口（get_event_count）
用于查询指定设备在特定时间段内的事件数量，支持按事件ID、标签、是否归档等条件筛选，常用于分页控制和数据统计。
（一）请求说明
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参数过长问题
2. 请求头（Header）
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
Authorization | String | 是 | 授权令牌，格式：JWT {token} 或 Bearer {token} |
Content-Type | String | 是 | 固定值：application/json |
3. 请求参数
| 参数名 | 类型 | 必选 | 位置 | 说明 |
|---|---|---|---|---|
device | String | 是 | GraphQL参数 QUERY | 设备端的UDID/UID（与流媒体接口的udid一致） |
start_time | String | 是 | GraphQL参数 QUERY | 起始时间（时间戳格式，毫秒），需小于end_time |
end_time | String | 是 | GraphQL参数 QUERY | 结束时间（时间戳格式，毫秒），需大于start_time |
is_archieve | Boolean | 否 | GraphQL参数 QUERY | 是否归档：true（仅查归档事件）、false（仅查未归档事件），默认查询全部 |
event_id | Int | 否 | GraphQL参数 QUERY | 事件ID，用于分类筛选（如1=移动侦测、2=人形侦测等，需与业务约定一致） |
tags | String | 否 | GraphQL参数 QUERY | 标签，多个标签以空格分隔（如"门口 花园"），精确匹配筛选 |
4. 请求体（POST 方式专用）
{
"query": "query {get_event_count(device:\"udid\",start_time:\"1583985297000\",end_time:\"1584011301000\",is_archieve:false,event_id:1,tags:\"门口\")}"
}
（二）响应说明
1. 响应状态码
| 状态码 | 徽章 | 说明 |
|---|---|---|
| 200 | 成功 | 请求成功，返回事件数量 |
| 400 | 参数错误 | 请求参数错误（如GraphQL语法错误、必填参数缺失、时间戳格式非法） |
| 401 | 授权失败 | 授权令牌无效或过期 |
| 500 | 服务器错误 | 服务器内部异常，请重试或联系技术支持 |
2. 响应数据结构
{
"data": {
"get_event_count": "Int" // 符合条件的事件数量，无匹配结果时返回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. 响应示例（成功）
成功响应
{
"data": {
"get_event_count": 761
}
}
无匹配结果响应
{
"data": {
"get_event_count": 0
}
}
参数错误响应（400）
{
"errors": [
{
"message": "Field 'start_time' of required type 'String!' is not provided",
"locations": [{"line": 1, "column": 25}]
}
]
}
三、查询事件列表接口（get_event_list）
用于查询云端事件列表，支持按设备、时间段、事件类型等条件筛选，可通过skip和limit控制分页。返回结果包含事件关键信息（如start_time_ts、thumbnail），为后续媒体操作提供必要参数。
说明：点击事件播放或者下载请参考流媒体模块的「回放接口（ask_media）」，需使用本接口返回的
device和start_time_ts参数。（一）请求说明
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默认值为50，最大值为100，超过最大值将按100返回
2. 请求头（Header）
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
Authorization | String | 是 | 授权令牌，格式：JWT {token} 或 Bearer {token} |
Content-Type | String | 是 | 固定值：application/json |
3. 请求参数
| 参数名 | 类型 | 必选 | 位置 | 说明 |
|---|---|---|---|---|
device | String | 是 | GraphQL参数 QUERY | 设备端的UDID/UID（与流媒体接口的udid一致） |
start_time | String | 是 | GraphQL参数 QUERY | 起始时间（时间戳格式，毫秒） |
end_time | String | 是 | GraphQL参数 QUERY | 结束时间（时间戳格式，毫秒） |
is_archieve | Boolean | 否 | GraphQL参数 QUERY | 是否归档：true（仅查归档事件）、false（仅查未归档事件），默认查询全部 |
event_id | Int | 否 | GraphQL参数 QUERY | 事件ID，用于分类筛选（如1=移动侦测、2=人形侦测等） |
tags | String | 否 | GraphQL参数 QUERY | 标签（如"门口"、"花园"），精确匹配 |
skip | Int | 否 | GraphQL参数 QUERY | 跳过的事件数量（分页用，如每次查20条，第2页填20，第3页填40），默认0 |
limit | Int | 否 | GraphQL参数 QUERY | 单次拉取事件数量上限，默认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}}"
}
（二）响应说明
1. 响应状态码
| 状态码 | 徽章 | 说明 |
|---|---|---|
| 200 | 成功 | 请求成功，返回事件列表 |
| 400 | 参数错误 | 请求参数错误（如GraphQL语法错误、必填参数缺失、limit超过最大值） |
| 401 | 授权失败 | 授权令牌无效或过期 |
| 500 | 服务器错误 | 服务器内部异常，请重试或联系技术支持 |
2. 响应数据结构
{
"data": {
"get_event_list": [
{
"pk": "String", // 事件唯一标识
"created": "String", // 事件创建时间（YYYY-MM-DD HH:MM:SS）
"updated": "String", // 事件修改时间（YYYY-MM-DD HH:MM:SS）
"device": "String", // 设备UDID
"account": "String", // 关联账户标识
"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", // 事件类型标识
"contract": "String", // 关联合约标识
"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. 响应示例（成功）
成功响应
{
"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"
}
]
}
}
无匹配结果响应
{
"data": {
"get_event_list": []
}
}
四、查询过期事件接口（get_archieved_event_list）
用于查询已经过期的云端事件列表，按设备分组返回事件集合，无需额外筛选参数。过期事件指expires时间早于当前时间的事件。
（一）请求说明
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）
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
Authorization | String | 是 | 授权令牌，格式：JWT {token} 或 Bearer {token} |
Content-Type | String | 是 | 固定值：application/json |
3. 请求参数
| 参数名 | 类型 | 必选 | 位置 | 说明 |
|---|---|---|---|---|
| - | - | - | - | 无额外请求参数，返回当前账户下所有设备的过期事件 |
4. 请求体（POST 方式专用）
{
"query": "query {get_archieved_event_list {device,events{pk,start_time,start_time_ts,expires,thumbnail}}}"
}
（二）响应说明
1. 响应状态码
| 状态码 | 徽章 | 说明 |
|---|---|---|
| 200 | 成功 | 请求成功，返回过期事件列表 |
| 400 | 参数错误 | 请求参数错误（如GraphQL语法错误） |
| 401 | 授权失败 | 授权令牌无效或过期 |
| 500 | 服务器错误 | 服务器内部异常，请重试或联系技术支持 |
2. 响应数据结构
{
"data": {
"get_archieved_event_list": [
{
"device": "String", // 设备UDID
"events": [ // 过期事件列表，结构同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. 响应示例（成功）
成功响应
{
"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"
}
]
}
]
}
}
五、修改事件标签接口（update_event）
用于修改指定事件的标签信息，需传递事件唯一标识pk和新的标签列表。标签修改为覆盖操作，将替换事件原有的所有标签。
（一）请求说明
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为简写，标准名称含event后缀）
2. 请求头（Header）
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
Authorization | String | 是 | 授权令牌，格式：JWT {token} 或 Bearer {token} |
Content-Type | String | 是 | 固定值：application/json |
3. 请求参数
| 参数名 | 类型 | 必选 | 位置 | 说明 |
|---|---|---|---|---|
pk | String | 是 | GraphQL参数 MUTATION | 事件唯一标识（通过get_event_list接口获取） |
tags | Array[String] | 是 | GraphQL参数 MUTATION | 标签列表（如["home","family"]），支持空数组 |
4. 请求体（POST 方式专用）
设置标签
{
"query": "mutation {update_event(pk:\"8dfaksjk2jkjkdjkjckjed3354\",tags:[\"home\",\"family\",\"门口\"])}"
}
清空标签
{
"query": "mutation {update_event(pk:\"8dfaksjk2jkjkdjkjckjed3354\",tags:[])}"
}
（二）响应说明
1. 响应状态码
| 状态码 | 徽章 | 说明 |
|---|---|---|
| 200 | 成功 | 请求成功，标签修改完成 |
| 400 | 参数错误 | 请求参数错误（如GraphQL语法错误、pk无效、标签格式非法） |
| 401 | 授权失败 | 授权令牌无效或过期 |
| 404 | 事件不存在 | 指定pk的事件不存在或已被删除 |
| 500 | 服务器错误 | 服务器内部异常，请重试或联系技术支持 |
2. 响应数据结构
{
"data": {
"update_event": "String" // 操作结果（Update event finish./失败原因）
}
}
（三）接口示例
1. 请求示例（curl）
设置标签
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/
清空标签
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. 响应示例（成功）
成功响应
{
"data": {
"update_event": "Update event finish."
}
}
六、删除事件接口（remove_event）
用于删除云端指定事件或特定时间段内的事件：pk不为空时删除指定事件（多个pk以空格分隔）；pk为空时删除指定时间段内的所有事件。
（一）请求说明
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）
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
Authorization | String | 是 | 授权令牌，格式：JWT {token} 或 Bearer {token} |
Content-Type | String | 是 | 固定值：application/json |
3. 请求参数
| 参数名 | 类型 | 必选 | 位置 | 说明 |
|---|---|---|---|---|
pk | String | 否 | GraphQL参数 MUTATION | 事件唯一标识，多个pk以空格分隔（如"pk1 pk2 pk3"） |
device | String | 是 | GraphQL参数 MUTATION | 设备UDID/UID（与流媒体接口的udid一致） |
start_time | String | 否 | GraphQL参数 MUTATION | 起始时间戳（毫秒），pk为空时必填 |
end_time | String | 否 | GraphQL参数 MUTATION | 结束时间戳（毫秒），pk为空时必填 |
4. 请求体（POST 方式专用）
删除指定事件
{
"query": "mutation {remove_event(pk:\"8dfaksjk2jkjkdjkjckjed3354 event789012\",device:\"KJKWJK\")}"
}
删除指定时间段事件
{
"query": "mutation {remove_event(device:\"KJKWJK\",start_time:\"1582398139849\",end_time:\"1582398239849\")}"
}
（二）响应说明
1. 响应状态码
| 状态码 | 徽章 | 说明 |
|---|---|---|
| 200 | 成功 | 请求成功，事件已删除 |
| 400 | 参数错误 | 请求参数错误（如pk和时间段都为空/都传、GraphQL语法错误） |
| 401 | 授权失败 | 授权令牌无效或过期 |
