又拍云 API 使用的那些小事

又拍云提供了丰富的 API 调用，为了减少用户在初次接入时可能会遇到的坑”，本文将对又拍云常用的 API 使用方法做个简单的梳理，力求让业务接入变得更简单，更高效。

目前我们的 API 主要有四大类，分别是：云存储 API，云处理 API，人工智能 API，后台管理 API。前三类 API 都有主流编程语言对应的 SDK 或可视化的集成工具。

SDK 的使用遵循说明文档配置环境，然后对方法进行引用，一般不会遇到太多的问题。不过有时我们需要抛开 SDK，自行根据文档来实现某个接口的某个功能时可能会遇到一些“坑”，调试的过程中有时候甚至会怀疑人生。调试 API 接口，除了直接用编程语言来调试，还推荐使用 Curl 命令或 Postman 来辅助调试。

云存储 API

云存储 API 是调用比较多的 API，在这个 API 中又以文件上传的接口调用最为频繁，我们就主要以这个接口为例，来做下详细讲述。

API 地址：http://v0.api.upyun.com
支持协议：HTTP ，HTTPS
认证方式：基本认证，签名认证
主要功能：上传文件，下载文件，删除（创建）文件（目录），获取文件信息，获取文件列表。

常见问题一：

上面是用 PUT 方法来上传文件，但是返回状态码 401，通过返回的 body 我们可以看出提示是比较清晰的：user not exists。这种情况一般是没有创建操作员或者创建了操作员但是没有授权给对应的服务。操作员这个概念会出现在云存储 API，云处理 API 和人工智能 API 中，所以这是个常见的 401 错误。

常见问题二：

依旧是401错误，不过返回的 body 信息不同：user need permission。这是提示操作员没有权限，因为我们对操作员的权限控制有三个，分别是：读取，写入，删除。

上传属于“写入”操作，所以需要把“可写入”权限勾选上。同理，如果在文件删除过程中出现该问题，那么就需要把“可删除”勾选上。

常见问题三：

调试工具正常，但是代码嵌入网页上传时候控制台报错。这是因为网站用的是 HTTPS 协议，但是请求的是 HTTP 协议的接口，浏览器是拒绝在 HTTPS 的网站内请求 HTTP 协议的地址的，所以把请求地址更改为：https://v0.api.upyun.com/ 即可。

常见问题四：上面三个问题都是用的基本认证，但是认证头并没有加密，只是简单的进行了 Base64 编码，如果在前端暴露出来，将会造成操作员账号泄露。就算只在后端使用，也存在一定的泄露风险。所以生产环境中一般使用签名认证。

文件上传有三种方法，

二进制 PUT 上传（适用于后端或者客户端上传）
表单 POST 上传（适用于浏览器上传）
FTP 上传

有时候我们出于某种需求，可能需要在前端使用 PUT 的方式进行浏览器上传。同样的，调试工具正常，但是代码嵌入网页上传时候控制台报错，接口返回 401 状态码，body 信息：need date header。

这是因为除了表单 POST 上传，其他用签名来认证的存储操作（PUT 上传，删除文件，云处理，内容识别等）都需要携带 Date 请求头，生成 Token 的时候 Date 的值也是参与运算的。但是，浏览器根据请求规范拒绝了自定义“unsafe header "Date"”，这怎么办？答案是为了兼容前端的一些请求场景，我们提供了自定义的 Date 请求头 —— X-Date，进行请求头设置和 Token 计算的时候用 X-Date 即可。当然也有人说那为什么不取消这个必须参数 Date 呢？这个校验头是出于安全考虑，从时间的维度上来尽可能的保障请求的合法性。

云处理 API

云处理 API 也是又拍云 API 中的一大类。云处理也需要操作员账号、密码以及权限等，所以上面云存储 API 中遇到账号问题也会在该 API 中出现，这里就不再赘述。

API 地址：http://p0.api.upyun.com，http://p1.api.upyun.com
支持协议：HTTP，HTTPS
认证方式：签名认证
主要功能：音视频异步（同步）处理，异步拉取，文件压缩及解压缩，文档转换。

云处理 API 的请求一般在服务端进行，前端只负责触发一个任务，所以可以避开浏览器的种种限制。这里常常遇到的问题无外乎是签名错误了。其实文档说明比较清楚了，签名的计算方式是：

Authorization: UPYUN <Operator>:<Signature>
<Signature> = Base64 (HMAC-SHA1 (<Password>,<Method>&<URI>&<Date>&<Content-MD5>))

一个成功的请求实例：

因为 Content-MD5 是非必选项，所以我们请求头中不需要添加 Content-MD5 请求头，那么计算签名的时候也就不需要把 body 的 MD5 参与进去了，如下：

Authorization: UPYUN <Operator>:<Signature>

<Signature> = Base64 (HMAC-SHA1 (<Password>,<Method>&<URI>&<Date>))

如果此时我们把 body 体

accept=json&service=tsqtestpic&notify_url=http://1.1.1.1&source=/x.mp4&tasks=W3siYXZvcHRzIjoiL3IvMy9zLzY0MHgzMjAvc3AvMTgwIiwicmV0dXJuX2luZm8iOnRydWUsInNhdmVfYXMiOiIveC5naWYiLCJ0eXBlIjoidmlkZW8ifV0= 的 MD5 值

d22d7d15f3111a4d1a3ea6359f35e78c 也参与 Signature 的计算，请求最后会报签名错误。也就是说如果请求头中没有使用 Content-MD5，那么计算签名时候就不能让 Content-MD5 参与计算，反之则需要 Content-MD5 参与计算，这个规则在云存储 API，人工智能 API 都是一致的。

人工智能API

人工智能 API 的调用规则与云存储和云处理的类似，也是使用的签名认证，签名的生成方式也一致。

API 地址：http://p0.api.upyun.com，http://banma.api.upyun.com
支持协议：HTTP，HTTPS
认证方式：签名认证
主要功能：图片识别，点播识别，文本识别

在调用内容识别API接口时，需要注意内容识别分为“有存储”和“无存储”两种鉴别方式。“有存储”指的是待鉴别的图片或者视频是存储在自己的存储服务中，此参与 Authorization 生成的是该存储的操作员账号和操作员密码，“无存储”指的是待鉴别的内容并没有在自己的存储中，此时的提交方式可以是内容本身或 URL，这种方式的 Authorization 生成用的是内容识别控制台中的 ClientKey 和 ClientSecret。

后台管理API

后台管理 API 是又拍云服务管理后台开放接口，使得用户可以对后台进行程序化配置，甚至开发出自己的简易管理后台。

API 地址：http://api.upyun.com
支持协议：HTTP，HTTPS
认证方式：Token 认证

Token 认证过程相对简单些，只需要添加一个请求头 Authorization: Bearer <Token> 来用对应的方法请求对应的接口即可，需要注意的是接口的 POST 和 PUT 请求的 body 都是 json 字符串，所以请求时 Content-Type 需要设置为 application/json。

以上主要对又拍云 API 的使用方法和常见问题做了简单的总结，结合接口的返回信息和文档说明，接入是一件比较简单的事情。在使用场景方面比如 PUT 上传时可以加上预处理作图请求头，图片会处理后再保存；POST 上传的同时可以加云处理的任务（如：色情识别，封面截图，转码适配等）。总体来说，这四大 API 的组合使用基本上可以满足用户的需求。