1. 服务使用请求
QQ机器人向服务供应商指定的URL端点发起HTTP GET请求,请求样例如下:
无身份验证的HTTP POST: http://fxservice.com/robot/serve?ts=1234513243234
有身份验证的HTTP POST: http://fxservice.com/robot/serve?ts=1234513243234&qq=124222313&type=message
Request Header
Content-Type: application/x-www-form-urlencoded
Content-Length: length
Charset: UTF-8
POST Body: #buy qty=1000 ac=John%20Smith
对于来自私有服务频道的请求,服务供应者可根据请求的QQ号和QQ号类型(来自QQ个人用户或是QQ群)来判断该类型的QQ号是否有服务权限,并由此决定返回值。type可能的值有:
message (为QQ个人用户)
group_message(为QQ群用户)
discu_message(为QQ临时讨论组)
ts参数是否设置由实际应用中QQ机器人的逻辑需求来决定。如果请求中设置了时间戳参数,相应的reqTS也必须出现在响应中。reqTS的值取自于请求值。
2. 服务查看响应
服务供应商返回xml形式的响应。其Schema如下所示。其中,retCode是返回值。如果用户未得到使用服务的权限,则返回数字4。
<?xml version="1.0"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" > <!-- Simple Type --> <xs:simpleType name="retCodetype"> <xs:restriction base="xs:short"/> <!-- 0: succeess --> <xs:enumeration value="9"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="messagetype"> <xs:restriction base="xs:string"/> </xs:simpleType> <xs:simpleType name="keytype"> <xs:restriction base="xs:token"/> <xs:pattern value="\{\[.*\]\}"/> </xs:simpleType> <xs:simpleType name="valuetype"> <!-- image URL must follows GET protocol GET header Accetp: image/png,image/*;q=0.8,*/*;q=0.5 --> <xs:restriction base="xs:anyURI"/> </xs:simpleType> <!-- the time stamp from request --> <xs:simpleType name="reqTStype"> <xs:restriction base="xs:long"/> </xs:simpleType> <!-- Complex Type --> <!-- due to qq's restriction, total image size within one message must smaller than 1 M --> <xs:complexType name="imageMaptype"> <xs:sequence> <xs:element name="key" type="keytype"/> <xs:element name="value" type="valuetype"/> </xs:sequence> </xs:complexType> <xs:complexType name="imagesType"> <xs:element name="imageMap" minOccurs="0" type="imageMaptype"/> </xs:complexType> <xs:complexType name="servetype"> <xs:sequence> <xs:element name="retCode" type="retCodetype"/> <xs:element name="message" type="messagetype"/> <xs:element name="images" minOccurs="0" type="imagesType"/> <!-- request time stamp is not mandatory in case it is not included in the request --> <xs:element name="reqTS" minOccurs="0" type="reqTStype"/> </xs:sequence> </xs:complexType> <xs:element name="serve" type="servetype"/> </xs:schema>
请求处理出错或用户没有访问权限时候的响应的XML Schema
<?xml version="1.0"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" > <!-- Simple Type --> <xs:simpleType name="retCodetype"> <xs:restriction base="xs:short"> <!-- 4: unauthorized 9: failure --> <xs:enumeration value="4"/> <xs:enumeration value="9"/> </xs:restriction> </xs:simpleType> <!-- Complex Type --> <xs:complexType name="servetype"> <xs:sequence> <xs:element name="retCode" type="retCodetype"/> <!-- request time stamp is not mandatory in case it is not included in the request --> <xs:element name="reqTS" minOccurs="0" type="reqTStype"/> </xs:sequence> </xs:complexType> <xs:element name="serve" type="servetype"/> </xs:schema>
响应样例
下示的xml响应样例中,图片以名-值对的形式关联所嵌入的位置(Key)以及图片源地址(Value)。机器人将以HTTP GET的形式从源地址中读取图片流字节。reqTS(请求时间戳)是机器人向服务供应者发起请求时,来自请求中的 ts 参数。如果请求中不包含 ts 参数,响应中也可不包含。
另外,retCode是返回值。如果用户未得到使用服务的权限,则返回数字4。如果请求处理中出现错误,则返回值为9。
<?xml version="1.0"?> <serve> <retCode>0</retCode> <message> <![CDATA[{[image1.jpg]}Purchase of 1000 US dolloar succeed {[image2.jpg]}]]> </message> <images> <imageMap> <key>{[image1.jpg]}</key> <value>http://fxservice.com/robot/image/image1.jpg</value> </imageMap> <imageMap> <key>{[image1.jpg]}</key> <value>http://fxservice.com/robot/image/image2.jpg</value> </imageMap> </image> <reqTS>1234513243234</reqTS> </serve>
请求失败或用户没有访问权限时候的响应
<?xml version="1.0"?> <serve> <retCode>4</retCode> <reqTS>1234513243234</reqTS> </serve>