标签别名 API
最新更新:2023-11-17
标签别名 API
Device API 用于在服务器端查询、设置、更新、删除设备的 tag,alias 信息,使用时需要注意不要让服务端设置的标签又被客户端给覆盖了。
- 如果不是熟悉 tag,alias 的逻辑建议只使用客户端或服务端二者中的一种。
- 如果是两边同时使用,请确认自己应用可以处理好标签和别名的同步。
需要了解 tag,alias 的详细信息,请参考对应客户端平台的 API 说明。
使用限制
- alias和设备只支持1对1的关系,不支持1对多或者多对1的关系
- 单个appkey下最大alias数为10万个
- 单个appkey下最大的Tag数为1万个
- 单个Tag下最大设备数为10万个
- 单个设备最多只能设置100个Tag
API 概述
Device API 用于在服务器端查询、设置、更新、删除设备的 tag,alias 信息。
包含了 device, tag, alias 三组 API。其中:
- device 用于查询 / 设置设备的各种属性,包含 tags, alias;
- tag 用于查询 / 设置 / 删除设备的标签;
- alias 用于查询 / 设置 / 删除设备的别名。
需要用到的关键信息还有 registration ID:
设备的 registration_id 在客户端集成后获取,详情查看 Web 的 API 文档;
服务端未提供 API 去获取设备的 registrationID 值,需要开发者在客户端获取到 registration ID 后上传给开发者服务器保存。
调用地址
API URL: https://webpush.api.engagelab.cc/v4/devices
查询设备的别名与标签
- 获取当前设备的所有属性,包含 tags, alias,手机号码 mobile。
调用地址
GET /v4/devices/{registration_id}
GET /v4/devices/{registration_id}
此代码块在浮窗中显示
请求示例
请求报头
GET /v4/devices/{registration_id}
Authorization: Basic (base64 auth string)
Accept: application/json
GET /v4/devices/{registration_id}
Authorization: Basic (base64 auth string)
Accept: application/json
此代码块在浮窗中显示
请求参数
- N/A
返回示例
成功返回
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
此代码块在浮窗中显示
返回数据
{"tags": ["tag1", "tag2"],
"alias": "alias1",
"mobile": "13012345678"
}
{"tags": ["tag1", "tag2"],
"alias": "alias1",
"mobile": "13012345678"
}
此代码块在浮窗中显示
- 找不到统计项就是 null, 否则为统计项的值
设置设备的别名与标签
- 更新当前设备的指定属性,当前支持 tags, alias,手机号码 mobile。
调用地址
POST /v4/devices/{registration_id}
POST /v4/devices/{registration_id}
此代码块在浮窗中显示
请求示例
请求报头
POST /v4/devices/{registration_id}
Authorization: Basic (base64 auth string)
Accept: application/json
POST /v4/devices/{registration_id}
Authorization: Basic (base64 auth string)
Accept: application/json
此代码块在浮窗中显示
请求数据
{
"tags": {
"add": [
"tag1",
"tag2"
],
"remove": [
"tag3",
"tag4"
]
},
"alias": "alias1",
"mobile": "13012345678"
}
{
"tags": {
"add": [
"tag1",
"tag2"
],
"remove": [
"tag3",
"tag4"
]
},
"alias": "alias1",
"mobile": "13012345678"
}
此代码块在浮窗中显示
请求参数
- tags: 支持 add, remove 或者空字符串。当 tags 参数为空字符串的时候,表示清空所有的 tags;add/remove 下是增加或删除指定的 tag;
- alias: 更新设备的别名属性;当别名为空串时,删除指定设备的别名;
- mobile:设备关联的手机号码;当 mobile 为空串时,表示清空设备关联的手机号码。
返回示例
成功返回
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
此代码块在浮窗中显示
返回数据
success
success
此代码块在浮窗中显示
失败返回
{"code":2xxxx, "message":"unknow err"}
{"code":2xxxx, "message":"unknow err"}
此代码块在浮窗中显示
查询标签列表
- 获取当前应用的所有标签列表。
调用地址
GET /v4/tags/
GET /v4/tags/
此代码块在浮窗中显示
请求示例
请求报头
GET /v4/tags/
Authorization: Basic (base64 auth string)
Accept: application/json
GET /v4/tags/
Authorization: Basic (base64 auth string)
Accept: application/json
此代码块在浮窗中显示
请求参数
- None
请求示例
成功返回
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
此代码块在浮窗中显示
返回数据
{
"tags": [
"tag1",
"tag2"
]
}
{
"tags": [
"tag1",
"tag2"
]
}
此代码块在浮窗中显示
- 找不到统计项就是 null,否则为统计项的值。
查询设备与标签的绑定关系
- 查询某个设备是否在 tag 下。
调用地址
GET /v4/tags/{tag_value}/registration_ids/{registration_id}
GET /v4/tags/{tag_value}/registration_ids/{registration_id}
此代码块在浮窗中显示
请求示例
请求报头
GET /v4/tags/{tag_value}/registration_ids/090c1f59f89
Authorization: Basic (base64 auth string)
Accept: application/json
GET /v4/tags/{tag_value}/registration_ids/090c1f59f89
Authorization: Basic (base64 auth string)
Accept: application/json
此代码块在浮窗中显示
请求参数
- registration_id 必须,设备的 registration_id
返回示例
成功返回
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
此代码块在浮窗中显示
返回数据
{"result": true/false}
{"result": true/false}
此代码块在浮窗中显示
更新标签
- 为一个标签添加或者删除设备。
调用地址
POST /v4/tags/{tag_value}
POST /v4/tags/{tag_value}
此代码块在浮窗中显示
请求示例
请求报头
POST /v4/tags/{tag_value}
Authorization: Basic (base64 auth string)
Accept: application/json
POST /v4/tags/{tag_value}
Authorization: Basic (base64 auth string)
Accept: application/json
此代码块在浮窗中显示
请求数据
{
"registration_ids":{
"add": [
"registration_id1",
"registration_id2"
],
"remove": [
"registration_id1",
"registration_id2"
]
}
}
{
"registration_ids":{
"add": [
"registration_id1",
"registration_id2"
],
"remove": [
"registration_id1",
"registration_id2"
]
}
}
此代码块在浮窗中显示
请求参数
- action 操作类型,有两个可选:"add","remove",标识本次请求是 "添加" 还是 "删除";
- registration_ids 需要添加 / 删除的设备 registration_id;
- add/remove 最多各支持 1000 个.
返回示例
成功返回
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
此代码块在浮窗中显示
返回数据
success
success
此代码块在浮窗中显示
失败返回
{"code":2xxxx, "message":"unknow err"}
{"code":2xxxx, "message":"unknow err"}
此代码块在浮窗中显示
删除标签
删除一个标签,以及标签与设备之间的关联关系。
调用地址
DELETE /v4/tags/{tag_value}
DELETE /v4/tags/{tag_value}
此代码块在浮窗中显示
请求示例
请求报头
DELETE /v4/tags/{tag_value}?platform=web
Authorization: Basic (base64 auth string)
Accept: application/json
DELETE /v4/tags/{tag_value}?platform=web
Authorization: Basic (base64 auth string)
Accept: application/json
此代码块在浮窗中显示
请求参数
- platform 可选参数,不填则默认为所有平台。
返回示例
成功返回
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-
此代码块在浮窗中显示
返回数据
success
失败返回
{"code":2xxxx, "message":"unknow err"}
{"code":2xxxx, "message":"unknow err"}
此代码块在浮窗中显示
查询别名 (与设备的绑定关系)
GET /v4/aliases/{alias_value}
获取指定 alias 下的设备,最多输出 10 个;
GET /v4/aliases/{alias_value}
获取指定 alias 下的设备,最多输出 10 个;
此代码块在浮窗中显示
查询别名
- 获取指定 alias 下的设备,最多输出 10 个,超过 10 个默认输出 10 个。
调用地址
GET /v4/aliases/{alias_value}
GET /v4/aliases/{alias_value}
此代码块在浮窗中显示
请求示例
请求报头
GET /v4/aliases/{alias_value}?platform=web
Authorization: Basic (base64 auth string)
Accept: application/json
GET /v4/aliases/{alias_value}?platform=web
Authorization: Basic (base64 auth string)
Accept: application/json
此代码块在浮窗中显示
请求参数
- platform 可选参数,不填则默认为所有平台。
返回示例
成功返回
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
此代码块在浮窗中显示
返回数据
{
"registration_ids": [
"registration_id1",
"registration_id2"
]
}
{
"registration_ids": [
"registration_id1",
"registration_id2"
]
}
此代码块在浮窗中显示
- 找不到统计项就是 null,否则为统计项的值。
删除别名
删除一个别名,以及该别名与设备的绑定关系。
DELETE /v4/aliases/{alias_value}
DELETE /v4/aliases/{alias_value}
此代码块在浮窗中显示
请求示例
请求报头
DELETE /v4/aliases/{alias_value}?platform=web
Authorization: Basic (base64 auth string)
Accept: application/json
DELETE /v4/aliases/{alias_value}?platform=web
Authorization: Basic (base64 auth string)
Accept: application/json
此代码块在浮窗中显示
请求参数
- platform 可选参数,不填则默认为所有平台。
返回示例
- 成功
success
success
此代码块在浮窗中显示
- 失败
{"code":2xxxx, "message":"unknow err"}
{"code":2xxxx, "message":"unknow err"}
此代码块在浮窗中显示
获取用户在线状态
调用地址
POST /v4/devices/status/
POST /v4/devices/status/
此代码块在浮窗中显示
请求示例
请求报头
POST /v4/devices/status/
Authorization: Basic (base64 auth string)
Accept: application/json
POST /v4/devices/status/
Authorization: Basic (base64 auth string)
Accept: application/json
此代码块在浮窗中显示
请求数据
{
"registration_ids": [
"010b81b3582",
"0207870f1b8",
"0207870f9b8"
]
}
{
"registration_ids": [
"010b81b3582",
"0207870f1b8",
"0207870f9b8"
]
}
此代码块在浮窗中显示
请求参数
- registration_ids 需要在线状态的用户 registration_id, 最多支持查询 1000 个 registration_id。
- 需要申请开通了这个业务的 Appkey 才可以调用此 API。
返回示例
成功返回
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
此代码块在浮窗中显示
返回数据
[
{
"regid": "010b81b3582",
"online": true
},
{
"regid": "0207870f1b8",
"online": false,
"last_online_time": "2014-12-16 10:57:07"
},
{
"regid": "0207870f9b8",
"online": false
}
]
[
{
"regid": "010b81b3582",
"online": true
},
{
"regid": "0207870f1b8",
"online": false,
"last_online_time": "2014-12-16 10:57:07"
},
{
"regid": "0207870f9b8",
"online": false
}
]
此代码块在浮窗中显示
返回数据
- online
- true: 10 分钟之内在线;
- false: 10 分钟之内不在线;
- last_online_time
- 当 online 为 true 时,该字段不返回;
- 当 online 为 false,且该字段不返回时,则表示最后一次在线时间是两天之前;
- 对于无效的 regid 或者不属于该 appkey 的 regid,会校验失败。
HTTP 状态码
参考文档:Http-Status-Code
业务返回码
Code | 描述 | 详细解释 | HTTP Status Code |
---|---|---|---|
21004 | 鉴权错误 | appkey非法 | 401 |
27000 | 系统内存错误 | 请重试 | 500 |
27001 | 参数错误 | 校验信息为空 | 401 |
27002 | 参数错误 | 参数非法 | 400 |
27004 | 参数错误 | 校验失败 | 401 |
27005 | 参数错误 | regisID 格式非法 | 400 |