AWS PaaS API参考指南

封装和发布自己的HTTP API

基于AWS PaaS的API架构,应用开发者可以使用Java语言封装和发布自己的HTTP API。

步骤

  1. 在您的App Java工程中编写Java类
  2. 使用Java注解,声明服务类型和参数结构
  3. 确定API请求的返回类型
  4. 发布和浏览服务
  5. 测试发布的API

步骤1:在您的App Java工程中编写Java类

获得本地开发环境,请移步这里

步骤2:使用Java注解,声明服务类型和参数结构

注解 说明
@Controller 类注解,描述API分类、注释等
@Mapping 方法注解,描述API方法名、注释等
@Param 参数注解,描述API参数结构

com.actionsoft.bpms.server.bind.annotation.Controller

该注解用于Java类,必须使用。注解属性说明如下:

属性 是否必须 说明
type Controller类型,当值为HandlerType.OPENAPI时为Web API
apiName Web API服务类别名称,例如:Process API
desc 该服务的描述信息

示例

@Controller(type = HandlerType.OPENAPI,
apiName = "Demo API",desc = "API扩展开发演示")
public class SayHello {
    ...
}

com.actionsoft.bpms.server.bind.annotation.Mapping

该注解用于Java类方法,必须使用。注解属性说明如下:

属性 是否必须 说明
value api名称,全局不重复。必须以.分割多个空间。例如:org.user.create
desc 该api的描述信息
authInfo 该api特定的授权验证方式,和CC集成身份中的资源匹配授权,该描述用于引导管理员配置集成身份的授权

示例

@Mapping(value = "demo.say")
public StringResponse say(){
    ...
}

com.actionsoft.bpms.server.bind.annotation.Param

该注解用于方法的参数、类属性,不必须使用。注解属性说明如下:

属性 是否必须 说明
value 参数名称,默认为方法的参数名
required 参数是否必须,默认为是
desc 参数的描写信息,值说明,示例等

示例

public StringResponse say(@Param(value = "str1",
desc = "字符串1", required = true) String str1) {
    ...
}

步骤3:确定API请求的返回类型

服务方法可以返回void或者返回一个com.actionsoft.bpms.api.common.ApiResponse子类。

不支持String、Integer等范围外类型的原因是,HTTP API被设计成结果响应式编程模式,即请求JSON时返回JSON、请求XML时返回XML。为此,开发者需遵循ApiResponse父类实现自己的对象封装。

常用的简单对象已提供在AWS PaaS开发框架中(%AWS-HOME%/bin/lib/aws-api-common.jar),封装的对象包括:

Java Object 封装的对象
String StringResponse
Boolean BoolResponse
Integer IntResponse
Long LongResponse
Map MapResponse
List ListMapResponse
Object ObjectResponse
Integer Array IntArrayResponse
String Array StringArrayResponse

如要返回的对象不在上述范围之内,开发者可以基于ApiResponse实现自定义对象,并在该类上增加@XmlRootElement注解,用于支持XML响应格式。

示例

@XmlRootElement
class CalcResponse extends ApiResponse {
    private int num1;
    private int num2;
    private int num3;

    public CalcResponse(int num1, int num2) {
        super();
        this.num1 = num1;
        this.num2 = num2;
        // 计算相加
        num3 = num1 + num2;
    }

    public int getNum1() {
        return num1;
    }

    public void setNum1(int num1) {
        this.num1 = num1;
    }

    public int getNum2() {
        return num2;
    }

    public void setNum2(int num2) {
        this.num2 = num2;
    }

    public int getNum3() {
        return num3;
    }

    public void setNum3(int num3) {
        this.num3 = num3;
    }

}

ApiResponse中属性errorCode来自:com.actionsoft.bpms.api.common.ErrorType,当errorCode值非空时,请求出现业务异常

下面给出一个完整的API封装示例

package com.actionsoft.apps.poc.api.local.api;

import javax.xml.bind.annotation.XmlRootElement;

import com.actionsoft.bpms.api.common.ApiResponse;
import com.actionsoft.bpms.server.bind.annotation.Controller;
import com.actionsoft.bpms.server.bind.annotation.HandlerType;
import com.actionsoft.bpms.server.bind.annotation.Mapping;
import com.actionsoft.bpms.server.bind.annotation.Param;
import com.actionsoft.sdk.service.response.StringResponse;

@Controller(type = HandlerType.OPENAPI, apiName = "Demo API", desc = "API扩展开发演示")
public class SayHello {

    // 返回简单String
    @Mapping(value = "demo.say")
    public StringResponse say(
    @Param(value = "str1",
    desc = "字符串1",
    required = true) String str1) {
        StringResponse r = new StringResponse();
        r.setData(str1);
        return r;
    }

    // 返回自定义的对象
    @Mapping(value = "demo.calc")
    public CalcResponse calc(
    @Param(value = "num1",
    desc = "数字1",
    required = true) Integer num1,

    @Param(value = "num2",
    desc = "数字2",
    required = true) Integer num2) {
        CalcResponse r = new CalcResponse(num1, num2);
        return r;
    }

}

@XmlRootElement
class CalcResponse extends ApiResponse {
    private int num1;
    private int num2;
    private int num3;

    public CalcResponse(int num1, int num2) {
        super();
        this.num1 = num1;
        this.num2 = num2;
        // 计算相加
        num3 = num1 + num2;
    }

    public int getNum1() {
        return num1;
    }

    public void setNum1(int num1) {
        this.num1 = num1;
    }

    public int getNum2() {
        return num2;
    }

    public void setNum2(int num2) {
        this.num2 = num2;
    }

    public int getNum3() {
        return num3;
    }

    public void setNum3(int num3) {
        this.num3 = num3;
    }

}

步骤4:发布和浏览服务

将编写的程序编译成jar,存放到您自己的应用lib目录下(假设应用名称是com.abc.apps.do,那么路径应该在%AWS-HOME%/apps/install/com.abc.apps.do/lib),如果开发者引用了三方jar资源,也一同存放到该目录下。

正常情况,这些jar资源将被动态加载到AWS PaaS容器,自动完成发布。当处于开发调试环境时,若首次未自动发布,可重启本地的AWS PaaS服务。

浏览服务 API服务端开发代码

步骤5:测试发布的API

您可以用熟悉的方式去测试刚刚发布的API。下面使用Java客户端模拟调用demo.saydemo.calc两个API

import java.util.HashMap;
import java.util.Map;

import com.actionsoft.bpms.api.OpenApiClient;

public class CallWebAPITest  {
    private static String apiServer = "http://localhost:8088/portal/openapi";
    private static String accessKey = "salesforce#1";
    private static String secret = "0a799959-8327";

    public static void say() {
        try {
            String apiMethod = "demo.say";
            Map<String, Object> args = new HashMap<String, Object>();
            args.put("str1", "Hi, AWS PaaS!");
            OpenApiClient client = new OpenApiClient(apiServer, accessKey, secret,
            OpenApiClient.FORMAT_JSON);
            String r = client.exec(apiMethod, args);
            System.out.println(r);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    public static void calc() {
        try {
            String apiMethod = "demo.calc";
            Map<String, Object> args = new HashMap<String, Object>();
            args.put("num1",5);
            args.put("num2",6);
            OpenApiClient client = new OpenApiClient(apiServer, accessKey, secret,
            OpenApiClient.FORMAT_JSON);
            String r = client.exec(apiMethod, args);
            System.out.println(r);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    public static void main(String args[]){
        say();
        calc();
    }

}

打印输出如下请求结果

{
  "data" : "Hi, AWS PaaS!",
  "result" : "ok"
}

{
  "num1" : 5,
  "num2" : 6,
  "num3" : 11,
  "result" : "ok"
}


Seven
 010-62962343-690
 liujx@actionsoft.com.cn
感谢您对该文档的关注!如果您对当前页面内容有疑问或好的建议,请与我联系。如果您需要解答相关技术问题请登录AWS客户成功社区