离线同步任务支持API数据源,支持该数据源的抽取(Reader)

使用前提


在使用之前需要在项目中心(新)完成API数据源的登记。
数据源登记过程中,需要填写如下信息:

  • 数据源名称:必填,API数据源的名称
  • 数据源标识:仅允许包含英文小写、数字、下划线,只允许英文小写开头,最大长度为64个字符。平台内唯一,保存数据源后数据标识不可修改
  • 归属项目:必填,由于元数据中心是项目组级别,因此此处支持选择项目组下的项目,默认为当前项目名称
  • 负责人:必填,默认为当前创建人员
  • 协助管理员:同负责人,有该数据源的管理权限,包括编辑、设置“源系统账号映射”。可在安全中心为自己或其他人设置该数据源的使用权限
  • URL:支持host域名或者IP:Port格式。支持http://https://
  • 自定义参数:自定义参数支持key-value的格式,用于静态数据
说明: 此处的参数引用时,使用$(XXX)格式进行引用。
唯一性校验规则:基于URL进行校验。

支持配置通过其它接口获取参数值,数据传输在调用API前,实时处理这个参数接口。需要注意的是,此处接口host同上述登记host,且不支持跨域获取接口参数。

  • 参数名称:必填,即变量名称
  • 请求方式:必填,支持POSTGET
  • Headers:请求中的Head参数
  • Body/Params:当请求类型为POST时,此处为Body,即参数放在请求体内;当请求类型为GET时,此处为Params,即参数一般直接跟在url后面
  • 截取内容:必填,即变量值,指的是请求返回的数据中需要返回的值。支持两种表达方式,a. 用.逐层获取json内的值; b. 用JSONPath获取json内的值

关于截取内容的方式:

  • 方式一:用“.”分隔变量。如果要返回下方“传输name”这个值,表达式为data.name。

    {
    "id":"1",
    "name":"传输",
    "data":{
         "name":"传输name"
         }
    }
  • 方式二:JSONPath表达式。方式一适用于大多数场景,但是由于只能逐层获取String,对于特殊场景需要使用方式二,即JSONPath表达式。如果要返回下方dataArr[0]这个对象,则在表达式$.dataArrr.[0]前加上前缀JSONPath,即JSONPath:$.dataArrr.[0]。如果要返回name=“arr1”,则表达式为JSONPath:$.dataArr.[0].name

    {
    "id":"1",
    "name":"传输",
    "data":{
         "name":"传输name"
         },
    "dataArr":[
         {
         "id":1,
         "name":"arr1"
         },
         {
         "id":2,
         "name":"arr2"
         }
    ]
    }

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&limitpageSize&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&limitpageSize&pageNumber,此处以pageSizepageNumber为例:

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

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

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