标签别名 API

Device API 用于在服务器端查询、设置、更新、删除设备的 tag,alias 信息，使用时需要注意不要让服务端设置的标签又被客户端给覆盖了。

如果不是熟悉 tag，alias 的逻辑建议只使用客户端或服务端二者中的一种。
如果是两边同时使用，请确认自己应用可以处理好标签和别名的同步。

需要了解 tag,alias 的详细信息，请参考对应客户端平台的 API 说明。

web - tag,alias

使用限制

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

此代码块在浮窗中显示

请求参数

返回示例

成功返回

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

标签别名 API

使用限制

API 概述

调用地址

查询设备的别名与标签

调用地址

请求示例

返回示例

设置设备的别名与标签

调用地址

请求示例

返回示例

查询标签列表

调用地址

请求示例

请求示例

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

调用地址

请求示例

返回示例

更新标签

调用地址

请求示例

返回示例

删除标签

调用地址

请求示例

返回示例

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

查询别名

调用地址

请求示例

返回示例

删除别名

请求示例

返回示例

获取用户在线状态

调用地址

请求示例

返回示例

HTTP 状态码

业务返回码

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