全部产品

HTTP 转 SOFAREST 入门(仅专有云)

更新时间:2020-09-03 15:08:24

本文介绍如何快速创建并发布一个 HTTP API 类型的 API 服务,通过 API 网关进行协议转换,使用 SOFAREST 协议将请求转发到后端业务系统集群。

操作步骤

说明:建议您先参见 快速入门概述,了解 API 网关的角色及完整使用流程。

入门流程

  1. API 发布者编写 SOFAREST Server
  2. API 发布者创建系统集群
  3. API 发布者创建 API 分组
  4. API 发布者创建并发布 HTTP API
  5. API 订阅者创建应用
  6. API 发布者创建授权对象
  7. API 发布者绑定授权对象
  8. API 订阅者编写 API 调用代码

示例工程

为方便快速体验 API 网关 HTTP 转 SOFAREST 的 API 服务,您可以点击此处下载本文涉及的 示例工程

步骤一:编写 SOFAREST Server

SOFAREST Server 的编写没有特殊的要求,按照 SOFAREST 的标准教程即可,此处简单编写一个 SampleRestFacade。

  1. @Path("/users")
  2. @Consumes(RestConstants.DEFAULT_CONTENT_TYPE)
  3. @Produces(RestConstants.DEFAULT_CONTENT_TYPE)
  4. public interface SampleRestFacade {
  5. @GET
  6. @Path("/user")
  7. public RestSampleFacadeResp<DemoUserModel> userInfo(@QueryParam("userName") String userName) ;
  8. }
  9. public class SampleRestFacadeRestImpl implements SampleRestFacade {
  10. @Override
  11. public RestSampleFacadeResp<com.alipay.gateway.endpoint.model.DemoUserModel> userInfo(String userName) {
  12. DemoUserModel demoUserModel = new DemoUserModel();
  13. demoUserModel.setRealName("Real " + userName);
  14. demoUserModel.setUserName(userName);
  15. RestSampleFacadeResp<DemoUserModel> result = new RestSampleFacadeResp<DemoUserModel>();
  16. result.setData(demoUserModel);
  17. result.setSuccess(true);
  18. return result;
  19. }
  20. }

将该 service 发布为 SOFAREST 服务,示例如下:

  1. <!-- sofa rest resource to deal with rest request -->
  2. <bean id="sampleRestFacadeRest" class="com.alipay.gateway.endpoint.impl.SampleRestFacadeRestImpl"/>
  3. <sofa:service ref="sampleRestFacadeRest" interface="com.alipay.gateway.endpoint.facade.SampleRestFacade" >
  4. <sofa:binding.rest>
  5. </sofa:binding.rest>
  6. </sofa:service>

进行本地测试,示例如下:

  1. curl -i 127.0.0.1:8341/webapi/users/user?userName=name
  2. {"success":true,"resultMsg":null,"requestId":null,"data":{"userId":0,"userName":"name","realName":"Real name"}}

步骤二:创建系统集群

  1. 进入 API 网关控制台页面,左侧导航栏选择 API 发布 > 系统集群
  2. 在系统集群列表页面,点击右上方的 创建系统集群 按钮。
  3. 在新弹出窗口中,您需要配置以下信息:
    • 系统集群名称:必填,用于识别系统集群。根据本示例,此处可使用 sofa-rest
    • 协议类型:支持 HTTP、SOFARPC、MRPC、SOFAREST。根据本示例,此处需选择 SOFAREST
    • 地址配置方式:SOFAREST 可以 手动配置 服务端地址,也可以通过 SOFA 注册中心 来订阅。本示例选择 手动配置
    • IP地址/域名:格式为 地址:端口。本示例中,IP 地址使用 30.39.170.42,端口号使用 8341
      • IP 地址或域名:
        • IP 地址格式为 (1~255).(0~255).(0~255).(0~255)
        • 域名可以包含字母、数字或者半角的连接符 “-“,总共不超过255 个字符。
      • 端口:HTTP 默认端口为 80,SOFARPC/MRPC/SOFAREST 默认端口为 12200。端口号范围为 1-65535。
    • 描述:选填,用于描述系统集群的作用等,64 个字符以内,可为空。
      创建系统集群
  4. 点击 确定

步骤三:创建 API 分组

  1. 进入 API 网关控制台页面,左侧导航栏中选择 API 发布 > API 分组,进入分组列表。
  2. 点击 API 分组列表右上方的 创建分组 按钮。
  3. 在新弹出窗口中,输入 API 分组信息:
    • 分组名称:必填,用于识别 API 分组。支持英文字母、中文、数字、_、-,32 个字符以内。本示例使用 sofarest-demo
    • 描述:选填,用于描述 API 分组的作用等,64 个字符以内,可为空。
      创建 API 分组
  4. 点击 确定

步骤四:创建并发布 HTTP API

  1. 进入 API 网关控制台 > API 发布 > API 管理 页,点击列表右上方的 创建 API
  2. 在新页面中,选择 HTTP API 类型,点击 创建
  3. 定义 API 步骤中,您需要配置以下信息:
    • API 分组:必选,选择上一步创建的 API 分组。
    • API 名称:必填,用于识别 API,支持英文字母、中文、数字、_、-,32 个字符以内。本示例使用 sofarest-demo
      说明:同一个 API 分组下,API 名称不能相同。
    • 描述:选填,用于描述 API 的作用等,64 个字符以内。
    • API 授权应用类型:必选,指定可以订阅并调用该 API 的应用类型。根据本示例,选择 应用
    • 请求路径:必填,针对应用设置的请求资源的 URL,通过请求路径可以定位到要请求的资源。根据本示例,输入 /rest
    • 路径匹配规则:选择 绝对匹配,即调用时完全匹配以上填写的路径。详见 路径匹配规则
    • 方法:必填,表明要对给定的 HTTP 资源执行的操作。本示例使用 GET
    • 安全认证:选择 密钥认证,表示订阅应用访问授权的 API 时需要使用密钥进行身份认证。
    • 请求参数:可选,详见 API 属性说明 > 请求参数
    • 响应参数:可选,详见 API 属性说明 > 响应参数
  4. 点击 下一步,进入后端配置页面,您需要选择 后端配置类型 并输入后端配置信息。根据本示例,需选择 系统集群 并配置具体集群信息。
    • 协议类型:必选,表示网关接收到请求后转发给的后端服务使用的通信协议类型。根据本示例,此处选择 SOFAREST
    • 接口名称:即 API 接口名称,支持英文字母、数字、. 、: 、@,以小写字母作为开头。根据本示例,此处输入 com.alipay.gateway.endpoint.facade.SampleRestFacade:1.0@rest
    • 请求路径:API 请求所指向的资源 URL。本示例使用 /webapi/users/user
    • 超时时间:必填,API 请求超时时间,单位为毫秒(ms),保持默认即可。
    • 路由策略:必选,表示当网关接收到语法后使用的路由策略。本例中选择 根据请求路径路由,即直接转发。
    • 系统集群:必选,选择步骤二创建的系统集群,即 sofa-rest
  5. 点击 创建。
  6. 创建完成后,点击 立即发布 发布该 API。
    创建并发布 API

步骤五:创建应用

  1. 进入 API 网关控制台 > API 订阅 > 应用管理 页,点击列表右上方的 创建应用
  2. 创建应用 窗口,选择 应用类型应用
  3. 输入 应用名称,用于识别应用。本例使用 sofarest
    创建应用
  4. 点击 确定

应用添加完成后,订阅者需在应用详情页,获取该应用 APPID。获取 APPID 后,需将 APPID 提供给想要订阅的 API 的发布者,获得该 API 的访问授权。

步骤六:创建授权对象

  1. 进入 API 网关控制台 > API 发布 > 授权管理 页,点击列表右上方的 创建授权对象
  2. 创建授权对象 窗口中,配置订阅方应用的授权信息。
    • 应用来源:必选。此处选 内部系统,表示授权给当前租户的当前环境下的应用订阅。
    • 应用名称:输入其上一步创建的应用名称,如 sofarest,系统会自动获取其 APPID 与类型。
    • 所属公司/部门:用于识别应用所属的公司或部门,可为空。
    • 描述:输入对该授权对象的备注信息,可为空。
      创建授权对象
  3. 点击 确定

步骤七:绑定授权对象

  1. API 管理 页面,找到待订阅 API,进入其详情页。
  2. 授权对象 标签页下,点击 绑定授权对象
  3. 添加授权对象 窗口中,找到刚刚创建的授权应用。
    绑定授权对象
  4. 勾选该应用,点击 确定,完成 API 授权。

完成绑定后,在 API 详情页,您还可以切换至 API 调试 标签页,进行调试,如下图所示。
调试

步骤八:编写 API 调用代码

  1. 获取如下服务配置信息:
    • 在订阅方应用详情页获取该应用的密钥(Access Key/Secret Key)。
      应用的密钥
    • 在 API 详情页获取该 API 的域名(host)、请求路径(path)与方法(method)。
      API 详情
  2. 编写调用代码,示例如下:

    1. public class GatewayTest {
    2. private String subAppAccessKey = "igZJjnTLDtTmrPn9";
    3. private String subAppSecretKey = "iFqOds2tqXxQU4oIzAGWw6dGC6BRORX8";
    4. private String gatewayUrl = "http://nhhondzqphmkkkd5.apigateway.cloud.58sit-ake2.alipay.net";
    5. private ApiClient apiClient;
    6. @Before
    7. public void initClient() {
    8. // 初始化请求客户端
    9. ApiSecretKey apiSecretKey = new ApiSecretKey(subAppAccessKey, subAppSecretKey);
    10. List<ApiSecretKey> secretKeys = new ArrayList<>();
    11. secretKeys.add(apiSecretKey);
    12. apiClient = new DefaultApiClient(gatewayUrl, secretKeys);
    13. }
    14. @Test
    15. public void testNoSignHttp() {
    16. ParamPostRequest request = new ParamPostRequest();
    17. request.setPath("rest");
    18. // 是否对响应进行签名校验
    19. request.setClientCheckSign(false);
    20. ApiResponse response = apiClient.execute(request);
    21. System.out.println(JSON.toJSONString(response));
    22. }
    23. }
  3. 发起调用后,可得出以下结果:
    1. {"body":"{\"success\":true,\"resultMsg\":null,\"requestId\":null,\"data\":{\"userId\":0,\"userName\":null,\"realName\":\"Real null\"}}"}

相关链接