素材管理 · 企微客服開發

[TOC] ## 概述企業使用自定義的資源時，比如發送本地圖片、視頻等。為了實現同一資源文件，一次上傳可以多次使用，我們提供了素材管理接口：以media\_id來標識資源文件，實現文件的上傳與下載。 ## 上傳臨時素材把媒體文件上傳到微信客服的服務器。 > 素材上傳得到media\_id，該media\_id僅三天內有效 **請求方式：**POST（**HTTPS**） **請求地址：**https://qyapi.weixin.qq.com/cgi-bin/media/upload?access\_token=ACCESS\_TOKEN&type=TYPE 使用multipart/form-data POST上傳文件，文件標識名為”media” **參數說明：** | 參數 | 必須 | 說明 | | --- | --- | --- | | access\_token | 是 | 調用接口憑證 | | type | 是 | 媒體文件類型，分別有圖片（image）、語音（voice）、視頻（video），普通文件（file） | POST的請求包中，form-data中媒體文件標識，應包含有**filename**、filelength、content-type等信息 > filename標識文件展示的名稱。比如，使用該media\_id發消息時，展示的文件名由該字段控制 **請求示例：** ~~~ POST https://qyapi.weixin.qq.com/cgi-bin/media/upload?access_token=accesstoken001&type=file HTTP/1.1Content-Type: multipart/form-data; boundary=-------------------------acebdf13572468Content-Length: 220---------------------------acebdf13572468Content-Disposition: form-data; name="media";filename="wework.txt"; filelength=6Content-Type: application/octet-streammytext---------------------------acebdf13572468-- ~~~ **返回數據：** ~~~ { "errcode": 0, "errmsg": ""， "type": "image", "media_id": "1G6nrLmr5EC3MMb_-zK1dDdzmd0p7cNliYu9V5w7o8K0", "created_at": "1380000000"} ~~~ **參數說明：** | 參數 | 說明 | | --- | --- | | type | 媒體文件類型，分別有圖片（image）、語音（voice）、視頻（video），普通文件(file) | | media\_id | 媒體文件上傳后獲取的唯一標識，3天內有效 | | created\_at | 媒體文件上傳時間戳 | **上傳的媒體文件限制** 所有文件size必須大于5個字節 * 圖片（image）：2MB，支持JPG,PNG格式 * 語音（voice）：2MB，播放長度不超過60s，**僅支持**AMR格式 * 視頻（video）：10MB，支持MP4格式 * 普通文件（file）：20MB ## 獲取臨時素材獲取微信客服的臨時素材。即下載臨時的多媒體文件。 **請求方式：**GET（**HTTPS**） **請求地址：**https://qyapi.weixin.qq.com/cgi-bin/media/get?access\_token=ACCESS\_TOKEN&media\_id=MEDIA\_ID **參數說明：** | 參數 | 必須 | 說明 | | --- | --- | --- | | access\_token | 是 | 調用接口憑證 | | media\_id | 是 | 媒體文件id, 見[上傳臨時素材](https://work.weixin.qq.com/servicer/docs_wx?id=26580#h2-u4E0Au4F20u4E34u65F6u7D20u6750) | **返回說明：** 正確時返回（和普通的http下載相同，請根據http頭做相應的處理）： ~~~ HTTP/1.1 200 OK Connection: close Content-Type: image/jpeg Content-disposition: attachment; filename="MEDIA_ID.jpg" Date: Sun, 06 Jan 2013 10:20:18 GMT Cache-Control: no-cache, must-revalidate Content-Length: 339721 Xxxx ~~~ 錯誤時返回（這里省略了HTTP首部）： ~~~ { "errcode": 40007, "errmsg": "invalid media_id"} ~~~ **附注：支持斷點下載（分塊下載）** 本接口支持通過在http header里指定`Range`來分塊下載。在文件很大，可能下載超時的情況下，推薦使用分塊下載。以curl命令進行測試為例，假如我有一個2048字節的文件，下面是獲取文件前1024字節： > curl ‘https://qyapi.weixin.qq.com/cgi-bin/media/get?access\_token=ACCESS\_TOKEN&media\_id=MEDIA\_ID’ -i -H “Range: bytes=0-1023” 生成如下http請求： > GET /cgi-bin/media/get?access\_token=ACCESS\_TOKEN&media\_id=MEDIA\_ID HTTP/1.1 > Host: qyapi.weixin.qq.com > Range: bytes 0-1023 服務器端會返回狀態碼為 206 Partial Content 的響應： > HTTP/1.1 206 Partial Content > Accept-Ranges: bytes > Content-Range: bytes 0-1023/2048 > Content-Length: 1024 > … > (1024 Bites binary content) 可以看到響應中有如下特點： * 狀態碼是`206 Partial Content`，而非`200 ok` * 返回的header中，`Accept-Ranges`首部表示可用于定義范圍的單位 * 返回的header中，`Content-Range`首部表示這一部分內容在整個資源中所處的位置更多協議詳情參考[RFC: Range Requests](https://tools.ietf.org/html/rfc7233#section-4.1)