上传文件
上传流程图
+-----------------+ +-----------------+ +-----------------+
| Client/Browser | | FORM API | | 知晓云 |
+-----------------+ +-----------------+ +-----------------+
| | |
+++ Request authorization +++
|-|====================================>|-|
|-| | |-|
|-| Response authorization |-|
|-|<====================================|-|
+++ | +++
| | |
+++ Upload +++ +++
|-|================>|-| |-|
|-| |-| |-|
|-| Response |-| |-|
|-|<================|-| |-|
+++ +++ +++
| | |
使用知晓云 Web API 上传文件需要以下两个步骤:
1. 获取上传文件所需授权凭证和上传地址
v2.1 接口规范了返回参数的输出,使用更方便。原获取上传文件所需授权凭证和上传地址 v1 接口已被废弃。
接口
POST /hserve/v2.1/upload/
请求参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
filename | string | N | 上传的文件名 |
category_id | string | N | 上传文件的所属分类,格式为文件分类的 ID 数组 |
category_name | string | N | 目录名,若同时指定 category_id 及 category_name ,将优先使用 category_id (可选) |
请求示例
curl -X POST \
-H "X-Hydrogen-Client-ID: [[client_id]]" \
-H "Authorization: Hydrogen-r1 {{AccessToken}}" \
-H "Content-Type: application/json" \
-d '{"filename": "test.jpg", "category_name": "cate"}' \
https://{{服务器域名}}/hserve/v2.1/upload/
返回参数
参数 | 类型 | 说明 |
---|---|---|
id | String | 上传的文件 ID |
policy | String | 文件上传配置 |
authorization | String | 文件上传凭证 |
path | String | 上传成功后的访问地址 URL |
upload_url | String | 上传文件的目标地址 |
name | String | 文件名 |
cdn_path | String | 文件在 CDN 中的相对路径 |
created_at | Integer | 文件创建时间戳 |
返回示例
{
"policy": "eyJkYXRlIjogIldlZCwgMDYgRGVjIDIwMTcgMDM6MzI6MzMgR01UIiwgIm5vdGlmeS11cmwiOiAiaHR0cHM6Ly9zc28uaWZhbnIuY29tL2V4dGFwaS9oeWRyb2dlbi91cHl1bi9jYWxsYmFjay8yODcvNWEyNzY0ZDFmZmYxZDYxYWQwZWNhMjQ1LyIsICJidWNrZXQiOiAiY2xvdWQtbWluYXBwLTI4NyIsICJzYXZlLWtleSI6ICIxZU1RUmxrSndoZ2FNaUNnLmdpZiIsICJleHBpcmF0aW9uIjogMTUxMjUzMTQ1M30=",
"upload_url": "https://v0.api.upyun.com/cloud-minapp-287",
"path": "https://cloud-minapp-287.cloud.ifanrusercontent.com/1eMQRlkJwhgaMiCg.gif",
"id": "5a2764d1fff1d61ad0eca245",
"authorization": "UPYUN allenzhang:MzmYCcWVjrWoeovC4+tM5Bgwusg=",
"name": "1eMQRlkJwhgaMiCg.gif",
"cdn_path": "1eMQRlkJwhgaMiCg.gif",
"created_at": 12344566
}
状态码说明
200
获得授权凭证成功
2. 使用上一步获取的授权凭证和上传地址,进行文件上传
接口
POST {UPLOAD_URL}
UPLOAD_URL
是调用上一步的接口所返回的字段 upload_url
的值,形如:
https://v0.api.upyun.com/cloud-minapp-18****
参数说明
Content-Type: multipart/form-data
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
authorization | string | Y | 授权凭证 |
file | string | Y | 上传的文件流 |
policy | string | Y | 授权凭证 |
请求示例
curl \
-F authorization="UPYUN allenzhang:aBIGd7s5Tjcc2khrnx2uxgjYuzw=" \
-F file=@"/Users/hehehe/Downloads/test.jpg" \
-F policy="eyJidWNrZXQiOiAiY2xvdWQtbWluYXBwLTE4NjMwIiwgImRhdGUiOiAiVGh1LCAxOCBBcHIgMjAxOSAwODoyMTo0MSBHTVQiLCAibm90aWZ5LXVybCI6ICJodHRwczovL3Nzby5pZmFuci5jb20vZXh0YXBpL2h5ZHJvZ2VuL3VweXVuL2NhbGxiYWNrLzE4NjMwLzVjYjgzMzk1YWNjNzM5NDMxNzBjZWFkNS8iLCAic2F2ZS1rZXkiOiAiMWhIMklmWlgwUlIzc1dvSS5wbmciLCAiZXhwaXJhdGlvbiI6IDE1NTU1NzYwMDF9=" \
https://v0.api.upyun.com/cloud-minapp-18630
返回参数说明
参数 | 类型 | 说明 |
---|---|---|
image-type | string | 图片类型 |
image-height | integer | 图片高度 |
image-width | integer | 图片宽度 |
code | integer | 响应码 |
time | array | 上传时间 |
file_size | array | 图片大小 |
url | integer | 图片链接 |
message | integer | 附加信息 |
mimetype | string | mime |
返回示例
{
"image-type": "GIF",
"image-frames": 8,
"image-height": 8,
"code": 200,
"file_size": 329,
"image-width": 8,
"url": "1eMQRlkJwhgaMiCg.gif",
"time": 1512531154,
"message": "ok",
"mimetype": "image/gif"
}
状态码说明
200
上传成功
如果需要获取文件上传成功后文件的完整 url,请使用步骤 1 接口返回的 file_link
获取上传文件所需授权凭证和上传地址 v1
接口
POST /hserve/v1/upload/
请求参数说明
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
filename | string | N | 上传的文件名 |
category_id | string | N | 上传文件的所属分类,格式为文件分类的 ID 数组 |
category_name | string | N | 目录名,若同时指定 category_id 及 category_name ,将优先使用 category_id (可选) |
请求示例
curl -X POST \
-H "X-Hydrogen-Client-ID: [[client_id]]" \
-H "Authorization: Hydrogen-r1 {{AccessToken}}" \
-H "Content-Type: application/json" \
-d '{"filename": "test.jpg", "category_name": "cate"}' \
https://{{服务器域名}}/hserve/v1/upload/
返回参数
参数 | 类型 | 说明 |
---|---|---|
id | string | 上传的文件 ID |
policy | string | 文件上传配置 |
authorization | string | 文件上传凭证 |
file_link | string | 文件上传成功后的访问地址 |
upload_url | string | 上传文件的目标地址 |
返回示例
{
"policy": "********eyJidWNrZXQiOiAiY2xvdWQtbWluYXBwLTE4NjMwIiwgImRhdGUiOiAiVGh1LCAxOCBBcHIgMjAxOSAwODoyMTo0MSBHTVQiLCAibm90aWZ5LXVybCI6ICJodHRwczovL3Nzby5pZmFuci5jb20vZXh0YXBpL2h5ZHJvZ2VuL3VweXVuL2NhbGxiYWNrLzE4NjMwLzVjYjgzMzk1YWNjNzM5NDMxNzBjZWFkNS8iLCAic2F2ZS1rZXkiOiAiMWhIMklmWlgwUlIzc1dvSS5wbmciLCAiZXhwaXJhdGlvbiI6IDE1NTU1NzYwMDF9*********",
"authorization": "UPYUN allenzhang:aBIGd7s5Tjcc2khrnx2uxgjYuzw=",
"upload_url": "https://v0.api.upyun.com/cloud-minapp-18****",
"id": "5cac3d2299ecae0c9e8****6",
"file_link": "https://cloud-minapp-18630.cloud.ifanrusercontent.com/1hDkLip5hcxdQpl5.jpg"
}
状态码说明
200
获得授权凭证成功
400
参数错误(不支持上传的文件格式)
404
找不到文件分类 ID