官方文档

极光推送设备管理 API 原文标题：极光推送_设备管理 API - 极光文档

发表时间：（页面未标注）采集时间：2026-10-09 10:49:15来源：docs.jiguang.cn原文语言：zh状态：完整

原始链接：https://docs.jiguang.cn/jpush/server/push/rest_api_v3_device

内容概要总结

极光推送服务端 REST API 的「设备管理（Device API）」文档，用于在服务器端查询、设置、更新、删除设备的 tag、alias 与手机号码 mobile。核心：设备以 registration_id（客户端集成后获取，服务端未提供获取接口，需客户端上传到开发者服务器）为键。接口包括 GET/POST /v3/devices/{registration_id}、GET/DELETE /v3/aliases/{alias_value}、POST /v3/aliases/{alias_value}、/v3/tags/ 系列，以及 VIP 的在线状态查询与测试设备管理。文档给出各接口的请求/返回 JSON 示例，并明确标签别名限制：单次 add/remove tag 上限 100 个、tag 命名 40 字节、单设备 tag 上限 1000 个、别名最多绑定 10 个设备。末尾附 7000–8004 业务错误码与对应 HTTP 状态码表。

原文内容（原文即中文）

极光文档

极光推送

REST API

设备管理 API

极光文档

极光推送

REST API

设备管理 API

标签别名 API

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

如果不是熟悉 tag，alias 的逻辑建议只使用客户端或服务端二者中的一种。

如果是两边同时使用，请确认自己应用可以处理好标签和别名的同步。

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

API 概述

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

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

device 用于查询/设置设备的各种属性，包含 tags, alias；

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

设备的 registration_id 在客户端集成后获取，详情查看 Android、 iOS、 HarmonyOS的 API 文档；

服务端未提供 API 去获取设备的 registrationID 值，需要开发者在客户端获取到 registration ID 后上传给开发者服务器保存。

调用地址

调用验证

详情参见 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"
}

设置设备的别名与标签

更新当前设备的指定属性，当前支持 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 个，每个 tag 命名长度限制为 40 字节，且总长度均不能超过 1000 字节。（判断长度需采用 UTF-8 编码）

可以多次调用 API 设置，一个设备（registrationID）能设置的 tag 上限为 1000 个，应用 tag 总数没有限制

有效的标签组成：字母（区分大小写）、数字、下划线、汉字、特殊字符 @!#$&*+=.|

alias：更新设备的别名属性；当别名为空串时，删除指定设备的别名；

注意：极光于 2020/03/10 对「别名设置」的上限进行限制，最多允许绑定 10 个设备，超过将报错 7015，如需更高上限，请联系商务，详情请阅读公告。

有效的别名组成：字母（区分大小写）、数字、下划线、汉字、特殊字符 @!#$&*+=.|

限制：alias 命名长度限制为 40 字节。（判断长度需采用 UTF-8 编码）

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

删除别名

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/
Authorization: Basic (base64 auth string)
Accept: application/json

GET /v3/tags/
 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"
]
}

{
 "tags": [
 "tag1",
 "tag2"
 ]
}

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

调用地址

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。

返回示例

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/
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 时，该字段不返回;

当 online 为 false，且该字段不返回时，则表示最后一次在线时间是两天之前；

对于无效的 regid 或者不属于该 appkey 的 regid，该 registration id 返回的结果为空;

测试设备管理（VIP）

支持新增/删除/查询/修改测试设备，确保测试模式下的每次推送仅触达测试用户；详细功能逻辑可参考文档：测试模式

新增测试设备

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

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=""

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

查询参数 registration_id 和 device_name 只能存在其一，不支持同时传递
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

//只支持修改名字
{
"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

极光推送 设备管理 API 原文标题：极光推送_设备管理 API - 极光文档

内容概要总结

原文内容（原文即中文）

标签别名 API

API 概述

调用地址

调用验证

查询设备的别名与标签

调用地址

请求示例

返回示例

设置设备的别名与标签

调用地址

请求示例

返回示例

查询别名

调用地址

请求示例

返回示例

删除别名

请求示例

返回示例

删除设备的别名

调用地址

请求示例

返回示例

查询标签列表

调用地址

请求示例

返回示例

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

调用地址

请求示例

返回示例

更新标签

调用地址

请求示例

返回示例

删除标签

调用地址

请求示例

返回示例

获取用户在线状态（VIP）

调用地址

请求示例

返回示例

测试设备管理（VIP）

新增测试设备

删除测试设备

获取测试设备列表

修改测试设备

调用返回

业务返回码

参考

极光推送设备管理 API 原文标题：极光推送_设备管理 API - 极光文档