创建、发布和调用API（云原生API网关）

1. 创建网关实例

网关实例是处理API请求的引擎。

1. 登录云原生API网关控制台，在左侧导航栏单击实例。

2. 在顶部菜单栏选择地域。

   重要

   地域必须与DataWorks工作空间地域完全一致。

3. 在实例页面，单击创建实例。

4. 在购买页面配置以下参数：

   • 商品类型：支持按量付费或包年包月。测试时可选用按量付费。

   • 网关名称：自定义一个易于识别的名称，例如 dataservice-prod。

   • 网关规格：测试可选择单节点规格，但生产环境建议使用多节点网关规格以保证SLA。

   • 网络访问类型：选择公网或公网+私网，以便后续通过互联网调用。使用公网访问类型会产生流量费用。

   • 专有网络：选择一个VPC。

     重要

     为保证网络连通，此处选择的VPC强烈建议与准备工作中Serverless资源组所在的VPC保持一致。如果VPC不一致，您将必须在后续手动创建后端服务。

   • 可用区选择：可选择自动分配或手动在不同可用区和交换机中分配实例。

   • 资源组：根据您的资源管理策略选择。

5. 单击立即购买并完成支付。实例创建过程约需1～5分钟，当实例状态变为运行中时，表示创建成功。

更多详情，请参见创建网关实例。

2. 添加域名

域名是API的公网访问入口。

1. 在云原生API网关控制台左侧导航栏选择域名，并确保顶部地域与网关实例一致。

2. 单击添加域名，配置以下信息：

   • 域名：填写您自己的域名，例如 api.example.com。在中国地域使用的独立域名需完成备案。

   • 协议：建议选择HTTPS以保障数据传输安全。选择HTTPS时，需要选择一个已有的SSL证书。

   • 其他配置：建议开启强制HTTPS和启用 HTTP/2，并根据安全要求指定TLS 版本。

更多详情，请参见创建域名。

3. 创建 REST API

REST API是一个逻辑容器，用于管理一组具有相同Base Path的API。DataWorks中的一个业务流程会与一个REST API绑定。

1. 在云原生API网关控制台左侧导航栏单击API，并确保顶部地域正确。

2. 单击创建API，然后在创建API页面中选择REST API卡片下的创建。

3. 在创建REST API面板中配置：

   • API名称：为您的API集合命名，此名称要求在当前地域下全局唯一，例如 dataservice-user-api。

   • Base Path：API的基本路径，作为URL的一部分。例如，配置为 /v1。最终的访问路径将是 协议://域名/BasePath/APIPath。

   • 版本管理：按需启用。

更多详情，请参见创建REST API并添加接口。

1. 创建业务流程

业务流程用于组织一组相关的API，并将其与API网关的REST API进行绑定。

1. 进入DataWorks控制台，在左侧导航栏进入数据服务 > 服务开发。

2. 单击左上角的新建图标，选择新建业务流程。

3. 在新建业务流程对话框中配置：

   • 业务名称：自定义，在工作空间内唯一，例如 用户查询业务。名称长度限制为4～50字符。

   • 网关类型：选择云原生API网关。

   • REST API：从下拉框中选择您在步骤一中创建的REST API（例如 dataservice-user-api）。如果未出现，可单击刷新按钮。

     重要

     业务流程绑定REST API后，不能换绑修改。请您谨慎选择。

2. 使用向导模式生成API

1. 在服务开发页面，将鼠标悬停在左上角的新建图标，单击新建API > 生成API。

2. 在生成API对话框中，选择向导模式并配置API的基本信息：

   • 目标文件夹：选择上一步创建的业务流程（用户查询业务）。

   • API名称：为具体的API命名，例如 根据用户ID查询用户。

   • API Path：接口的具体路径，例如 /user/info。它将与Base Path拼接成完整的URL路径。API Path必须以/开头，且长度不超过200字符。

   • 请求方式：选择GET或者POST。使用GET请求方式时，请求参数仅支持放在QUERY中。

   • 返回类型：选择JSON。

3. 单击创建，进入API的图形化编辑页面。

   说明

   脚本模式创建可参考通过脚本模式生成API。

3. 配置API

在API编辑页面，通过选择表 > 选择参数 > 配置参数的流程，完成API的核心逻辑定义。

1. 选择表（数据源与表）

   在页面左侧的选择表区域进行配置：

   • 数据源类型：选择 MaxCompute(ODPS)。

   • 数据源名称：选择您在准备工作中已配置好的数据源。

   • 数据表名称：选择 user_info 表。

   • 若使用MaxCompute数据源，需要配置加速方式以提升性能。

2. 选择参数（请求与返回）

   选择表后，下方的选择参数区域会列出该表的所有字段。

   • 配置请求参数：勾选 user_id 字段，然后单击并勾选设为请求参数。

   • 配置返回参数：勾选 user_id 和 user_name 字段，然后单击并勾选设为返回参数。

3. 配置请求参数详情 在页面右侧的请求参数页签，为user_id参数配置示例值（例如 10001），这有助于后续的测试。

   最佳实践：建议将有索引的字段设为请求参数，以优化查询性能。

4. 配置服务资源组与环境

   在页面右侧的服务资源组区域进行配置：

   • 资源组类型：必须选择独享服务资源组，并在下拉框中选择已与当前工作空间绑定的资源组。

   • 环境配置：

     • 超时时间：云原生API网关等待DataWorks响应的最长时间，例如 3 秒。

     • 单次请求数据条数上限：限制单次API调用返回的最大记录数，例如 2000条。

5. 配置安全认证

   在页面右侧的安全认证区域进行配置：当启动消费者认证之后，可选择以下三种认证类型之一。

   说明

   DataWorks各工作空间自动在云原生API网关创建一个与工作空间同名的消费者，您无需手动创建。

   配置方式	说明	场景适用
   API Key	客户端需将凭证按指定方式添加到请求中，网关验证其合法性与权限。适用于非敏感操作场景，安全性低于 JWT、AK/SK，需注意凭证管理与保护。	适合轻量级、快速接入以及对安全性要求一般的场景。
   JWT	JSON Web Token (JWT) 是一种在客户端与服务端之间安全传输信息的标准，通过 HMAC、RSA 或 ECDSA 签名确保信息可验证和可信。JWT 认证可在网关中实现身份验证与访问控制。	适用于分布式系统和单点登录（SSO）场景。
   HMAC	基于 HMAC 算法的 AK/SK 签名认证方式要求客户端在调用 API 时，使用签名密钥对请求内容进行签名计算，并将签名一同发送至服务端验证 。	适合对数据完整性和防篡改有较高要求的场景。

6. 保存API：完成所有配置后，单击顶部工具栏的保存图标。

1. 测试API

API必须先成功通过测试才能被提交。

1. 在API编辑页面，单击工具栏中的API测试按钮。

2. 在API测试对话框中，为请求参数user_id填入一个存在的示例值（如 10001），然后单击开始测试。

3. 在右侧查看返回内容，确认数据是否符合预期。响应时长可用于评估性能。

4. 若测试失败，请根据错误提示检查数据源、表、参数或资源组配置。

2. 提交API

测试通过后，将API提交，生成一个待发布的版本。

1. 在API编辑页面，单击工具栏的提交按钮。

2. 提交成功后，系统会自动生成一个API版本。您可以在右侧的版本管理页签中查看。

3. 如果您的工作空间配置了审批流，API版本状态将为待申请。您需要单击申请发布并发起申请，待审批人处理通过后，状态变为可发布。

   若未配置审批流，版本状态通常直接为可发布。

3. 发布API到云原生API网关

这是将API部署到线上环境的最后一步。

1. 在API编辑页面的右侧版本页签中，找到状态为可发布的版本，单击其操作列的发布。

2. 在发布API到云原生API网关对话框中，配置以下三项（均为必填）：

   • 域名：选择您在步骤一中添加的域名。

     重要

     同一REST API下的所有API 域名一致，此处发布时对域名的修改将影响同一REST API下的所有API 的域名调用。

   • 网关实例：选择您在步骤一中创建的网关实例。

   • 后端服务：

     • 如果网关实例VPC与DataWorks资源组VPC一致，此处选择默认即可。

     • 如果VPC不一致，此处必须选择在云原生网关API创建后端服务。

       创建后端服务

       执行此步骤的前提是：在步骤一中创建网关实例时，选择的VPC与Serverless资源组的VPC不一致。 如果两者VPC一致，请跳过此节。

       后端服务的作用是用于请求数据服务，打通两个不同的VPC。

       1. 在云原生API网关控制台的实例列表中，单击目标实例ID。

       2. 在实例详情页的左侧导航栏中，选择服务。

       3. 单击创建服务。如果系统提示，请先在来源页签创建一个来源。

       4. 在创建服务时，配置服务名称并关联已创建的来源。

       更多详情，请参见创建服务。