又拍雲提供了豐富的 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¬ify_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 的組合使用基本上可以滿足使用者的需求。
推薦閱讀：