HTTP API 入门

操作步骤

示例工程

为方便快速开发体验 API 网关 HTTP API 服务，您可以下载本文涉及的 示例工程。

步骤一：编写 HTTP Server

为方便快速体验 API 网关 HTTP API 服务发布与调用，此处编写一个简单的 Spring Boot Server。

@RestController
public class StartController {

    @RequestMapping("/hello/world")
    public String hello() {
        System.out.println("hello");
        Map<String, String> m = new HashMap<>();
        m.put("hello", "world");

        return JSON.toJSONString(m);
    }
}

编写完成后，将服务部署在 API 网关可以访问到的服务器上，启动该 server。

步骤二：创建系统集群

1. 进入金融分布式架构控制台。

2. 在左侧导航栏单击 API 统一网关 > API 发布 > 系统集群。

3. 在系统集群列表页面，单击 创建系统集群 按钮。

4. 在新弹出窗口中，您需要配置以下信息：

   • 系统集群名称：必填，用于识别系统集群。本示例使用 helloserver。

   • 协议类型：根据本示例，选择 HTTP。

   • 地址配置方式：选择手动配置，即手动配置系统集群的 IP 地址或域名。

   • IP地址/域名：格式为 地址：端口。本示例中，IP 地址为 http://127.0.0.1，端口号为 8080。

     • IP 地址或域名：

       • IP 地址格式为 （1~255）.（0~255）.（0~255）.（0~255）。

       • 域名可以包含字母、数字或者半角的连接符 （-），总共不超过 200 个字符。

       • 域名必须以 http:// 或 https:// 开头。

     • 端口：HTTP 默认端口为 80，SOFARPC 默认端口为 12200。端口号范围为 1-65535。

   • 认证方式：即网关向后端系统集群发送请求时是否加签。本示例，不使用认证功能，选择 无。

     说明

     如需认证功能，在步骤一编写后端系统、本地 API 服务开发时需要接入网关 SDK。详见 编写HTTP API。

   • 描述：用于描述系统集群的作用等，64 个字符以内，可为空。

     

5. 完成后单击 确定。

步骤三：创建 API 分组

1. 在左侧导航栏单击 API 发布 > API 分组，进入分组列表。

2. 单击 API 分组列表右上方的 创建分组 按钮。

3. 在新弹出窗口中，输入 API 分组信息：

   • 分组名称：必填，用于识别 API 分组。支持英文字母、中文、数字、下划线（_）、连接符（-），32 个字符以内。本示例使用 hello。

   • 描述：选填，用于描述 API 分组的作用等，64 个字符以内，可为空。

     

4. 完成后单击 确定。

步骤四：创建并发布 HTTP API

1. 在左侧导航栏单击 API 发布 > API 管理 页，单击列表右上方的 创建 API。

2. 在新页面中，选择 HTTP API 类型，单击 创建。

3. 在 定义 API 步骤中，您需要配置以下信息：

   • API 分组：必选，选择步骤三创建的 API 分组。

   • API 名称：必填，用于识别 API，支持英文字母、中文、数字、下划线（_）、连接符（-），32 个字符以内。本示例使用 hello。

     说明

     同一个 API 分组下，API 名称不能相同。

   • 描述：选填，用于描述 API 的作用等，64 个字符以内。

   • API 授权应用类型：必选，指定可以订阅并调用该 API 的应用类型。根据本示例，需选择 应用。

   • 请求路径：必填，针对应用设置的请求资源的 URL，通过请求路径可以定位到要请求的资源。根据本示例，需输入 /hello/world。

   • 路径匹配规则：选择 绝对匹配，即调用时完全匹配以上填写的路径。详见 路径匹配规则。

   • 方法：必填，表明要对给定的 HTTP 资源执行的操作。本示例使用 GET。

   • 请求参数：即 API 订阅者向网关发起请求时要配置的参数。详见 API 属性说明 > 请求参数。

   • 响应参数：即网关向订阅者发送响应时的返回值类型和错误码等。详见 API 属性说明 > 响应参数。

     

4. 单击 下一步，进入后端配置页面，您需要选择 后端配置类型 并输入后端配置信息。根据本示例，需选择 系统集群 并配置具体集群信息。

   • 协议类型：必选，表示网关接收到请求后转发给的后端服务使用的通信协议类型。根据本示例，选择 HTTP。

   • 请求路径：API 请求所指向的资源 URL。本示例使用 /hello/world。

   • 超时时间：必填，API 请求超时时间，单位为毫秒（ms），保持默认 3000 毫秒即可。

   • 路由策略：必选，表示当网关接收到语法后使用的路由策略。本例中选择 根据请求路径路由，即直接转发。

   • 系统集群：必选，选择步骤二创建的系统集群，即 helloserver。

     

5. 单击 创建。

6. 创建完成后，单击 立即发布 发布该 API。

步骤五：创建应用

1. 在左侧导航栏单击 API 订阅 > 应用管理 页，单击列表右上方的 创建应用。

2. 在 创建应用 窗口，选择 应用类型 为 应用。

3. 输入 应用名称，用于识别应用。本例使用 hello。

   

4. 单击 确定。

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

步骤六：创建授权对象

1. 在左侧导航栏单击 API 发布 > 授权管理 页，单击列表右上方的 创建授权对象。

2. 在 创建授权对象 窗口中，配置订阅方应用的授权信息。

   • 应用来源：必选。此处选 内部系统 即可，表示授权给当前租户的当前环境下的应用订阅。

   • 应用名称：输入步骤五创建的应用名称，如 hello，系统会自动获取其 APPID 与类型。

   • 所属公司/部门：用于识别应用所属的公司或部门，可为空。

   • 描述：输入对该授权对象的备注信息，可为空。

     

3. 完成后单击 确定。

步骤七：绑定授权对象

1. 在 API 管理 页面，找到待订阅 API，进入其详情页。

2. 在 授权对象 标签页下，单击 绑定授权对象。

3. 在 添加授权对象 窗口中，找到步骤六创建的授权应用。

   

4. 勾选该应用，单击 确定，完成 API 授权。

步骤八：编写 API 调用代码

1. 获取如下服务配置信息：

   • 在订阅方应用详情页获取该应用的密钥（Access Key/Secret Key）。

     

   • 在 API 详情页获取该 API 的域名（host）、请求路径（path）与方法（method）。

     

2. 编写调用代码，此处以 Java 代码为例：

   说明

   如果 API 开启了密钥认证，您还需要在工程中配置相应的 Access Key 和 Secret Key，推荐使用启动参数和环境变量的形式。

   # 客户端请求的ak、sk，就是应用的密钥信息
   gateway.accessKey=<testAccessKey ID>
   gateway.secretKey=<testSecretKey ID>
   apigateway.url=<yourGatewayURL>

      @Value("${gateway.accessKey}")
      private String accessKey;
   
      @Value("${gateway.secretKey}")
      private String secretKey;
   
      @Value("${apigateway.url}")
      private String gatewayurl;
   
       @Before
       public void initClient() {
           // 初始化请求客户端
           ApiSecretKey apiSecretKey = new ApiSecretKey(gateway.accessKey, gateway.secretKey);
           List<ApiSecretKey> secretKeys = new ArrayList<>();
           secretKeys.add(apiSecretKey);
           apiClient = new DefaultApiClient(gatewayUrl, secretKeys);
       }
   
       @Test
       public void testNoSignHttp() {
           ParamGetRequest request = new ParamGetRequest();
           request.setPath("hello");
   
           // 是否对响应进行签名校验
           request.setClientCheckSign(false);
   
           ApiResponse response = apiClient.execute(request);
   
           System.out.println(JSON.toJSONString(response));
       }

3. 发起调用后，可得出以下结果：

   {"body":"{\"hello\":\"world\"}"}

注意事项

如果您使用的是本文档的示例工程，可以将 com.alipay.gateway.quickstart.Config#apiServletSignFilter 方法中的 filter.setCheckSign(true); 注释掉。注释之后，将不会对请求进行验签验证；否则会报“获取签名密钥失败”的错误。