数据导入（私有化查看）

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

导入有两种方式，其中方式二在410版本开始支持，导入方式二相对于导入方式一更为简单容易操作，用户自己操作时推荐使用方式二

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}

第一次导入前需要在机器上执行

zkServers=$(hostname -I | awk '{print $1}')':2181/kafka_vpc_lf' &&  echo $zkServers
/opt/tiger/kafka/bin/kafka-topics.sh --zookeeper $zkServers --create --if-not-exists --replication-factor 2 --partitions 3 --topic history_data
/opt/tiger/kafka/bin/kafka-topics.sh --zookeeper $zkServers --create --if-not-exists --replication-factor 2 --partitions 3 --topic history_illegal_data
kubectl scale deployment vpc-task-realtime-finder-history -n datafinder --replicas 1

用户需要按照如下格式准备数据，将数据写入到topic：history_data中。

参考格式 #

示例(不是所有字段)如下：

{
  "event_name": "Theme_Launch",
  "log_type": "mario_event",
  "user": {
    "user_unique_id": "70294365443",
    "global_id": "yrdyyrdyrdy"
    "user_platform":"web"
  },
  "header": {
    "ab_version": "15335",
    "device_brand": "小米",
    "device_model": "mi 8 ud",
    "app_channel": "xiaomi",
    "custom": "{"upush_device_token":"AnYqyMyZ4Cng4g05kBowM2Hd2xlEdtYc4L-v8Ai61MaC","register_time":"1616733526400","sdk_version_name":"5.5.3","__is_history":"true","sdk_version_code":"15049989"}",
    "timezone": 8,
    "region": "CN",
    "app_id": 10000000,
    "app_version": "6.1.0",
    "resolution": "2248x1080",
    "os_name": "android",
    "app_version_minor": "",
    "carrier": "中国电信",
    "app_name": "rangers_6027_colorfulclouds",
    "sdk_version_v2": "5050390",
    "package": "com.nowcasting.activity",
    "os_version": "10",
    "client_ip": "120.38.207.236",
    "access": "wifi",
    "language": "zh"
  },
  "session_id": "5f8f144b-6e6a-431d-959d-01a2ee60df69",
  "server_time": 1616758482,
  "duration": 0,
  "params": "{"type":"DefaultTheme"}",
  "local_time_ms": 1616758481773
}

具体字段说明 #

event #

最外层字段说明

user #

user内字段说明，其中标黄字段为设备的特征字段，ios(vendor_id、 idfa)，android(open_udid、client_udid、oaid、build_serial、imei），通过这些特征生成device_id。

注意事项

1. global_id是客户数据中标识用户的字段：例如有两条匿名事件或者一个匿名一个实名事件，客户可以通过一个字段来标识这两个事件来自同一个用户，则这个字段就可以作为global_id。web端匿名情况下，用其进行hash生成web_id

header #

header内字段说明，header里大部分字段是预置公共属性，custom里是用户自定义公共属性

用户数据导入 #

用户数据的大题导入格式同上，需要进行的修改有:
event_name: __profile_set / __profile_set_once event_name填为__profile_set（设置用户属性）或__profile_set_once（设置不变的用户属性）
params: 填为需要上报的属性。

用户导入

如果只需要导入用户，并不需要设置属性等，通过通过如下方式上报

{
  "event_name": "__profile_set_once",
  "log_type": "mario_event",
  "user": {
    "user_unique_id": "70294365443",
    "global_id": "yrdyyrdyrdy"
    "user_platform":"web"
  },
  "header": {
    "timezone": 8,
    "app_id": 10000000
  },
  "server_time": 1616758482,
  "params": "{"fist_event_time": 1616758481773}",
  "local_time_ms": 1616758481773
}

first_event_time代表这个用户的首次事件时间（local_time_ms需要等于first_even_time）， 通过这个方式，可以直接注册用户并标识用户首次事件时间。

用户属性设置

参考示例：

{
  "event_name": "__profile_set",
  "log_type": "mario_event",
  "user": {
    "user_unique_id": "70294365443",
    "global_id": "yrdyyrdyrdy"
    "user_platform":"web"
  },
  "header": {
    "timezone": 8,
    "app_id": 10000000
  },
  "server_time": 1616758482,
  "params": "{"name":"tom"}",
  "local_time_ms": 1616758481773
}

通过如上事件即可以为该用户上报一个用户属性 name=tom，如果这个用户是第一次上报数据，也可以为其进行用户注册。

数据校验 #

在历史数据构建时，对于格式不合法或因为其他问题无法正常构建的历史数据，会另外写到一个topic中，并标记错误原因。
错误数据topic ： history_illegal_event
event中会额外添加的字段：