為什么要遷移到新版接口

• 全新的新版（V2）接口較舊版（V1）接口具有更豐富的功能、更高效、更規(guī)范、更可控等優(yōu)勢，很好地滿足了開發(fā)者的需求。

• V1接口使用的OAuth1.0授權(quán)方式無法適應(yīng)進(jìn)一步的開放，已被各大開放平臺棄用，由全新的OAuth2.0授權(quán)方式取代。

新版接口較舊版接口的優(yōu)勢

• 1、更多功能
  • a）V2較V1新增了大量接口，增強(qiáng)的關(guān)系接口、搜索話題接口、短鏈接口、熱門微博接口、位置服務(wù)接口、通知接口、通用
    • 服務(wù)接口、社交電視接口；
  • b）另外，SCOPE授權(quán)功能、好友分組接口、邀請接口、社交化接口、表態(tài)接口也即將開放。

• 2、更高效
  • a）微博、評論、用戶等返回值增加trim開關(guān)，按需返回?cái)?shù)據(jù)，減少冗余數(shù)據(jù)占用帶寬，適應(yīng)移動應(yīng)用特點(diǎn)；
  • b）微博評論、轉(zhuǎn)發(fā)數(shù)可以隨微博返回值直接返回，無需額外調(diào)用接口，減輕程序負(fù)擔(dān)；
  • c）用戶返回值增加互粉好友數(shù)、是否關(guān)注我、是否被我關(guān)注等信息，直觀地體現(xiàn)用戶關(guān)系；
  • d）timeline類接口未來將全部增加篩選過濾功能（feature）和應(yīng)用隔離功能（base_app），可按應(yīng)用需要篩選和隔離消息流。

• 3、更規(guī)范
  • a）統(tǒng)一參數(shù)、返回值字段，全部小寫字母，單詞和單詞之間用“_”鏈接；
  • b）接口URI，全部采用：域+版本號+資源類+接口名+返回值格式+參數(shù)；
  • c）核心字段：微博、評論、用戶、關(guān)系全部標(biāo)準(zhǔn)化，避免核心字段在不同接口中返回值不同，從而降低開發(fā)成本；
  • d）統(tǒng)一的新錯誤返回值格式及錯誤碼，V2錯誤碼地址：http://open.weibo.com/wiki/Error_code。

• 4、更可控
  • a）將接口分為兩級權(quán)限：普通、高級，使高級功能接口的權(quán)限控制更清晰、透明；
  • b）添加了接口授權(quán)管理控制臺：接口可以分組打包，并對應(yīng)用開放授權(quán)及接口級別的申請，縮減申請流程。

V1禁止調(diào)用時間

• 1、2012年7月24日，禁止所有“未審核應(yīng)用”調(diào)用V1接口；
• 2、2012年8月27日，禁止所有用戶量在1000以下的“已審核應(yīng)用”調(diào)用V1接口（已審核Xweibo應(yīng)用暫時不受影響）；
• 3、2012年10月初左右，禁止所有應(yīng)用調(diào)用V1接口，具體時間請關(guān)注@微博開放平臺 。
• 4、2012年12月20日，禁止“累計(jì)使用人數(shù)小于500,000”的應(yīng)用使用V1接口。

• 禁止調(diào)用V1接口的應(yīng)用在調(diào)用V1接口時會返回：“40109 Oauth Error: consumer_key_refused! ” 錯誤提示。

• V1接口將在近期全面下線，本文為所有仍使用V1接口的已審核應(yīng)用提供遷移引導(dǎo)，幫助您更快地完成遷移。

遷移中常見問題

• 1、Xweibo組件及應(yīng)用如何過度到V2版？
  • Xweibo已審核上線應(yīng)用在10月左右暫時不受影響，需要積極配合Xweibo官方提示進(jìn)行相應(yīng)的升級。請關(guān)注Xweibo官網(wǎng)：http://x.weibo.com 。

• 2、V1中的私信及獲取用戶信息接口為什么不開放？
  • 私信及涉及隱私的用戶信息接口被大量應(yīng)用濫用，導(dǎo)致大量用戶投訴，給平臺的開放造成了非常惡劣影響，出于對用戶隱私的保護(hù)，平臺決定不再開放此類導(dǎo)致用戶信息泄漏的接口。

• 3、OAuth2.0授權(quán)需要申請嗎？
  • OAuth2.0授權(quán)無需申請，任何應(yīng)用都可以使用。
  • 需要額外申請的是授權(quán)有效期或客戶端驗(yàn)證授權(quán)。授權(quán)有效期可在應(yīng)用控制臺，接口管理標(biāo)簽下的授權(quán)機(jī)制選項(xiàng)中進(jìn)行在線申請，客戶端驗(yàn)證授權(quán)申請方式參見第二個問題。

• 4、怎么申請客戶端的驗(yàn)證授權(quán)（Resource Owner Password Credentials）方式？
  • 因?yàn)镺Auth2.0的客戶端驗(yàn)證授權(quán)會獲得用戶明文密碼，所以實(shí)行有限開放。

• • 申請條件：
  • a）應(yīng)用分類屬于桌面客戶端、手機(jī)客戶端。
  • b）應(yīng)用本身已經(jīng)通過開放平臺文案、廣場審核，并在廣場上展示超過15天。
  • c）應(yīng)用使用人數(shù)在30000以上。
  • d）應(yīng)用本身功能與微博關(guān)聯(lián)緊密。

• • 滿足條件后在應(yīng)用控制臺的“接口管理”-->“授權(quán)機(jī)制”中申請。

• 5、手機(jī)客戶端、PC客戶端應(yīng)用是否需要設(shè)置回調(diào)頁？
  • 需要，使用Web應(yīng)用的驗(yàn)證授權(quán)(Authorization Code)方式的客戶端也需要設(shè)置授權(quán)回調(diào)頁或綁定域名，在程序中以webview的方式進(jìn)行調(diào)用授權(quán)頁面返回code，具體實(shí)現(xiàn)參考相應(yīng)的客戶端SDK：http://open.weibo.com/wiki/SDK。

• 6、如何查詢應(yīng)用的access_token有效期是多少？
  • a）桌面客戶端、手機(jī)客戶端類應(yīng)用，測試：1天、盡審核：7天、審核后并上廣場展示后：90天。
  • b）非客戶端類應(yīng)用，測試1天、普通7天、中級15天、高級30天、合作90天。

• 7、如何申請延長應(yīng)用的access_token有效期？
  • a）桌面客戶端、手機(jī)客戶端類應(yīng)用，未審核應(yīng)用在應(yīng)用控制臺申請審核通過后7天，如需要達(dá)到90天有效期，審核通過后
    • 在申請廣場審核。
  • b）非客戶端類應(yīng)用，未審核應(yīng)用在應(yīng)用控制臺申請審核通過后為普通級別7天， 如需申請更高級別，在應(yīng)用控制臺“接口管
    • 理”-->“調(diào)用頻次”中進(jìn)行申請。

• 8、如何計(jì)算某個用戶的access_token過期時間？
  • a）用戶授權(quán)時，oauth2/access_token接口返回的expires_in（單位：秒）值就是access_token的生命周期。
  • b）從上述對應(yīng)表中，找到應(yīng)用所對應(yīng)的授權(quán)有效期，過期時間 = 用戶授權(quán)時間 + 授權(quán)有效期。

• • 應(yīng)用的授權(quán)有效期可以訪問接口訪問權(quán)限說明或在應(yīng)用控制臺查看。

• 9、access_token過期后怎么處理？
  • access_token過期調(diào)用接口時，平臺會返回錯誤碼為21332的錯誤，此時需要引導(dǎo)用戶重新進(jìn)行授權(quán)。建議在每次獲得用戶授權(quán)時保存過期時間，在每次調(diào)用接口前判斷用戶access_token是否過期。

• • 引導(dǎo)已授權(quán)用戶再次授權(quán)時，如果此用戶為已登錄微博狀態(tài)，則授權(quán)頁面為“一閃而過”無需用戶再點(diǎn)擊“授權(quán)”按鈕，如果想讓用戶重新登錄授權(quán)，則在調(diào)用authorize接口是傳入?yún)?shù)：forcelogin=true，默認(rèn)不填（授權(quán)頁一閃而過）此參數(shù)相當(dāng)于forcelogin=false。

• 10、已上線應(yīng)用如何進(jìn)行本地測試？
  • a）應(yīng)用不含高級權(quán)限或高級接口，建議申請一個普通的Appkey進(jìn)行本地測試；
  • b）應(yīng)用含高級接口或高級權(quán)限，可以考慮綁定hosts指向本地測試代碼進(jìn)行測試。
    • 例如：應(yīng)用redirect_uri為：http://aa.abc.com/index.php ，而對應(yīng)的本地地址為http://127.0.0.1/index.php，則您可
      • 以將測試機(jī)hosts綁定成：127.0.0.1 aa.abc.com 。

• 11、如何將已授權(quán)用戶從OAuth1.0過度到OAuth2.0授權(quán)？
  • 應(yīng)用授權(quán)方式從OAuth1.0遷移到OAuth2.0時，應(yīng)用的授權(quán)用戶總數(shù)不變，以下是進(jìn)行用戶過度的兩個建議：
  • a）直接上線OAuth2.0授權(quán)版本，OAuth2.0獲取access_token時返回用戶的uid，根據(jù)此uid判斷該用戶為老用戶或新用
    • 戶，新增或更新數(shù)據(jù)庫中用戶access_token等信息；
  • b）使用get_oauth2_token接口換取OAuth2.0的access_token，此方法可以免去用戶對OAuth2.0第一次授權(quán)，適當(dāng)延長過
    • 度OAuth2.0的時間以完成a）的實(shí)現(xiàn)（對于授權(quán)有效期較長或客戶端類應(yīng)用可以考慮此方法）。

• • • 注意：做批量換取是需謹(jǐn)慎，同一個OAuth1.0的Access Token只能換取一次(多次調(diào)用將返回同一個token)，過期時間
      • • 從第一次換取的時候計(jì)算。

• 12、遷移時是否需要添加測試帳號？
  • a）測試帳號僅對未審核應(yīng)用限制，如果您的應(yīng)用在V1時已經(jīng)審核通過，則無需添加測試用戶。
  • b）如果您使用了未審核的Appkey進(jìn)行測試，需要您在應(yīng)用或網(wǎng)站控制臺“應(yīng)用信息”或“網(wǎng)站信息”-->“測試帳號”中添加測試帳
    • 號，未審核應(yīng)用只有應(yīng)用創(chuàng)建者與測試帳號才能調(diào)用接口。

• 13、V2版接口返回值為什么僅支持JSON格式不支持XML格式返回？
  • a）接口返回值中可能會含有html等字段，采用XML格式返回時需要對html進(jìn)行特殊處理，直接影響到平臺包裝返回值及開
    • 發(fā)者解析返回值的效率；
  • b）對于JS等語言在解析復(fù)雜的XML難度較高，效率較低；
  • c）XML格式較JSON采用Key-Value的形式有很大冗余，不符合手機(jī)客戶端等對性能要求較高的應(yīng)用需求。

• 14、有哪些高級接口，怎么申請新版高級接口？
  • 在V2接口文檔中接口名稱后標(biāo)注著： 圖標(biāo)則表示此接口為高級接口。高級接口申請要求應(yīng)用需要通過文案審核，并無作惡情況發(fā)生。其他要求及申請流程見：高級接口申請指南。

• 15、閱讀完遷移指南后仍有問題怎么辦？
  • a）通過開放平臺問答系統(tǒng)快速獲得幫助；
  • b）將問題通過評論的方式發(fā)送到@微博API 與遷移相關(guān)的微博下，我們將一一解答。

• 其他問題詳見：接口問題FAQ。

V1到V2怎么遷移

簡述

• V1遷移到V2主要需要完成OAuth1.0到OAuth2.0的過度及完成V1原有接口與V2中新接口的對應(yīng)替換。

遷移時需要完成的工作

• 1、授權(quán)方式的遷移，OAuth1.0升級到OAuth2.0；
• 2、閱讀遷移注意事項(xiàng)及常見問題解決建議；
• 3、新舊接口的遷移，接口調(diào)用地址、調(diào)用方式、參數(shù)、返回值、錯誤信息處理的代碼改造。

OAuth1.0升級到OAuth2.0

• 1、OAuth2.0簡述
  • OAuth2.0是較OAuth1.0更簡單更安全的授權(quán)方式，同時支持Web，桌面和移動應(yīng)用。是未來微博開放平臺最主要的用戶身份驗(yàn)證和授權(quán)方式。

• 2、遷移前準(zhǔn)備
  • 請先閱讀OAuth2.0開發(fā)指南。
  • OAuth2.0授權(quán)方式與OAuth1.0相比，引入授權(quán)回調(diào)頁與綁定域名，簡化了授權(quán)流程，同時也提升了授權(quán)的安全性。

• • 在實(shí)現(xiàn)OAuth2.0授權(quán)方式前，針對不同的應(yīng)用我們需要設(shè)置應(yīng)用的授權(quán)回調(diào)頁或進(jìn)行域名的綁定，用于獲得授權(quán)成功后返回的code，再通過code獲取access_token。

• • 使用開發(fā)者帳號登錄http://open.weibo.com，進(jìn)入“我的應(yīng)用”控制臺需要遷移的應(yīng)用進(jìn)行設(shè)置：
  • a）網(wǎng)站接入類
    • 點(diǎn)擊控制臺導(dǎo)航“網(wǎng)站信息”，在網(wǎng)站基本信息中查看網(wǎng)站域名。如果您的網(wǎng)站應(yīng)用還未驗(yàn)證所有權(quán)，會提示您進(jìn)行所有權(quán)驗(yàn)證，點(diǎn)擊進(jìn)入驗(yàn)證頁面完成所有權(quán)驗(yàn)證。Web應(yīng)用請參考：Web應(yīng)用遷移指引 。

• • • 注意：驗(yàn)證時填寫的網(wǎng)站域名即為您的應(yīng)用的綁定域名。

• • b）站內(nèi)應(yīng)用
    • 站內(nèi)應(yīng)用已經(jīng)是OAuth2.0授權(quán)方式，無需做改動。

• • c）客戶端應(yīng)用 & 其他應(yīng)用
    • 點(diǎn)擊控制臺導(dǎo)航“應(yīng)用信息”—> “高級信息”，進(jìn)行授權(quán)回調(diào)頁或域名的綁定。設(shè)置回調(diào)頁不需要二審，方便您進(jìn)行測試開發(fā)。綁定域名需要進(jìn)行二審，二審時線上應(yīng)用不受影響，綁定域名增加應(yīng)用的安全性，同時該域名下的所有頁面都可作為授權(quán)回調(diào)頁。

• • • 注意：客戶端也需要設(shè)置授權(quán)回調(diào)頁或綁定域名，在程序中以webview的方式進(jìn)行調(diào)用授權(quán)頁面返回code，具體實(shí)現(xiàn)可
      • • 以參考：移動應(yīng)用遷移指引 。 其他客戶端可以參考相應(yīng)SDK：http://open.weibo.com/wiki/SDK 。

• 3、OAuth2.0授權(quán)實(shí)現(xiàn)
  • 主要流程（請先閱讀OAuth2.0開發(fā)指南）：

• • a）引導(dǎo)需要授權(quán)的用戶訪問如下地址

• • • https://api.weibo.com/oauth2/authorize?client_id=YOUR_APP_KEY&response_type=code&redirect_uri=YOUR_REGISTERED_REDIRECT_URI ；

• • • 注意：redirect_uri必須為綁定域名下網(wǎng)頁或設(shè)置的回調(diào)地址。

• • b）如果用戶同意授權(quán),頁面跳轉(zhuǎn)至 YOUR_REGISTERED_REDIRECT_URI/?code=CODE

• • • 注意：每次返回的code值都是不一樣的且在換取access_token后失效。

• • c）使用code換取access_token

• • • https://api.weibo.com/oauth2/access_token?client_id=YOUR_APP_KEY&client_secret=YOUR_APP_SECRET&grant_type=authorization_code&redirect_uri=YOUR_REGISTERED_REDIRECT_URI&code=CODE ；

• • • 注意：必須使用POST方式提交，其中client_id=YOUR_APP_KEY&client_secret=YOUR_APP_SECRET可以使用
      • • basic方式加入header中。

• • d）返回值
    • {"access_token":"SlAV32hkKG","remind_in":"3600","expires_in":3600,"uid":"1902538057"}
    • 注意：OAuth2.0的access_token較OAuth1.0具有一定的有效期，當(dāng)access_token過期時需要引導(dǎo)用戶重新授權(quán)。應(yīng)用
      • • 的授權(quán)有效期可以訪問接口訪問權(quán)限說明或在應(yīng)用控制臺查看。

• • e）使用獲得的OAuth2.0 Access Token調(diào)用API
    • 讀取接口一般使用GET方式提交，如：
    • 接口：statuses/home_timeline
    • 調(diào)用：https://api.weibo.com/2/statuses/home_timeline.json?access_token=SlAV32hkKG&count=20 ；

• • • 寫入接口必須使用POST方式提交，如：
    • 接口：statuses/upload
    • 調(diào)用：https://upload.api.weibo.com/2/statuses/upload.json

• • • 注意：參數(shù)信息放入header及body中，除access_token外，其他參數(shù)必須放入body中請求。
    • upload請求消息體舉例：

• • • • => Send header, 301 bytes (0x12d)
      • POST /2/statuses/upload.json HTTP/1.1
      • User-Agent: curl/7.19.4 (i586-pc-mingw32msvc) libcurl/7.19.4 Ope
      • nSSL/0.9.8g zlib/1.2.3
      • Host: upload.api.weibo.com
      • Accept: */*
      • Content-Length: 38694
      • Expect: 100-continue
      • Content-Type: multipart/form-data; boundary=--------------------
      • --------8933e7b00565

• • • • <= Recv header, 23 bytes (0x17)
      • HTTP/1.1 100 Continue
      • => Send data, 370 bytes (0x172)
      • ------------------------------8933e7b00565
      • Content-Disposition: form-data; name="access_token"

• • • • 2.00RQs9XCmlEQDD4fb4b0bfe3Be7ZQE
      • ------------------------------8933e7b00565
      • Content-Disposition: form-data; name="status"

• • • • Test02
      • ------------------------------8933e7b00565
      • Content-Disposition: form-data; name="pic"; filename="psu.jpg"
      • Content-Type: image/jpeg

V1接口遷移到V2接口

• 在實(shí)現(xiàn)OAuth2.0授權(quán)后，接下來需要將應(yīng)用使用的V1版接口對應(yīng)遷移到V2版接口。此時需要根據(jù)新接口的調(diào)用地址、調(diào)用方式、參數(shù)、返回值、錯誤信息處理來進(jìn)行代碼的改造。

• 以下是V2版接口與V1版接口的對應(yīng)列表，部分舊版接口由于用戶投訴或性能等原因已不再提供，同時新版接口提供豐富的高級接口開放優(yōu)質(zhì)應(yīng)用申請，您可以直接在應(yīng)用控制臺中提交高級接口申請。

• 此外，SCOPE授權(quán)功能、好友分組接口、邀請接口、社交化等接口已經(jīng)在平臺開放計(jì)劃中，我們將在保證功能、性能及穩(wěn)定性后適時開放，詳細(xì)的開放日期請您關(guān)注@微博API。
• 如果現(xiàn)有接口未能滿足您的需求，歡迎@微博API進(jìn)行反饋，我們將根據(jù)開發(fā)者需求強(qiáng)度及微博用戶利益權(quán)衡適度開放。