為什么要遷移到新版接口

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

• V1接口使用的OAuth1.0授權方式無法適應進一步的開放，已被各大開放平臺棄用，由全新的OAuth2.0授權方式取代。

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

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

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

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

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

V1禁止調用時間

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

• 禁止調用V1接口的應用在調用V1接口時會返回：“40109 Oauth Error: consumer_key_refused! ” 錯誤提示。

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

遷移中常見問題

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

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

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

• 4、怎么申請客戶端的驗證授權（Resource Owner Password Credentials）方式？
  • 因為OAuth2.0的客戶端驗證授權會獲得用戶明文密碼，所以實行有限開放。

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

• • 滿足條件后在應用控制臺的“接口管理”-->“授權機制”中申請。

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

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

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

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

• • 應用的授權有效期可以訪問接口訪問權限說明或在應用控制臺查看。

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

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

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

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

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

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

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

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

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

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

V1到V2怎么遷移

簡述

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

遷移時需要完成的工作

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

OAuth1.0升級到OAuth2.0

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

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

• • 在實現OAuth2.0授權方式前，針對不同的應用我們需要設置應用的授權回調頁或進行域名的綁定，用于獲得授權成功后返回的code，再通過code獲取access_token。

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

• • • 注意：驗證時填寫的網站域名即為您的應用的綁定域名。

• • b）站內應用
    • 站內應用已經是OAuth2.0授權方式，無需做改動。

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

• • • 注意：客戶端也需要設置授權回調頁或綁定域名，在程序中以webview的方式進行調用授權頁面返回code，具體實現可
      • • 以參考：移動應用遷移指引 。 其他客戶端可以參考相應SDK：http://open.weibo.com/wiki/SDK 。

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

• • a）引導需要授權的用戶訪問如下地址

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

• • • 注意：redirect_uri必須為綁定域名下網頁或設置的回調地址。

• • b）如果用戶同意授權,頁面跳轉至 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具有一定的有效期，當access_token過期時需要引導用戶重新授權。應用
      • • 的授權有效期可以訪問接口訪問權限說明或在應用控制臺查看。

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

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

• • • 注意：參數信息放入header及body中，除access_token外，其他參數必須放入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接口

• 在實現OAuth2.0授權后，接下來需要將應用使用的V1版接口對應遷移到V2版接口。此時需要根據新接口的調用地址、調用方式、參數、返回值、錯誤信息處理來進行代碼的改造。

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

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