标签别名 API
最新更新:2023-11-17
标签别名 API
Device API 用于在服务器端查询、设置、更新、删除设备的 tag,alias 信息,使用时需要注意不要让服务端设置的标签又被客户端给覆盖了。
- 如果不是熟悉 tag,alias 的逻辑建议只使用客户端或服务端二者中的一种。
- 如果是两边同时使用,请确认自己应用可以处理好标签和别名的同步。
需要了解 tag,alias 的详细信息,请参考对应客户端平台的 API 说明。
限制条件与规则 for TAG使用
- TAG的数量限制:在单个appkey下,你可以最多创建10万个Tag。
- TAG的长度限制:每个Tag的最大长度是40字节。你可以使用的有效字符包括字母(需要注意大小写)、数字、下划线以及汉字。
- 设备绑定TAG的数量限制:每个设备最多可以绑定100个Tag。
- 设备数量限制:在单个Tag下,你可以最多添加10万个设备。
如果您需要增加这些限制的上限,请联系我们:Sales@engagelab.com
限制条件与规则 for alias使用
- 设备与alias的映射关系:一个alias只能对应一个设备,不能对应多个设备。同样,每个设备在appkey范围内也只能映射到一个alias,不能映射到多个alias。
- alias的数量限制:在单个appkey下,你可以创建最多10万个alias。
- alias的长度限制:每个alias的最大长度是40字节。你可以使用的有效字符包括字母(需要注意大小写)、数字、下划线以及汉字。
如果您需要增加这些限制的上限,请联系我们:Sales@engagelab.com
API 概述
Device API 用于在服务器端查询、设置、更新、删除设备的 tag,alias 信息。
包含了 device, tag, alias 三组 API。其中:
- device 用于查询 / 设置设备的各种属性,包含 tags, alias;
- tag 用于查询 / 设置 / 删除设备的标签;
- alias 用于查询 / 设置 / 删除设备的别名。
需要用到的关键信息还有 registration ID:
设备的 registration_id 在客户端集成后获取,详情查看 Android、iOS 的 API 文档;
服务端未提供 API 去获取设备的 registrationID 值,需要开发者在客户端获取到 registration ID 后上传给开发者服务器保存。
调用地址
API URL: https://push.api.engagelab.cc/v4/devices
查询AppKey下的tag数量
调用地址
GET /v4/tags_count
GET /v4/tags_count
此代码块在浮窗中显示
请求示例
请求报头
GET /v4/tags_count
Authorization: Basic (base64 auth string)
Accept: application/json
GET /v4/tags_count
Authorization: Basic (base64 auth string)
Accept: application/json
此代码块在浮窗中显示
请求示例
curl -X GET http://127.0.0.1/v4/tags_count/ -u "appKey:appSecret"
curl -X GET http://127.0.0.1/v4/tags_count/ -u "appKey:appSecret"
此代码块在浮窗中显示
请求参数
- N/A
返回示例
- 成功的响应将返回一个JSON对象,其中包含一个tagsCount字段,这是一个键值对的集合,键是tag名称,值是该tag下的数量。
- 如果请求失败,将返回一个包含错误信息的JSON对象。code字段表示错误码,message字段表示错误信息。
成功返回
{
"tagsCount": {
"tag1": 0,
"tag2": 1,
"tag3": 2
}
}
{
"tagsCount": {
"tag1": 0,
"tag2": 1,
"tag3": 2
}
}
此代码块在浮窗中显示
失败返回
{
"error": {
"code": 21008,
"message": "app_key is not a 24 size string or does not exist"
}
}
{
"error": {
"code": 21008,
"message": "app_key is not a 24 size string or does not exist"
}
}
此代码块在浮窗中显示
查询设备的别名与标签
- 获取当前设备的所有属性,包含 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=android,ios
Authorization: Basic (base64 auth string)
Accept: application/json
DELETE /v4/tags/{tag_value}?platform=android,ios
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 下的设备。;
GET /v4/aliases/{alias_value}
获取指定 alias 下的设备。;
此代码块在浮窗中显示
调用地址
GET /v4/aliases/{alias_value}
GET /v4/aliases/{alias_value}
此代码块在浮窗中显示
请求示例
请求报头
GET /v4/aliases/{alias_value}?platform=android,ios
Authorization: Basic (base64 auth string)
Accept: application/json
GET /v4/aliases/{alias_value}?platform=android,ios
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_ids": [
"registration_id1"
]
}
此代码块在浮窗中显示
- 找不到统计项就是 null,否则为统计项的值。
删除别名
删除一个别名,以及该别名与设备的绑定关系。
DELETE /v4/aliases/{alias_value}
DELETE /v4/aliases/{alias_value}
此代码块在浮窗中显示
请求示例
请求报头
DELETE /v4/aliases/{alias_value}?platform=android,ios
Authorization: Basic (base64 auth string)
Accept: application/json
DELETE /v4/aliases/{alias_value}?platform=android,ios
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 |
21008 | 参数错误 | app_key不是24位字符串或者不存在 | 400 |
27010 | 参数错误 | alias已经绑定另外一个regid | 400 |