You need to enable JavaScript to run this app.
导航

数据导入(私有化查看)

最近更新时间2023.08.15 14:23:10

首次发布时间2022.06.07 14:31:53

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

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

导入方式一

1. 相关概念

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

2. 数据准备

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

2.1 数据格式

2.1.1 用户数据格式

字段数据类型是否可以为空如果为空填充为含义备注
global_idString用户非空唯一id,用于关联用户和事件,需要在导入时和事件中的global_id关联,确保同一个用户的global_id在事件和用户数据中一致global_id 不可重复
uuidString空字符串用户唯一iduuid 非空值不可重复
idfaString空字符串Identifier For Advertising(仅 IOS)
idfvString空字符串Identifier For Vendor(仅 IOS)
openudidString空字符串安卓唯一设备标识(仅 Android)
register_timeLong用户注册时间的毫秒时间戳
timezoneLong时区例如 8, -8, 0
platformString用户设备注册平台android 或 ios
int_profilesMap<String, Long>空Map所有值类型整型的用户属性集合
float_profilesMap<String, Double>空Map所有值类型浮点型的用户属性集合
string_profilesMap<String, String>空Map所有值类型字符串的用户属性集合
string_array_profilesMap<String, List>空Map所有值类型字符串数组的用户属性集合

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

2.1.2事件数据格式

字段数据类型是否可以为空如果为空填充为含义
global_idString用户非空唯一id,用于关联用户和事件
eventString事件名
timeLong事件发生的毫秒时间戳
server_timeLongtime字段事件到达服务端的毫秒时间戳
timezoneLong时区例如 8, -8, 0
int_paramsMap<String, Long>空Map所有值类型整型的事件属性集合
float_paramsMap<String, Double>空Map所有值类型浮点型的事件属性集合
string_paramsMap<String, String>空Map所有值类型字符串的事件属性集合
string_array_paramsMap<String, List>空Map所有值类型字符串数组的事件属性集合

2.2预置事件&属性

2.2.1 预置事件及事件属性

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

事件名称事件含义平台属性名称属性中文名属性存放位置属性含义
app_launch应用启动事件App
小程序scene场景值int_params用户从何种场景启动小程序
小程序query_from_title页面标题string_params用户启动的页面标题
小程序path页面地址string_params用户启动的页面地址
app_terminate应用关闭事件Appduration本次打开应用的会话时长int_params本次打开应用的会话时长
小程序session_duration本次打开应用的会话时长int_params本次打开应用的会话时长
小程序session_depth会话深度string_params会话深度
小程序exit_page会话退出页string_params用户跳出页面
小程序scene场景值int_params用户从何种场景启动小程序
predefine_pageview用户浏览页面Weburl访问链接string_params用户访问的 url
Weburl_path访问路径string_params用户访问的路径
Webreferrerstring_params来源 url
Webtitle页面标题string_params
小程序path页面地址string_params访问路径
小程序scene场景值int_params用户从何种场景启动小程序
小程序title页面标题string_params
predefine_pageview_hide用户退出页面小程序duration停留时长int_params用户浏览页面的停留时长
小程序path页面地址string_params页面地址
小程序scene场景值int_params用户从何种场景启动小程序
on_share分享小程序path页面地址string_params用户分享的页面地址
title标题string_params用户分享的页面标题

2.2.2 预置公共属性

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

属性名称属性中文名属性含义平台数据类型备注
app_channel渠道软件安装渠道App 小程序int_params
app_region软件国家软件国家Appstring_params
sdk_version应用版本sdk应用版本号Appstring_params如 1.0.1
app_version软件版本软件版本App 小程序 Webstring_params如 1.0.1
app_version_minor四位版本号四位版本号Appstring_params如 1.0.0.0
client_ipIP地址用户IP地址App 小程序 Webstring_params
device_brand手机品牌用户使用手机品牌APP 小程序string_params
device_model手机型号用户使用手机型号APP 小程序string_params
language系统语言系统语言App 小程序 Webstring_params
network_type网络类型用户所处网络环境类型App 小程序string_params如 wifi, 4G 等
network_carrier运营商用户运营商App 小程序string_params如 中国移动、中国联通、中国电信 等
os_name操作系统操作系统App 小程序 Webstring_params如 android、 ios、windows
os_version系统版本操作系统版本App 小程序 Webstring_params
package安装包名安装包名Appstring_params
region系统国家系统国家Appstring_params
resolution分辨率用户手机分辨率App 小程序 Webstring_params
browser浏览器浏览器名Webstring_params
browser_version浏览器版本浏览器版本Webstring_params

mp_platform

小程序平台

小程序类型

小程序

string_params

"0" - 微信
"1" - 支付宝
"2" - 今日头条
"3" - 快应用
"4" - 小游戏

mp_platform_app_version平台版本号小程序平台版本号小程序string_paramsdatafinder 版本 >= 3.1.x 支持

event_platform

-

事件来源平台

小程序 Web

string_params

"mp" - 小程序
"web" - Web

mp_platform_basic_version小程序基础库版本小程序基础库版本小程序string_params

2.2.3 预制用户属性

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

属性名称属性中文名属性含义平台存放位置备注
gender性别性别小程序string_profiles为 male 或 female

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

最外层字段说明

字段名字段含义数据类型是否必填
log_type标识日志类型,一般事件为:mario_event, app端app_launch事件为:launch,app端app_terminate事件为terminatestring
event_name事件名string
session_id会话id,用于计算会话信息string
duration会话持续时间,app_terminate事件会包含int
server_time服务端时间,秒级时间戳long
local_time_ms客户端时间long
params事件属性,json序列化的字符串string
user见下文
header见下文

user

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

字段名字段含义数据类型是否必填
global_id客户自己标识同一个用户的ID,无论匿名还是实名用户都应该有,string
user_unique_id用户id,实名登陆的用户需要有,匿名用户应该为空string
vendor_idapp端ios必须包含的id,用于生成device_idstringios是
idfaios可以包含string
open_udidapp端android必须包含的id,用于生成device_idstringandroid是
client_udidandroid可以包含string
oaidandroid可以包含string
build_serialandroid可以包含string
imeiandroid可以包含string
user_platform标识是web还是app,如果是app(匿名用户vendor_id和open_udid必须有,不然无法生成id)string

注意事项

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

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

字段名字段含义数据类型是否必填
app_id应用id,即要导入finder的app_idint
app_name应用的英文名string
app_channel激活安装渠道string
os_name操作系统(**ios/web/mac/windows/android/wap/**linux)string
os_versionapp版本号string
app_package安装包名string
app_versionapp版本号string
app_version_minor4位版本号string
access网络访问类型string
device_brand设备品牌string
device_model设备型号string
carrier运营商string
creative_idstring
campaign_idstring
ad_idstring
resolutionstring
device_manufacturerstring
heightstring
widthstring
sdk_version_v2string
user_agentstring
browserstring
browser_versionstring
app_regionstring
app_languagestring
regionstring
ab_versionstring
platformstring
timezonestring
utm_campaignstring
utm_sourcestring
utm_mediumstring
utm_contentstring
utm_termstring
custom用户自定义公共属性的json的字符串,string

用户数据导入

用户数据的大题导入格式同上,需要进行的修改有:
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中会额外添加的字段:

字段名含义类型
import_error错误原因string
import_time处理时间string