AI 助理
备案控制台
文档
输入文档关键字查找
首页 SOFAStack API 统一网关 快速入门 HTTP API 入门

HTTP API 入门

更新时间：
我的收藏

本文将引导您创建、发布并调用一个 HTTP 类型的 API 服务，以快速体验 API 网关。

操作步骤

说明

建议您先阅读 快速入门概述，了解 API 网关的角色及完整使用流程。

http-api-入门

示例工程

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

步骤一：编写 HTTP Server

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

说明

不使用后端集群认证功能时，API 网关对 HTTP Server 无要求。如需网关和服务端之间的双向认证，则需要接入网关 SDK。目前仅提供 Java SDK。详见 HTTP API 服务开发。

@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 个字符以内，可为空。

      1

  5. 完成后单击 确定。

步骤三：创建 API 分组

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

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

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

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

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

      2

  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 属性说明 > 响应参数。

      3

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

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

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

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

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

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

      5

  5. 单击 创建。

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

步骤五：创建应用

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

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

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

    11

  4. 单击 确定。

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

步骤六：创建授权对象

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

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

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

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

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

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

      22

  3. 完成后单击 确定。

步骤七：绑定授权对象

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

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

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

    11

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

步骤八：编写 API 调用代码

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

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

      111

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

      1111

  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); 注释掉。注释之后，将不会对请求进行验签验证；否则会报“获取签名密钥失败”的错误。

注释

上一篇：概述下一篇：HTTP 转 SOFARPC 入门
文档推荐