服务简介

微博平台订阅服务提高了应用获取微博数据的效率。根据应用指定的订阅条件，如：关键词、用户、域名等，平台主动将新产生的数据实时推送给应用，应用不需要轮询请求接口。

订阅服务优点如下：

1、将新数据实时推送给应用；

2、节省网络开销；

3、提供数据量更多更全；

4、提高应用访问接口的效率；

订阅条件

订阅用户：

开发者可最多指定10000个用户。当订阅微博时，微博为指定用户发出的，则推送；当订阅评论时，推送指定用户发布的微博下的评论（不是该指定用户发出的评论）；若不指定，则无此限制。

订阅关键词：

开发者可最多指定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个。每个订阅的关键词总数、用户总数不能超过20000个，且不能重复订阅。

微博平台对某些关键词和用户会设置成保护状态，被保护的关键词和用户不能被订阅。一个关键词被保护后，包含此关键词的词都不能被订阅。订阅的关键词及按关键词过滤后的数据不区分大小写、简繁体。

③ 推送服务就绪：

开发者若在申请单中指定了推送开始时间，则在指定开始时间该订阅的推送服务就绪；若没有指定，则订阅生成后推送服务就已经就绪。

④ 应用连接、推送开始：

若订阅已经生成，但推送服务未就绪，则开发者订阅管理后台的推送状态显示：准备中；若推送服务已经就绪，则显示：准备就绪。在准备就绪状态下，应用才可以调用接口进行连接，接收数据。否则，调用接口时报错。

调用接口如下：

● 订阅微博，调用接口：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） 已终止：

若开发者未指定推送结束时间，则一直推送；若指定结束时间，则在指定的推送结束时间终止推送。相当于此订阅过期，不会再被重启使用。此时服务为已终止状态；