QQ机器人开放式服务框架 Version 0.1 Draft - 使用服务

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>