Image API v3

概述

功能说明

需要结合Push Android SDK v3.9.0及其以上版本配套使用。开发者提交图片或者网络资源 URL 至极光服务器,极光会根据开发者需求对接适配各个厂商,同时开发者将从极光得到对应资源的MediaID,该MediaID可于 Push API v3 中使用,达到统一推送大图片、大图标和小图标的需求。

各通道支持及要求情况

  1. 该接口可适配的厂商通道有:极光、小米、OPPO、华为以及FCM;
  2. 目前该接口暂不提供存储文件服务,故请确保提交的图片资源可被访问且符合要求;
  3. 不同通道对不同类型的图片支持情况不同,具体如下表格所示:
      极光通道 小米 OPPO 华为 FCM
    大图片 1. 支持http
    2. 支持https
    3. 支持本地资源路径,且必须是sdcard的相对路径,需要指定文件后缀
    1. 支持http
    2. 支持https
    3. 暂不支持小米国际版适配
    1. 支持http
    2. 支持https
    - 1. 支持http
    2. 支持https
    3. 支持本地资源路径,且必须是sdcard的相对路径,需要指定文件后缀
    大图标 1. 支持http
    2. 支持https
    3. 支持位于drawable资源文件夹的图标路径,无需指定文件后缀
    1. 支持http
    2. 支持https
    1. 支持http
    2. 支持https
    1. 支持https
    1. 支持http
    2. 支持https
    3. 支持位于drawable资源文件夹的图标路径,无需指定文件后缀
    小图标 1. 支持http
    2. 支持https
    3. 支持位于drawable资源文件夹的图标路径,无需指定文件后缀
    1. 支持http
    2. 支持https
    - 1. 支持本地资源路径,且必须提交以 /raw/ 开头的路径,无需指定文件后缀 -

备注:以上都仅支持 jpg 、 jpeg 以及 png 格式的资源。

调用地址

https://api.jpush.cn/v3/images

调用验证

HTTP Header(头)里加一个字段(Key/Value 对):

Authorization: Basic base64_auth_string

其中 base64_auth_string 的生成算法为:base64(appKey:masterSecret)
即,对 appKey 加上冒号,加上 masterSecret 拼装起来的字符串,再做 base64 转换。

新增图片(URL方式)

调用地址

POST https://api.jpush.cn/v3/images/byurls

功能说明

通过指定网络图片资源的URL形式来新增一个适配

调用示例

Request Header

> POST /v3/images/byurls HTTP/1.1
> Content-Type: application/json
> Authorization: Basic MjhhMTBjMDkwNGI1Y2Q2MjJhYWRhZWIxOmU5ZmFhMmM5NzYzZGViZDIwZTdkZTFlYg==

Request Body

{
    "image_type": 2,
    "image_url": "https://xx.com/xx.jpg",
    "oppo_image_url": "https://xx.com/oppo.jpg",
    "xiaomi_image_url": "https://xx.com/xiaomi.jpg",
    "huawei_image_url": "",
    "fcm_image_url": "",
    "jiguang_image_url": "https://xx.com/jiguang.jpg"
}

完整的参数说明如下:

关键字 选项 含义
image_type 必填 指定适配的图片类型:1大图片-2大图标-3小图标
image_url 可选 公共的图片地址;
如果设置了该字段,则当其他字段不设置值时,将该字段的内容作为其他字段的默认值;
例如:仅该字段以及极光字段有值,而小米、OPPO字段无值,则小米、OPPO字段值将被设置成与该字段值相同,但不会改变极光字段值。
jiguang_image_url 可选 配置极光通道的图片地址
xiaomi_image_url 可选 配置小米通道的图片地址;
如果您的应用没有通过极光平台开通小米厂商通道,则不对该字段做处理;
本接口将会对该地址的图片资源自动进行尺寸的调整和压缩,以适配小米对该图片的要求,其要求具体见参考;
若提交的图片资源尺寸不符,则进行等比例缩放且以留白的形式进行调整,而不会对图片进行剪裁;若适配调整失败,将返回错误;建议提交与要求相符的图片资源,小米厂商对该图片要求请参考小米——大图/大文本/Large icon
oppo_image_url 可选 配置适配OPPO通道的图片地址;
如果您的应用没有通过极光平台开通OPPO厂商通道,则不对该字段做处理;
本接口将会对该地址的图片资源自动进行尺寸的调整和压缩,以适配 OPPO 对该图片的要求,其要求具体见参考;
若提交的图片资源尺寸不符,则进行等比例缩放且以留白的形式进行调整,而不会对图片进行剪裁;若适配调整失败,将返回错误;建议提交与要求相符的图片资源,OPPO 厂商对该图片要求请参考OPPO——图片上传
huawei_image_url 可选 配置华为通道的图片地址;
如果您的应用没有通过极光平台开通华为厂商通道,则不对该字段做处理。
fcm_image_url 可选 配置FCM通道的图片地址;
如果您的应用没有通过极光平台开通FCM厂商通道,则不对该字段做处理。

备注:
1. image_url以及各通道的字段值不能同时为空;
2. 指定的厂商图片字段,仅在厂商支持相应图片类型的情况下被处理;如配置了华为厂商的大图片地址,由于华为厂商不支持大图片类型,则结果中华为字段将为空值。

返回示例

成功返回

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

Success Response Data
{
    "media_id": "jgmedia-2-14b23451-0001-41ce-89d9-987b465122da",   // 得到的结果 media_id ,推送时可将该id作为参数传递给 Push 推送接口,具体见参考
    "oppo_image_url": "3653918_5f92b5739ae676f5745bcbf4",   // 适配 OPPO 要求后 OPPO 响应得到的 id
    "xiaomi_image_url": "http://f6.market.xiaomi.com/download/MiPass/01fff50f50ba193f94074ec/d1671936d468383f.png",     // 适配小米要求后小米响应得到的图标地址
    "huawei_image_url": "https://xx.com/xx.jpg",    // 配置的华为图标地址
    "fcm_image_url": "https://xx.com/xx.jpg",   // 配置的FCM图标地址
    "jiguang_image_url": "https://xx.com/jiguang.jpg"   // 配置的极光通道的图标地址
}

失败返回

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

Failed Response Data
{
    "error": {
        "code": 1002,
        "message": "Missing authen info."
    }
}

新增图片(文件方式)

调用地址

POST https://api.jpush.cn/v3/images/byfiles

功能说明

通过上传图片文件形式来新增一个适配,该接口目前仅支持小米和 OPPO 。

调用示例

curl  --request POST 'https://api.jpush.cn/v3/images/byfiles' --header 'Content-Type: multipart/form-data' --header 'Authorization: Basic MjhhMTBjMDkwNGI1Y2Q2MjJhYWRhZWIxOmU5ZmFhMmM5NzYzZGViZDIwZTdkZTFlYg=='  --form 'xiaomi_file=@/home/user/pictures/test_file1.jpg'  --form 'oppo_file=@/home/user/pictures/test_file2.jpg' --form 'image_type=1'

完整的参数说明如下:

关键字 选项 含义
image_type 必填 指定适配的图片类型:1大图片-2大图标-3小图标
oppo_file 可选 上传配置OPPO通道的图片文件;
本接口将会对该图片文件大小进行校验,若不适配 OPPO 对该图片的要求,则返回错误,OPPO 对该图片对要求参考OPPO——图片上传
xiaomi_file 可选 上传配置小米通道的图片文件
本接口将会对该图片文件大小进行校验,若不适配小米对该图片的要求,则返回错误,小米对该图片对要求参考小米——大图/大文本/Large icon

备注:oppo_filexiaomi_file不能同时为空。

返回示例

成功返回

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

Success Response Data
{
    "media_id": "jgmedia-1-6d98e85f-d3a5-412a-bdec-de1b75bd3ad3",   // 得到的结果 media_id ,推送时可将该id作为参数传递给 Push 推送接口,具体见参考
    "oppo_image_url": "3653918_5f92b5739ae676f5745bcbf4",   // 适配 OPPO 要求后 OPPO 响应得到的 id
    "xiaomi_image_url": "http://f6.market.xiaomi.com/download/MiPass/01fff50f50ba193f94074ec/d1671936d468383f.png",     // 适配小米要求后小米响应得到的图标地址
    "huawei_image_url": "",
    "fcm_image_url": "",
    "jiguang_image_url": ""
}

失败返回

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

Failed Response Data
{
    "error": {
        "code": 1002,
        "message": "Missing authen info."
    }
}

更新图片(URL方式)

调用地址

PUT https://api.jpush.cn/v3/images/byurls/{mediaId}

功能说明

通过指定网络图片资源的URL形式来修改/更新适配结果

调用示例

Request Header

> PUT /v3/images/byurls/jgmedia-2-14b23451-0001-41ce-89d9-987b465122da HTTP/1.1
> Content-Type: application/json
> Authorization: Basic MjhhMTBjMDkwNGI1Y2Q2MjJhYWRhZWIxOmU5ZmFhMmM5NzYzZGViZDIwZTdkZTFlYg==

Request Body

{
    "oppo_image_url": "",
    "xiaomi_image_url": "",
    "huawei_image_url": "https://xx.com/new_huawei.jpg",
    "fcm_image_url": "",
    "jiguang_image_url": "http://xx.com/new_jiguang.jpg"
}

完整的参数说明如下:

关键字 选项 含义
jiguang_image_url 可选 更新配置极光通道的图片地址
xiaomi_image_url 可选 配置小米通道的图片地址;
如果您的应用没有通过极光平台开通小米厂商通道,则不对该字段做处理;
本接口将会对该地址的图片资源自动进行尺寸的调整和压缩,以适配小米对该图片的要求,其要求具体见参考;
若提交的图片资源尺寸不符,则进行等比例缩放且以留白的形式进行调整,而不会对图片进行剪裁;若适配调整失败,将返回错误;建议提交与要求相符的图片资源,小米厂商对该图片要求请参考小米——大图/大文本/Large icon
oppo_image_url 可选 配置适配OPPO通道的图片地址;
如果您的应用没有通过极光平台开通OPPO厂商通道,则不对该字段做处理;
本接口将会对该地址的图片资源自动进行尺寸的调整和压缩,以适配 OPPO 对该图片的要求,其要求具体见参考;
若提交的图片资源尺寸不符,则进行等比例缩放且以留白的形式进行调整,而不会对图片进行剪裁;若适配调整失败,将返回错误;建议提交与要求相符的图片资源,OPPO 厂商对该图片要求请参考OPPO——图片上传
huawei_image_url 可选 配置华为通道的图片地址;
如果您的应用没有通过极光平台开通华为厂商通道,则不对该字段做处理。
fcm_image_url 可选 配置华为通道的图片地址;
如果您的应用没有通过极光平台开通FCM厂商通道,则不对该字段做处理。

备注:
1. 各通道的字段值不能同时为空;
2. 若未指定更新配置的厂商地址,则该厂商的配置结果保留更新前的值而不会被置空,如该接口例子中的小米通道;
3. 若指定更新配置的厂商不支持对应类型,则该厂商的配置结果将保留更新前的值而不会被覆盖。

返回示例

成功返回

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

Success Response Data
{
    "media_id": "jgmedia-2-14b23451-0001-41ce-89d9-987b465122da",   // 更新的 media_id ,推送时可将该id作为参数传递给 Push 推送接口,具体见参考
    "oppo_image_url": "3653918_5f92b5739ae676f5745bcbf4",   // 适配 OPPO 要求后 OPPO 响应得到的 id
    "xiaomi_image_url": "http://f6.market.xiaomi.com/download/MiPass/01fff50f50ba193f94074ec/d1671936d468383f.png",     // 适配小米要求后小米响应得到的图标地址
    "huawei_image_url": "https://xx.com/new_huawei.jpg",    // 配置的华为图标地址
    "fcm_image_url": "https://xx.com/xx.jpg",   // 配置的FCM图标地址
    "jiguang_image_url": "http://xx.com/new_jiguang.jpg"   // 配置的极光通道的图标地址
}

失败返回

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

Failed Response Data
{
    "error": {
        "code": 1002,
        "message": "Missing authen info."
    }
}

更新图片(文件方式)

调用地址

PUT https://api.jpush.cn/v3/images/byfiles/{mediaId}

功能说明

通过上传图片文件形式来修改/更新适配结果,该接口目前仅支持小米和 OPPO

调用示例

curl  --request PUT 'https://api.jpush.cn/v3/images/byfiles/jgmedia-1-6d98e85f-d3a5-412a-bdec-de1b75bd3ad3' --header 'Content-Type: multipart/form-data' --header 'Authorization: Basic MjhhMTBjMDkwNGI1Y2Q2MjJhYWRhZWIxOmU5ZmFhMmM5NzYzZGViZDIwZTdkZTFlYg=='  --form 'xiaomi_file=@/home/user/pictures/test_file1.jpg'  --form 'oppo_file=@/home/user/pictures/test_file2.jpg'

完整的参数说明如下:

关键字 选项 含义
oppo_file 可选 上传配置OPPO通道的图片文件;
本接口将会对该图片文件大小进行校验,若不适配 OPPO 对该图片的要求,则返回错误,OPPO 对该图片对要求参考OPPO——图片上传
xiaomi_file 可选 上传配置小米通道的图片文件
本接口将会对该图片文件大小进行校验,若不适配小米对该图片的要求,则返回错误,小米对该图片对要求参考小米——大图/大文本/Large icon

备注:oppo_filexiaomi_file不能同时为空

返回示例

成功返回

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

Success Response Data
{
    "media_id": "jgmedia-1-6d98e85f-d3a5-412a-bdec-de1b75bd3ad3",   // 更新的 media_id ,推送时可将该id作为参数传递给 Push 推送接口,具体见参考
    "oppo_image_url": "3653918_3_5f9a5f7cb3c87bf699b332a5",   // 适配 OPPO 要求后 OPPO 响应得到的 id
    "xiaomi_image_url": "http://f8.market.xiaomi.com/download/MiPass/0dfdb5eba1bbb8d1671983fdb2be94074ec/8a350da36d46835768f17f48a6b12b2765cec115.png",     // 适配小米要求后小米响应得到的图标地址
    "huawei_image_url": "",
    "fcm_image_url": "",
    "jiguang_image_url": ""
}

失败返回

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

Failed Response Data
{
    "error": {
        "code": 1002,
        "message": "Missing authen info."
    }
}

状态码说明

Code 描述 详细解释 HTTP Status Code
1000 系统内部错误 服务器端内部逻辑错误,请稍后重试 500
1002 验证失败 缺少Authorization信息 400
1004 验证失败 1. Authorization中的token格式错误
2. appkey无效
3. appkey与masterSecret不匹配
401
1102 缺少必要参数 缺少必要参数 400
1103 参数值不合法 1. 上传文件太大
2. 文件格式不正确
3. 提交的 mediaId 无效
4. “the result is all of invalid”请检查是否开通配置了对应的厂商通道及图片类型是否支持
5. 其他错误
400
1030 服务超时 1. 服务内部调用超时
2. 图片适配厂商响应超时
503

调用限制

  • 上传文件大小不超过 2M
  • API 请求频率限制与 Push API v3 接口共享

参考


Copyright 2011-2020, jiguang.cn, All Rights Reserved.
粤ICP备12056275号-13 深圳市和讯华谷信息技术有限公司

Documentation built with MkDocs.