服務(wù)簡(jiǎn)介

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

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

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

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

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

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

訂閱條件

訂閱用戶：

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

訂閱關(guān)鍵詞：

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

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

訂閱域名：

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

訂閱應(yīng)用：

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

訂閱媒體類型：

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

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

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

訂閱百分比：

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

訂閱時(shí)間范圍：

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

使用步驟

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

① 生成訂閱：

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

返回?cái)?shù)據(jù)見(jiàn)：示例。

⑥ 推送終止：

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

使用說(shuō)明

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

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

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

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

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

狀態(tài)說(shuō)明

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

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

1） 準(zhǔn)備中：

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

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

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

3） 已開(kāi)啟：

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

4） 已暫停：

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

5） 已終止：

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