為什麼要遷移到新版介面

• 全新的新版（V2）介面較舊版（V1）介面具有更豐富的功能、更有效率、更規格、更可控等優勢，很好地滿足了開發者的需求。

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

新版介面較舊版介面的優點

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

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

• 3、更規範
  • a）統一參數、傳回值字段，全部小寫字母，單字和單字之間以「_」連結；
  • b）介面URI，全部採用：域版本號資源類別介面名稱傳回值格式參數；
  • c）核心欄位：微博、評論、使用者、關係全部標準化，避免核心欄位在不同介面中傳回值不同，進而降低開發成本；
  • d）統一的新錯誤回傳值格式及錯誤碼，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）應用程式本身功能與微博關聯緊密。

• • #在應用程式控制台的「介面管理」-->“授權機制」中申請。

• 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是否過期。

• • #已授權使用者再次授權時，如果此使用者為已登入微博狀態，授權頁面為「一閃而過」無需使用者再點選「授權」按鈕，如果想讓使用者重新登入授權，則在呼叫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進行測試，則需要您在應用程式或網站控制台「套用資訊」或「網站資訊」-->「測試帳號」中新增測試帳
    • 號，未審核應用程式只有應用程式建立者與測試帳號才能呼叫介面。

• #13、V2版介面回傳值為什麼只支援JSON格式不支援XML格式回傳？
  • a）介面返回值中可能會含有html等字段，採用XML格式返回時需要對html進行特殊處理，直接影響到平台包裝返回值及開
    • 發者解析返回值的效率；
  • b）對於JS等語言在解析複雜的XML難度較高，效率較低；
  • c）XML格式較JSON採用Key- Value的形式有很大冗餘，不符合手機用戶端等對效能要求較高的應用需求。

• 14、有哪些高階接口，怎麼申請新版高階接口？
  • 在V2介面文件中介面名稱後面標示： 圖示則表示此介面為進階介面。高級介面申請要求應用需要通過文案審核，並無作惡情況發生。其他要求及申請流程請見：高階介面申請指南。

• 15、閱讀完遷移指南後仍有問題怎麼辦？
  • a）透過開放平台問答系統快速獲得協助；
  • b）將問題透過評論的方式發送到@微博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開發指南。
  • OAuth2.0授權方式與OAuth1.0相比，引入授權回呼頁與綁定域名，簡化了授權流程，同時也提升了授權的安全性。

• • 在實作OAuth2.0授權方式前，針對不同的應用程式我們需要設定應用程式的授權回呼頁或進行網域名稱的綁定，用於獲得授權成功後回傳的code，再透過code取得access_token。

• • 使用開發者帳號登入http://open.weibo.com，進入「我的應用程式」控制台需要遷移的應用程式進行設定：
  • a）網站接入類別
    • 點擊控制台導航“網站資訊”，在網站基本資訊中查看網站域名。如果您的網站應用程式尚未驗證所有權，會提示您進行所有權驗證，點擊進入驗證頁面完成所有權驗證。 Web應用請參考：Web應用遷移指引 。

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

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

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

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

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

• ##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&client_secret=YOUR_APP_SECRET&grant_type=authorization_code&client_secret=YOUR_APP_SE.uri ;

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

• • • d）傳回值
    • {"access_token":"SlAV32hkKG","re​​mind_in":"3600","expires_in":3600,"uid":"1902538057"}

• • • 寫入介面必須使用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=------- -------------

• • #<= Recv header, 23 bytes (0x17)
  HTTP/1.1 100 Continue
=> Send data, 370 bytes (0x172)

-------------------- ----------8933e7b00565

##2.00RQs9XCmlEQDD4fb4b0bfe3Be7ZQE

#----- -------------------------8933e7b00565
• Content-Disposition: form-data; name="status"
  #Test02
------------------------------8933e7b00565

Content-Disposition: form-data; name="pic" ; filename="psu.jpg"

• V1介面遷移到V2介面

在實作OAuth2.0授權後，接下來需要將應用程式使用的V1版介面對應遷移到V2版接口。此時需要根據新介面的呼叫位址、呼叫方式、參數、回傳值、錯誤訊息處理來進行程式碼的改造。