离线同步任务支持API数据源，支持该数据源的抽取（Reader）。

使用前提

在使用之前需要在“项目配置-项目中心（新）-数据源管理”完成该类型数据源的登记并测试通过（可在控制台的用户手册中查看具体登记详情信息），以及获取该数据源类型或数据的读权限（配置入口在安全中心-项目下的具体成员或角色）。

API作为数据来源

在数据来源端选择数据源类型API及已经登记的API名称，完成请求方法及路径、Headers、Body/Params、总量字段及特殊字符替换的填写。

  • 前置处理：针对API需要前置认证等复杂场景，任务支持选取UDF Studio的UDF用于前置处理，传输请求API接口前会调用UDF的apply方法，得到用户处理后的url，header，params和body再去请求API。
    使用说明：
    1）实现接口 Function>, Map>>
    2）传输请求API接口前会调用UDF的apply方法，得到用户处理后的url，header，params和body再去请求API。
    3）建议对UDF的依赖jar进行shade避免冲突
    编码示例： 

      public class UDF implements
        Function<Map<String, Map<String, String>>, Map<String, Map<String, String>>>  {
@Override
public Map<String, Map<String, String>> apply(Map<String, Map<String, String>> stringStringMap) {
    // 请求api的header
    Map<String, String> header = stringStringMap.get("header");
    // 请求参数（get请求会有）
    Map<String, String> paramsMap = stringStringMap.get("params");
    // 任务参数包含body（post请求会有）、url、requestType(get/post)
    Map<String, String> taskInfoMap = stringStringMap.get("taskInfo");
    // 做些你想做的处理逻辑，比如塞点参数进header、paramsMap、body
    if ("get".equals(taskInfoMap.get("requestType"))) {
      header.put("appId", "super");
      paramsMap.put("searchKey", "111");
    } else {
      header.put("appId", "super");
      taskInfoMap.put("body", "");
    }
    // 返回map
    // 如果是get请求会根据用户处理完返回的header,params,url去请求
    // 如果是post请求会根据用户处理完返回的header,body,url去请求
    return stringStringMap;
}

    }

  • 总量字段：如果启用分页，此项为必填项。支持offset&limit和pageSize&pageNumber，如果选用offset&limit将会产生参数$(offset)、$(limit);如果选用pageSize&pageNumber将会产生参数$(pageSize)、$(pageNumber)。此处输入框中总量字段指的是返回结果中用来表示API请求获取到的总返回接过数。例如，请求内容： { "corpAccessToken":"CORP_ACCESS_TOKEN", "corpId":"CORP_ID"， "pageSize":"$(pageSize)", "pageNumber":"$(pageNumber)" }，返回结果：{ totalCount: 1000, pageSize: 10, pageNumber: 1, ...}，此处总量字段输入的内容为totalCount。

  • 特殊字符：选择是否开启及替换内容。
    • 不可见字符请使用Unicode编码表示。
    • 使用下列字符：|、^、$、.、*、\、?、+、{ 、}、[、 ]、( 、)时，请在字符前添加"\"来表示。
    • 需要替换多个特殊字符时，字符间请使用“,”分隔。不支持替换“,”字符。

使用说明

任务参数配置

在数据源登记时，配置通过其它接口获取参数值需要添加参数如下图所示：

该参数在新建离线同步任务中进行引用时，填写方式如下：

列映射处理

当数据来源为API时，同样支持字段映射配置，不过API调用接口的返回值会被处理成一个JSON字符串，且列名为response，因此只能导入目标端为String类型的字段里，且目标端只有1个字段。

如果未启用分页，则导入后在目标端中显示1行1列；如果启用分页，则导入后在目标端中显示1列多行。此处支持通过JSONPath表达式取response中的值。

分页参数填写

系统支持两种分页参数，offset&limit和pageSize&pageNumber，此处以pageSize和pageNumber为例：

  • 数据源登记配置API相关内容，在自定义参数中填写参数名称和值，如下图所示。

    其中，pageSize表示一页返回的数量，pageNumber表示起始页码值。

  • 在离线同步任务新建任务时，可在Params中填写get的请求变量值。

    基本信息 说明
    数据源 必填项，选择数据源类型为API的选项
    请求类型：目前支持POST、GET两种类型，后面需要输入API的路径信息
    新建数据源：当API选择不到，需要新增API，点击“新建数据源”按钮添加API信息
    查找方式 必填项，选项为库表选择和正则匹配，默认为库表选择:
    库表选择：支持搜索或直接选择数据库表
    正则匹配：通过正则表达式来匹配数据表
    Headers 填写API的 Header信息，填写属性和值信息，点击添加可新增行列，点击删除按钮删除行列
    Params 填写API的Params信息，点击添加可新增行列，删除去掉行列
    body 填写Api的Body信息，复制源API的json数组信息
    前置处理 可以开启或者关闭，用于对API传输前的前置处理，如通过UDF函数对数据进行简单的处理，可以点击查看函数使用说明，也可以点击前往UDF市场进行查看和创建UDF函数
    数据主体 从返回结果中查询单个JSON对象或者JSON数组的路径，请填写JSONPath表达式，例如：{ "id":1,"name":"xx1”}。
    返回数据结构 必填，单选，单条数据和数组数据，如数据主体为对象，请选择“单条数据”，会将对象中的单行数据抽取为一条同步记录；如数据主体为数组，请选择“数组数据”，会将数组中的多行数据抽取为多条同步记录
    启动分页 选填，打开开关后，分页方式：需要选择分页方式pageSize&pageNumber、offset&limit两个选项；总量字段：返回结果中表示API请求获取到的返回记录总数的字段的JSON路径，请填写JSONPath表达式。
    空字段处理 必填，当一条数据解析时，Json路径中找不到字段时的处理方式，默认选项为任务报错、也可以选择设置为null数据填充，任务继续执行
    超时时间 数据获取超时的最大允许时间。如果API接口返回数据耗时超过数据获取超时时间，则数据获取失败并任务报错。单位为秒，必填，可以填写数字。
    特殊字符替换 可以选填，用户可以对数据主题中的一些特殊字符进行转换
    1.不可见字符请使用Unicode编码表示。 2.使用下列字符：|、^、$、.、*、\、?、+、{ 、}、[、 ]、( 、)时，请在字符前添加"\"来表示。示例：“|”字符表示为“|”。 3.需要替换多个特殊字符时，字符间请使用“,”分隔。不支持替换“,”字符。默认不填写替换值则会被替换为空置，使用添加、删除按钮新增行数
    数据预览 全部配置完成之后，可以点击数据预览，预览数据传输API的数据结构。