Campaign与Twitter对接预研成果分享
日期:2015.4.28 作者:程文博
笔者声明:本文档的技术资料主要引用自Twitter官网,全文介绍了笔者在整个Twitter实践过程中的一些见闻和感悟,其中一些总结与论断属于个人见解,由于笔者的英语水平和代码能力有限,所以阐述中难免存在纰漏,欢迎您提出宝贵意见和建议,本文档最终解释权归原作者所有。
使用twitter,首先得厘清twitter里边的一些基本业务对象,Twitter主要由以下业务对象构成:;下面给出各个概念的官方解释:
Note:Twitter IDs(两个版本,javascript一般解析String版本)
Whenconsuming the API using JSON, it is important to always use thefield id_strinstead of id. This is due to the way Javascript andother languages that consume JSON evaluate large integers.
对twitter的业务对象有基本的了解后,毫无疑问,我们关注更多的是Twitter为广大开发者提供的API了,Twitter提供的API有多种,根据Campaign系统的业务需要,目前只用到其中的Rest API和Streaming API;下面是两个概念的官方解释:
Rest API原理图
Streaming API原理图
经过对官网API的阅读和研究,基本定位出Campaign各需求,以下是campaign需求和Twitter官网对应的API地址:
1. 获取关注人
https://dev.twitter.com/rest/reference/get/followers/list
2. 发布twitter消息,可以带#和@功能,以及附加图片的功能
https://dev.twitter.com/rest/reference/post/statuses/update
https://dev.twitter.com/rest/reference/post/media/upload
3. 获取被@的消息
https://dev.twitter.com/rest/reference/get/statuses/mentions_timeline
4. 发送,回复私信功能
https://dev.twitter.com/rest/reference/post/direct_messages/new
note: 5,6,7 需求统一用Streaming API处理
5. 获取被点赞的事件和事件主体(什么消息,被什么人点赞)
6. 获取被关注的和取消关注
7. 接受私信功能
https://dev.twitter.com/streaming/reference/get/user
以上就是我们解决需求的最原始依据。
由于从头解析API报文可能会消耗比较大的工作量和时间,为了在短时间内快速对接Twitter的功能,Twitter官方为广大JAVA开发者推荐twitter4j这个免费开源框架,经过笔者的亲手测研,发现使用该框架能极大地简化开发过程,快速集成Twitter的核心功能。这是twitter4j官网地址:http://twitter4j.org/en/index.html
有了这些材料,现在着手搭建一个测试Twitter功能的web工程,
这是测试所有需求完毕后的工程文件概览图;
在调用twitter API之前,我们首先需要通过Twitter服务器的OAuth认证;既然说到这里,相信有不少人还不知道OAuth是个什么玩意,那么笔者先给出一些关于OAuth的介绍:
OAuth(开放授权)是一个开放标准,允许用户让第三方应用访问该用户在某一网站上存储的私密的资源(如照片,视频,联系人列表),而无需将用户名和密码提供给第三方应用。使用OAuth,Twitter应用无需知道用户的Twitter口令,只需要得到Twitter和用户双方的授权信息(后面会说这个授权信息——其实就是Token)即可。
目前Twitter官方给出了OAuth1.0版本和OAuth2.0版本两种类型的认证方式,它们各自有自己的应用场景。其中OAuth1.0版本又分为Application-user authentication和Application-onlyauthentication两种认证方式。不论哪种认证方式,我们首先要在Twitter官网注册自己开发的APP,Twitter官网会为我们生成Consumer Key (API Key) 、Consumer Secret (API Secret) 、AccessToken 、Access Token Secret四种参数值。
Application-user authentication要求第三方应用提供Consumer Key (API Key) ,Consumer Secret (API Secret) 两种参数值,而这些参数的设定通过Twitter官网注册APP即可获得,该认证方式的一个显著特点就是:服务器端与客户端要经过两次握手才能完全通过认证,第一次握手就是客户端把参数值设置好,发送给服务器端,服务器校验通过,会将RequestToken返回给客户端,再利用重定向转到Twitter登陆页面以获取特定用户的授权;以下是笔者给出的代码截图:
在获取特定用户的授权以后,页面会跳转到注册APP时填写的Callback URL所对应的页面,这里有一个需要大家注意的细节,在这次页面跳转的过程中,twitter服务器会把oauth_token和oauth_verifier两个参数追加到CallbackURL后边,我们获取其中的oauth_verifier参数,有了RequestToken和oauth_verifier两个重要参数,我们就可以再一次向Twitter服务器提交认证,经过这次握手成功,整个认证过程就顺利结束了,以下是笔者给出的代码截图:
Application-only authentication要求第三方应用提供Consumer Key (API Key) 、Consumer Secret (API Secret) 、Access Token 、Access Token Secret四种参数值,通过开源jar包提供的方法获得了twitter对象,就表明认证通过,该认证方式优点是操作相对简单,局限性是只能绑定开发者账号,不能绑定其他用户的账号。以下是笔者给出的代码截图:
通过服务器认证后,接下来叙述需求1到需求4的实现过程,
需求1:获取关注人信息
首先根据我们campaign业务的需要,再仔细对照Twitter中User对象属性列表,我们只需要提取其中的id和screenName作为我们的userId和userName,特别说明:screenName是Twitter用户独一无二的非数字账号,我们把关注人定义为BizUser对象,该对象包含一个long类型的userId属性和一个String类型的userName属性。注意到twitter4j框架为我们提供的getFollowerList方法返回值是分页的User对象列表,每页最多只能获取200个用户,关于该方法的描述,详见官网API文档,我们只需要把绑定的Twitter用户名传进去,就能获得该用户的粉丝,如果粉丝数量较多,我们可能需要利用游标cursor遍历每一页的数据,以下是笔者提供的代码截图:
笔者同时给出对应此需求的接口定义以供参考:
List<BizUser> obtainFollowers()
需求2:发布twitter消息,可以带#和@功能以及图片功能
所谓的twitter消息,实质指的就是Twitter中为我们提供的status对象,可以这么武断的认为,除了私信以外的所有消息(包括回复、评论等),其代码实现都是通过status对象,这足以凸显其在Twitter业务当中的重要地位。谈到如何实现#和@功能,其实代码层面没有更多的东西,我们只需要在编辑twitter消息的时候,把带#和@符号的字串加入到消息文本中即可,不过这里头涉及到使用这两种特殊符号的注意事项,除了文本开头和结束位置,我们必须保证#字串(同理@字串)前后是空格符号或者标点符号,否则Twitter将会把这些特殊字串当成普通文本处理,导致不能产生高亮效果。下图是使用示例:
至于图片功能,twitter4j框架定义了Media对象处理图片,而StatusUpdate对象包含Media类型属性,我们只需要把File类型的值(该file指向一图片)传给media属性,就能把你的图片加入到你的新消息中,以下是笔者给出的代码截图:
笔者同时给出对应此需求的接口定义以供参考:
void updateNews(Stringnews,File media)
注释:news就是你发布的twitter消息,String类型;media是你上传的图片,File类型
需求3:获取被@的消息
所谓被@的消息,可以这样理解:谁提及了你,不论这个人是你的关注者还是陌生人,@功能可以被广泛地应用在很多场景,例如:回复、评论以及普通推文消息中;只要有人@了你,你就可以在通知中查看到相关的消息,而Twitter官方为开发者提供的接口,就是返回最近20条@你的消息,返回类型是Status的列表。通过仔细对比Status对象中的属性列表,并参照我们的业务需要,我们只需要提取其中的ScreenName和Text作为我们的userName和content。基于以上,我们需要定义BizTwitt业务类型来接收参数值,BizTwitt类包含userName和content属性,都是String类型。以下是笔者提供的代码截图:
笔者同时给出基于该需求的接口定义仅供参考:
List<BizTwitt> obtainMentions()
需求4:发送、回复私信功能
所谓私信,当然就是只有通信双方才能看到的消息。twitter4j框架为我们提供了简单易行的接口sendDirectMessage,通过该接口,我们只需要知道被私信人的id或者screenName,并把编辑好的消息传进去,就可以完成私信功能。以下是笔者给出的代码截图:
笔者同时给出针对该需求的接口定义仅供参考:
Void sendDirectMsg(longtargetId,String targetName,String news)
注释:第一个和第二个参数,两者必须有一个非空;news是你编辑的私信内容,String类型
需求5、6、7同属于Stream事件监听
客户端需要与Twitter服务器端建立长期稳定的连接,通过该连接,客户端能实时接收到服务器端发来的事件消息,这里边涉及到OAuth2.0认证、拥塞控制和如何维护长连接等诸多复杂问题。幸运的是,twitter4j框架为我们提供了一种非常简便的实现方式,我们只需要实现UserStreamListener监听器,并重写你想监听的方法。以下是笔者提供的代码截图:
从上图你可以看到:我们需要获得TwitterStream对象,并在该对象设置好API KEY和API Secret,并通过Access Token 、AccessToken Secret获得AccessToken,再把该AccessToken设置到TwitterStream中,即可通过OAuth2.0认证,接下来就是创建监听器,下图就是针对我们业务需求要重写的方法:
方法中代码根据你的因为无需求可以任意处理。
个人建议:把这些事件监听功能封装为一个独立后台进程,在项目启动时加载进去,以保证数据的完整性。
后记:细心的人或许注意到笔者在调用Rest api时多次用到Twitter对象,这是twitter4j框架为我们提供的对象,我们很多业务功能的调用都需要通过该对象来实现,所以有必要把Twitter对象作为一个全局的系统变量保存起来,以便多次使用。本文档提供的代码示例都经过测验证实可行,但在实际系统功能集成过程中,开发者需要根据具体情况给出相应代码实现以及优化,切勿生搬硬套,以免造成不必要的麻烦。