在私有化部署场景下，经常会有历史数据导入的需求。本文将介绍增长分析产品是如何支持数据导入的，您可以参考本文档完成数据导入。其中，文档中使用的导入工具可以咨询运维人员单独获取。

推荐使用JAVA SDK或者HTTP API的方式进行数据导入

该导入方式需要咨询运维人员获取导入工具

1. 相关概念

公共属性： 也称用户属性，用于描述事件通用的一些属性，通常用来刻画设备、用户、环境等，比如网络类型、设备ID、操作系统等，一般SDK里默认采集的属性信息作为公共属性；
事件参数： 用于描述一个事件所携带的参数，比如浏览页面事件，参数有url和referer，分别表示被访问页面和来源页面；
自定义属性： 在公共属性满足不了分析需求时，可以通过自定义属性的方式进行补充，比如地域信息；
事件导入和用户属性导入： DataFinder采用的维度建模方式，事件表作为事实表，用户属性表作为维度表，因此在导入时支持分别导入事件和用户属性。
需要先进行用户属性导入，再进行事件导入，否则在分析时会丢失用户属性。

2. 数据准备

数据分为用户以及事件两部分。导入时，某个事件必须能与某个用户相关联。需要提供如下格式的数据，原始数据格式默认为parquet格式。

2.1 数据格式

2.1.1 用户数据格式

在 增长分析产品的 用户体系中，使用设备ID + uuid 确定一个用户。对于一个 uuid 存在的用户，历史数据迁移完成，以及接入 SDK 后能识别为同一个用户。但对于 uuid 不存在的匿名用户，若历史数据中无设备ID，则可能在接入 SDK 后被识别为不同用户。

2.1.2事件数据格式

2.2预置事件&属性

2.2.1 预置事件及事件属性

事件属性是不同事件特有的属性，按类型存放在事件数据中的 int_params、float_params、string_params 字段中。

2.2.2 预置公共属性

公共属性是每个事件都应当具有的属性，同样按类型存放在事件数据中的int_params、float_params、string_params。

2.2.3 预制用户属性

用户属性是描述用户的属性，按类型存放在 int_profiles、string_profiles、float_profiles 中。

3. 使用方法

下面命令中数据的path都是hdfs的路径，

3.1 用户导入

运行以下命令进行用户导入。该命令会注册用户并导入用户属性，映射文件的生成位置以及 schema 同用户注册任务。任务首先会寻找该 app 对应的映射文件。对不存在于映射文件中的用户进行注册，然后对所有用户进行属性导入。

./import_user.sh --input_path {user_file_path} --app_id {app_id} [--profile_time {profile_time_ms}]

用户导入可以多次运行，每次运行只会注册并导入未注册的用户。如果需要全量重新导入用户数据，可以添加参数 --import_all。导入默认发送转换后的 json string 到 user_profile 中，也可以使用 --topic {topic} 指定发送的 topic。

离线实时数据并存

在某些时候，离线导入数据以及实时数据同时存在。考虑以下场景:

用户 a 在历史数据中存在一个用户属性 nick_name = bob。随后用户 a 通过实时数据修改该属性为 nick_name = John。由于导入用户属性采用 set 方式，且认为导入的属性为最新版本，因此如果此时导入用户历史数据，则 nick_name = bob 会覆盖 nick_name = John 造成用户最新的属性丢失。
为了避免这种情况需要手动添加 --profile_time 。指定 profile_time 后，如果某个属性存在 profile 服务会对比 profile_time 与该属性最近一次修改的时间，如果 profile_time 小于该时间，则不会更新属性。即历史导入的属性不会覆盖最新的属性。一般来说，profile_time 应当设置为用户数据从历史环境中导出完成时的毫秒时间戳。

3.2 事件导入

运行以下命令进行事件导入。该任务会寻找该 app 对应的映射文件。并根据事件的 global_id join 映射文件获取 ssid 以及 device_id 并填充到事件中，注意这里 join 的是 映射文件中的用户，而不是 clickhouse 中的用户，未能 join 成功的事件不会上传，并被列入导入失败的事件数量中。

./import_event.sh --input_path {evet_file_path} --app_id {app_id}

其中 {evet_file_path} 为事件属性在 HDFS 上的路径。{app_id} 含义同上。
事件导入默认发送转换后的 json string 到 behavior_event 中，也可以使用 --topic {topic}指定发送的 topic。
重复运行事件导入任务会产生重复数据，如果导入过程出现错误，则需要清除历史数据后再重新导入

字段校验

运行该命令会对数据字段进行校验，确保用户提供的必要字段正确。

./check.sh --user_path {user_file_path} --event_path {event_file_path}

用户数据以及事件数据可以单独校验。如果单独对事件进行校验，则在该 app_id 对应的用户注册任务已经完成的情况下，可以指定 app_id 替代用户数据路径 {user_file_path} 如:

./check.sh --event_path {event_file_path} --app_id {app_id}

指定 app_id 后会使用该 app 已经生成的映射文件对事件和用户的关联关系进行检测。如果用户数据路径以及 app_id 都未提供，则无法检测事件和用户的关联情况。
校验结果示例如下:

{
  "info" : {
    "用户总数" : 10001
  },
  "warning" : {
    "存在用户注册时间小于等于 0 或为 null" : 10001
  },
  "error" : {
    "存在用户 global_id 重复" : 9999,
    "存在用户无 global_id" : 10000,
    "存在用户 platform 不正确" : 10001
  }
}
{
  "info" : {
    "事件总数" : 12001
  },
  "warning" : {
    "存在事件无属性" : 12001,
    "存在事件无法关联到到用户" : 12000
  },
  "error" : {
    "存在事件无事件名" : 12001
  }
}

检查结果为不同等级的{信息: 数量}键值对。其中包括三个等级，分别为:

• info: 一些描述信息，例如总条数。
• warning: 警告信息。
• error: 错误信息。

存在警告信息对导入结果不会产生较大影响，但仍然需要用户确认其影响范围。而存在错误信息则表示该数据无法进行导入，必须要求用户修正这些错误才能进行下一步导入工作。
其中警告信息以及对应含义为:

• 存在用户注册时间小于等于 0 或为 null: 用户注册时间不存在或为空，该部分用户导入到 finder 系统中后注册事件属性会被设置为注册到 finder 系统中的时间而不是历史注册的事件。
• 存在安卓用户 openudid 不存在: 安卓用户不存在 openudid。导入后可能会使得匿名用户增多。
• 存在 IOS 用户 idfv 不存在: IOS 用户不存在 idfv。导入后可能会使得匿名用户增多。
• 存在事件无法关联到到用户: 该部分事件无法导入到 finder 系统中。
• 存在事件无属性: 部分事件属性列表为空，请检查是否符合预期。

其中错误信息及其对应含义为:

• 存在用户 global_id 重复: 必须保证用户数据中 global_id 为唯一。
• 存在用户无 global_id: 用户必须存在 global_id 否则无法关联到事件。
• 存在用户 platform 不正确: platform 不正确的用户无法注册，请确保 platform 正确。
• 存在事件无事件名: 无事件名的事件导入到 finder 系统中无法分析，请保证事件存在事件名。

自定义事件公共属性

某些场景用户需要自定义事件公共属性，可以通过设置文件指定。文件格式为 json:

{
    "common_param_names": [
        "custom_ip",
        "custom_nick_name"
    ]
}

然后在运行用户导入时添加 --config-file 选项，例如:

./import_event.sh --app_id 10000035 --input_path /user/datarangers/mock_data/events.json --file_format json --config-file config.json

文档中描述的预置事件公共属性字段会自动转换，无需手动通过配置文件添加。

3.3 删除已生产的映射文件

某些测试场景下需要清除已经生成的映射文件，可以使用以下命令进行:
./clear_id.sh {app_id}