微信開(kāi)放平臺(tái)：朋友圈API參考文檔
用戶(hù)授權(quán)
客戶(hù)端的授權(quán)流程
針對(duì)沒(méi)有后臺(tái)服務(wù)器的 App 類(lèi)型，如移動(dòng)平臺(tái)的 App 應(yīng)用，微信使用 OAuth2.0 的 Implicit Grant 方式授權(quán)，流程如下：
- 用戶(hù)訪(fǎng)問(wèn)第三方應(yīng)用，使用到分享至微信朋友圈的功能，應(yīng)用檢測(cè)到?jīng)]有用戶(hù)的授權(quán)信息，于是將用戶(hù)引導(dǎo)至授權(quán)頁(yè)面;
- 當(dāng)用戶(hù)未登錄時(shí)，將要求先登錄，否則繼續(xù)下一步;
- 授權(quán)頁(yè)面為一個(gè)對(duì)話(huà)框，顯示應(yīng)用信息以及請(qǐng)求的訪(fǎng)問(wèn)權(quán)限，并提示用戶(hù)選擇允許或拒絕;
- 對(duì)話(huà)框?qū)⒅囟ㄏ蚧貞?yīng)用，若授權(quán)成功則帶上 Access Token，否則帶上相應(yīng)的錯(cuò)誤碼。
客戶(hù)端授權(quán)流程得到的 Access Token 有效期為 2 小時(shí)，過(guò)期后需重新走授權(quán)流程。
服務(wù)器端的授權(quán)流程
服務(wù)端的授權(quán)流程為 OAuth2.0 定義的 Authentication Code Grant 的授權(quán)方式，我們推薦朋友圈應(yīng)用使用服務(wù)端的授權(quán)流程。在該授權(quán)流程中，App 除了可以得到用戶(hù)的 AccessToken 外還有 RefreshToken， RefreshToken 過(guò)期時(shí)間為一年。
服務(wù)端的授權(quán)流程如下:
- 當(dāng)用戶(hù)未登錄時(shí)，將要求先登錄，否則繼續(xù)下一步;
- 授權(quán)頁(yè)面為一個(gè)對(duì)話(huà)框，顯示應(yīng)用信息以及請(qǐng)求的訪(fǎng)問(wèn)權(quán)限，并提示用戶(hù)選擇允許或拒絕;
- 當(dāng)用戶(hù)允許后，微信將以重定向的方式回到App，并帶上一個(gè)授權(quán)碼，否則將提示失敗;
- 第三方應(yīng)用通過(guò)后臺(tái)訪(fǎng)問(wèn)微信 API，通過(guò)授權(quán)碼換取Access Token和Refresh Token。
通過(guò)服務(wù)端的授權(quán)流程得到的 AccessToken 有效期為 30 天，過(guò)期后使用 RefreshToken 即可換取新的 AccessToken。
授權(quán)連接
URL: https://open.weixin.qq.com/oauth
| 參數(shù)列表 | 參數(shù)含義 |
|---|---|
| appid | 從微信開(kāi)放平臺(tái)申請(qǐng)的AppId |
| response_type | 返回類(lèi)型，值為code或token之一 |
| redirect_uri | 授權(quán)成功后的重定向頁(yè)面，默認(rèn)為App預(yù)留在微信的uri |
| scope | 可選參數(shù)，所申請(qǐng)授權(quán)的資源域，以空格分開(kāi)，目前僅支持并默認(rèn)選擇post_timeline |
| state | 可選參數(shù)，自定義重定向uri的參數(shù) |
服務(wù)端流程請(qǐng)求連接樣例:
https://open.weixin.qq.com/oauth?appid=hello&response_type=code
用戶(hù)成功授權(quán)后返回樣例:
HTTP/1.1 302 Found
Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA
用戶(hù)拒絕授權(quán)的返回樣例:
HTTP/1.1 302 Found
Location: https://client.example.com/cb?error=access_denied
客戶(hù)端流程請(qǐng)求連接樣例:
https://open.weixin.qq.com/oauth?appid=hello&response_type=token
用戶(hù)成功授權(quán)后返回樣例:
HTTP/1.1 302 Found
Location: https://client.example.com/cb#access_token=ASDFBCDEFGHIJKLMN&expires_in=259200
用戶(hù)拒絕授權(quán)的返回樣例:
HTTP/1.1 302 Found
Location: https://client.example.com/cb#error=access_denied
API列表
| 名稱(chēng) | 功能 |
|---|---|
| GET /token | 獲取Access Token |
| POST /media | 上傳附件 |
| GET /media/:media_id | 下載附件內(nèi)容 |
| POST /timeline | 發(fā)表到朋友圈 |
GET /token
URL: https://api.weixin.qq.com/token.format
用于通過(guò)授權(quán)code換取access token和refresh token，或用于通過(guò)refresh token換取新的access token。
| 參數(shù)列表 | 參數(shù)含義 |
|---|---|
| grant_type | 獲取的token類(lèi)型，authentication_code 或 refresh_token |
| code | 當(dāng)grant_type為authentication_code時(shí)填寫(xiě)，此為用戶(hù)授權(quán)后得到的授權(quán)碼 |
| refresh_token | 當(dāng)grant_type為refresh_token時(shí)填寫(xiě) |
| redirect_uri | 當(dāng)grant_type為authentication_code時(shí)填寫(xiě)，需和oauth步驟所填寫(xiě)的redirect_uri相同 |
當(dāng)應(yīng)用走服務(wù)器端的授權(quán)流程時(shí)，通過(guò)該API使用授權(quán)碼換取access token和refresh token，此時(shí)grant_type需設(shè)置為authentication_code，請(qǐng)求URL如下：
GET "https://api.weixin.qq.com/token?appid=wx1234hello" "&grant_type=authorization_code&code=4433222&redirect_Uri=" "http%3A//www.example.com/weixin_redirect"
返回樣例：
{
"refresh_token" : "93Zkx2gyQVaeIbS1CTDFSZilrVyj1Q1Ts2UeArlEnbrP6bKDyWAz4WlIHu_
wwasdfLNNLfmn023mNA0nX",
"access_token" : "3Zkx2gyQVaeIbS1CTDFSZilrVyj1Q1Ts2UeArlEnbrP6bKDyWAz4WlIHu_Lj
JqUNdYDYlyxrGOw1ywdb4sAyahgskuUBvSSx6EO2oxowQmcwdC3YTDkSJPTF
6yoKpfZkY2mIGBeaMZKsXcfWoTP94g",
"expires_in" : 7200
}
當(dāng)access token過(guò)期時(shí)，可通過(guò)refresh token獲取新的access token，請(qǐng)求樣例：
GET "https://api.weixin.qq.com/token?appid=wx1234abcd" "&grant_type=refresh_token&secret=egs1mwxkfpt459" "&refresh_token=93Zkx2gyQVaeIbS1CTDFSZilrVyj1Q1Ts2UeArlEnbrP6bKDyWAz4WlIHu_wwasdfLNNLfmn023mNA0nX"
返回樣例：
{
"access_token" : "K3Zkx2gyQVaeIbinDDmZ1CTDFSZilrVyj1Q1Ts2UeArlEnbrP6bKDyWAz4WlIHu_
LjJqUNdYDYlyxrGOw1ywdGGb4sAyahgskuUBvSSx6EO2oxowQmcwdC3YTDkSJPTF
6yoKpfZkY2mIGBeaMZKs",
"expires_in" : 7200
}
POST /media
URL: https://api.weixin.qq.com/media.format
| 參數(shù)列表 | 參數(shù)含義 |
|---|---|
| type | 附件類(lèi)型，目前僅支持image |
| media[] | 附件內(nèi)容 |
該API用于上傳一個(gè)附件到微信服務(wù)器，成功后將得到一個(gè)媒體id（media_id）表示該附件，從而分享至用戶(hù)朋友圈。
上傳的圖片大小限制為2M，如果原圖寬度超過(guò)640px，微信服務(wù)器將對(duì)圖片進(jìn)行等比例縮放后存儲(chǔ)。
請(qǐng)求樣例（使用curl工具）：
curl -F "media=@test.jpg" "https://api.weixin.qq.com/media?type=image&access_token=3Zkx2gyQVaeIbS1CTDFSZilrVyj1Q1Ts2UeArlEnbrP6bKDyWAz4WlIHu_LjJqUNdYDYlyxrGOw1ywdb4sAyahgskuUBvSSx6EO2oxowQmcwdC3YTDkSJPTF6yoKpfZkY2mIGBeaMZKsXcfWoTP94g"
返回樣例：
{
"media_id" : "fPPPmh9EBsgdrqaSJvl6nPvchUfbDxN8lmGTMBN2BWABP_usGso5Qx7raSraaXAT",
"type" : "image",
"created_at" : 1335415865
}
GET /media/:media_id
URL: https://api.weixin.qq.com/media/:media_id.format
| 參數(shù)列表 | 參數(shù)含義 |
|---|---|
| media_id | 附件id |
該API用于下載媒體附件。
請(qǐng)求樣例（使用curl工具）：
curl "https://api.weixin.qq.com/media/fPPPmh9EBsgdrqaSJvl6nPvchUfbDxN8lmGTMBN2BWABP_usGso5Qx7raSraaXAT?access_token=3Zkx2gyQVaeIbS1CTDFSZilrVyj1Q1Ts2UeArlEnbrP6bKDyWAz4WlIHu_LjJqUNdYDYlyxrGOw1ywdb4sAyahgskuUBvSSx6EO2oxowQmcwdC3YTDkSJPTF6yoKpfZkY2mIGBeaMZKsXcfWoTP94g"
POST /timeline
URL: https://api.weixin.qq.com/timeline.format
| 參數(shù)列表 | 參數(shù)含義 |
|---|---|
| content_type | 指定消息的類(lèi)型，必填，目前支持五類(lèi)：text、photo、feed、video和music。 |
| title | 一句話(huà)描述，當(dāng)content_type是feed時(shí)為必填字段。 對(duì)于content_type為feed，該字段可以是文章標(biāo)題； 對(duì)于content_type為music，該字段可以是歌曲名和歌手； 對(duì)于content_type為video，該字段可以是視頻的名稱(chēng)。 |
| media_list | media_id列表，content_type為feed、music和video時(shí)必填。多個(gè)media_id以“,”分隔。 當(dāng)content_type為photo，最多可以提供9個(gè)media_id，多出部分會(huì)被拋棄。 當(dāng)content_type為feed、music和video時(shí)，只可提供1個(gè)media_id作為消息的縮略圖，多出部分會(huì)被拋棄。 |
| media_url | 音樂(lè)文件地址，當(dāng)content_type為music時(shí)必填。協(xié)議支持http和https，格式支持mp3和wav。 |
| content_url | 內(nèi)容鏈接，當(dāng)content_type為feed、music和video時(shí)必填 |
| coordinates | 經(jīng)緯度，用“,”分隔，可選。數(shù)據(jù)格式為(latitude,longitude) |
該API用于分享內(nèi)容至用戶(hù)的朋友圈中，title或media_list兩個(gè)參數(shù)至少選擇其中之一。
請(qǐng)求示例 1（使用curl工具）：
curl -d "title=hello&coordinates=10.00,10.00&media_list=fPPPmh9EBsgdrqaSJvl6nPvchUfbDxN8lmGTMBN2BWABP_usGso5Qx7raSraaXAT,fPPPmh9EBsgdrqaSJvl6nPvchUfbDxN8lmGTMBN2BWABP_usGso5Qx7raSraaXAT" "https://api.weixin.qq.com/timeline?access_token=3Zkx2gyQVaeIbS1CTDFSZilrVyj1Q1Ts2UeArlEnbrP6bKDyWAz4WlIHu_LjJqUNdYDYlyxrGOw1ywdb4sAyahgskuUBvSSx6EO2oxowQmcwdC3YTDkSJPTF6yoKpfZkY2mIGBeaMZKsXcfWoTP94g"
成功返回：
{
"id" : 11232109051049549826,
"created_at" : 1333007682
}
失敗返回：
{
"time" : 1338972300,
"error" : { "msg": "content_url is missing", "code": 40329 }
}
請(qǐng)求示例 2：
curl -d "title=Complcated&coordinates=24.00,114.00&media_list=L5JPCzX96wnwcE4Hthh&content_url=http%3A%2F%2Fy.qq.com%2Fi%2Fsong.html%23p%3D7B2273&media_url=http%3A%2F%2Fy.qq.com%2Fi%2Fsong.html%23p%3D7B2273&content_type=music" "https://api.weixin.qq.com/timeline?access_token=3Zkx2gyQVaeIbS1CTDFSZilrVyj1Q1Ts2UeArlEnbrP6bKDyWAz4WlIHu_LjJqUNdYDYlyxrGOw1ywdb4sAyahgskuUBvSSx6EO2oxowQmcwdC3YTDkSJPTF6yoKpfZkY2mIGBeaMZKsXcfWoTP94g"
請(qǐng)求示例2在微信朋友圈展示的效果圖如下：：
