File API v3

概述

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

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

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

调用地址

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

调用验证

HTTP Header(头)里加一个字段(Key/Value 对):
Authorization: Basic base64_auth_string
其中 base64_auth_string 的生成算法为:base64(appKey:masterSecret) 即,对 appKey 加上冒号,加上 masterSecret 拼装起来的字符串,再做 base64 转换。

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

Request Params

  • type 文件类型,当前可取值为: alias、registration_id,不能为空。
  • filename 文件名
  • 文件一行一个内容,忽略每行的前后空格和换行符作为实际的registration_id值或者alias值
  • 文件只支持 txt 格式
  • 文件不超过 10M
  • 文件自创建起,服务器会保存30天,超过有效期,服务器自动将文件删除
  • 有效期内的文件不允许超过20个

返回示例

HTTP/1.1 200

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

Response Params

  • file_id:文件id,后续供删除、查询、推送时使用。

查询有效文件列表

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

调用地址

GET 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" },
        {"file_id": "xxxx-xxxx", "type": "registration_id", "create_time": "2019-10-13 13:36:55" },
        {...}
    ]
}

Response Params

JSON Array

  • total_count:当前有效的文件数。
  • files 文件列表详情
  • file_id 文件id
  • type 文件类似,当前只有 alias、registration_id 两种类型
  • create_time 文件创建(上传)时间

删除文件

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

调用地址

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

返回示例

HTTP/1.1 200

Response Params

N/A

  • 删除成功返回空字符串,http状态码是200。
  • file_id 不存在当成功处理。

查询指定文件详情

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

调用地址

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

返回示例

HTTP/1.1 200

{
    "file_id": "7d431e42dfa6a6d693ac2d04-374004a2-bc6c-4abc-bde5-9f1a9671d307",
    "type": "alias", // 文件类型
    "create_time": "2019-10-12 13:36:55" // 创建时间
}

Response Params

JSON Object

  • file_id 文件id
  • type 文件类似,当前只有 alias、registration_id 两种类型
  • create_time 文件创建(上传)时间

调用返回

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

调用限制

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

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

Documentation built with MkDocs.