Eps/wikitest

跳转到: 导航, 搜索
(接收事件推送)
(接收事件推送)
第298行: 第298行:
  
  
<p>[http://weibosdk.codeplex.com/ php代码示例]&nbsp;&nbsp;&nbsp;&nbsp;    [http://weibosdk.codeplex.com/ java代码示例]</p>
+
<p>[http://www.sinaimg.cn/blog/developer/wiki/xiaoxituisong_php_demo.rar php代码示例]&nbsp;&nbsp;&nbsp;&nbsp;    http://www.sinaimg.cn/blog/developer/wiki/xiaoxituisong_java_demo.rar java代码示例]</p>
  
  

2014年4月22日 (二) 13:55的版本

目录

消息推送服务概述

当一个和认证用户相关的消息或者事件发生时(如某个用户向认证用户发送消息),微博服务器将POST消息数据包到开发者填写的URL上;


在开发者首次使用事件推送服务时,需要先通过一次校验来和微博服务器建立首次连接;微博服务器发送GET请求到开发者填写的URL上,校验参数如下表所示:

校验参数字段 字段类型 字段说明
signature string 微博加密签名,signature结合了开发者appsecret参数和请求中的timestamp参数,nonce参数
timestamp string 时间戳
nonce string 随机数
echostr string 随机字符串


signature参数的加密规则为:将appsecret参数,timestamp参数,nonce参数进行字典排序后,将三个参数字符串拼接成一个字符串进行sha1加密;开发者收到请求后,首先通过加密后的signature参数来校验GET请求的真实性,如果确认此次GET请求来自微博服务器,原样返回echostr参数内容就可以成功建立首次连接,否则连接失败。


建立首次连接后,后续每次微博事件推送时也都会带上signature、timestamp、nonce三个参数,开发者依然可以通过对signature的校验判断此条消息的真实性。校验方式与首次建立连接一致。

请求样例:

如果:
appsercret=xyz123xyz , timestamp=1397022061823 , nonce=57155157时

那么:
拼接后的字符串为:139702206182357155157xyz123xyzsha1
签名后的结果为:90e4c22c90a58f26526c2dd5b6c56c8822edeaa1
验证url有效性请求的样例为:http://yoururlnonce=57155157&timestamp=1397022061823&echostr=dnPdpTZz85&signature=90e4c22c90a58f26526c2dd5b6c56c8822edeaa1

此时如果返回的是echostr的值(此样例中为dnPdpTZz85)则通过url验证。

接收普通消息

建立首次连接后,当认证用户有新消息时,微博消息推送服务会POST消息数据包到开发者填写的URL上,当前支持的普通消息类型包括:

注意:需要对接收到的消息体type或subtype做兼容,当出现未知类型时可忽略此消息。)

纯文本类型私信和留言消息:text

{
    "type": "text",
    "receiver_id": 1902538057,
    "sender_id": 2489518277,
    "created_at": "Mon Jul 16 18:09:20 +0800 2012",
    "text": "私信或留言内容",
    "data": {}
}
返回值说明
属性 值的类型 说明描述
type string text
receiver_id int64 消息的接收者
sender_id int64 消息的发送者
created_at string 消息创建时间
text string 私信内容
data string 消息内容,纯文本私信或留言为空


位置类型私信消息:position

{
    "type": "position",
    "receiver_id": 1902538057,
    "sender_id": 2489518277,
    "created_at": "Mon Jul 16 18:09:20 +0800 2012",
    "text": "我在这里: http://t.cn/zQgLLYO",
    "data": {
        "longitude": "116.308586",
        "latitude": "39.982525"
      }
}
返回值说明
属性 值的类型 说明描述
type string mention
receiver_id int64 消息的接收者
sender_id int64 消息的发送者
created_at string 消息创建时间
text string 原位置私信文本,没有时用默认文案“发送了一个位置”
data string 消息内容
data:longitude string 经度
data:latitude string 纬度


语音类型私信和留言消息:voice

{
    "id": 1211260020031347,
    "type": "voice",
    "receiver_id": 1902538057,
    "sender_id": 2489518277,
    "created_at": "Mon Jul 16 18:09:20 +0800 2012",
    "text": "发了一个语音消息",
    "data": {
        "vfid": 821804459,    // 发送者用此ID查看语音
        "tovfid": 821804469  // 接收者用此ID查看语音
    }
}
返回值说明
属性 值的类型 说明描述
type string voice
receiver_id int64 消息的接收者
sender_id int64 消息的发送者
created_at string 消息创建时间
text string 私信内容
data string 消息内容,纯文本私信或留言为空
data:vfid string 语音文件ID,发送者通过此ID读取语音
data:tovfid string 语音文件ID,接收者通过此ID读取语音
查看(下载)认证用户接收到的语音方法一
curl "https://upload.api.weibo.com/2/mss/msget?access_token=RECIPIENT_ACCESS_TOKEN&fid=TOVFID"

1,"RECIPIENT_ACCESS_TOKEN":返回结果中接收者(recipient_id)通过OAuth2授权返回的access_token;
2,"TOVFID":返回结果data字段中的tovfid。

查看(下载)认证用户接收到的语音方法二
curl -u "USERNAME:PASSWORD" "https://upload.api.weibo.com/2/mss/msget?source=APPKEY&fid=TOVFID"

1,"USERNAME:PASSWORD"为"recipient_id"(认证用户)的微博登录用户名和密码,此时方法二中的APPKEY应用所有者为"recipient_id";
2,"TOVFID":返回结果data字段中的tovfid。


图片类型私信和留言消息:image

{
    "type": "image",
    "receiver_id": 1902538057,
    "sender_id": 2489518277,
    "created_at": "Mon Jul 16 18:09:20 +0800 2012",
    "text": "发了一张图片",
    "data": {
        "vfid": 821804459,     // 发送者用此ID查看图片
        "tovfid": 821804469    // 接收者用此ID查看图片
    }
}
返回值说明
属性 值的类型 说明描述
type string image
receiver_id int64 消息的接收者
sender_id int64 消息的发送者
created_at string 消息创建时间
text string 私信内容
data string 消息内容,纯文本私信或留言为空
data:vfid string 图片ID,发送者通过此ID读取图片
data:tovfid string 图片ID,接收者通过此ID读取图片
查看(下载)图片
curl "https://upload.api.weibo.com/2/mss/msget?access_token=RECIPIENT_ACCESS_TOKEN&fid=TOVFID"

1,"RECIPIENT_ACCESS_TOKEN":返回结果中接收者(receiver_id)通过OAuth2授权返回的access_token;
2,"TOVFID":返回结果data字段中的tovfid。

接收事件推送

建立首次连接后,当认证用户有新消息时,微博消息推送服务会POST消息数据包到开发者填写的URL上,当前支持的事件类型:

事件消息:event

{
    "type": "event",
    "receiver_id": 1902538057,
    "sender_id": 2489518277,
    "created_at": "Mon Jul 16 18:09:20 +0800 2012",
    "text": "事件消息",
    "data": {
        "subtype": "EVENT",
        "key": "EVENT_KEY",
        "ticket": "TICKET",
    }
}


php代码示例     http://www.sinaimg.cn/blog/developer/wiki/xiaoxituisong_java_demo.rar java代码示例]


返回值说明
属性 值的类型 说明描述
type string event
receiver_id int64 消息的接收者
sender_id int64 消息的发送者
created_at string 消息创建时间
text string 默认文案。subtype为follow或unfollow时分别为“关注事件消息”、“取消关注事件消息”;为subscribe或unsubscribe时为触发订阅的私信关键词(如“dy”),非私信触发时(点击订阅按钮)为“订阅事件消息”、“取消订阅事件消息”;subtype为scan或scan_follow时为“扫描二维码”;
data string 消息内容
data:subtype string follow:关注事件,unfollow取消关注事件,subscribe订阅事件,unsubscribe订阅事件。scan和scan_follow为二维码扫描事件。
data:key string subtype为follow、unfollow、subscribe或unsubscribe时不返回
data:ticket string subtype为scan和scan_follow时才返回

被@消息:mention

说明:指定的认证用户需被授予接收“被@消息”权限,此接口才返回“被@消息”,申请可邮件 open_api@sina.com

{
    "type": "mention",
    "receiver_id": 1902538057,
    "sender_id": 2489518277,
    "created_at": "Mon Jul 16 18:09:20 +0800 2012",
    "text": "被@的微博或评论文本信息",
    "data": {
        "subtype": "MENTION_TYPE,
        "key": "MENTION_KEY"
    }
}

// 默认仅返回可信用户的@,如需返回所有用户@,认证用户可访问此链接设置:http://account.weibo.com/set/message
返回值说明
属性 值的类型 说明描述
type string mention
receiver_id int64 消息的接收者
sender_id int64 消息的发送者
created_at string 消息创建时间
text string 被@的微博或评论文本信息
data string 消息内容
data:subtype string status:@的微博,comment:@的评论
data:key string 当subtype为status时为微博ID,为comment时为评论ID

发送被动响应

对于每一个POST请求,开发者在响应包(Get)中返回特定JSON包,对该消息进行响应。微博服务器在五秒内收不到响应会断掉连接,并且重新发起请求,总共重试三次; 关于重试的消息排重,推荐使用消息ID排重。

假如开发者无法保证在五秒内处理并回复,可以直接回复空串,微博服务器不会对此作任何处理,并且不会发起重试。

如果发送被动响应消息,则返回JSON格式如下: 注意:JSON格式中的data字段内容必须进行UTF8格式的URLEncode

{
    "result": true,
    "receiver_id":"123456",
    "sender_id":"123123",
    "type": "text",
    "data":"{}"
}


当前支持回复的私信类型(type)中,data参数支持的参数:

纯文本类型私信消息:text

例如,当text文本为“中文消息”时:
{
    "text": "中文消息"
}
返回样例:
{
    "result": true,
    "sender_id":"123",
    "receiver_id":"456",
    "type": "text",
    "data":"%7B%22text%22%3A%22%E4%B8%AD%E6%96%87%E6%B6%88%E6%81%AF%22%7D"
}
data参数支持的参数
参数名称 值的类型 是否必填 说明描述
text string true 要回复的私信文本内容。文本大小必须小于300个汉字。

举例: 当data对应json为{"text": "纯文本响应"} 时,则进行URLEncode后对应data参数值为:"%7B%22text%22%3A%20%22%E7%BA%AF%E6%96%87%E6%9C%AC%E5%93%8D%E5%BA%94%22%7D%20"。


图文类型私信消息:articles

例如:
{
    "articles": [
        {
            "display_name": "两个故事",
            "summary": "今天讲两个故事,分享给你。谁是公司?谁又是中国人?​",
            "image": "http://storage.mcp.weibo.cn/0JlIv.jpg",
            "url": "http://e.weibo.com/mediaprofile/article/detail?uid=1722052204&aid=983319"
        },
        ... //最多支持8个图文,建议为1或3个
    ]
}
返回样例:
{
    "result": true,
    "sender_id":"123",
    "receiver_id":"456",
    "type": "articles",
    "data":"%7B%22articles%22%3A%5B%7B%22display_name%22%3A%22%E4%B8%A4%E4%B8%AA%E6%95%85%E4%BA%
8B%22%2C%22summary%22%3A%22%E4%BB%8A%E5%A4%A9%E8%AE%B2%E4%B8%A4%E4%B8%AA%E6%95%85%E4%BA%8B%EF%BC%8C%E5%88%86%E4%BA%AB%E7%BB%99%E4%BD%A0%E3%80%82%E8%B0%81%E6%98%AF%E5%85%AC%E5%8F%B8%EF%BC%9F%E8%B0%81%E5%8F%88%E6%98%AF%E4%B8%AD%E5%9B%BD%E4%BA%BA%EF%BC%9F%E2%80%8B%22%2C%22image%22%3A%22http%3A%2F%2Fstorage.mcp.weibo.cn%2F0JlIv.jpg%22%2C%22url%22%3A%22http%3A%2F%2Fe.weibo.com%2Fmediaprofile%2Farticle%2Fdetail%3Fuid%3D1722052204%26aid%3D983319%22%7D%5D%7D"
}


data参数支持的参数
参数名称 值的类型 是否必填 说明描述
articles:display_name string true 图文的显示名称标题
articles:summary string true 图文的文字描述,大于等于2个图文时,仅显示第一个图文的描述
articles:image string true 图文的缩略显示图片,需为JPG、PNG格式,单图及多图第一张推荐使用280*155,多图非第一张推荐使用64*64
articles:url string true 图文的URL地址,点击后跳转



位置类型私信消息:position

例如:
{
    "longitude": "344.3344",
    "latitude": "232.343434"
}

返回样例:
{
    "result": true,
    "sender_id":"123",
    "receiver_id":"456",
    "type": "position",
    "data":"%7B%22longitude%22%3A%22344.3344%22%2C%22latitude%22%3A%22232.343434%22%7D"
}


data参数支持的参数
参数名称 值的类型 是否必填 说明描述
longitude string true 经度
latitude string true 纬度


微信XML格式兼容

除了上述的JSON格式,微博消息推送服务还支持“微信XML格式兼容”; 第三方可以通过http://open.weibo.com/wiki/Eps/push/set_format 接口来选择自己需要的格式是XML还是JSON;

XML格式详细描述如下:

接收消息推送

1. text消息的XML格式

<xml>
 <ToUserName><![CDATA[toUser]]></ToUserName>
 <FromUserName><![CDATA[fromUser]]></FromUserName> 
 <CreateTime>1348831860</CreateTime>
 <MsgType><![CDATA[text]]></MsgType>
 <Content><![CDATA[this is a test]]></Content>
 <MsgId>1234567890123456</MsgId>
</xml>
返回值说明
XML参数 在JSON格式中对应的参数 说明描述
ToUserName receiver_id 消息的接收者
FromUserName sender_id 消息的发送者
CreateTime created_at 消息创建时间
MsgType type text
Content text 私信内容
MsgId 暂无对应字段 该字段内容为空

2. image消息的XML格式

<xml>
 <ToUserName><![CDATA[toUser]]></ToUserName>
 <FromUserName><![CDATA[fromUser]]></FromUserName>
 <CreateTime>1348831860</CreateTime>
 <MsgType><![CDATA[image]]></MsgType>
 <PicUrl><![CDATA[this is a url]]></PicUrl>
 <MediaId><![CDATA[media_id]]></MediaId>
 <MsgId>1234567890123456</MsgId>
 </xml>
返回值说明
XML参数 在JSON格式中对应的参数 说明描述
ToUserName receiver_id 消息的接收者
FromUserName sender_id 消息的发送者
CreateTime created_at 消息创建时间
MsgType type image
PicUrl 无对应字段 该字段内容为空
MediaID data:tovfid 私信内容
MsgId 暂无对应字段 该字段为空

3. voice消息的XML格式

<xml>
<ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[fromUser]]></FromUserName>
<CreateTime>1357290913</CreateTime>
<MsgType><![CDATA[voice]]></MsgType>
<MediaId><![CDATA[media_id]]></MediaId>
<Format><![CDATA[Format]]></Format>
<MsgId>1234567890123456</MsgId>
</xml>
返回值说明
XML参数 在JSON格式中对应的参数 说明描述
ToUserName receiver_id 消息的接收者
FromUserName sender_id 消息的发送者
CreateTime created_at 消息创建时间
MsgType type voice
PicUrl 无对应字段 该字段内容为空
MediaID data:tovfid 私信内容
Format 暂无对应字段 该字段为空
MsgId 暂无对应字段 该字段为空

4. position消息的XML格式

<xml>
<ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[fromUser]]></FromUserName>
<CreateTime>1351776360</CreateTime>
<MsgType><![CDATA[location]]></MsgType>
<Location_X>23.134521</Location_X>
<Location_Y>113.358803</Location_Y>
<Scale>20</Scale>
<Label><![CDATA[位置信息]]></Label>
<MsgId>1234567890123456</MsgId>
</xml>
返回值说明
XML参数 在JSON格式中对应的参数 说明描述
ToUserName receiver_id 消息的接收者
FromUserName sender_id 消息的发送者
CreateTime created_at 消息创建时间
MsgType type position
Location_X data:latitude 纬度
Location_Y data:longitude 经度
Scale 暂无对应字段 该字段为空
Label 暂无对应字段 该字段为空
MsgId 暂无对应字段 该字段为空

5. 关注/取消关注,订阅/取消订阅消息的XML格式

<xml>
<ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[FromUser]]></FromUserName>
<CreateTime>123456789</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[subscribe]]></Event>
</xml>
返回值说明
XML参数 在JSON格式中对应的参数 说明描述
ToUserName receiver_id 消息的接收者
FromUserName sender_id 消息的发送者
CreateTime created_at 消息创建时间
MsgType type event
Event data:subtype follow:关注事件,unfollow取消关注事件,subscribe订阅事件,unsubscribe订阅事件。

6. 扫描带参数二维码事件的XML格式 用户扫描带场景值二维码时,可能推送以下两种事件: 如果用户还未关注二维码生成方的官方账号,则扫描后进入关注列表;如果用户点击关注,则微博会给第三方推送scan_follow事件;

<xml>
<ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[FromUser]]></FromUserName>
<CreateTime>123456789</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[subscribe]]></Event>
<EventKey><![CDATA[qrscene_123123]]></EventKey>
<Ticket><![CDATA[TICKET]]></Ticket>
</xml>
返回值说明
XML参数 在JSON格式中对应的参数 说明描述
ToUserName receiver_id 消息的接收者
FromUserName sender_id 消息的发送者
CreateTime created_at 消息创建时间
MsgType type event
Event data:subtype scan_follow
EventKey data:key 事件Key值,action_name为前缀,后面为二维码的scene_id值
Ticket data:ticket 二维码的ticket,可用来换取二维码图片

如果用户已经关注二维码生成方的官方账号,则扫描后进入和该官方账号的私信对话界面中,并且微博会给第三方推送scan事件;

<xml>
<ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[FromUser]]></FromUserName>
<CreateTime>123456789</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[SCAN]]></Event>
<EventKey><![CDATA[SCENE_VALUE]]></EventKey>
<Ticket><![CDATA[TICKET]]></Ticket>
</xml>
返回值说明
XML参数 在JSON格式中对应的参数 说明描述
ToUserName receiver_id 消息的接收者
FromUserName sender_id 消息的发送者
CreateTime created_at 消息创建时间
MsgType type event
Event data:subtype scan
EventKey data:key 事件Key值,action_name为前缀,后面为二维码的scene_id值
Ticket data:ticket 二维码的ticket,可用来换取二维码图片

发送被动响应

1. 回复text消息的XML格式

<xml>
 <ToUserName><![CDATA[toUser]]></ToUserName>
 <FromUserName><![CDATA[fromUser]]></FromUserName> 
 <CreateTime>1348831860</CreateTime>
 <MsgType><![CDATA[text]]></MsgType>
 <Content><![CDATA[this is a test]]></Content>
</xml>
参数说明
XML参数 在JSON格式中对应的参数 说明描述
ToUserName receiver_id 消息的接收者
FromUserName sender_id 消息的发送者
CreateTime created_at 消息创建时间
MsgType type text
Content data:text 私信内容;微博对于要回复的私信文本内容,要求文本大小必须小于300个汉字;如果超过300个汉字,则微博会自动截断超过部分

2. 回复图文消息的XML格式

<ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[fromUser]]></FromUserName>
<CreateTime>12345678</CreateTime>
<MsgType><![CDATA[news]]></MsgType>
<ArticleCount>2</ArticleCount>
<Articles>
<item>
<Title><![CDATA[title1]]></Title> 
<Description><![CDATA[description1]]></Description>
<PicUrl><![CDATA[picurl]]></PicUrl>
<Url><![CDATA[url]]></Url>
</item>
<item>
<Title><![CDATA[title]]></Title>
<Description><![CDATA[description]]></Description>
<PicUrl><![CDATA[picurl]]></PicUrl>
<Url><![CDATA[url]]></Url>
</item>
</Articles>
返回值说明
XML参数 在JSON格式中对应的参数 说明描述
ToUserName receiver_id 消息的接收者
FromUserName sender_id 消息的发送者
CreateTime created_at 消息创建时间
MsgType type articles
ArticleCount 无对应字段 该字段内容会自动忽略掉;另外微博最多支持8个图文,如果超过8个图文,则微博会自动截断超过部分;
Title articles:display_name 图文的显示名称标题,文本大小必须小于60个汉字。
Description articles:summary 图文的文字描述,文本大小必须小于300个汉字,支持空格与换行,三个或三个以上的空格、换行缩减为两个。
PicUrl articles:image 图文的图片链接,仅支持PNG、JPG类型。
Url articles:url 图文的URL地址,点击后跳转。