- 如果使用命令行方式调用SDK,根据需要将standaloned的运行包放在调用端的CLASSPATH环境里 ws-sdk-1.0.4.2plus.jar
- 如果用编程的方式使用SDK,则需要将需要的dependency放到你的pom.xml (该依赖已经在maven central repository存在)
<dependency>
<groupId>com.alibaba.csb.sdk</groupId>
<artifactId>ws-client</artifactId>
<version>1.1.0</version>
</dependency>
当WebService服务由CSB开放出来后,客户端需要生成标准的Proxy或Dispatch来进行调用, SDK的作用是每次调用时做方法拦截把安全需要的KV信息添加到HTTP请求头部分。 程序方式使用SDK编写的方式为:
import com.alibaba.csb.sdk.HttpCaller;
import com.alibaba.csb.ws.sdk.WSClientSDK;
...
**注意:**在编程方式调用时,首先要在整个JVM范围内启动一次WSClientSDK.warmup()来加载SDK所需要的类, 否则在第一次调用WSClientSDK时会很慢(~5s)
//首先使用标准的WS Client方法获取Proxy或者Dispath
MyPort proxy = ...;
//bind AK/SK到 proxy上
String ak = "xxxxx";
String sk = "xxxxx";
String apiName = xx;
String apiVersion = xx;
proxy = WSClientSDK.bind(proxy, ak, sk, apiName, apiVersion);
//使用返回的Proxy,调用客户端方法
Response response = proxy.method1(...);
…
根据CSB的设计约定,当CSB开放成WebService服务时,对应的WSDL的地址为如下格式:
a. 如果接入是 HTTP 协议,则开放出的 WSDL 地址是:
http://broker-vip:9081/$api_name/$api_version/ws2restful?wsdl
$api_name 为发布的服务名;
$api_version 为发布的服务版本;
"ws2restful"为固定值。
b. 如果接入是 HSF 协议, 则开放出来的 WSDL 地址是:
http://broker-vip:9081/$api_name/$api_version/$method?wsdl
$api_name 为发布的服务名; $api_version 为发布的服务版本; $method 为发布服务时对应的接入方法名。 c. 如果接入是 WS 协议(即WS透传), 则开放出来的 WSDL 地址是:
http://broker-vip:9081/$api_name/$api_version/ws2ws?wsdl
$api_name 为发布的服务名; $api_version 为发布的服务版本; "ws2ws"为固定值。
为了快速测试一个CSB开放出来的WebService服务,WS-SDK工具包提供了命令行方式调用的工具。
$ java -jar ws-client.jar -h
usage: java -jar wsclient.jar [options...]
-ak <arg> accessKey
-api <arg> 服务名
-d,--debug 打印调试信息
-ea <arg> endpoint地址,e.g:
http://broker-ip:9081/api/version/method
-h,--help 打印帮助信息
-ns <arg> 在wsdl中定义的服务的target namespace
-pname,--portName <arg> 在wsdl中定义的端口名
-rd <arg> soap请求内容,如果设置该选项时,-rf选项被忽略
-rf <arg> soap请求文件, 文件里定义soap请求的XML内容
-sk <arg> secretKey
-sname,--serviceName <arg> 在wsdl中定义的服务名
-soap12 -soap12 为soap12调用, 不定义为soap11
-version <arg> 服务版本
-wa <arg> wsdl地址,e.g:
http://broker-ip:9081/api/version/method?wsdl
TIP: 你可以使用系统参数-Dtest.stress.times=n 在压测或者限流测试时使用的参数,一次命令行调用可以发起n次调用
TIP: 如何从已知的WSDL中确定上述调用参数
java -jar target/ws-client-1.0.4.4-SNAPSHOT.jar -ak ak -sk sk -api PING -version vcsb \
-wa http://11.239.187.178:9081/PING/vcsb/ws2restful?wsdl \
-ea http://11.239.187.178:9081/PING/vcsb/ws2restful \
-ns http://ws2restful.PING.csb/ -sname PING -pname ws2restfulPortType \
-rd '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:test="http://ws2restful.PING.csb/">
<soapenv:Header/>
<soapenv:Body>
<test:ws2restful>
<name>abc</name>
</test:ws2restful>
</soapenv:Body>
</soapenv:Envelope>'
如果不使用-rd选项,可以把请求内容保存到一个文件中,然后使用-rf 指定这个文件。
**注意:**命令行方式不支持调用附件或者MTOM形式的WSDL服务
- Web Service SDK本身不能代替Client端的调用存根(即Dispatch 或者Proxy),所以首先用户需要使用Web Service标准的客户端工具生成Client端的调用存根;
- 使用Web Service SDK 提供的方法将调用服务需要的AccessKey, SecrectKey, ApiName, ApiVersion, 时间戳,指纹等信息以及通过这些信息生成的签名设置到Client端存 根上(即:Proxy,Dispatch);
- 使用处理过的客户端Proxy(或者Dispatch)发送请求服务时,Web Service SDK会将需要传送的安全和签名信息添加到HTTP Header中,并把这些信息传递给服务提供端进行鉴权和验签。
- 经过SDK处理后的HTTP请求中会包含如下的Header信息:
_api_access_key:abc
_api_name:api-name
_api_version:1.0.0
_api_timestamp:1473042916741
_api_fingerprint:sayComplex
_api_signature:AAAF/e2Scg/vv6PWRl1X/0RgRcQ=
mock_response:true [可选]
-
签名相关的公共HTTP Header包括: _api_access_key, _api_name, _api_version,_api_timestamp, _api_fingerprint, _api_signature。其中api_signature是根据SOAP Header里另外的三个Header组成的key=value格式,并按照key 的名 称字典排序,然后把相应的key=value使用&拼接成规范串(即,_api_access_key=xxxxx&api_name=xxx&_api_fingerprint=xxxx&api_timestamp=xxxx&_api_version=xxxx); mock_response是一个特殊的header, 通常在接口测试时候使用,当设置为true时,使Web Service 调用直接返回服务定义时候声明的Mock Soap Response,而不去调用后端真正的接入服务。
com.alibaba.csb.ws.sdk.AxisCallWrapper类的介绍
Axis客户端Call的wrapper类, 用以在发送soap请求前,将CSB所要求的签名信息存放到http header里, 具体用法:
//设置服务调用的安全信息
String apiName = "PING"; //要调用的服务名称
String apiVersion = "vcsb.ws"; //要调用的服务版本
String ak = "xxxx"; //订购服务的accessKey
String sk = "xxxx"; //订购服务的secrectKey
Service service = new Service();
// 首先,构造封装Call对象
Call call = AxisCallWrapper.createCallWrapper(service, ak, sk, apiName, apiVersion);
// 然后,使用封装Call对象进行方法调用
call.setTargetEndpointAddress("http://localhost:9081/PING/vcsb.ws/ws2ws");
call.setOperationName(new QName("http://hc.wsprocess.csb.alibaba.com/", "ping"));
call.addParameter("arg0", // 设置要传递的参数
org.apache.axis.encoding.XMLType.XSD_STRING, javax.xml.rpc.ParameterMode.IN);
Object[] args = { "wiseking" };
Object ret = call.invoke(args);
System.out.println("ret=" + ret);
注意,如果要正确使用这个类,需要在你的WSClientSDK编译和运行环境中包含axis依赖, 如:
<dependency>
<groupId>axis</groupId>
<artifactId>axis</artifactId>
<version>1.4</version>
</dependency>
<dependency>
<groupId>org.apache.axis</groupId>
<artifactId>axis-jaxrpc</artifactId>
<version>1.4</version>
</dependency>