高级功能 API

获取推送唯一标识(cid)

功能说明

cid 是用于防止 api 调用端重试造成服务端的重复推送而定义的一个推送参数。用户使用一个 cid 推送后，再次使用相同的 cid 进行推送，则会直接返回第一次成功推送的结果，不会再次进行推送。
cid 的有效期为 1 天。cid 的格式为：{appkey}-{uuid}
在使用 cid 之前，必须通过接口获取你的 cid 池。获取时 type=push 或者不传递 type 值。

调用地址

GET https://api.jpush.cn/v3/push/cid[?count=n[&type=xx]]

调用验证

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

请求示例

请求报头

curl --insecure -X GET -v https://api.jpush.cn/v3/push/cid?count=3 -H "Content-Type: application/json" -u "2743204aad6fe2572aa2d8de:e674a3d0fd42a53b9a58121c"

          curl --insecure -X GET -v https://api.jpush.cn/v3/push/cid?count=3 -H "Content-Type: application/json" -u "2743204aad6fe2572aa2d8de:e674a3d0fd42a53b9a58121c"

此代码块在浮窗中显示

GET /v3/push/cid?count=3 Authorization: Basic (base64 auth string) Content-Type: text/plain Accept: application/json

          GET /v3/push/cid?count=3
Authorization: Basic (base64 auth string)
Content-Type: text/plain
Accept: application/json

此代码块在浮窗中显示

请求参数

count 可选参数。数值类型，不传则默认为 1。范围为 [1, 1000] type 可选参数。CID 类型。取值：push（默认），schedule

          count
    可选参数。数值类型，不传则默认为 1。范围为 [1, 1000]
type
    可选参数。CID 类型。取值：push（默认），schedule

此代码块在浮窗中显示

返回示例

成功返回

HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 Response Data { "cidlist": [ "8103a4c628a0b98994ec1949-128eeb45-471c-49f3-b442-a05c20c9ed56", "8103a4c628a0b98994ec1949-6e44d7f1-89f5-48a8-bec4-e359c15b13e5", "8103a4c628a0b98994ec1949-47e0a960-ce67-4e71-94ce-b4b9e8813af0" ] }

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

 Response Data

{
    "cidlist": [
        "8103a4c628a0b98994ec1949-128eeb45-471c-49f3-b442-a05c20c9ed56",
        "8103a4c628a0b98994ec1949-6e44d7f1-89f5-48a8-bec4-e359c15b13e5",
        "8103a4c628a0b98994ec1949-47e0a960-ce67-4e71-94ce-b4b9e8813af0"
    ]
}

此代码块在浮窗中显示

返回参数

cidlist cid 列表

          cidlist
    cid 列表

此代码块在浮窗中显示

推送校验 API

功能说明

该 API 只用于验证推送调用是否能够成功，与推送 API 的区别在于：不向用户发送任何消息。
其他字段说明：同推送 API。

调用地址

POST https://api.jpush.cn/v3/push/validate

调用验证

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

请求示例

curl --insecure -X POST -v https://api.jpush.cn/v3/push/validate -H "Content-Type: application/json" -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1" -d '{ "platform": "all", "audience": "all", "notification": { "alert": "Hi,JPush !", "android": { "extras": { "android-key1": "android-value1" } }, "ios": { "sound": "sound.caf", "badge": "+1", "extras": { "ios-key1": "ios-value1" } } } }' > POST /v3/push HTTP/1.1 > Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==

          curl --insecure -X POST -v https://api.jpush.cn/v3/push/validate -H "Content-Type: application/json" -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1" -d '{
    "platform": "all",
    "audience": "all",
    "notification": {
        "alert": "Hi,JPush !",
        "android": {
            "extras": {
                "android-key1": "android-value1"
            }
        },
        "ios": {
            "sound": "sound.caf",
            "badge": "+1",
            "extras": {
                "ios-key1": "ios-value1"
            }
        }
    }
}'

> POST /v3/push HTTP/1.1
> Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==

此代码块在浮窗中显示

返回示例

< HTTP/1.1 200 OK < Content-Type: application/json { "sendno": "0", "msg_id": "18100287008546343" }

          < HTTP/1.1 200 OK
< Content-Type: application/json
{
    "sendno": "0",
    "msg_id": "18100287008546343"
}

此代码块在浮窗中显示

推送撤销 API

功能说明

撤销操作首先会从服务端尝试撤销（Android 消息，排队中 / 发送中状态可以服务端撤销；iOS 消息，排队中状态可以服务端撤销）；其次，针对 Push SDK（JPush Android SDK v3.5.0 及以上和 JPush iOS SDK v3.2.8 及以上），会尝试从设备端撤销已展示但未被点击的消息。

调用地址

DELETE https://api.jpush.cn/v3/push/{msgid}

调用验证

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

请求示例

DELETE /v3/push/{msgid} Authorization: Basic (base64 auth string) Content-Type: text/plain Accept: application/json

          DELETE /v3/push/{msgid}
    Authorization: Basic (base64 auth string)
    Content-Type: text/plain
    Accept: application/json

此代码块在浮窗中显示

返回示例

成功返回

HTTP/1.0 200 Content-Type: application/json Content-Length: 0

          HTTP/1.0 200
  Content-Type: application/json
  Content-Length: 0

此代码块在浮窗中显示

失败返回

HTTP/1.0 400 Content-Type: application/json Content-Length: 0

          HTTP/1.0 400
  Content-Type: application/json
  Content-Length: 0

此代码块在浮窗中显示

{ "error":{ "code":1003, "message":"msgid doesn't exist" } }

          {
  "error":{
    "code":1003,
    "message":"msgid doesn't exist"
  }
}

此代码块在浮窗中显示

厂商配额查询 API

功能说明

厂商为了控制应用推送消息的频率，会根据应用在厂商的日联网数计算每天推送数量上限。目前已知小米、oppo、vivo都有每天的额度控制，额度可以在厂商后台查询，也可以通过极光WebPortal控制台查询；为了进一步方便开发展，极光汇总了三个平台的查询接口，供开发者调用查询。

调用地址

GET https://api.jpush.cn/v3/push/quota

调用验证

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

请求示例

GET /v3/push/quota Authorization: Basic (base64 auth string) Content-Type: text/plain Accept: application/json

          GET /v3/push/quota
    Authorization: Basic (base64 auth string)
    Content-Type: text/plain
    Accept: application/json

此代码块在浮窗中显示

返回示例

成功返回

HTTP/1.0 200 Content-Type: application/json Content-Length: 0

          HTTP/1.0 200
  Content-Type: application/json
  Content-Length: 0

此代码块在浮窗中显示

{ "code": 0, // 返回code 0表示接口调用成功 "message": "success" // success 表示接口调用成功 "data": { "xiaomi_quota": { // 小米配额 "operation": { // 运营消息 "total": 100, // 可用总额度 "used": 20 // 已使用额度 } }, "oppo_quota": { // OPPO配额 "operation": { // 运营消息 "total": 100, "used": 20 } }, "vivo_quota": { // vivo配额 "system": { // 系统消息 "total": 100, // 开通了不限量时，返回-1 "used": 20 // 开通了不限量时，返回-1 }, "operation": { // 运营消息 "total": 100, "used": 20 } } } // 返回数据，需要返回数据的接口会将数据放在此字段返回 }

          {
    "code": 0, // 返回code 0表示接口调用成功
    "message": "success" // success 表示接口调用成功
    "data": {
        "xiaomi_quota": { // 小米配额
            "operation": { // 运营消息
                "total": 100, // 可用总额度
                "used": 20 // 已使用额度
            }
        },
        "oppo_quota": { // OPPO配额
            "operation": { // 运营消息
                "total": 100,
                "used": 20
            }
        },
        "vivo_quota": { // vivo配额
            "system": { // 系统消息
                "total": 100, // 开通了不限量时，返回-1
                "used": 20 // 开通了不限量时，返回-1
            },
            "operation": { // 运营消息
                "total": 100,
                "used": 20
            }
        }
    } // 返回数据，需要返回数据的接口会将数据放在此字段返回
}

此代码块在浮窗中显示

失败返回

HTTP/1.0 400 Content-Type: application/json Content-Length: 0

          HTTP/1.0 400
  Content-Type: application/json
  Content-Length: 0

此代码块在浮窗中显示

{ "code": 1004, // 返回code非0表示失败 "message": "app_key does not exist" // 接口调用失败，则提示失败原因 }

          {
    "code": 1004, // 返回code非0表示失败
    "message": "app_key does not exist" // 接口调用失败，则提示失败原因
}

此代码块在浮窗中显示

注意事项

厂商配额查询 API 接口频率和 Push API 接口频率共享，消耗 Push API 接口频率。

文件推送 API

功能说明

支持指定文件唯一标识（file_id）进行推送，文件唯一标识（file_id）可以参考 File API v3 的文件上传接口获得。

调用验证

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

调用地址

文件立即推送

POST https://api.jpush.cn/v3/push/file

文件定时推送

POST https://api.jpush.cn/v3/schedules

调用说明

推送支持的参数和普通 Push API v3 参数一致，仅仅只是 audience 参数和 Push API v3 接口有区别，此接口支持的 audience 参数仅仅支持传递 file。

请求示例

文件立即推送

{ "platform":"all", "audience":{ "file":{"file_id":"004f2b2c3d8fc649fa60ad2c-15563487-577d-4bb0-806b-56f1a19e06c1"} }, "notification":{"alert":"Hello, JPush!"}, "message":{"msg_content":"Hello, JPush!"}, "options":{ "time_to_live":600, "apns_production":false } }

          {
    "platform":"all",
    "audience":{
        "file":{"file_id":"004f2b2c3d8fc649fa60ad2c-15563487-577d-4bb0-806b-56f1a19e06c1"}
    },
    "notification":{"alert":"Hello, JPush!"},
    "message":{"msg_content":"Hello, JPush!"},
    "options":{
        "time_to_live":600,
        "apns_production":false
    }
}

此代码块在浮窗中显示

文件定时推送

{ "cid": "7103a4c428a0b98974ec1849-711161d4-5f17-4d2f-b855-5e5a8909b26e", "name":"Schedule_Name", "enabled":true, "trigger":{ "periodical":{ "start":"2021-02-19 12:00:00", "end":"2021-03-19 18:30:00", "time":"18:05:00", "time_unit":"day", "frequency":1 } }, "push":{ "platform":"all", "audience":{ "file":{"file_id":"004f2b2c3d8fc649fa60ad2c-15563487-577d-4bb0-806b-56f1a19e06c1"} }, "notification":{"alert":"Hello, JPush!"}, "message":{"msg_content":"Hello, JPush!"}, "options":{ "time_to_live":600, "apns_production":false } } }

          {
    "cid": "7103a4c428a0b98974ec1849-711161d4-5f17-4d2f-b855-5e5a8909b26e",
    "name":"Schedule_Name",
    "enabled":true,
    "trigger":{
        "periodical":{
            "start":"2021-02-19 12:00:00",
            "end":"2021-03-19 18:30:00",
            "time":"18:05:00",
            "time_unit":"day",
            "frequency":1
        }
    },
    "push":{
        "platform":"all",
        "audience":{
            "file":{"file_id":"004f2b2c3d8fc649fa60ad2c-15563487-577d-4bb0-806b-56f1a19e06c1"}
        },
        "notification":{"alert":"Hello, JPush!"},
        "message":{"msg_content":"Hello, JPush!"},
        "options":{
            "time_to_live":600,
            "apns_production":false
        }
    }
}

此代码块在浮窗中显示

返回示例

< HTTP/1.1 200 OK < Content-Type: application/json { "sendno": "0", "msg_id": "18100287008546343" }

          < HTTP/1.1 200 OK
< Content-Type: application/json
{
    "sendno": "0",
    "msg_id": "18100287008546343"
}

此代码块在浮窗中显示

注意事项

文件推送（文件立即推送 / 文件定时推送） API 接口频率规则和 File API v3 频率规则一样 20 次 /min，且各个文件相关接口频率会互相消耗。
对于即时推送，建议创建推送任务 5 分钟后再执行文件删除操作，否则推送任务可能会失败。
对于文件定时推送，创建定时任务成功后，若任务被执行前文件被删除，则任务执行时推送动作将会失败。

应用分组文件推送 API（VIP）

功能说明

该 API 用于为开发者在 portal 端创建的应用分组进行文件推送，推送参数和格式跟文件推送一样。

此接口只对已经开通权限对客户支持，未开通权限客户使用将会返回错误返回码 2007。

调用文件上传接口获取 file_id 时，需要使用 dev_key 和 dev_secret 进行验证，详情参考文件上传接口。

调用地址

POST https://api.jpush.cn/v3/grouppush/file

调用验证

需要注意对是，此接口鉴权使用的是 base64(groupkey:group_secret)

groupkey 可以在创建的分组信息中获取，使用起来同 AppKey 类似，但在使用的时候前面要加上 “group-” 前缀，group_secret 对应分组信息中的 Group Master Secret，详情参考分组推送 API。

请求示例

curl --insecure -X POST -v https://api.jpush.cn/v3/grouppush/file -H "Content-Type: application/json" -u "group-e4c938578ee598be517a2243:71d1dc4dae126674ed386b7b" -d '{ "platform": [ "android" ], "audience": { "file": { "file_id": "9516d30d2c128dd2000e35b6-e4b030ed-6f89-468c-8f3a-41302f88fe44" } }, "notification": { "android": { "alert": "notification content", "title": "notification title" } }, "message": { "msg_content": "message content" } }'

          curl --insecure -X POST -v https://api.jpush.cn/v3/grouppush/file -H "Content-Type: application/json" -u "group-e4c938578ee598be517a2243:71d1dc4dae126674ed386b7b" -d '{
    "platform": [
        "android"
    ],
    "audience": {
        "file": {
            "file_id": "9516d30d2c128dd2000e35b6-e4b030ed-6f89-468c-8f3a-41302f88fe44"
        }
    },
    "notification": {
        "android": {
            "alert": "notification content",
            "title": "notification title"
        }
    },
    "message": {
        "msg_content": "message content"
    }
}'

此代码块在浮窗中显示

返回示例

{ "0c3de43c6a6b68c9f4261b06": { "msg_id": "18100287417805254", "sendno": "0" }, "35c424abde12f475566ca8af": { "msg_id": "18100287207481882", "sendno": "0" }, "8f02a4fa717a6235734d92de": { "msg_id": "18100287420699802", "sendno": "0" }, "group_msgid": "cbp0jnu09s687o2j1oa0" }

          {
    "0c3de43c6a6b68c9f4261b06": {
        "msg_id": "18100287417805254",
        "sendno": "0"
    },
    "35c424abde12f475566ca8af": {
        "msg_id": "18100287207481882",
        "sendno": "0"
    },
    "8f02a4fa717a6235734d92de": {
        "msg_id": "18100287420699802",
        "sendno": "0"
    },
    "group_msgid": "cbp0jnu09s687o2j1oa0"
}

此代码块在浮窗中显示

调用返回

详情参考推送 API。