标签别名 API

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

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

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

API 概述

Device API 用于在服务器端查询、设置、更新、删除设备的 tag, alias 信息。

包含了 device, tag, alias 三组 API。其中：

device 用于查询/设置设备的各种属性，包含 tags, alias；
tag 用于查询/设置/删除设备的标签；
alias 用于查询/设置/删除设备的别名。

需要用到的关键信息还有 registration ID：

设备的 registration_id 在客户端集成后获取，详情查看 Android、 iOS、 HarmonyOS的 API 文档；
服务端未提供 API 去获取设备的 registrationID 值，需要开发者在客户端获取到 registration ID 后上传给开发者服务器保存。

调用地址

https://device.jpush.cn

调用验证

详情参见 REST API 概述的鉴权方式说明。

查询设备的别名与标签

获取当前设备的所有属性，包含 tags, alias，手机号码 mobile。

调用地址

GET /v3/devices/{registration_id}

          GET /v3/devices/{registration_id}

此代码块在浮窗中显示

请求示例

请求报头

GET /v3/devices/{registration_id} Authorization: Basic (base64 auth string) Accept: application/json

          GET /v3/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。
使用短信业务，请结合服务端 SMS_MESSAGE 字段。

调用地址

POST /v3/devices/{registration_id}

          POST /v3/devices/{registration_id}

此代码块在浮窗中显示

请求示例

请求报头

POST /v3/devices/{registration_id} Authorization: Basic (base64 auth string) Accept: application/json

          POST /v3/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；
- 一次 add/remove tag 的上限均为 100 个，且总长度均不能超过 1000 字节。
- 可以多次调用 API 设置，一个设备（registrationID）能设置的 tag 上限为 1000 个，应用 tag 总数没有限制。
alias：更新设备的别名属性；当别名为空串时，删除指定设备的别名；
- 注意：极光于 2020/03/10 对「别名设置」的上限进行限制，最多允许绑定 10 个设备，超过将报错 7015，如需更高上限，请联系商务，详情请阅读公告。
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

此代码块在浮窗中显示

返回数据

查询别名

获取指定 alias 下的设备，最多输出 10 个，超过 10 个默认输出 10 个。
“设置设备的别名”接口调整过更高上限的客户，如需返回更高上限，请联系商务申请调整查询返回的上限数。

调用地址

GET /v3/aliases/{alias_value}

          GET /v3/aliases/{alias_value}

此代码块在浮窗中显示

请求示例

请求报头

GET /v3/aliases/{alias_value}?platform=android,ios,quickapp,hmos&new_format=true Authorization: Basic (base64 auth string) Accept: application/json

          GET /v3/aliases/{alias_value}?platform=android,ios,quickapp,hmos&new_format=true
  Authorization: Basic (base64 auth string)
  Accept: application/json

此代码块在浮窗中显示

请求参数

platform 可选参数，不填则默认为所有平台。
new_format 可选参数，为 true 表示按照新格式返回，不传递或者为 false 则表示按照旧格式返回。

返回示例

成功返回

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"
    ]
}

此代码块在浮窗中显示

新回数据

{ "data": [ { "registration_id": "160a3797c806b5dbb10", "platform": "ios", "last_online_date": "2022-07-18" }, { "registration_id": "120a3797c806b5dbb10", "platform": "android", "last_online_date": "2022-01-18" }, { "registration_id": "150a3797c806b5drf05", "platform": "hmos", "last_online_date": "2024-04-25" } ] }

          {
    "data": [
        {
            "registration_id": "160a3797c806b5dbb10",
            "platform": "ios",
            "last_online_date": "2022-07-18"
        },
        {
            "registration_id": "120a3797c806b5dbb10",
            "platform": "android",
            "last_online_date": "2022-01-18"
        },
        {
            "registration_id": "150a3797c806b5drf05",
            "platform": "hmos",
            "last_online_date": "2024-04-25"
        } 
    ]
}

此代码块在浮窗中显示

找不到统计项就是 null，否则为统计项的值。

删除别名

删除一个别名，以及该别名与设备的绑定关系。

DELETE /v3/aliases/{alias_value}

          DELETE /v3/aliases/{alias_value}

此代码块在浮窗中显示

请求示例

请求报头

DELETE /v3/aliases/{alias_value}?platform=android,ios,quickapp,hmos Authorization: Basic (base64 auth string) Accept: application/json

          DELETE /v3/aliases/{alias_value}?platform=android,ios,quickapp,hmos
  Authorization: Basic (base64 auth string)
  Accept: application/json

此代码块在浮窗中显示

请求参数

platform 可选参数，不填则默认为所有平台。

返回示例

删除设备的别名

批量解绑设备与别名之间的关系。

调用地址

POST /v3/aliases/{alias_value}

          POST /v3/aliases/{alias_value}

此代码块在浮窗中显示

请求示例

请求报头

POST /v3/aliases/{alias_value} Authorization: Basic (base64 auth string) Accept: application/json

          POST /v3/aliases/{alias_value}
  Authorization: Basic (base64 auth string)
  Accept: application/json

此代码块在浮窗中显示

请求数据

{ "registration_ids":{"remove": ["registration_id1", "registration_id2"]} }

          {
  "registration_ids":{"remove": ["registration_id1", "registration_id2"]}
}

此代码块在浮窗中显示

请求参数

registration_ids 必填参数，需要和该alias解除绑定的的registration_id值，最多支持1000个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

此代码块在浮窗中显示

失败返回

HTTP/1.1 400 BAD REQUEST Content-Type: application/json; charset=utf-8

          HTTP/1.1 400 BAD REQUEST
  Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

{ "error":{"code":7013,"illegal_rids":["010922a358e"]} }

          {
    "error":{"code":7013,"illegal_rids":["010922a358e"]}
}

此代码块在浮窗中显示

查询标签列表

获取当前应用的所有标签列表，每个平台最多返回 100 个。

调用地址

GET /v3/tags/

          GET /v3/tags/

此代码块在浮窗中显示

请求示例

请求报头

GET /v3/tags/ Authorization: Basic (base64 auth string) Accept: application/json

          GET /v3/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 /v3/tags/{tag_value}/registration_ids/{registration_id}

          GET /v3/tags/{tag_value}/registration_ids/{registration_id}

此代码块在浮窗中显示

请求示例

请求报头

GET /v3/tags/{tag_value}/registration_ids/090c1f59f89 Authorization: Basic (base64 auth string) Accept: application/json

          GET /v3/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 /v3/tags/{tag_value}

          POST /v3/tags/{tag_value}

此代码块在浮窗中显示

请求示例

请求报头

POST /v3/tags/{tag_value} Authorization: Basic (base64 auth string) Accept: application/json

          POST /v3/tags/{tag_value}
  Authorization: Basic (base64 auth string)
  Accept: application/json

此代码块在浮窗中显示

请求数据

{ "registration_ids":{ "add": [ "registration_id1", "registration_id2" ], "remove": [ "registration_id3", "registration_id4" ] } }

          {
        "registration_ids":{
            "add": [
                "registration_id1",
                "registration_id2"
            ],
            "remove": [
                "registration_id3",
                "registration_id4"
            ]
        }
}

此代码块在浮窗中显示

请求参数

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

此代码块在浮窗中显示

失败返回

{ "error": { "code": 7016, "illegal_rids": [ "160a3797c8824c6b905" ] } }

          {
    "error": {
        "code": 7016,
        "illegal_rids": [
            "160a3797c8824c6b905"
        ]
    }
}

此代码块在浮窗中显示

删除标签

删除一个标签，以及标签与设备之间的关联关系。

调用地址

DELETE /v3/tags/{tag_value}

          DELETE /v3/tags/{tag_value}

此代码块在浮窗中显示

请求示例

请求报头

DELETE /v3/tags/{tag_value}?platform=android,ios,quickapp,hmos Authorization: Basic (base64 auth string) Accept: application/json

          DELETE /v3/tags/{tag_value}?platform=android,ios,quickapp,hmos
  Authorization: Basic (base64 auth string)
  Accept: application/json

此代码块在浮窗中显示

请求参数

platform 可选参数，不填则默认为所有平台。

返回示例

获取用户在线状态（VIP）

查询用户是否在线，如需要开通此接口，请联系：商务客服。

调用地址

POST /v3/devices/status/

          POST /v3/devices/status/

此代码块在浮窗中显示

请求示例

请求报头

POST /v3/devices/status/ Authorization: Basic (base64 auth string) Accept: application/json

          POST /v3/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

此代码块在浮窗中显示

返回数据

{ "010b81b3582": { "online": true }, "0207870f1b8": { "online": false, "last_online_time": "2014-12-16 10:57:07" }, "0207870f9b8": { "online": false } }

          {
     "010b81b3582": {
         "online": true
     },
     "0207870f1b8": {
          "online": false,
          "last_online_time": "2014-12-16 10:57:07"
     },
     "0207870f9b8": {
          "online": false
    }
}

此代码块在浮窗中显示

返回参数

online
- true: 10 分钟之内在线；
- false: 10 分钟之内不在线；
last_online_time
- 当 online 为 true 时，该字段不返回;
- 当 online 为 false，且该字段不返回时，则表示最后一次在线时间是两天之前；
对于无效的 regid 或者不属于该 appkey 的 regid，该 registration id 返回的结果为空;

测试设备管理（VIP）

支持新增/删除/查询/修改测试设备，确保测试模式下的每次推送仅触达测试用户；详细功能逻辑可参考文档：测试模式
如需要开通此接口，请联系：商务客服。

新增测试设备

接口路径：/v3/test/model/add
请求方法：POST
请求参数：

{ "device_name":string, //开发者自定义的设备名称 "registration_id":string, //极光生成的设备唯一标识 }

          {
    "device_name":string,  //开发者自定义的设备名称
    "registration_id":string, //极光生成的设备唯一标识
}

此代码块在浮窗中显示

返回参数

// 正常返回无（未出现错误不返回参数） // 错误返回 { "error": { "code":int, "message":string } }

          // 正常返回
无（未出现错误不返回参数）

// 错误返回
{
    "error": {
        "code":int,
        "message":string
    }
}

此代码块在浮窗中显示

删除测试设备

接口路径：/v3/test/model/delete/{registration_id}
请求方法：DELETE
请求参数：

registration_id：极光生成的设备唯一标识

          registration_id：极光生成的设备唯一标识

此代码块在浮窗中显示

返回参数

// 正常返回无（未出现错误不返回参数） // 错误返回 { "error": { "code":int, "message":string } }

          // 正常返回
无（未出现错误不返回参数）

// 错误返回
{
    "error": {
        "code":int,
        "message":string
    }
}

此代码块在浮窗中显示

获取测试设备列表

接口路径：/v3/test/model/list?page=1&page_size=10&device_name=""&registration_id=""
请求方法：GET
请求参数：

registration_id：精确查询，string类型，极光生成的设备唯一标识 device_name：模糊查询，string类型，开发者自定义的设备名称 page：查询页数，int类型 page_size：每页记录条数，int类型说明： 1. 查询参数 registration_id 和 device_name 只能存在其一，不支持同时传递 2. page 和 page_size不传默认返回所有数据（默认为1和200），二者要么都传，要么都不传

          registration_id：精确查询，string类型，极光生成的设备唯一标识
device_name：模糊查询，string类型，开发者自定义的设备名称
page：查询页数，int类型
page_size：每页记录条数，int类型

说明：
1. 查询参数 registration_id 和 device_name 只能存在其一，不支持同时传递
2. page 和 page_size不传默认返回所有数据（默认为1和200），二者要么都传，要么都不传

此代码块在浮窗中显示

返回参数

正常返回 { "total":int "detail":[{ "device_name":string, //设备名称 "device_model":string, //设备型号 "registration_id":string, //极光生成的设备唯一标识 "registration_time":string, //设备注册时间，格式：2025-01-01 00:00:00 "create_time":string //信息添加时间，格式：2025-01-01 00:00:00 }] "page":int "page_size":int } 错误返回 { "error": { "code":int, "message":string } }

          正常返回
{
    "total":int
    "detail":[{
        "device_name":string,  //设备名称
        "device_model":string,  //设备型号
        "registration_id":string,  //极光生成的设备唯一标识
        "registration_time":string,  //设备注册时间，格式：2025-01-01 00:00:00 
        "create_time":string  //信息添加时间，格式：2025-01-01 00:00:00 
    }]
    "page":int
    "page_size":int
}

错误返回
{
    "error": {
        "code":int,
        "message":string
    }
}

此代码块在浮窗中显示

修改测试设备

接口路径：/v3/test/model/update
请求方法：PUT
请求参数：

//只支持修改名字 { "registration_id"：string //极光生成的设备唯一标识 "device_name"：string //开发者自定义的设备名称 }

          //只支持修改名字
{
    "registration_id"：string //极光生成的设备唯一标识
    "device_name"：string //开发者自定义的设备名称
}

此代码块在浮窗中显示

返回参数

// 正常返回无（未出现错误不返回参数） // 错误返回 { "error": { "code":int, "message":string } }

          // 正常返回
无（未出现错误不返回参数）

// 错误返回
{
    "error": {
        "code":int,
        "message":string
    }
}

此代码块在浮窗中显示

调用返回

业务返回码

Code	描述	详细解释	HTTP Status Code
7000	内部错误	系统内部错误	500
7001	校验信息为空	调用验证中的 Appkey 与 MasterSecret 为空	401
7002	请求参数非法	1. 请检查是否有设备满足 audience 的目标条件； 2. 推送目标超过 255 天不活跃，被排除在推送目标之外。	400
7004	校验失败	检查调用验证中的 Appkey 与 MasterSecret 是否正确	401
7008	appkey 不存在	检查工程填写的 Appkey 是否与官网应用一致	400
7010	接口请求地址/路径错误	检查接口请求地址	404
7013	部分请求参数非法	需严格遵守文档参数类型与值说明	400
7014	请求非法	检测到tag/alias值短时间内累计操作用户量过大，超过合理的使用范围，需要检查业务逻辑。	400
7015	别名绑定设备数超过限制	极光于 2020/03/10 对「别名设置」的上限进行限制，最多允许绑定 10 个设备，如需更高上限，请联系商务。	400
7016	设备绑定标签数超过限制	一个设备最多允许绑定 1000 个标签	400
7030	系统繁忙，稍后重试	系统繁忙，稍后重试	400
8002	参数错误	测试设备管理相关API接口请求参数出错，可能原因： registration_id非法、device_name长度非法、registration_id 或者 device_name 已经存在、device_name 或者registration_id参数缺失等	400
8003	无权限	测试设备管理相关API接口仅支持VIP客户使用，可联系商务咨询	403
8004	设备超限	测试设备最多支持添加200个	400

参考

参考文档：Http-Status-Code