本文以实际场景为例介绍接入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
- curl
- 非公开访问(需要订购)的服务。
在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,不支持出参配置。
接入后端服务
@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,不支持出参配置。
接入后端服务
@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请求说明
图注 | 取值 | 描述 |
---|---|---|
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地址,调用时可以根据实际的服务地址进行设置。 |