上传文件

上传流程图

  1. +-----------------+ +-----------------+ +-----------------+
  2. | Client/Browser | | FORM API | | 知晓云 |
  3. +-----------------+ +-----------------+ +-----------------+
  4. | | |
  5. +++ Request authorization +++
  6. |-|====================================>|-|
  7. |-| | |-|
  8. |-| Response authorization |-|
  9. |-|<====================================|-|
  10. +++ | +++
  11. | | |
  12. +++ Upload +++ +++
  13. |-|================>|-| |-|
  14. |-| |-| |-|
  15. |-| Response |-| |-|
  16. |-|<================|-| |-|
  17. +++ +++ +++
  18. | | |

使用知晓云 Web API 上传文件需要以下两个步骤:

1. 获取上传文件所需授权凭证和上传地址

v2.1 接口规范了返回参数的输出,使用更方便。原获取上传文件所需授权凭证和上传地址 v1 接口已被废弃。

接口

POST /hserve/v2.1/upload/

请求参数说明

参数类型必填说明
filenamestringN上传的文件名
category_idstringN上传文件的所属分类,格式为文件分类的 ID 数组
category_namestringN目录名,若同时指定 category_id 及 category_name ,将优先使用 category_id (可选)

请求示例

  1. curl -X POST \
  2. -H "X-Hydrogen-Client-ID: [[client_id]]" \
  3. -H "Authorization: Hydrogen-r1 {{AccessToken}}" \
  4. -H "Content-Type: application/json" \
  5. -d '{"filename": "test.jpg", "category_name": "cate"}' \
  6. https://{{服务器域名}}/hserve/v2.1/upload/

返回参数

参数类型说明
idString上传的文件 ID
policyString文件上传配置
authorizationString文件上传凭证
pathString文件上传成功后的访问地址
upload_urlString上传文件的目标地址
nameString文件名
cdn_pathString文件在 CDN 中保存的路径
created_atInteger文件创建时间戳

返回示例

  1. {
  2. "policy": "eyJkYXRlIjogIldlZCwgMDYgRGVjIDIwMTcgMDM6MzI6MzMgR01UIiwgIm5vdGlmeS11cmwiOiAiaHR0cHM6Ly9zc28uaWZhbnIuY29tL2V4dGFwaS9oeWRyb2dlbi91cHl1bi9jYWxsYmFjay8yODcvNWEyNzY0ZDFmZmYxZDYxYWQwZWNhMjQ1LyIsICJidWNrZXQiOiAiY2xvdWQtbWluYXBwLTI4NyIsICJzYXZlLWtleSI6ICIxZU1RUmxrSndoZ2FNaUNnLmdpZiIsICJleHBpcmF0aW9uIjogMTUxMjUzMTQ1M30=",
  3. "upload_url": "https://v0.api.upyun.com/cloud-minapp-287",
  4. "path": "https://cloud-minapp-287.cloud.ifanrusercontent.com/1eMQRlkJwhgaMiCg.gif",
  5. "id": "5a2764d1fff1d61ad0eca245",
  6. "authorization": "UPYUN allenzhang:MzmYCcWVjrWoeovC4+tM5Bgwusg=",
  7. "name": "1eMQRlkJwhgaMiCg.gif",
  8. "cdn_path": "1eMQRlkJwhgaMiCg.gif",
  9. "created_at": 12344566
  10. }

状态码说明

200 获得授权凭证成功

2. 使用上一步获取的授权凭证和上传地址,进行文件上传

接口

POST {UPLOAD_URL}

UPLOAD_URL 是调用上一步的接口所返回的字段 upload_url 的值,形如:

  1. https://v0.api.upyun.com/cloud-minapp-18****

参数说明

Content-Type: multipart/form-data

参数类型必填说明
authorizationstringY授权凭证
filestringY上传的文件流
policystringY授权凭证

请求示例

  1. curl \
  2. -F authorization="UPYUN allenzhang:aBIGd7s5Tjcc2khrnx2uxgjYuzw=" \
  3. -F file=@"/Users/hehehe/Downloads/test.jpg" \
  4. -F policy="eyJidWNrZXQiOiAiY2xvdWQtbWluYXBwLTE4NjMwIiwgImRhdGUiOiAiVGh1LCAxOCBBcHIgMjAxOSAwODoyMTo0MSBHTVQiLCAibm90aWZ5LXVybCI6ICJodHRwczovL3Nzby5pZmFuci5jb20vZXh0YXBpL2h5ZHJvZ2VuL3VweXVuL2NhbGxiYWNrLzE4NjMwLzVjYjgzMzk1YWNjNzM5NDMxNzBjZWFkNS8iLCAic2F2ZS1rZXkiOiAiMWhIMklmWlgwUlIzc1dvSS5wbmciLCAiZXhwaXJhdGlvbiI6IDE1NTU1NzYwMDF9=" \
  5. https://v0.api.upyun.com/cloud-minapp-18630

返回参数说明

参数类型说明
image-typestring图片类型
image-heightinteger图片高度
image-widthinteger图片宽度
codeinteger响应码
timearray上传时间
file_sizearray图片大小
urlinteger图片链接
messageinteger附加信息
mimetypestringmime

返回示例

  1. {
  2. "image-type": "GIF",
  3. "image-frames": 8,
  4. "image-height": 8,
  5. "code": 200,
  6. "file_size": 329,
  7. "image-width": 8,
  8. "url": "1eMQRlkJwhgaMiCg.gif",
  9. "time": 1512531154,
  10. "message": "ok",
  11. "mimetype": "image/gif"
  12. }

状态码说明

200 上传成功

如果需要获取文件上传成功后文件的完整 url,请使用步骤 1 接口返回的 file_link

获取上传文件所需授权凭证和上传地址 v1

接口

POST /hserve/v1/upload/

请求参数说明

参数类型必填说明
filenamestringN上传的文件名
category_idstringN上传文件的所属分类,格式为文件分类的 ID 数组
category_namestringN目录名,若同时指定 category_id 及 category_name ,将优先使用 category_id (可选)

请求示例

  1. curl -X POST \
  2. -H "X-Hydrogen-Client-ID: [[client_id]]" \
  3. -H "Authorization: Hydrogen-r1 {{AccessToken}}" \
  4. -H "Content-Type: application/json" \
  5. -d '{"filename": "test.jpg", "category_name": "cate"}' \
  6. https://{{服务器域名}}/hserve/v1/upload/

返回参数

参数类型说明
idstring上传的文件 ID
policystring文件上传配置
authorizationstring文件上传凭证
file_linkstring文件上传成功后的访问地址
upload_urlstring上传文件的目标地址

返回示例

  1. {
  2. "policy": "********eyJidWNrZXQiOiAiY2xvdWQtbWluYXBwLTE4NjMwIiwgImRhdGUiOiAiVGh1LCAxOCBBcHIgMjAxOSAwODoyMTo0MSBHTVQiLCAibm90aWZ5LXVybCI6ICJodHRwczovL3Nzby5pZmFuci5jb20vZXh0YXBpL2h5ZHJvZ2VuL3VweXVuL2NhbGxiYWNrLzE4NjMwLzVjYjgzMzk1YWNjNzM5NDMxNzBjZWFkNS8iLCAic2F2ZS1rZXkiOiAiMWhIMklmWlgwUlIzc1dvSS5wbmciLCAiZXhwaXJhdGlvbiI6IDE1NTU1NzYwMDF9*********",
  3. "authorization": "UPYUN allenzhang:aBIGd7s5Tjcc2khrnx2uxgjYuzw=",
  4. "upload_url": "https://v0.api.upyun.com/cloud-minapp-18****",
  5. "id": "5cac3d2299ecae0c9e8****6",
  6. "file_link": "https://cloud-minapp-18630.cloud.ifanrusercontent.com/1hDkLip5hcxdQpl5.jpg"
  7. }

状态码说明

200 获得授权凭证成功

400 参数错误(不支持上传的文件格式)

404 找不到文件分类 ID