• REST、SOAP协议互转

    目前接口平台仅仅支持SOAP/REST两种接口风格的协议互转。用户只需要编辑接口,选择发布类型即可。

    REST和SOAP的区别

    REST与SOAP在注册时有两处出现,一处是在注册时,选择服务类别,一处是在注册时编辑接口选择发布类型。一般都选择REST。

    对于服务注册时的服务类别,内部接口只可选择REST,外部接口可选择REST、SOAP,在前端有所不同。数据源接口选择REST、SOAP没有区别。

    重点在于选择接口发布类型,当发布类型为REST时,接口的请求报文为JSON类型。而发布类型为SOAP时,请求报文为XML类型。

    当接口选择REST发布类型时,自动生成的URL中包含namespace、serverCode、interfaceCode,例如:/v1/rest/invoke?namespace=HZERO&serverCode=TEST0506&interfaceCode=TEST05061710

    当接口选择SOAP发布类型时,自动生成的URL统一为/v1/soap/invoke?wsdl

    接口发布类型为REST接口调用

    发布类型为REST的接口调用方式,在服务注册章节的平台接口调用说明已有介绍。

    接口发布类型为SOAP接口调用

    SOAP的请求参数与响应参数,与REST的参数一致。

    与REST不同的是,SOAP将 接口编码、服务编码、命名空间这三个参数放在请求报文里面,请求报文为XML格式。

    请求报文示例:

    <?xml version="1.0" encoding="utf-8"?>
    <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:m="http://interface.hzero.org/v1/">
        <soap:Body>
            <m:invoke>
                <!-- 接口编码 -->
                <interfaceCode>12710_DATASOURCE_0401</interfaceCode>
                <!-- 服务编码 -->
                <serverCode>HITF_12710_DATASOURCE_TEST</serverCode>
                <!-- 命名空间 -->
                <namespace>HZERO</namespace>
                <payload>
                    <!-- 目标接口路径参数 -->
                    <pathVariableMap>
                        <!-- key代表参数名称,标签值代表参数值 -->
                        <dataEntryList key="organization_id">0</dataEntryList>
                    </pathVariableMap>
                    <!-- 目标接口url问号后面的参数 -->
                    <requestParamMap/>
                    <!-- 目标接口头部参数:若目标地址是SOAP,我们通常会再次设置Content-Type 以及SOAPAction字段 -->
                    <headerParamMap/>
                    <mediaType>Content-Type: application/JSON</mediaType>
                    <!-- 这里需要注意,如果目标地址是SOAP,我们在此填写目标地址对应的接口<opreationName>标签里面的xml片段,并且我们需要用
                    <![CDATA[xml片段]]转义,若是json,直接写json字符串就好-->
                    <payload>xxx</payload>
                </payload>
            </m:invoke>
        </soap:Body>
    </soap:Envelope>
    

    HTTP请求示例:

    POST /hitf/v1/soap/invoke HTTP/1.1
    Host: dev.hzero.org:8080
    Content-Type: application/xml
    Authorization: Bearer be7b7686-2667-445c-81f9-98b815687b2b
    
    <?xml version="1.0" encoding="utf-8"?>
    <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:m="http://interface.hzero.org/v1/">
        <soap:Body>
            <m:invoke>
                <interfaceCode>12710_DATASOURCE_0401</interfaceCode>
                <serverCode>HITF_12710_DATASOURCE_TEST</serverCode>
                <namespace>HZERO</namespace>
                <payload>
                    <!-- 目标接口路径参数,若目标接口是SOAP无需设置此参数 -->
                    <pathVariableMap>
                        <!-- key代表参数名称,标签值代表参数值 -->
                        <dataEntryList key="organization_id">0</dataEntryList>
                    </pathVariableMap>
                    <!-- 目标接口url问号后面的参数 -->
                    <requestParamMap>  
                   		<dataEntryList key=""></dataEntryList>
                	</requestParamMap>
                    <!-- 目标接口头部参数:若目标地址是SOAP,我们通常会再次设置Content-Type 以及SOAPAction字段 -->
                    <headerParamMap/>
                    <mediaType>Content-Type: application/JSON</mediaType>
                    <!-- 这里需要注意,如果目标地址是SOAP,我们在此填写目标地址对应的接口<opreationName>标签里面的xml片段,并且我们需要用
                    <![CDATA[xml片段]]转义,若是json,直接写json字符串就好-->
                    <payload>xxx</payload>
                </payload>
            </m:invoke>
        </soap:Body>
    </soap:Envelope>
    

    响应结果示例:

    <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
        <soap:Body>
            <ns2:invokeResponse xmlns:ns2="http://interface.hzero.org/v1/">
                <return>
                    <invokeKey>b9d24727-ba2b-4bb9-b2c1-d6af6853d2de</invokeKey>
                    <status>200</status>
                    <payload>xxx</payload>
                </return>
            </ns2:invokeResponse>
        </soap:Body>
    </soap:Envelope>
    

    对于SOAP接口统一的URL:http://hzeronb.saas.hand-china.com/hitf/v1/soap/invoke?wsdl

    POSTMAN请求报文示例:

    <?xml version="1.0" encoding="utf-8"?>
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v1="http://interface.hzero.org/v1/">
       <soapenv:Body>
          <v1:invoke>
             <!--Optional:-->
             <namespace>HZERO</namespace>
             <!--Optional:-->
             <serverCode>TEST0506</serverCode>
             <!--Optional:-->
             <interfaceCode>TEST001</interfaceCode>
             <!--Optional:-->
             <payload>
                <!--Optional:-->
                <headerParamMap>
                   <!--Zero or more repetitions:-->
                   <dataEntryList key=""></dataEntryList>
                </headerParamMap>
                <!--Optional:-->
                <pathVariableMap>
                   <!--Zero or more repetitions:-->
                   <dataEntryList key=""></dataEntryList>
                </pathVariableMap>
                <!--Optional:-->
                <requestParamMap>
                   <!--Zero or more repetitions:-->
                   <dataEntryList key=""></dataEntryList>
                </requestParamMap>
                <!--Optional:-->
                <bodyParamMap>
                   <!--Zero or more repetitions:-->
                   <dataEntryList key=""></dataEntryList>
                </bodyParamMap>
                <!--Optional:-->
                <mediaType></mediaType>
                <!--Optional:-->
                <payload></payload>
             </payload>
          </v1:invoke>
       </soapenv:Body>
    </soapenv:Envelope>
    

    响应结果示例:

    <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
        <soap:Body>
            <ns2:invokeResponse xmlns:ns2="http://interface.hzero.org/v1/">
                <return>
                    <invokeKey>7bd0eabb-cbee-4037-96f5-cb810782b967</invokeKey>
                    	<payload>{"content":[{"model_id":10009},{"model_id":10011},{"model_id":10015},{"model_id":10019},{"model_id":10023},{"model_id":10024},{"model_id":10026},{"model_id":10027},{"model_id":10028},{"model_id":10029}],"pageable":"INSTANCE","last":true,"totalPages":1,"totalElements":10,"first":true,"sort":{"sorted":false,"unsorted":true},"numberOfElements":10,"size":0,"number":0}</payload>
                    <status>200</status>
                </return>
            </ns2:invokeResponse>
        </soap:Body>
    </soap:Envelope>