訂閱服務手冊
服務簡介
微博平台訂閱服務提高了應用程式取得微博資料的效率。根據應用程式指定的訂閱條件，如：關鍵字、使用者、網域名稱等，平台主動將新產生的資料即時推送給應用，應用程式不需要輪詢請求介面。
訂閱服務優點如下：
1、將新資料即時推送給應用程式；
2、節省網路開銷；
#3、提供資料量更多更全；
4、提高應用程式存取介面的效率；
訂閱用戶：
開發者可指定最多20000個關鍵字。當訂閱微博時，微博中含有指定關鍵字，則推送；當訂閱評論時，評論對應的微博含有此關鍵字、或評論本身含有此關鍵字的評論則推送；若不指定，則無此限制。
##訂閱域名：
開發者可最多指定20個網域。當訂閱微博時，微博中包含短鏈所對應原始鏈接為指定域名下的，則推送；當訂閱評論時，評論對應的微博內包含短鏈所對應原始鏈接為指定域名的評論則推送；若不指定，則無此限制。
訂閱應用程式：
開發者可指定只推送產生訂閱的應用程式產生的數據，若不指定則推送所有應用程式的資料。
訂閱媒體類型：
當訂閱微博時，才可以指定該條件。開發者可指定原創、轉發、影片、音樂、或圖片類型。則推送指定類型的微博；若不指定，則無此限制；當訂閱評論時，無此篩選條件。
訂閱資料類型：
開發者可指定推送微博、或評論資料；若不指定，則預設推送微博。
訂閱百分比：
開發者可指定滿足以上訂閱條件的資料的百分比，若不指定，則推送滿足條件的1%資料。
開發者可指定推送開始時間和結束時間。在指定開始時間推送服務準備就緒，結束時間終止推播。若不指定，開始時間預設等於訂閱產生時間，一直推送。在推播服務準備就緒時，開發者可以呼叫介面進行連接，從而接收資料。
使用步驟
訂閱服務使用步驟如下：
① 產生訂閱：
開發者線下填寫訂閱服務申請單，填寫訂閱條件等信息，平台人員根據申請單信息，產生訂閱。每個應用程式可以有多個訂閱。需要試用訂閱服務的開發者，請在線上自助提交申請（詳見接入指南），不用填寫申請單。
② 設定訂閱的關鍵字、使用者：
#訂閱服務申請單中「訂閱關鍵字」、「訂閱使用者」選擇否時，忽略此步驟。選擇是時，則需保證關鍵字訂閱清單和使用者訂閱清單一定不為空。訂閱關鍵字、用戶（若已經訂閱了關鍵字、用戶，則可忽略此步驟），請求介面：subscribe/update_subscribe
請求該介面的IP一定是訂閱時指定的IP列表中的某個IP位址，否則會傳回錯誤提示：Ip is limited（ip受限）。當只傳subid時，傳回該訂閱的訂閱訊息，包括訂閱的關鍵字清單、使用者清單。
每個關鍵字由逗號分隔，逗號分隔的關鍵字之間是邏輯「或」的關係。
每個關鍵字長度不能超出36個漢字。
每個關鍵字內部支援“與”、“非”邏輯，邏輯“與”，由“空格”分隔：如A B；邏輯“非”，由“空格-”分隔：如A - B。當關鍵字兩側帶有雙引號時，表示關鍵字內容絕對匹配，邏輯運算失效，如：“A B”，不再表示邏輯A與B。
每個關鍵字內部被邏輯運算子分隔的子關鍵字總數不能超過1000個，每個訂閱的邏輯符個數不能超過500個。
每次呼叫介面訂閱的關鍵字不能超過20個。每次呼叫介面訂閱的用戶不能超過50個。每個訂閱的關鍵字總數、使用者總數不能超過20,000個，且不能重複訂閱。
微博平台對某些關鍵字和使用者會設定成保護狀態，被保護的關鍵字和使用者不能被訂閱。一個關鍵字被保護後，包含此關鍵字的字詞都不能被訂閱。訂閱的關鍵字及依關鍵字過濾後的資料不區分大小寫、簡繁體。
③ 推送服務就緒：
開發者若在申請單中指定了推送開始時間，則在指定開始時間該訂閱的推送服務就緒；若沒有指定，則訂閱產生後推送服務已就緒。
④ 應用連線、推送開始：
若訂閱已經生成，但推送服務未就緒，則開發者訂閱管理後台的推送狀態顯示：準備中；若推播服務已經就緒，則顯示：準備就緒。在準備就緒狀態下，應用程式才可以呼叫介面進行連接，接收資料。否則，呼叫接口時報錯。
呼叫介面如下：
● 訂閱微博，呼叫介面：datapush/status
●● 訂閱評論，呼叫介面：datapush/comment
##################
java調用，請參閱範例程式碼。
⑤ 應用接收資料：
連線成功後，介面將會向開發者的連線位址推送微博、或評論資料。每個完整的微博或評論資料以json形式傳回，預設採用UTF-8編碼，且以\r\n分隔。每條資料資訊最大長度為4096位元組。
返回資料見：範例。
⑥ 推送終止：
若開發者未指定推送結束時間，則一直推送；若指定結束時間，則在指定的推送結束時間終止推送。相當於此訂閱過期，不會再重新啟動使用。
使用說明
應用程式透過HTTP長連線請求介面/datapush/status或/ datapush/comment接收資料。需傳入參數subid（訂閱ID）告知平台推送哪個訂閱的資料。若請求正確，則傳回對應資料結果。若請求異常，則傳回對應錯誤訊息。
為了緩解伺服器壓力，平台推送資料每十分鐘會斷開一次，應用程式需要相容，重新HTTP長連接請求接口，並可以帶上上次斷開時的id值，作為參數since_id的值傳入，如：/datapush/status?subid=xxx&since_id=XXX 。應用就可以從斷開的點連續取得資料。所以需要應用保留服務斷開時的id，作為下次請求的參數值。
因為訂閱服務推送的數據是即時的，所以平台只保留五分鐘的數據，斷開超過五分鐘，則參數since_id不再支持，若傳入since_id，則返回錯誤提示：Illegal param since_id（since_id不合法，超過時間限制）。如果不傳since_id，平台會過濾目前時間點前5萬個資料中符合條件的資料推送給使用者。
當應用程式出現違規操作或其他原因，平台會暫停該訂閱的資料推送功能，即不再推送資料。直到問題解決後，平台可以重新啟動推播功能。應用需要HTTP長連線重新請求介面。
另外，應用程式請求介面的IP一定是訂閱時指定的IP清單中的某個IP位址，否則會傳回錯誤提示：Ip is limited（ip受限）。
狀態說明
在開發者管理中心，可以看到服務的各種顯示狀態，如下圖紅框所示：
服務狀態有：準備中、準備就緒、已開啟、已暫停、已終止五種。
1） 準備中：
訂閱已產生但未到開發者指定的推送開始時間，為準備中狀態（此時開發者無法連接接收資料）。如果開發者未指定推播開始時間，則訂閱產生後，無準備中狀態，直接進入準備就緒狀態。
2） 準備就緒：
訂閱生成，已到推送開始時間，但開發者未連接接收數據，為準備就緒狀態。或訂閱生成，開發者未指定推播開始時間，開發者未連接接收數據，則服務也為準備就緒狀態。
3） 已開啟：
在準備就緒狀態下，開發者連線接收數據，服務進入已開啟狀態。
4） 已暫停：
當應用程式出現違規操作或由於其他原因，平台將該訂閱的推送功能暫停，則服務轉為已暫停狀態。
5） 已終止：
若開發者未指定推送結束時間，則一直推送；若指定結束時間，則在指定的推送結束時間終止推送。相當於此訂閱過期，不會再重新啟動使用。此時服務為已終止狀態；
