全部产品

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
publicclassStartController{

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

return JSON.toJSONString(m);
}
}

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

步骤二:创建系统集群

  1. 进入 API 网关控制台页面,左侧导航栏选择 API 发布 > 系统集群

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

  3. 在新弹出窗口中,您需要配置以下信息:

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

    • 协议类型:根据本示例,选择 HTTP

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

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

      • IP 地址或域名:

        • IP 地址格式为 (1~255).(0~255).(0~255).(0~255)

        • 域名可以包含字母、数字或者半角的连接符 (-),总共不超过255 个字符。

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

      • 端口:HTTP 默认端口为 80,SOFARPC/MRPC 默认端口为 12200。端口号范围为 1-65535。

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

      说明
      如需认证功能,在步骤一编写后端系统、本地 API 服务开发时需要接入网关 SDK。详见 编写HTTP API
    • 描述:用于描述系统集群的作用等,64 个字符以内,可为空。创建系统集群

  4. 完成后单击 确定

步骤三:创建 API 分组

  1. 进入 API 网关控制台页面,左侧导航栏中选择 API 发布 > API 分组,进入分组列表。

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

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

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

    • 描述:选填,用于描述 API 分组的作用等,64 个字符以内,可为空。创建 API 分组

  4. 完成后单击 确定

步骤四:创建并发布 HTTP API

  1. 进入 API 网关控制台 > 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 网关控制台 > API 订阅 > 应用管理 页,单击列表右上方的 创建应用

  2. 创建应用 窗口,选择 应用类型应用

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

  4. 单击 确定

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

步骤六:创建授权对象

  1. 进入 API 网关控制台 > API 发布 > 授权管理 页,单击列表右上方的 创建授权对象

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

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

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

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

    • 描述:输入对该授权对象的备注信息,可为空。创建授权对象

  3. 完成后单击 确定

步骤七:绑定授权对象

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

  2. 授权对象 标签页下,单击 绑定授权对象

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

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

步骤八:编写 API 调用代码

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

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

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

  2. 编写调用代码,此处以 Java 代码为例:

    publicclassGatewayTest{
    privateString subAppAccessKey ="UH4tR0Tr4XnclIA8d";
    
    privateString subAppSecretKey ="060WysxEmlujA4wsNKU1JOUOZNpzdSoY";
    
    privateString gatewayUrl ="http://el8tng1lbmn3clja.apigateway.inc.alipay.net";
    
    privateApiClient apiClient;
    
    @Before
    publicvoid initClient(){
    // 初始化请求客户端
    ApiSecretKey apiSecretKey =newApiSecretKey(subAppAccessKey, subAppSecretKey);
    List<ApiSecretKey> secretKeys =newArrayList<>();
         secretKeys.add(apiSecretKey);
         apiClient =newDefaultApiClient(gatewayUrl, secretKeys);
    }
    
    @Test
    publicvoid testNoSignHttp(){
    ParamGetRequest request =newParamGetRequest();
         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); 注释掉。注释之后,将不会对请求进行验签验证;否则会报“获取签名秘钥失败”的错误。

注释