服務(wù)簡介

微博平臺訂閱服務(wù)提高了應(yīng)用獲取微博數(shù)據(jù)的效率。根據(jù)應(yīng)用指定的訂閱條件，如：關(guān)鍵詞、用戶、域名等，平臺主動將新產(chǎn)生的數(shù)據(jù)實(shí)時推送給應(yīng)用，應(yīng)用不需要輪詢請求接口。

訂閱服務(wù)優(yōu)點(diǎn)如下：

1、將新數(shù)據(jù)實(shí)時推送給應(yīng)用；

2、節(jié)省網(wǎng)絡(luò)開銷；

3、提供數(shù)據(jù)量更多更全；

4、提高應(yīng)用訪問接口的效率；

訂閱條件

訂閱用戶：

開發(fā)者可最多指定10000個用戶。當(dāng)訂閱微博時，微博為指定用戶發(fā)出的，則推送；當(dāng)訂閱評論時，推送指定用戶發(fā)布的微博下的評論（不是該指定用戶發(fā)出的評論）；若不指定，則無此限制。

訂閱關(guān)鍵詞：

開發(fā)者可最多指定20000個關(guān)鍵詞。當(dāng)訂閱微博時，微博中含有指定關(guān)鍵詞，則推送；當(dāng)訂閱評論時，評論對應(yīng)的微博含有此關(guān)鍵詞、或評論本身含有此關(guān)鍵詞的評論則推送；若不指定，則無此限制。

注：當(dāng)轉(zhuǎn)發(fā)微博的內(nèi)容中不含該關(guān)鍵詞，而原微博中包含，這種情況不推送

訂閱域名：

開發(fā)者可最多指定20個域名。當(dāng)訂閱微博時，微博中包含短鏈所對應(yīng)原始鏈接為指定域名下的，則推送；當(dāng)訂閱評論時，評論對應(yīng)的微博內(nèi)包含短鏈所對應(yīng)原始鏈接為指定域名的評論則推送；若不指定，則無此限制。

訂閱應(yīng)用：

開發(fā)者可指定只推送生成訂閱的應(yīng)用產(chǎn)生的數(shù)據(jù)，若不指定則推送所有應(yīng)用的數(shù)據(jù)。

訂閱媒體類型：

當(dāng)訂閱微博時，才可以指定該條件。開發(fā)者可指定原創(chuàng)、轉(zhuǎn)發(fā)、視頻、音樂、或圖片類型。則推送指定類型的微博；若不指定，則無此限制；當(dāng)訂閱評論時，無此篩選條件。

訂閱數(shù)據(jù)類型：

開發(fā)者可指定推送微博、或評論數(shù)據(jù)；若不指定，則默認(rèn)推送微博。

訂閱百分比：

開發(fā)者可指定滿足以上訂閱條件的數(shù)據(jù)的百分比，若不指定，則推送滿足條件的1%數(shù)據(jù)。

訂閱時間范圍：

開發(fā)者可指定推送開始時間和結(jié)束時間。在指定開始時間推送服務(wù)準(zhǔn)備就緒，結(jié)束時間終止推送。若不指定，則開始時間默認(rèn)等于訂閱生成時間，一直推送。在推送服務(wù)準(zhǔn)備就緒時，開發(fā)者可以調(diào)用接口進(jìn)行連接，從而接收數(shù)據(jù)。

使用步驟

訂閱服務(wù)使用步驟如下：

① 生成訂閱：

開發(fā)者線下填寫訂閱服務(wù)申請單，填寫訂閱條件等信息，平臺人員根據(jù)申請單信息，生成訂閱。每個應(yīng)用可以有多個訂閱。需要試用訂閱服務(wù)的開發(fā)者，請在線自助提交申請（詳見接入指南），不用填寫申請單。

② 設(shè)置訂閱的關(guān)鍵詞、用戶：

訂閱服務(wù)申請單中“訂閱關(guān)鍵詞”、“訂閱用戶”選擇否時，忽略此步驟。選擇是時，則需保證關(guān)鍵詞訂閱列表和用戶訂閱列表一定不為空。訂閱關(guān)鍵詞、用戶（若已經(jīng)訂閱了關(guān)鍵詞、用戶，則可忽略此步驟），請求接口：subscribe/update_subscribe

請求該接口的IP一定是訂閱時指定的IP列表中的某個IP地址，否則會返回錯誤提示：Ip is limited（ip受限）。當(dāng)只傳subid時，返回該訂閱的訂閱信息，包括訂閱的關(guān)鍵詞列表、用戶列表。

每個關(guān)鍵詞由逗號分隔，逗號分隔的關(guān)鍵詞之間是邏輯“或”的關(guān)系。

每個關(guān)鍵詞長度不能超出36個漢字。

每個關(guān)鍵詞內(nèi)部支持“與”、“非”邏輯，邏輯“與”，由“空格”分隔：如A B；邏輯“非”，由“空格-”分隔：如A -B。當(dāng)關(guān)鍵詞兩邊帶有雙引號時，表示關(guān)鍵詞內(nèi)容絕對匹配，邏輯運(yùn)算失效，如：“A B”，不再表示邏輯A與B。

每個關(guān)鍵詞內(nèi)部被邏輯運(yùn)算符分隔的子關(guān)鍵詞總數(shù)不能超過1000個，每個訂閱的邏輯符個數(shù)不能超過500個。

每次調(diào)用接口訂閱的關(guān)鍵詞不能超過20個。每次調(diào)用接口訂閱的用戶不能超過50個。每個訂閱的關(guān)鍵詞總數(shù)、用戶總數(shù)不能超過20000個，且不能重復(fù)訂閱。

微博平臺對某些關(guān)鍵詞和用戶會設(shè)置成保護(hù)狀態(tài)，被保護(hù)的關(guān)鍵詞和用戶不能被訂閱。一個關(guān)鍵詞被保護(hù)后，包含此關(guān)鍵詞的詞都不能被訂閱。訂閱的關(guān)鍵詞及按關(guān)鍵詞過濾后的數(shù)據(jù)不區(qū)分大小寫、簡繁體。

③ 推送服務(wù)就緒：

開發(fā)者若在申請單中指定了推送開始時間，則在指定開始時間該訂閱的推送服務(wù)就緒；若沒有指定，則訂閱生成后推送服務(wù)就已經(jīng)就緒。

④ 應(yīng)用連接、推送開始：

若訂閱已經(jīng)生成，但推送服務(wù)未就緒，則開發(fā)者訂閱管理后臺的推送狀態(tài)顯示：準(zhǔn)備中；若推送服務(wù)已經(jīng)就緒，則顯示：準(zhǔn)備就緒。在準(zhǔn)備就緒狀態(tài)下，應(yīng)用才可以調(diào)用接口進(jìn)行連接，接收數(shù)據(jù)。否則，調(diào)用接口時報錯。

調(diào)用接口如下：

● 訂閱微博，調(diào)用接口：datapush/status

● 訂閱評論，調(diào)用接口：datapush/comment

java調(diào)用，見示例代碼。

⑤ 應(yīng)用接收數(shù)據(jù)：

連接成功后，接口將向開發(fā)者的連接地址推送微博、或評論數(shù)據(jù)。每條完整的微博或評論數(shù)據(jù)以json形式返回，默認(rèn)采用UTF-8編碼，且以\r\n分隔。每條數(shù)據(jù)信息最大長度為4096字節(jié)。

返回數(shù)據(jù)見：示例。

⑥ 推送終止：

若開發(fā)者未指定推送結(jié)束時間，則一直推送；若指定結(jié)束時間，則在指定的推送結(jié)束時間終止推送。相當(dāng)于此訂閱過期，不會再被重啟使用。

使用說明

應(yīng)用通過HTTP長連接請求接口/datapush/status或/ datapush/comment接收數(shù)據(jù)。需傳入?yún)?shù)subid（訂閱ID）告知平臺推送哪個訂閱的數(shù)據(jù)。若請求正確，則返回相應(yīng)數(shù)據(jù)結(jié)果。若請求異常，則返回相應(yīng)錯誤信息。

為了緩解服務(wù)器壓力，平臺推送數(shù)據(jù)每十分鐘會斷開一次，應(yīng)用程序需要兼容，重新HTTP長連接請求接口，并可以帶上上次斷開時的id值，作為參數(shù)since_id的值傳入，如：/datapush/status?subid=xxx&since_id=XXX 。應(yīng)用就可以從斷開的點(diǎn)連續(xù)獲取數(shù)據(jù)。所以需要應(yīng)用保留服務(wù)斷開時的id，作為下次請求的參數(shù)值。

因?yàn)橛嗛喎?wù)推送的數(shù)據(jù)是實(shí)時的，所以平臺只保留五分鐘的數(shù)據(jù)，斷開超過五分鐘，則參數(shù)since_id不再支持，若傳入since_id，則返回錯誤提示：Illegal param since_id（since_id不合法，超過時間限制）。 如果不傳since_id，平臺會過濾當(dāng)前時間點(diǎn)前5萬條數(shù)據(jù)中符合條件的數(shù)據(jù)推送給用戶。

當(dāng)應(yīng)用出現(xiàn)違規(guī)操作或其他原因，平臺會暫停該訂閱的數(shù)據(jù)推送功能，即不再推送數(shù)據(jù)。直到問題解決后，平臺可以重啟推送功能。應(yīng)用需要HTTP長連接重新請求接口。

另外，應(yīng)用請求接口的IP一定是訂閱時指定的IP列表中的某個IP地址，否則會返回錯誤提示：Ip is limited（ip受限）。

狀態(tài)說明

在開發(fā)者管理中心，可以看到服務(wù)的各種顯示狀態(tài)，如下圖紅框所示：

服務(wù)狀態(tài)有：準(zhǔn)備中、準(zhǔn)備就緒、已開啟、已暫停、已終止五種。

1） 準(zhǔn)備中：

訂閱已經(jīng)生成但未到開發(fā)者指定的推送開始時間，為準(zhǔn)備中狀態(tài)（此時開發(fā)者無法連接接收數(shù)據(jù)）。如果開發(fā)者未指定推送開始時間，則訂閱生成后，無準(zhǔn)備中狀態(tài)，直接進(jìn)入準(zhǔn)備就緒狀態(tài)。

2） 準(zhǔn)備就緒：

訂閱生成，已經(jīng)到推送開始時間，但開發(fā)者未連接接收數(shù)據(jù)，為準(zhǔn)備就緒狀態(tài)?；蛴嗛喩桑_發(fā)者未指定推送開始時間，開發(fā)者未連接接收數(shù)據(jù)，則服務(wù)也為準(zhǔn)備就緒狀態(tài)。

3） 已開啟：

在準(zhǔn)備就緒狀態(tài)下，開發(fā)者連接接收數(shù)據(jù)，服務(wù)進(jìn)入已開啟狀態(tài)。

4） 已暫停：

當(dāng)應(yīng)用出現(xiàn)違規(guī)操作或由于其他原因，平臺將該訂閱的推送功能暫停，則服務(wù)轉(zhuǎn)為已暫停狀態(tài)。

5） 已終止：

若開發(fā)者未指定推送結(jié)束時間，則一直推送；若指定結(jié)束時間，則在指定的推送結(jié)束時間終止推送。相當(dāng)于此訂閱過期，不會再被重啟使用。此時服務(wù)為已終止?fàn)顟B(tài)；