标签别名 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"

此代码块在浮窗中显示

请求参数

返回示例

成功的响应将返回一个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

此代码块在浮窗中显示

请求参数

返回示例

成功返回

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

标签别名 API

限制条件与规则 for TAG使用

限制条件与规则 for alias使用

API 概述

调用地址

查询AppKey下的tag数量

调用地址

请求示例

返回示例

查询设备的别名与标签

调用地址

请求示例

返回示例

设置设备的别名与标签

调用地址

请求示例

返回示例

查询标签列表

调用地址

请求示例

请求示例

查询设备与标签的绑定关系

调用地址

请求示例

返回示例

更新标签

调用地址

请求示例

返回示例

删除标签

调用地址

请求示例

返回示例

查询别名 （与设备的绑定关系）

调用地址

请求示例

返回示例

删除别名

请求示例

返回示例

获取用户在线状态

调用地址

请求示例

返回示例

HTTP 状态码

业务返回码

查询别名（与设备的绑定关系）