OneService 分页最佳实践

OneService API 分页是一种管理大量数据流的常见技术。本文将为您介绍在OneService API 查询中实现分页的方法，以及如何调用开启了分页的 API。

1 前提条件

进行 API 进行分页设置时，您需先准备以下相关内容：

1. 已加入数据服务项目，且需要是该项目的数据开发或项目管理员角色。
2. 已在数据源模块创建了相关的数据源，及对应的物理表和逻辑表，并拥有表的读权限。详见数据源。

2 脚本式 API 如何进行分页设置

2.1 新建脚本式 API

1. 登录 DataLeap租户控制台 。
2. 在概览界面顶部服务窗口，单击数据服务按钮，可快速进入到数据服务功能界面。
3. 进入到 API 开发界面，在左侧目录树上单击新建 API 按钮，在弹窗界面中，选择脚本式 API 类型。
4. 并按实际情况，填写 API 相关的基本信息和更多配置，如 API 名称、存储目录、最大 QPS、报警模版等信息。信息配置说明详见 3 新建 API。
   
5. 信息填写完成后，单击保存按钮，完成脚本式 API 新建。

2.2 配置脚本式 API

脚本式 API 创建完成后，您便可以选取对应的逻辑表进行 API 的开发。

1. 下拉选择已创建成功的逻辑表，脚本式创建 API，支持选择同源多张逻辑表，最多选择 10 张。

2. 并在 SQL 编辑界面，输入业务实际的查询 SQL 语句。

   说明

   在 API 设计中，您可以在 SQL 查询语句中使用LIMIT子句来添加分页功能。其中LIMIT子句需要两个参数：pageNum和pageSize

   • pageNum：表示查询的当前页码；
   • pageSize：表示每页显示的数据条数。

   下面是一个样例，展示了如何在 SQL 查询语句中配置分页：

   SELECT
       room_id,
       pay_amt,
       product_click_pay_cnt_ratio
   FROM
       room_pay_amt
   WHERE
       product_click_pay_cnt_ratio >= #{product_click_pay_cnt_ratio}
   ORDER BY
       pay_amt DESC
   LIMIT
       #{pageNum}, #{pageSize}
   

   
   全屏编辑时示例如下：
   

3. SQL 编辑完成后，您可单击“解析”按钮，来自动解析脚本的请求参数信息；单击“运行”按钮，查询成功后，也可自动填充 API 返回参数信息。

4. 根据实际场景配置 API 其余高级配置信息。详见4.1 脚本式。

脚本式 API SQL 逻辑和参数配置完成后，您可进行后续的 API 测试和发布操作。详见6 测试 API、7 发布API。

3 向导式 API 如何进行分页设置

3.1 新建脚本式 API

1. 登录 DataLeap租户控制台 。
2. 在概览界面顶部服务窗口，单击数据服务按钮，可快速进入到数据服务功能界面。
3. 进入到 API 开发界面，在左侧目录树上单击新建 API 按钮，在弹窗界面中，选择向导式 API 类型。
4. 并按实际情况，填写 API 相关的基本信息和更多配置，如 API 名称、存储目录、最大 QPS、报警模版等信息。信息配置说明详见 3 新建 API。
   
5. 信息填写完成后，单击保存按钮，完成向导式 API 新建。

3.2 配置向导式 API

向导式 API 创建完成后，您便可以选取对应的逻辑表进行 API 的开发。

1. 下拉选择已创建成功的逻辑表，向导式创建 API，仅支持同时选择 1 张逻辑表。
2. 在参数设置中，按实际场景设置请求参数和返回参数信息，您可单击“添加”按钮，同时添加多个请求或返回参数。
3. 更多参数设置操作详见4.2 向导式。
4. 请求和返回参数设置完成后，展开高级配置信息，在高级配置项中打开“开启分页”开关，开启后，平台在 API 页面测试 API 时，会自动添加 pageNum 和 pageSize 参数。
   操作如下图所示：
   
5. 在 API 测试界面，自定义输入 pageNum 和 pageSize 参数值，并单击测试按钮，并可完成分页查询。
   

向导式 API 参数配置和测试完成后，您可进行后续的 API 发布操作。详见7 发布API。

4 调用说明

如果需要在 API 返回结果中显示查询表的总计数，需要在请求体Option中新增配置项，如下所示

{
    "Id": 6,
    "Val": 0,
    "Val_": "{\"with_total\": true}"
}

下面是一个请求的curl命令样例，它请求了页码 1 和每页 10 条记录，并要求在返回结果中增加 TotalCnt 来显示返回 SQL 查询的总记录数：

curl --location 'http://xx.xx.xx.xx/invoker_engine/query_with_params' \
--header 'user: bytedance' \
--header 'env: ONLINE' \
--header 'Content-Type: application/json' \
--data '{
    "ApiID": "170113520485xxxxxx",
    "Option": [
        {
            "Id": 100,
            "Val": 0,
            "Val_": "$DPS_TOKEN"
        },
        {
            "Id": 6,
            "Val": 0,
            "Val_": "{\"with_total\": true}"
        }
    ],
    "Params": {   
        "product_click_pay_cnt_ratio":0,
        "pageNum": 1,
        "pageSize": 10
        }
}'

在返回结果中，数据会按分页要求返回，并会新增字段 TotalCnt 标明查询表的总数，如下所示：