上传文件

上传流程图

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

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

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

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

接口

POST https://cloud.minapp.com/oserve/v2.1/upload/

参数说明

Content-Type: application/json

参数类型必填说明
filenameStringN上传的文件名
category_idStringN上传文件的所属分类,格式为文件分类的 ID 数组

返回参数

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

代码示例

  1. curl -X POST \
  2. -H "Authorization: Bearer 52ce223c5adbb66fa188a959a8b08889adb3580c" \
  3. -H "Content-Type: application/json" \
  4. -d '{
  5. "filename":"crop.gif",
  6. "category_id":"5a1ba7b708443e7fc5f2fb18"
  7. }' \
  8. https://cloud.minapp.com/oserve/v2.1/upload/
  1. var request = require('request');
  2. var opt = {
  3. uri: 'https://cloud.minapp.com/oserve/v2.1/upload/',
  4. method: 'POST',
  5. headers: {
  6. Authorization: `Bearer ${token}`
  7. },
  8. json: { // 指定 data 以 "Content-Type": 'application/json' 传送
  9. filename: 'aTest.xlsm',
  10. category_id: '5a3b569109a80579061d63xx'
  11. }
  12. }
  13. request(opt, function(err, res, body) {
  14. console.log(res.statusCode, body)
  15. })
  1. <?php
  2. $param = array(
  3. 'filename' =>'aTest.xlsm',
  4. 'category_id'=> '5a3b569109a80579061d63xx'
  5. );
  6. $url = 'https://cloud.minapp.com/oserve/v2.1/upload/';
  7. $ch = curl_init();
  8. $header = array(
  9. "Authorization: Bearer {$token}",
  10. 'Content-Type: application/json; charset=utf-8'
  11. );
  12. curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
  13. curl_setopt($ch, CURLOPT_TIMEOUT, 30);
  14. curl_setopt($ch, CURLOPT_URL, $url);
  15. curl_setopt($ch, CURLOPT_POST, true);
  16. curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($param));
  17. curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  18. curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
  19. $res['response'] = curl_exec($ch); // 反馈结果
  20. $res['status_code'] = curl_getinfo($ch, CURLINFO_HTTP_CODE); // 请求状态码
  21. curl_close($ch);

返回示例

  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 获得授权凭证成功,400 参数错误(不支持上传的文件格式),404 找不到文件分类 ID

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

接口

POST {UPLOAD_URL}

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

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

参数说明

Content-Type: multipart/form-data

参数类型必填说明
authorizationStringY授权凭证
fileStringY上传的文件流
policyStringY授权凭证

代码示例

  1. curl -X POST \
  2. -H "Authorization: Bearer 52ce223c5adbb66fa188a959a8b08889adb3580c" \
  3. -H "Content-Type: multipart/form-data" \
  4. -F authorization="UPYUN allenzhang:MzmYCcWVjrWoeovC4+tM5Bgwusg=" \
  5. -F file=@"filename" \
  6. -F policy="eyJkYXRlIjogIldlZCwgMDYgRGVjIDIwMTcgMDM6MzI6MzMgR01UIiwgIm5vdGlmeS11cmwiOiAiaHR0cHM6Ly9zc28uaWZhbnIuY29tL2V4dGFwaS9oeWRyb2dlbi91cHl1bi9jYWxsYmFjay8yODcvNWEyNzY0ZDFmZmYxZDYxYWQwZWNhMjQ1LyIsICJidWNrZXQiOiAiY2xvdWQtbWluYXBwLTI4NyIsICJzYXZlLWtleSI6ICIxZU1RUmxrSndoZ2FNaUNnLmdpZiIsICJleHBpcmF0aW9uIjogMTUxMjUzMTQ1M30=" \
  7. https://v0.api.upyun.com/cloud-minapp-287
  1. var request = require('request');
  2. var fs = require('fs');
  3. var opt = {
  4. uri: upload_url, // 获取上传文件的授权凭证成功返回的 upload_url
  5. method: 'POST',
  6. headers: {
  7. Authorization: `Bearer ${token}`
  8. },
  9. formData: { // 指定 data 以 "Content-Type": "multipart/form-data" 传送
  10. authorization,
  11. policy,
  12. file: fs.createReadStream(__dirname + '/demo.js') // 参数需为文件流
  13. }
  14. }
  15. request(opt, function(err, res, body) {
  16. console.log(res.statusCode, body)
  17. })
  1. <?php
  2. // 兼容 PHP 版本
  3. if (class_exists('CURLFile')) {
  4. $param = array(
  5. 'file' => new \CURLFile(realpath( __DIR__.'/demo.gif'),'gif','demo.gif')
  6. );
  7. } else {
  8. $param = array(
  9. 'file'=>'@'.realpath( __DIR__.'/demo.gif')
  10. );
  11. }
  12. $param['authorization'] = {$authorization};//获取上传文件的授权凭证成功返回的 authorization
  13. $param['policy'] = {$policy};//获取上传文件的授权凭证成功返回的 policy
  14. $url = {$upload_url}; //获取上传文件的授权凭证成功返回的 upload_url
  15. $ch = curl_init();
  16. $header = array(
  17. "Authorization: Bearer {$token}",
  18. 'Content-Type: multipart/form-data; charset=utf-8'
  19. );
  20. curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
  21. curl_setopt($ch, CURLOPT_TIMEOUT, 30);
  22. curl_setopt($ch, CURLOPT_URL, $url);
  23. curl_setopt($ch, CURLOPT_POST, true);
  24. curl_setopt($ch, CURLOPT_POSTFIELDS, $param);
  25. curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  26. curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
  27. $res['response'] = curl_exec($ch); // 反馈结果
  28. $res['status_code'] = curl_getinfo($ch, CURLINFO_HTTP_CODE); // 请求状态码
  29. curl_close($ch);

返回示例

  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 https://cloud.minapp.com/oserve/v1/upload/

参数说明

Content-Type: application/json

参数类型必填说明
filenameStringN上传的文件名
category_idStringN上传文件的所属分类,格式为文件分类的 ID 数组

返回参数

参数类型说明
idString上传的文件 ID
policyString文件上传配置
authorizationString文件上传凭证
file_linkString文件上传成功后的访问地址
upload_urlString上传文件的目标地址

代码示例

  1. curl -X POST \
  2. -H "Authorization: Bearer 52ce223c5adbb66fa188a959a8b08889adb3580c" \
  3. -H "Content-Type: application/json" \
  4. -d '{
  5. "filename":"crop.gif",
  6. "category_id":"5a1ba7b708443e7fc5f2fb18"
  7. }' \
  8. https://cloud.minapp.com/oserve/v1/upload/
  1. var request = require('request');
  2. var opt = {
  3. uri: 'https://cloud.minapp.com/oserve/v1/upload/',
  4. method: 'POST',
  5. headers: {
  6. Authorization: `Bearer ${token}`
  7. },
  8. json: { // 指定 data 以 "Content-Type": 'application/json' 传送
  9. filename: 'aTest.xlsm',
  10. category_id: '5a3b569109a80579061d63xx'
  11. }
  12. }
  13. request(opt, function(err, res, body) {
  14. console.log(res.statusCode, body)
  15. })
  1. <?php
  2. $param = array(
  3. 'filename' =>'aTest.xlsm',
  4. 'category_id'=> '5a3b569109a80579061d63xx'
  5. );
  6. $url = 'https://cloud.minapp.com/oserve/v1/upload/';
  7. $ch = curl_init();
  8. $header = array(
  9. "Authorization: Bearer {$token}",
  10. 'Content-Type: application/json; charset=utf-8'
  11. );
  12. curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
  13. curl_setopt($ch, CURLOPT_TIMEOUT, 30);
  14. curl_setopt($ch, CURLOPT_URL, $url);
  15. curl_setopt($ch, CURLOPT_POST, true);
  16. curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($param));
  17. curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  18. curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
  19. $res['response'] = curl_exec($ch); // 反馈结果
  20. $res['status_code'] = curl_getinfo($ch, CURLINFO_HTTP_CODE); // 请求状态码
  21. curl_close($ch);

返回示例

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

状态码说明

200 获得授权凭证成功,400 参数错误(不支持上传的文件格式),404 找不到文件分类 ID