文件管理 API

概述

API 层面支持文件推送功能，具体推送方式参考文件推送；

此模块 API 主要针对的是文件上传、查询、删除操作；

调用文件推送接口推送前，必须先通过此模块接口上传文件，得到文件唯一标识（file_id）后方能推送。

调用地址

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

调用验证

详情参见 REST API 概述的鉴权方式说明。
2020.08.11日开始，新增支持 base64(dev_key:dev_secret) 鉴权，当使用 base64(dev_key:dev_secret) 鉴权时，要求开发者已经通过了极光平台开通了 VIP 文件应用分组推送权限，只有开启权限的开发者，才能通过 dev_key 调用 fileapi 的各个接口，否则返回 1105 错误码。
- dev_key 和 dev_secret 分别对应：极光官网个人账户信息中的”开发者标识(DevKey)“ 和“API DevSecret”。

上传文件

可以将要推送的 alias 或者registration_id 值先写入本地文件，然后将本地文件上传到极光服务器，后续就可以直接指定文件推送了。

调用地址

POST https://api.jpush.cn/v3/files/{type}

请求示例

curl -F "filename=@registration_id.txt" -F "ttl=720" https://api.jpush.cn/v3/files/registration_id -u "115cc609860982ede0e3bdd4:2e2023ade697b989087dcc53" > POST /v3/files/registration_id HTTP/2 > Host: api.jpush.cn > Authorization: Basic MTE1Y2M2MDk4NjA5ODJlZGUwZTNiZGQ0OjJlMjAyM2FkZTY5N2I5ODkwODdkY2M1Mw== > User-Agent: curl/7.64.1 > Accept: */* > Content-Length: 209 > Content-Type: multipart/form-data; boundary=------------------------6fd6ff237027ae34

          curl -F "filename=@registration_id.txt" -F "ttl=720" https://api.jpush.cn/v3/files/registration_id -u "115cc609860982ede0e3bdd4:2e2023ade697b989087dcc53"

> POST /v3/files/registration_id HTTP/2
> Host: api.jpush.cn
> Authorization: Basic MTE1Y2M2MDk4NjA5ODJlZGUwZTNiZGQ0OjJlMjAyM2FkZTY5N2I5ODkwODdkY2M1Mw==
> User-Agent: curl/7.64.1
> Accept: */*
> Content-Length: 209
> Content-Type: multipart/form-data; boundary=------------------------6fd6ff237027ae34

此代码块在浮窗中显示

请求参数

type 文件类型，当前可取值为： alias、registration_id，不能为空。
filename 文件名
- 文件一行一个内容，忽略每行的前后空格和换行符作为实际的registration_id值或者alias值。
- 文件只支持txt格式，要求文件内容必须是utf8编码。
- 文件不超过 10M。
- 文件自创建起，若不指定ttl参数，则服务器会默认保存720小时（即30天），超过有效期，服务器自动将文件删除。
- 有效期内的文件不允许超过20个。
ttl 文件有效期
- 可选参数，整型类型，单位是小时，默认值是720小时。
- 数值范围在[1,720]间，即1小时至720小时（30天）。

返回示例

HTTP/1.1 200 { "file_id": "8103a4c628a0b98994ec1949-374004a2-bc6c-4abc-bde5-9f1a9671d307" }

          HTTP/1.1 200

{
"file_id": "8103a4c628a0b98994ec1949-374004a2-bc6c-4abc-bde5-9f1a9671d307"
}

此代码块在浮窗中显示

返回参数

file_id：文件id，后续供删除、查询、推送时使用。

查询有效文件列表

获取当前保存在极光服务器的有效文件列表。

调用地址

GET https://api.jpush.cn/v3/files

请求示例

curl -X GET -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1" https://api.jpush.cn/v3/files

          curl -X GET -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1" https://api.jpush.cn/v3/files

此代码块在浮窗中显示

返回示例

HTTP/1.1 200 { "total_count": 3, "files": [ {"file_id": "xxxx-xxxx", "type": "alias", "create_time": "2019-10-12 13:36:55", "expire_time": "2019-10-19 13:36:57", "file_name": "xxx"}, {"file_id": "xxxx-xxxx", "type": "registration_id", "create_time": "2019-10-13 13:36:55", "expire_time": "2019-10-20 13:36:57", "file_name": "xxx"}, {...} ] }

          HTTP/1.1 200

{
    "total_count": 3,
    "files": [
        {"file_id": "xxxx-xxxx", "type": "alias", "create_time": "2019-10-12 13:36:55", "expire_time": "2019-10-19 13:36:57", "file_name": "xxx"},
        {"file_id": "xxxx-xxxx", "type": "registration_id", "create_time": "2019-10-13 13:36:55", "expire_time": "2019-10-20 13:36:57", "file_name": "xxx"},
        {...}
    ]
}

此代码块在浮窗中显示

返回参数

JSON Array

total_count：当前有效的文件数。
files 文件列表详情
- file_id 文件id
- type 文件类似，当前只有 alias、registration_id 两种类型
- create_time 文件创建（上传）时间
- expire_time 文件过期时间，当设置了文件有效期（即提交了ttl参数）则会携带该字段返回
- file_name 文件上传时的文件名（自2021-10-14日启用）

删除文件

删除保存在极光服务器的指定文件。

调用地址

DELETE https://api.jpush.cn/v3/files/{file_id}

请求示例

curl -X DELETE -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1" https://api.jpush.cn/v3/files/7d431e42dfa6a6d693ac2d04-374004a2-bc6c-4abc-bde5-9f1a9671d307

          curl -X DELETE -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1" https://api.jpush.cn/v3/files/7d431e42dfa6a6d693ac2d04-374004a2-bc6c-4abc-bde5-9f1a9671d307

此代码块在浮窗中显示

返回示例

HTTP/1.1 200

          HTTP/1.1 200

此代码块在浮窗中显示

返回参数

N/A

删除成功返回空字符串，http状态码是200。
file_id 不存在当成功处理。
对于即时推送，建议创建推送任务5分钟后再执行文件删除操作，否则推送任务可能会失败。
对于文件定时推送，创建定时任务成功后，若任务被执行前文件被删除，则任务执行时推送动作将会失败。

查询指定文件详情

查询保存在极光服务器的，指定文件的详细信息。

调用地址

GET https://api.jpush.cn/v3/files/{file_id}

请求示例

curl -XGET -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1" https://api.jpush.cn/v3/files/7d431e42dfa6a6d693ac2d04-374004a2-bc6c-4abc-bde5-9f1a9671d307

          curl  -XGET -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1" https://api.jpush.cn/v3/files/7d431e42dfa6a6d693ac2d04-374004a2-bc6c-4abc-bde5-9f1a9671d307

此代码块在浮窗中显示

返回示例

HTTP/1.1 200 { "file_id": "7d431e42dfa6a6d693ac2d04-374004a2-bc6c-4abc-bde5-9f1a9671d307", "type": "alias", // 文件类型 "create_time": "2019-10-12 13:36:55", // 创建时间 "expire_time": "2019-10-20 13:36:57", // 文件过期时间，当设置了文件有效期（即提交了ttl参数）则会携带该字段返回 "file_name": "test.txt" // 文件上传时的文件名（自2021-10-14日启用） }

          HTTP/1.1 200

{
    "file_id": "7d431e42dfa6a6d693ac2d04-374004a2-bc6c-4abc-bde5-9f1a9671d307",
    "type": "alias", // 文件类型
    "create_time": "2019-10-12 13:36:55",    // 创建时间
    "expire_time": "2019-10-20 13:36:57",    // 文件过期时间，当设置了文件有效期（即提交了ttl参数）则会携带该字段返回
    "file_name": "test.txt"                  // 文件上传时的文件名（自2021-10-14日启用）
}

此代码块在浮窗中显示

返回参数

JSON Object

file_id 文件id
type 文件类似，当前只有 alias、registration_id 两种类型
create_time 文件创建（上传）时间
expire_time 文件过期时间，当设置了文件有效期（即提交了ttl参数）则会携带该字段返回
file_name 文件上传时的文件名（自2021-10-14日启用）

调用返回

Code	描述	详细解释	HTTP Status Code
1100	系统内部错误	服务器端内部逻辑错误，请稍后重试	500
1101	验证失败	检查 Appkey 与 MasterSecret	400
1102	缺少了必须的参数	文件上传时缺少了filename字段	400
1103	参数值不合法	1. 上传文件为空 2. 上传文件太大 3. 文件格式不正确 4. 文件中部分行的长度大于阈值40字节 5. 有效期范围不正确 6. 其他错误	400
1104	请求文件不存在	服务器端无法根据调用者传进来的file_id找到对应的文件	400
1112	文件个数超过限制	单个appkey有效文件不能超过20个，超过限制返回该错误	400
1105	无权限	未开通开发者级别当文件操作接口相关权限	403

调用限制

文件最多有效数（当前未过期数）总数 20 个；超过后返回失败。
文件大小不超过 10M
文件最多保存30天
API 请求最大频率当前为 20次/分
以上所有文件相关接口的频率会互相影响和消耗。