本文以实际场景为例介绍接入WebService协议开放RESTful协议,以帮助您深入理解开放服务。

背景信息

本文仅介绍在实际场景中接入WebService协议开放RESTful服务时一些重要的配置步骤和参数,如需了解完整的流程和参数解释,请参见发布后端已有服务

本文列举了接入WebService协议开放RESTful协议的几种场景:
调用CSB开放服务时,支持多种请求方式,请根据实际场景选择:
  • 公开访问(无需订购)的服务。
    • curl
      #使用Path传值
      curl -H'Content-Type:x-www-form-urlencoded' --data "${Body参数}" "http://CSB服务地址:8086/${服务版本}/${服务名称}/开放Path?Query参数"
      
      #使用query传值
      curl --data "${Body参数}" "http://CSB服务地址:8086/开放Path?_api_name=${服务名称}&_api_version=${服务版本}&Query参数"
      
      #使用Header传值
      curl -H"_api_name:${服务名称}" -H"_api_version:${服务版本}" --data "${Body参数}" "http://CSB服务地址:8086/开放Path?Query参数"
    • CSB SDK
      #非JSON请求。
      java -jar http-client.jar -api ${服务名称} -version ${服务版本} -D'param1=value1' -D'param2=value2' -url http://CSB服务地址:8086/开放Path
      
      #JSON请求。
      java -jar http-client.jar -api ${服务名称} -version ${服务版本} -cbJSON "${JSONBody}" -url http://CSB服务地址:8086/开放Path
  • 非公开访问(需要订购)的服务。
    在CSB SDK的基础上增加-ak '${访问凭证ak}' -sk '${访问凭证sk}'
    #非JSON请求。
    java -jar http-client.jar -api ${服务名称} -version ${服务版本} -ak ${访问凭证ak} -sk ${访问凭证sk} -D'param1=value1' -D'param2=value2' -url http://CSB服务地址:8086/开放Path
    
    #JSON请求。
    java -jar http-client.jar -api ${服务名称} -version ${服务版本} -ak ${访问凭证ak} -sk ${访问凭证sk} -cbJSON "${JSONBody}" -url http://CSB服务地址:8086/开放Path

FORM

说明 FORM场景,接入WebService协议只支持开放为RESTful协议。

服务配置

接入WebService开放RESTful,不支持出参配置。

FROM-服务配置

接入后端服务

@WebService(endpointInterface = "com.alibaba.edas.carshop.itemcenter.biz.ItemBizService", targetNamespace = "http://service.ken.com")
@BindingType(value = SOAPBinding.SOAP12HTTP_BINDING)
public interface ItemBizService {
    Item add(@WebParam(name = "item") Item item);
}

调用服务

#使用CSB-SDK请求CSB开放服务。
java -jar httpclient.jar -api item.ws.add -version 1.0.0 -method post \
-D 'item={"itemName":"benz","quantity":10}' -url http://csb.target.server:8086/CSB

#通过Header参数curl CSB服务
curl -H "_api_name:multilevel" -H "_api_version:1.0.0" -X POST \
-d 'item={"itemName":"benz","quantity":10}' http://csb.target.server:8086/CSB

请求结果

{
    "ns2:addResponse": {
        "return": {
            "itemName": "benz",
            "quantity": 20
        }
    }
}

WSDL

<wsdl:definitions
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:tns="http://service.ken.com"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:ns1="http://schemas.xmlsoap.org/soap/http" name="ItemWsServiceImplService" targetNamespace="http://service.ken.com">
    <wsdl:types>
        <xs:schema
            xmlns:xs="http://www.w3.org/2001/XMLSchema"
            xmlns:tns="http://service.ken.com" elementFormDefault="unqualified" targetNamespace="http://service.ken.com" version="1.0">
            <xs:element name="add" type="tns:add"/>
            <xs:element name="addResponse" type="tns:addResponse"/>
            <xs:element name="item" type="tns:item"/>
            <xs:complexType name="add">
                <xs:sequence>
                    <xs:element minOccurs="0" name="item" type="tns:item"/>
                </xs:sequence>
            </xs:complexType>
            <xs:complexType name="item">
                <xs:complexContent>
                    <xs:extension base="tns:traceEntity">
                        <xs:sequence>
                            <xs:element minOccurs="0" name="description" type="xs:string"/>
                            <xs:element minOccurs="0" name="itemName" type="xs:string"/>
                            <xs:element maxOccurs="unbounded" minOccurs="0" name="manufacturer" nillable="true" type="xs:string"/>
                            <xs:element minOccurs="0" name="quantity" type="xs:long"/>
                        </xs:sequence>
                    </xs:extension>
                </xs:complexContent>
            </xs:complexType>
            <xs:complexType name="traceEntity">
                <xs:complexContent>
                    <xs:extension base="tns:baseDTO">
                        <xs:sequence>
                            <xs:element minOccurs="0" name="trace" type="tns:trace"/>
                        </xs:sequence>
                    </xs:extension>
                </xs:complexContent>
            </xs:complexType>
            <xs:complexType name="baseDTO">
                <xs:complexContent>
                    <xs:extension base="tns:baseEntity">
                        <xs:sequence>
                            <xs:element minOccurs="0" name="gmtCreated" type="xs:dateTime"/>
                        </xs:sequence>
                    </xs:extension>
                </xs:complexContent>
            </xs:complexType>
            <xs:complexType name="baseEntity">
                <xs:sequence>
                    <xs:element minOccurs="0" name="id" type="xs:anyType"/>
                </xs:sequence>
            </xs:complexType>
            <xs:complexType name="trace">
                <xs:sequence>
                    <xs:element minOccurs="0" name="bizId" type="xs:string"/>
                    <xs:element minOccurs="0" name="requestId" type="xs:string"/>
                    <xs:element minOccurs="0" name="rpcId" type="xs:string"/>
                    <xs:element minOccurs="0" name="traceId" type="xs:string"/>
                </xs:sequence>
            </xs:complexType>
            <xs:complexType name="addResponse">
                <xs:sequence>
                    <xs:element minOccurs="0" name="return" type="tns:item"/>
                </xs:sequence>
            </xs:complexType>
        </xs:schema>
    </wsdl:types>
    <wsdl:message name="add">
        <wsdl:part element="tns:add" name="parameters"></wsdl:part>
    </wsdl:message>
    <wsdl:message name="addResponse">
        <wsdl:part element="tns:addResponse" name="parameters"></wsdl:part>
    </wsdl:message>
    <wsdl:portType name="ItemBizService">
        <wsdl:operation name="add">
            <wsdl:input message="tns:add" name="add"></wsdl:input>
            <wsdl:output message="tns:addResponse" name="addResponse"></wsdl:output>
        </wsdl:operation>
    </wsdl:portType>
    <wsdl:binding name="ItemWsServiceImplServiceSoapBinding" type="tns:ItemBizService">
        <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
        <wsdl:operation name="add">
            <soap:operation soapAction="" style="document"/>
            <wsdl:input name="add">
                <soap:body use="literal"/>
            </wsdl:input>
            <wsdl:output name="addResponse">
                <soap:body use="literal"/>
            </wsdl:output>
        </wsdl:operation>
    </wsdl:binding>
    <wsdl:service name="ItemWsServiceImplService">
        <wsdl:port binding="tns:ItemWsServiceImplServiceSoapBinding" name="ItemWsServiceImplPort">
            <soap:address location="http://service.ken.com:8080/ws/ItemService"/>
        </wsdl:port>
    </wsdl:service>
</wsdl:definitions>

请求后端服务

代码的service.ken.com是测试用的后端RESTful应用。

curl --location --request POST 'http://service.ken.com:8080/ws/ItemService' \
--header 'Content-Type: application/xml' \
--data-raw '<soapenv:Envelope
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:wst="http://service.ken.com">
    <soapenv:Header/>
    <soapenv:Body>
        <wst:add>
            <item>
                <itemName>benz</itemName>
                <quantity>10</quantity>
            </item>
        </wst:add>
    </soapenv:Body>
</soapenv:Envelope>'

后端服务返回

<soap:Envelope
    xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns2:addResponse
            xmlns:ns2="http://service.ken.com">
            <return>
                <itemName>benz</itemName>
                <quantity>20</quantity>
            </return>
        </ns2:addResponse>
    </soap:Body>
</soap:Envelope>

FORM复杂

说明 FORM复杂场景,接入WebService协议只支持开放为RESTful协议。

服务配置

接入WebService开放RESTful,不支持出参配置。

FROM复杂-服务配置

接入后端服务

@WebService(endpointInterface = "com.alibaba.edas.carshop.itemcenter.biz.ItemBizService", targetNamespace = "http://service.ken.com")
@BindingType(value = SOAPBinding.SOAP12HTTP_BINDING)
public interface ItemBizService {
    OrderInfo addOrderInfo(@WebParam(name = "orderInfo") OrderInfo orderInfo);
}

请求代码

#通过CSB SDK请求CSB服务
java -jar httpclient.jar -api multilevel -version 1.0.0 -method post \
-D 'orderInfo={
    "orders": {
        "order": [{
            "custName": "doctest",
            "custNo": 119640,
            "items": {
                "item": [{
                    "goodsName": "cookies",
                    "goodsNo": 1
                }, {
                    "goodsName": "apple",
                    "goodsNo": 2
                }]
            }
        }, {
            "custName": "apptest",
            "custNo": 87981,
            "items": {
                "item": [{
                    "goodsName": "banana",
                    "goodsNo": 3
                }, {
                    "goodsName": "coffee",
                    "goodsNo": 4
                }]
            }
        }]
    }
}' -url http://csb.target.server:8086/CSB

#通过Header参数curl CSB服务
curl -H "_api_name:multilevel" -H "_api_version:1.0.0" -X POST -d 'orderInfo={
    "orders": {
        "order": [{
            "custName": "doctest",
            "custNo": 119640,
            "items": {
                "item": [{
                    "goodsName": "cookies",
                    "goodsNo": 1
                }, {
                    "goodsName": "apple",
                    "goodsNo": 2
                }]
            }
        }, {
            "custName": "apptest",
            "custNo": 87981,
            "items": {
                "item": [{
                    "goodsName": "banana",
                    "goodsNo": 3
                }, {
                    "goodsName": "coffee",
                    "goodsNo": 4
                }]
            }
        }]
    }
}' http://csb.target.server:8086/CSB

请求结果

{
    "ns2:addOrderInfoResponse": {
        "return": {
            "orders": {
                "order": [{
                    "custNo": 119640,
                    "custName": "doctest",
                    "items": {
                        "item": [{
                            "goodsNo": 1,
                            "goodsName": "cookies"
                        }, {
                            "goodsNo": 2,
                            "goodsName": "apple"
                        }]
                    }
                }, {
                    "custNo": 87981,
                    "custName": "apptest",
                    "items": {
                        "item": [{
                            "goodsNo": 3,
                            "goodsName": "banana"
                        }, {
                            "goodsNo": 4,
                            "goodsName": "coffee"
                        }]
                    }
                }]
            }
        }
    }
}

WSDL

<?xml version='1.0' encoding='UTF-8'?>
<wsdl:definitions
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:tns="http://service.ken.com"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:ns1="http://schemas.xmlsoap.org/soap/http" name="ItemWsServiceImplService" targetNamespace="http://service.ken.com">
    <wsdl:types>
        <xs:schema
            xmlns:xs="http://www.w3.org/2001/XMLSchema"
            xmlns:tns="http://service.ken.com" elementFormDefault="unqualified" targetNamespace="http://service.ken.com" version="1.0">
            <xs:element name="addOrderInfo" type="tns:addOrderInfo"/>
            <xs:element name="addOrderInfoResponse" type="tns:addOrderInfoResponse"/>
            <xs:element name="order" type="tns:order"/>
            <xs:element name="orderInfo" type="tns:orderInfo"/>
            <xs:element name="product" type="tns:product"/>
            <xs:complexType name="addOrderInfo">
                <xs:sequence>
                    <xs:element minOccurs="0" name="orderInfo" type="tns:orderInfo"/>
                </xs:sequence>
            </xs:complexType>
            <xs:complexType name="orderInfo">
                <xs:sequence>
                    <xs:element minOccurs="0" name="orders">
                        <xs:complexType>
                            <xs:sequence>
                                <xs:element maxOccurs="unbounded" minOccurs="0" name="order" type="tns:order"/>
                            </xs:sequence>
                        </xs:complexType>
                    </xs:element>
                </xs:sequence>
            </xs:complexType>
            <xs:complexType name="order">
                <xs:sequence>
                    <xs:element minOccurs="0" name="custNo" type="xs:long"/>
                    <xs:element minOccurs="0" name="custName" type="xs:string"/>
                    <xs:element minOccurs="0" name="items">
                        <xs:complexType>
                            <xs:sequence>
                                <xs:element maxOccurs="unbounded" minOccurs="0" name="item" type="tns:product"/>
                            </xs:sequence>
                        </xs:complexType>
                    </xs:element>
                </xs:sequence>
            </xs:complexType>
            <xs:complexType name="product">
                <xs:sequence>
                    <xs:element minOccurs="0" name="goodsNo" type="xs:long"/>
                    <xs:element minOccurs="0" name="goodsName" type="xs:string"/>
                </xs:sequence>
            </xs:complexType>
            <xs:complexType name="addOrderInfoResponse">
                <xs:sequence>
                    <xs:element minOccurs="0" name="return" type="tns:orderInfo"/>
                </xs:sequence>
            </xs:complexType>
        </xs:schema>
    </wsdl:types>
    <wsdl:message name="addOrderInfo">
        <wsdl:part element="tns:addOrderInfo" name="parameters"></wsdl:part>
    </wsdl:message>
    <wsdl:message name="addOrderInfoResponse">
        <wsdl:part element="tns:addOrderInfoResponse" name="parameters"></wsdl:part>
    </wsdl:message>
    <wsdl:portType name="ItemBizService">
        <wsdl:operation name="addOrderInfo">
            <wsdl:input message="tns:addOrderInfo" name="addOrderInfo"></wsdl:input>
            <wsdl:output message="tns:addOrderInfoResponse" name="addOrderInfoResponse"></wsdl:output>
        </wsdl:operation>
    </wsdl:portType>
    <wsdl:binding name="ItemWsServiceImplServiceSoapBinding" type="tns:ItemBizService">
        <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
        <wsdl:operation name="addOrderInfo">
            <soap:operation soapAction="" style="document"/>
            <wsdl:input name="addOrderInfo">
                <soap:body use="literal"/>
            </wsdl:input>
            <wsdl:output name="addOrderInfoResponse">
                <soap:body use="literal"/>
            </wsdl:output>
        </wsdl:operation>
    </wsdl:binding>
    <wsdl:service name="ItemWsServiceImplService">
        <wsdl:port binding="tns:ItemWsServiceImplServiceSoapBinding" name="ItemWsServiceImplPort">
            <soap:address location="http://service.ken.com:8080/ws/ItemService"/>
        </wsdl:port>
    </wsdl:service>
</wsdl:definitions>

请求后端服务

代码的service.ken.com是测试用的后端RESTful应用。

curl --location --request POST 'http://service.ken.com:8080/ws/ItemService' \
--header 'Content-Type: application/xml' \
--data-raw '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ken.com">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:addOrderInfo>
         <orderInfo>
            <orders>
               <order>
                  <custNo>119640</custNo>
                  <custName>doctest</custName>
                  <items>
                     <item>
                        <goodsNo>1</goodsNo>
                        <goodsName>cookies</goodsName>
                     </item>
                     <item>
                        <goodsNo>2</goodsNo>
                        <goodsName>apple</goodsName>
                     </item>
                  </items>
               </order>
               <order>
                  <custNo>87981</custNo>
                  <custName>apptest</custName>
                  <items>
                     <item>
                        <goodsNo>3</goodsNo>
                        <goodsName>banana</goodsName>
                     </item>
                     <item>
                        <goodsNo>4</goodsNo>
                        <goodsName>coffee</goodsName>
                     </item>
                  </items>
               </order>
            </orders>
         </orderInfo>
      </ser:addOrderInfo>
   </soapenv:Body>
</soapenv:Envelope>'

后端服务返回

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns2:addOrderInfoResponse xmlns:ns2="http://service.ken.com">
            <return>
                <orders>
                    <order>
                        <custNo>119640</custNo>
                        <custName>doctest</custName>
                        <items>
                            <item>
                                <goodsNo>1</goodsNo>
                                <goodsName>cookies</goodsName>
                            </item>
                            <item>
                                <goodsNo>2</goodsNo>
                                <goodsName>apple</goodsName>
                            </item>
                        </items>
                    </order>
                    <order>
                        <custNo>87981</custNo>
                        <custName>apptest</custName>
                        <items>
                            <item>
                                <goodsNo>3</goodsNo>
                                <goodsName>banana</goodsName>
                            </item>
                            <item>
                                <goodsNo>4</goodsNo>
                                <goodsName>coffee</goodsName>
                            </item>
                        </items>
                    </order>
                </orders>
            </return>
        </ns2:addOrderInfoResponse>
    </soap:Body>
</soap:Envelope>

JSON

说明 接入WebService开放RESTful不支持JSON场景。

WebService请求说明

WebService请求说明
图注 取值 描述
1 -soap12 SOAP的版本,根据WSDL设置命名空间:xmlns:soap12="http://www.w3.org/2003/05/soap-enveloap"xmlns:soap="http://schemas.xmlsoap.org/soap/envloap/"
2 -ns 目标命名空间。
3 -pname 端口号。
4 -sname 服务名称。
5 -ea 默认的Endpoint地址,调用时可以根据实际的服务地址进行设置。