Device API v3

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

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

API 概述

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

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

  • device 用于查询/设置设备的各种属性,包含 tags, alias;
  • tag 用于查询/设置/删除设备的标签;
  • alias 用于查询/设置/删除设备的别名。
    需要用到的关键信息还有 registration ID:

  • 设备的 registration_id 在客户端集成后获取,详情查看 AndroidiOSWinPhone 的 API 文档;

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

调用地址

https://device.jpush.cn

如果创建的极光应用分配的北京机房,并且 API 调用方的服务器也位于北京,则比较适合调用极光北京机房的 API,可以提升一定的响应速度。

通过极光 Web 控制台 “应用设置” -> "应用信息" 中可以看到应用所在机房。如果应用所在地为北京机房,同时会给出各 API 的调用地址。

北京机房 Push API 调用地址: https://bjapi.push.jiguang.cn/v3/device

详细对应关系见 “应用信息” 中 “服务器所在地” 后的信息。

查询设备的别名与标签

  1. GET /v3/devices/{registration_id}
  2. 获取当前设备的所有属性,包含 tags, alias,手机号码 mobile

Example Request

Request Header

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

Request Params

  • N/A

Example Response

Response Header

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=utf-8

Response Data

  1. {
  2. "tags": ["tag1", "tag2"],
  3. "alias": "alias1",
  4. "mobile": "13012345678"
  5. }
  • 找不到统计项就是 null,否则为统计项的值

设置设备的别名与标签

使用短信业务,请结合服务端 SMS_MESSAGE 字段

  1. POST /v3/devices/{registration_id}
  2. 更新当前设备的指定属性,当前支持 tags, alias,手机号码 mobile

Example Request

Request Header

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

Request Body

  1. {
  2. "tags":{
  3. "add": [
  4. "tag1",
  5. "tag2"
  6. ],
  7. "remove": [
  8. "tag3",
  9. "tag4"
  10. ]
  11. },
  12. "alias": "alias1",
  13. "mobile":"13012345678"
  14. }

Request Params

  • tags:支持 add, remove 或者空字符串。当 tags 参数为空字符串的时候,表示清空所有的 tags;add/remove 下是增加或删除指定的 tag;
    • 一次 add/remove tag 的上限均为 100 个,且总长度均不能超过 1000 字节。
    • 可以多次调用 API 设置,一个设备(registrationID)能设置的 tag 上限为 1000 个,应用 tag 总数没有限制 。
  • alias:更新设备的别名属性;当别名为空串时,删除指定设备的别名;
  • mobile:设备关联的手机号码;当 mobile 为空串时,表示清空设备关联的手机号码。

Example Response

Response Header

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=utf-8

Response Data

  • N/A

查询别名

获取指定 alias 下的设备,最多输出 10 个;

  1. GET /v3/aliases/{alias_value}

Example Request

Request Header

  1. GET /v3/aliases/{alias_value}?platform=android,ios
  2. Authorization: Basic (base64 auth string)
  3. Accept: application/json

Request Params

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

Example Response

Response Header

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=utf-8

Response Data

  1. {
  2. "registration_ids": ["registration_id1", "registration_id2"]
  3. }
  • 找不到统计项就是 null,否则为统计项的值。

删除别名

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

  1. DELETE /v3/aliases/{alias_value}

Example Request

Request Header

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

Request Params

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

Example Response

Response

  • N/A

查询标签列表

  1. GET /v3/tags/

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

Example Request

Request Header

  1. GET /v3/tags/
  2. Authorization: Basic (base64 auth string)
  3. Accept: application/json

Request Params

  • None

Example Response

Response Header

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=utf-8

Response Data

  1. {
  2. "tags": ["tag1", "tag2"]
  3. }
  • 找不到统计项就是 null,否则为统计项的值。

判断设备与标签绑定关系

  1. GET /v3/tags/{tag_value}/registration_ids/{registration_id}
  2. 查询某个设备是否在 tag 下。

Example Request

Request Header

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

Request Params

  • registration_id 必须,设备的 registration_id

Example Response

Response Header

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=utf-8

Response Data

  1. {
  2. "result": true/false
  3. }

更新标签

为一个标签添加或者删除设备。

  1. POST /v3/tags/{tag_value}

Example Request

Request Header

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

Request Body

  1. {
  2. "registration_ids":{
  3. "add": [
  4. "registration_id1",
  5. "registration_id2"
  6. ],
  7. "remove": [
  8. "registration_id3",
  9. "registration_id4"
  10. ]
  11. }
  12. }

Request Params

  • action 操作类型,有两个可选:"add","remove",标识本次请求是"添加"还是"删除"。
  • registration_ids 需要添加/删除的设备 registration_id。
  • add/remove 最多各支持 1000 个;

Example Response

Response Header

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=utf-8

Response Data

  • N/A

删除标签

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

  1. DELETE /v3/tags/{tag_value}

Example Request

Request Header

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

Request Params

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

Example Response

  • N/A

获取用户在线状态(VIP 专属接口)

如需要开通此接口,请联系:商务客服

Example Request

Request Header

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

Request Data

  1. {
  2. "registration_ids":["010b81b3582", "0207870f1b8", "0207870f9b8"]
  3. }

Request Params

  • registration_ids 需要在线状态的用户 registration_id, 最多支持查询 1000 个 registration_id;
  • 需要申请开通了这个业务的 Appkey 才可以调用此 API。

Example Response

Response Header

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=utf-8

Response Data

  1. {
  2. "010b81b3582": {
  3. "online": true
  4. },
  5. "0207870f1b8": {
  6. "online": false,
  7. "last_online_time": "2014-12-16 10:57:07"
  8. },
  9. "0207870f9b8": {
  10. "online": false
  11. }
  12. }

Response Params

  • online

    • true: 10 分钟之内在线;
    • false: 10 分钟之内不在线;
  • last_online_time

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

调用返回

业务返回码

Code描述详细解释HTTP Status Code
7000内部错误系统内部错误500
7001校验信息为空调用验证中的 Appkey 与 MasterSecret 为空401
7002请求参数非法需严格遵守文档参数类型与值说明400
7004校验失败检查调用验证中的 Appkey 与 MasterSecret 是否正确401
7008appkey 不存在检查工程填写的 Appkey 是否与官网应用一致400
7013部分请求参数非法需严格遵守文档参数类型与值说明400
7030系统繁忙,稍后重试系统繁忙,稍后重试503

参考

参考文档:Http-Status-Code