又拍雲 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 的組合使用基本上能夠知足用戶的需求。

推薦閱讀：

受到 1 萬點暴擊，二狗子被 DDoS 攻擊的慘痛經歷
五分鐘讀懂什麼是容器雲​