QQ机器人开放式服务框架 Version 0.1 Draft - 学习服务

1. 服务学习请求

QQ机器人向服务供应商指定的URL端点发起HTTP GET请求，Sample Request如下：

无身份验证的HTTP GET / POST: http://fxservice.com/robot/fxchange
有身份验证的HTTP GET / POST: http://fxservice.com/robot/fxchange?&qq=124222313&type=group

Request Header Content-Type: application/x-www-form-urlencoded
Content-Length: length
Charset: UTF-8

对于来自私有服务频道的请求，服务供应者可根据请求的QQ号和QQ号类型（来自QQ个人用户或是QQ群）来判断该类型的QQ号是否有权限教QQ机器人学习所选择的服务，并由此决定返回值。type可能的值有：

• message （为QQ个人用户）
• group_message（为QQ群用户）
• discu_message（为QQ临时讨论组）

ts参数是否设置由实际应用中QQ机器人的逻辑需求来决定。如果请求中设置了时间戳参数，相应的reqTS也必须出现在响应中。reqTS的值取自于请求值。

2. 服务查看响应

服务供应商返回xml形式的响应。响应Schema如下：

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" >

    <xs:simpleType name="retCodetype">
        <xs:restriction base="xs:short">
            <!-- 
    0: succeess
            -->
            <xs:enumeration value="0"/>
        </xs:restriction>
    </xs:simpleType>
    <xs:simpleType name="nametype">
        <xs:restriction base="xs:token"/>
    </xs:simpleType>
    <xs:simpleType name="versiontype">
        <xs:restriction base="xs:token"/>
    </xs:simpleType>
    <xs:simpleType name="servetype">
        <xs:restriction base="xs:anyURI"/>
    </xs:simpleType>
    <!-- Each hook must be unique not only in each service, but also among all the services -->
    <xs:simpleType name="hooktype">
        <xs:restriction base="xs:token"/>
        <xs:pattern value="#.+"/>
    </xs:simpleType>
    <!-- Use <br/> explicitely as line separator in help tag -->
    <xs:simpleType name="helptype">
        <xs:restriction base="xs:string"/>
    </xs:simpleType>
    <xs:simpleType name="authtype">
        <xs:restriction base="xs:boolean"/>
    </xs:simpleType>

    <xs:complexType name="hookstype">
        <xs:element name="name" maxOccurs="unbounded" type="nametype"/>
    </xs:complexType>

    <xs:complexType name="servicetype">
        <xs:sequence>
            <xs:element name="retCode" type="retCodetype"/>      
            <xs:element name="name" type="nametype"/>
            <xs:element name="version" type="versiontype"/>    
            <xs:element name="serve" type="servetype"/>
            <xs:element name="hooks" type="hookstype"/>
            <xs:element name="help" type="helptype"/>
            <xs:element name="auth" type="authtype"/>
        </xs:sequence>
    </xs:complexType>

    <xs:element name="service" type="serivcetype"/>
</xs:schema> 

请求处理中出错或用户没有访问权限时候的响应的XML Schema

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" >

    <xs:simpleType name="retCodetype">
        <xs:restriction base="xs:short">
            <!-- 
    4: unauthorized
            -->
            <xs:enumeration value="4"/>
        </xs:restriction>
    </xs:simpleType>

    <xs:complexType name="servicetype">
        <xs:sequence>
            <xs:element name="retCode" type="retCodetype"/>
         </xs:sequence>
    </xs:complexType>

    <xs:element name="service" type="serivcetype"/>
</xs:schema> 

 

响应样例

服务供应商返回xml形式的响应。其Schema如下所示。其中，retCode是返回值。如果用户未得到使用服务的权限，则返回数字4。如果请求处理中出现错误，则返回值为9。

<?xml version="1.0"?>
<sevice>
    <retCode>0</retCode>
    <name>fxservice</name>
    <version>1.0a<version>
    <serve>http://fxservice.com/robot/serve</serve>
    <hooks>
        <hook><![CDATA[#fxservice]]><hook>
        <hook><![CDATA[#外汇交易]]><hook>
    </hooks>
    <help>
       <![CDATA[
Foreign Exchange Service provides purchase, sell and enquiry with the following instructions: <br/>
    #buy <qty=QTY> <unit=UNIT> <ac=A/c> <br/>
    #sell <qty=QTY> <unit=UNIT> <ac=A/c> <br/>
    #enquiry <unit=UNIT> <br/>
        ]]>    
    </help>
    <auth>true</auth>
</sevice>

请求失败或用户没有访问权限时候的响应

<?xml version="1.0"?> 
    <sevice>   
    <retCode>4</retCode> 
</sevice>