本文以实际场景为例介绍接入HSF协议开放RESTful协议,以帮助您深入理解开放服务。
背景信息
本文仅介绍在实际场景中接入HSF协议开放RESTful服务时一些重要的配置步骤和参数,如需了解完整的流程和参数解释,请参见发布后端已有服务。
本文列举了接入HSF协议开放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场景,接入HSF协议支持开放为RESTful和WebService协议。
服务配置
接入后端代码
public ResultDTO<Item> add(Item item);
调用服务
您可以选择以下任一请求代码调用CSB开放的服务:
#通过Header参数curl CSB服务。 curl -H "_api_name:item.hsf.add" -H "_api_version:1.0.0" \ -d 'item={"itemName":"benz","quantity":10}' http://csb.target.server:8086/CSB
#使用CSB-SDK请求CSB服务 java -jar httpclient.jar -api item.hsf.add -version 1.0.0 -method post \ -D 'item={"itemName":"benz","quantity":10}' -url http://csb.target.server:8086/CSB
请求结果
{
"body": {
"msg": "SUCCESS",
"result": {
"itemName": "benz",
"trace": {
"traceId": "0ba783c115673295906521002d****",
"requestId": "0ba783c115673295902731001d****",
"rpcId": "0.1"
},
"quantity": 12
},
"code": "0"
},
"code": 200,
"message": "SUCCESS",
"requestId": "0ba783c115673295906521002d****"
}
JSON
说明 JSON场景,接入HSF协议只支持开放为RESTful协议;且还需要CSB Broker的版本大于等于3.8.1。
服务配置
接入后端代码
public ResultDTO<Item> add(Item item);
调用服务
#使用CSB SDK请求CSB服务。
java -jar httpclient.jar -api item.hsf.add.json -version 1.0.0 -method post \
-cbJSON '{"item":{"itemName":"benz","quantity":10}}' \
-url http://csb.target.server:8086/CSB
请求代码
{
"body": {
"msg": "SUCCESS",
"result": {
"itemName": "benz",
"trace": {
"traceId": "0ba783c115673295906521002d****",
"requestId": "0ba783c115673295902731001d****",
"rpcId": "0.1"
},
"quantity": 12
},
"code": "0"
},
"code": 200,
"message": "SUCCESS",
"requestId": "0ba783c115673295906521002d****"
}
参数MAP(CSB服务和后端代码均未指定Map.Value类型)
服务配置
接入后端代码
@Override
public <T> ResultDTO<List<T>> addMap(Map<String, T> param) {
return ResultDTO.getSuccessResult(param.values().stream().collect(Collectors.toList()));
}
调用服务
说明 CSB服务和后端代码均未指定Map.Value类型,可通过JSON class转换为HSF对应参数;不指定class无法转换为指定T,此时T为JSONObject。
#使用CSB SDK请求CSB服务。
java -jar httpclient.jar -api map.hsf.add -version 1.0.0 -method post \
-D 'param={
"jack": {
"name": "jack",
"age": 10,
"details": {
"NativePlace": {
"province": "江苏",
"city": "南京"
},
"PresentAddress": {
"province": "北京",
"city": "北京"
}
},
"class":"com.alibaba.edas.carshop.itemcenter.Contact"
},
"lucy": {
"name": "lucy",
"age": 10,
"details": {
"NativePlace": {
"province": "河北",
"city": "唐山"
},
"PresentAddress": {
"province": "广东",
"city": "深圳"
}
},
"class":"com.alibaba.edas.carshop.itemcenter.Contact"
}
}' -url http://localhost:8086/CSB
请求结果
{
"body": {
"msg": "SUCCESS",
"result": [{
"name": "lucy",
"details": {
"NativePlace": {
"province": "河北",
"city": "唐山",
"class": "com.alibaba.edas.carshop.itemcenter.Detail"
},
"PresentAddress": {
"province": "广东",
"city": "深圳",
"class": "com.alibaba.edas.carshop.itemcenter.Detail"
}
},
"class": "com.alibaba.edas.carshop.itemcenter.Contact",
"age": 10
}, {
"name": "jack",
"details": {
"NativePlace": {
"province": "江苏",
"city": "南京",
"class": "com.alibaba.edas.carshop.itemcenter.Detail"
},
"PresentAddress": {
"province": "北京",
"city": "北京",
"class": "com.alibaba.edas.carshop.itemcenter.Detail"
}
},
"class": "com.alibaba.edas.carshop.itemcenter.Contact",
"age": 10
}],
"code": "0"
},
"code": 200,
"message": "SUCCESS",
"requestId": "0ba783c115679524648981002d88dd"
}
参数List<Map>(CSB服务和后端代码均未指定Map.Value类型)
服务配置
接入后端代码
@Override
public <T> ResultDTO<List<T>> addMapList(List<Map<String, T>> params) {
return ResultDTO.getSuccessResult(params.stream().map(x -> x.values()).flatMap(x -> x.stream()).collect(Collectors.toList()));
}
调用服务
说明 CSB服务和后端代码均未指定Map.Value类型,可通过JSON class转换为HSF对应参数;不指定class无法转换为指定T,此时T为JSONObject。
#使用CSB SDK请求CSB服务。
java -jar httpclient.jar -api map.hsf.adds -version 1.0.0 -method post \
-D 'params=[{
"jack": {
"name": "jack",
"age": 10,
"details": {
"NativePlace": {
"province": "江苏",
"city": "南京"
},
"PresentAddress": {
"province": "北京",
"city": "北京"
}
},
"class":"com.alibaba.edas.carshop.itemcenter.Contact"
},
"lucy": {
"name": "lucy",
"age": 10,
"details": {
"NativePlace": {
"province": "河北",
"city": "唐山"
},
"PresentAddress": {
"province": "广东",
"city": "深圳"
}
},
"class":"com.alibaba.edas.carshop.itemcenter.Contact"
}
}, {
"lily": {
"name": "lily",
"age": 10,
"details": {
"NativePlace": {
"province": "江苏",
"city": "南京"
},
"PresentAddress": {
"province": "北京",
"city": "北京"
}
},
"class":"com.alibaba.edas.carshop.itemcenter.Contact"
}
}]' -url http://localhost:8086/CSB
请求结果
{
"body": {
"msg": "SUCCESS",
"result": [{
"name": "lucy",
"details": {
"NativePlace": {
"province": "河北",
"city": "唐山",
"class": "com.alibaba.edas.carshop.itemcenter.Detail"
},
"PresentAddress": {
"province": "广东",
"city": "深圳",
"class": "com.alibaba.edas.carshop.itemcenter.Detail"
}
},
"class": "com.alibaba.edas.carshop.itemcenter.Contact",
"age": 10
}, {
"name": "jack",
"details": {
"NativePlace": {
"province": "江苏",
"city": "南京",
"class": "com.alibaba.edas.carshop.itemcenter.Detail"
},
"PresentAddress": {
"province": "北京",
"city": "北京",
"class": "com.alibaba.edas.carshop.itemcenter.Detail"
}
},
"class": "com.alibaba.edas.carshop.itemcenter.Contact",
"age": 10
}, {
"name": "lily",
"details": {
"NativePlace": {
"province": "江苏",
"city": "南京",
"class": "com.alibaba.edas.carshop.itemcenter.Detail"
},
"PresentAddress": {
"province": "北京",
"city": "北京",
"class": "com.alibaba.edas.carshop.itemcenter.Detail"
}
},
"class": "com.alibaba.edas.carshop.itemcenter.Contact",
"age": 10
}],
"code": "0"
},
"code": 200,
"message": "SUCCESS",
"requestId": "0ba783c115679526561641002d8d2f"
}
参数MAP(后端服务指定Map.Value类型)
服务配置
接入后端代码
指定Map.Value类型。
@Override
public ResultDTO<List<Contact>> addMapFixedValType(Map<String, Contact> param) {
return ResultDTO.getSuccessResult(Lists.newArrayList(param.values()));
}
调用服务
#使用CSB SDK请求CSB服务。
java -jar httpclient.jar -api map.hsf.add.fixtype -version 1.0.0 -method post \
-D 'param={
"jack": {
"name": "jack",
"age": 10,
"details": {
"NativePlace": {
"province": "江苏",
"city": "南京"
},
"PresentAddress": {
"province": "北京",
"city": "北京"
}
}
},
"lucy": {
"name": "lucy",
"age": 10,
"details": {
"NativePlace": {
"province": "山西",
"city": "太原"
},
"PresentAddress": {
"province": "浙江",
"city": "杭州"
}
}
}
}' -url http://localhost:8086/CSB
请求结果
{
"body": {
"msg": "SUCCESS",
"result": [{
"name": "lucy",
"details": {
"NativePlace": {
"province": "山西",
"city": "太原",
"class": "com.alibaba.edas.carshop.itemcenter.Detail"
},
"PresentAddress": {
"province": "浙江",
"city": "杭州",
"class": "com.alibaba.edas.carshop.itemcenter.Detail"
}
},
"class": "com.alibaba.edas.carshop.itemcenter.Contact",
"age": 10
}, {
"name": "jack",
"details": {
"NativePlace": {
"province": "江苏",
"city": "南京",
"class": "com.alibaba.edas.carshop.itemcenter.Detail"
},
"PresentAddress": {
"province": "北京",
"city": "北京",
"class": "com.alibaba.edas.carshop.itemcenter.Detail"
}
},
"class": "com.alibaba.edas.carshop.itemcenter.Contact",
"age": 10
}],
"code": "0"
},
"code": 200,
"message": "SUCCESS",
"requestId": "0ba783c115679539733771002dabe8"
}
参数POJO.Map
服务配置
接入后端代码
package com.alibaba.edas.carshop.itemcenter;
import java.util.Map;
@Data
public class Contact extends JsonClass {
private String name;
private int age;
private Map<String, Detail> details;
}
@Data
class Detail extends JsonClass {
private String province;
private String city;
private String area;
private String address;
}
public ResultDTO<Contact> addMapField(Contact contact) {
return ResultDTO.getSuccessResult(contact);
}
调用服务
#使用CSB SDK请求CSB服务。
java -jar httpclient.jar -api map-field.hsf.add -version 1.0.0 -method post \
-D 'contact={
"name": "jack",
"age": 10,
"details": {
"NativePlace": {
"province": "江苏",
"city": "南京"
},
"PresentAddress": {
"province": "北京",
"city": "北京"
}
}
}' -url http://localhost:8086/CSB
请求结果
{
"body": {
"msg": "SUCCESS",
"result": {
"name": "jack",
"details": {
"NativePlace": {
"province": "江苏",
"city": "南京",
"class": "com.alibaba.edas.carshop.itemcenter.Detail"
},
"PresentAddress": {
"province": "北京",
"city": "北京",
"class": "com.alibaba.edas.carshop.itemcenter.Detail"
}
},
"class": "com.alibaba.edas.carshop.itemcenter.Contact",
"age": 10
},
"code": "0"
},
"code": 200,
"message": "SUCCESS",
"requestId": "0ba783c115679538866181002da9ae"
}