# 数据规则

本章节将会详细介绍 TA 后台的数据结构、数据类型以及数据限制。通过本章节，您将了解如何构建符合规则的数据，排查数据传输问题。

如果您使用的是 LogBus 或 RESTful API 上传数据，需要按照本章节中的数据规则对数据进行格式处理。

# 一、数据结构

TA 后台接受的是符合规则的 JSON 数据：如果使用的是 SDK 接入，则数据将会被转化成 JSON 数据进行传输。如果使用 LogBus 或 POST 方法上传数据，则数据需要是符合规则的 JSON 数据。

JSON 数据以行为单位：即一行一条 JSON 数据，对应物理意义上的一条数据，数据意义上对应的是用户产生一次行为，或者是设置一次用户属性。

数据格式及要求如下（为了方便阅读，数据经过排版，真实环境下请勿换行）：

  • 以下是事件数据的样例：
{
  "#account_id": "ABCDEFG-123-abc",
  "#distinct_id": "F53A58ED-E5DA-4F18-B082-7E1228746E88",
  "#type": "track",
  "#ip": "192.168.171.111",
  "#uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "#time": "2017-12-18 14:37:28.527",
  "#event_name": "test",
  "properties": {
    "argString": "abc",
    "argNum": 123,
    "argBool": true
  }
}
  • 以下是用户属性设置的样例：
{
  "#account_id": "ABCDEFG-123-abc",
  "#distinct_id": "F53A58ED-E5DA-4F18-B082-7E1228746E88",
  "#type": "user_set",
  "#uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "#time": "2017-12-18 14:37:28.527",
  "properties": {
    "userArgString": "abc",
    "userArgNum": 123,
    "userArgBool": true
  }
}

"#type"的值可以替换为"user_setOnce"、"user_add"、"user_unset"、"user_append"、"user_del"

从结构和功能上，可以将一条 JSON 数据分为两个部分：

properties 的同层其他字段，组成了该条数据的基本信息，其中只包括以下几项：

  • 表示触发用户的账号 ID#account_id与访客 ID#distinct_id
  • 表示触发时间#time，可精确到秒或毫秒
  • 表示数据类型（事件还是用户属性设置）的#type
  • 表示事件名称的#event_name（仅事件数据带有）
  • 表示用户 IP 的#ip
  • 表示数据唯一性的#uuid

请注意，除以上几项外，其余以“#”开头的属性都需要放在 properties 的内层

properties 的内层，是该条数据的内容，也就是事件中的属性，或者需要设置的用户属性，在后台分析时作为属性或分析对象被直接使用。

从结构上来看，这两部分与报文头（Header）和报文体（Content）有些类似，接下来将会详细介绍这两部分各字段的含义。

# 1.1 数据信息部分

如下图红框标识，与"properties"同层的数个字段组成了该条数据的信息部分：

这些字段包含了这条数据的触发用户、触发时间等数据信息，其特点是所有字段都以“#”开头，本节将会梳理各字段的意义以及如何配置。

# 1.1.1 用户信息（#account_id与#distinct_id）

#account_id与#distinct_id是 TA 后台用来识别用户的两个字段，其中#account_id为用户在登录状态下的 ID，#distinct_id为用户在未登录状态下标识，TA 后台会根据这个两个字段判断该行为的触发用户，其中优先根据#account_id进行判断，具体规则参见用户识别规则一章。

#account_id与#distinct_id至少要传入一个，如果所有事件都是在用户登录状态下触发的，则只传入#account_id是可行的，如果有事件是在未登录状态（包括注册前）触发的，则建议将两个字段都填入。

# 1.1.2 数据类型信息（#type与#event_name）

#type决定了该条数据的类型，是用户的行为记录、还是修改用户属性的操作处理，每一条数据都需要配置#type字段。#type的取值分为两类，track代表这条数据是用户行为记录，以user_开头代表对用户属性进行操作，具体意义如下：

  1. track：向事件表传入一个事件，事件的上传都为 track
  2. user_set：对用户表进行操作，覆盖一个或多个用户属性，如果该属性已有值存在，覆盖先前值
  3. user_setOnce：对用户表进行操作，初始化一个或多个用户属性，如果该属性已有值存在，则忽略本次操作
  4. user_add：对用户表进行操作，为一个或多个数值型用户属性做累加计算
  5. user_unset：对用户表进行操作，清空该名用户的一个或多个用户属性的属性值
  6. user_del：对用户表进行操作，删除该名用户
  7. user_append：对用户表进行操作，为用户的列表类型属性值添加元素

当#type的取值为track时，即该条数据是行为记录时，必须配置事件的名称#event_name，必须以字母开头，只能包含：数字，字母（忽略大小写）和下划线“_”，长度最大为 50 个字符。请注意配置时不要带有空格。如果该条数据是修改用户属性的操作，则不需要#event_name字段。

需要注意的是，用户属性是用户具有节点意义的属性，不建议在短时间内进行频繁修改，对于需要频繁变更的属性，建议放在事件中作为事件属性

# 1.1.3 触发时间（#time）

#time为事件产生的时间，必须要配置，格式必须是精确到毫秒（"yyyy-MM-dd HH:mm:ss.SSS"）或秒（"yyyy-MM-dd HH:mm:ss"）的字符串

尽管对 User 表的操作数据也需要配置#time，但对于用户属性的操作会按照后台收到数据的先后顺序进行操作。

比如用户重传了过去某天的 User 表操作数据，则无论是属性的覆盖还是初始化都会照常进行，并不会根据#time 字段进行判断

# 1.1.4 触发地点（#ip）

#ip是设备的 IP 地址，可选配置，TA 将会根据 IP 地址计算用户的地理位置信息，如果您在"properties"中传入了#country、#province、#city 等地理位置属性，则会以您传入的值为准

# 1.1.5 数据唯一 ID（#uuid）

#uuid是用以表示数据唯一性的字段，可选配置，格式必须为 uuid 的标准格式。TA 将会根据数据量，将会在一段时间内，在接收端校验是否短时间内出现相同#uuid的数据（即重复数据），并将重复数据直接抛弃，不再入库

需注意，通过#uuid进行的接收端校验只会对近几个小时接收到的数据进行校验，主要解决因网络抖动问题造成的短时数据重复，无法将接收到的数据与全量数据进行校验。如需对数据进行去重，请联系 TA 工作人员。

# 1.2 数据主体部分

数据的另一部分，则是properties内层所包含的数据，properties是一个 JSON 对象，里面的数据以键值对的形式表示。如果是用户行为数据，其代表了该行为的属性及指标（相当于行为表中的字段），这些属性及指标可在分析时直接使用；如果是用户属性的操作处理，则代表需要设置的属性内容。

key 值为该属性的名称，类型是字符串，自定义的属性必须以字母开头，只能包含：数字，字母（忽略大小写）和下划线“_”，且长度最大只能 50 个字符；另外还存在以#开头的 TA 预置属性，您可以在预置属性一章中了解更多信息，但需要注意，大多数情况下建议只使用自定义的属性，不使用#。

value 值为该属性的值，可以是数值、字符串、时间与布尔值，数据类型的表示方式如下表所示：

TA 数据类型 取值样例 取值说明 JSON 数据类型
数值 123,1.23 数据范围是-9E15 至 9E15 Number
字符串 "ABC","上海" 字符的默认上限是 2KB String
时间 "2019-01-01 00:00:00","2019-01-01 00:00:00.000" "yyyy-MM-dd HH:mm:ss.SSS"或"yyyy-MM-dd HH:mm:ss"，如需表示日期，可使用"yyyy-MM-dd 00:00:00" String
布尔 true,false - Boolean
列表 ["a","1","true"] 列表中的元素都会转变为字符串类型 Array

需要注意，所有属性的类型会根据第一次收到该属性值的类型所决定，后续数据的类型必须与相应属性的类型一致，类型不匹配的属性将被丢弃（该条数据其余符合类型的属性将保留），TA 不会进行类型的兼容转换。

# 二、数据处理规则

TA 服务器在收到数据之后，会进行一些处理，本节将会结合实际使用场景，TA 后台的处理规则：

# 2.1 收到新事件数据

在收到新增事件的数据后，TA 后台会自动地创建新增事件与其属性的关联模型；如果收到了新的属性，则首次收到该属性时的属性类型将会设置为该属性的类型，属性的类型之后将不能修改。

# 2.2 增添事件的属性

如果需要对已有事件增添属性，只需要在上传数据时将新增属性一并传入即可，TA 后台将会动态地关联事件与新增属性，不需要进行其他配置。

# 2.3 属性不一致的处理

当收到一条事件数据，其中某属性的类型与后台已存的该属性的类型不一致，则该属性的值将会被抛弃（即取值为 null）。

# 2.4 弃用事件属性

如果需要弃用事件某个属性，则只需要在 TA 后台的元数据管理中将该属性隐藏即可，后续传输的数据可不传该属性。TA 后台不会删除该属性的数据，隐藏操作也是可逆的，如果在属性被隐藏后仍传输该属性，该属性的值仍会被保留。

# 2.5 多事件共有属性

不同事件的同名属性被视为是同一属性，类型一致，因此需要保证所有同名属性的类型一致，以避免由于类型不一致而导致的属性值被抛弃。

# 2.6 用户表操作逻辑

修改用户在用户表中的数据，也就是上报数据中#type字段为user_set、user_setOnce、user_add、user_unset、user_append或user_del的数据，本质上可以看作是一条指令，也就是对该条数据所指用户的用户表数据进行操作，操作的类型由#type字段决定，而操作的内容以properties中的属性所决定。

以下是主要的用户表属性操作的具体逻辑：

# 2.6.1 覆盖用户属性(user_set)

根据数据中的用户 ID 确定进行操作的用户，再根据properties中的属性，覆盖所有属性，如果某个属性不存在则新建该属性。

# 2.6.2 初始化用户属性(user_setOnce)

根据数据中的用户 ID 确定进行操作的用户，再根据properties中的属性，对未赋值（为空）的属性进行设置，如果该用户的某需要设置的属性已经有值，则不会进行覆盖，如果某个属性不存在则新建该属性。

# 2.6.3 累加用户属性(user_add)

根据数据中的用户 ID 确定进行操作的用户，再根据properties中的属性，对数值型的属性进行累加操作，如果传入负值相当于原属性值减去传入值，如果该用户的某需要设置的属性未赋值（为空），则会默认设置为 0 后再进行累加操作，如果该属性不存在则新建该属性。

# 2.6.4 清空用户属性值(user_unset)

根据数据中的用户 ID 确定进行操作的用户，再根据properties中的属性，清空其中的所有属性（即设置成 NULL），如果某个属性不存在不会新建该属性。

# 2.6.5 添加列表型用户属性的元素(user_append)

根据数据中的用户 ID 确定进行操作的用户，再根据properties中的属性，对列表型的属性进行添加元素操作

# 2.6.6 删除用户(user_del)

根据数据中的用户 ID 确定进行操作的用户，将该用户从用户表中删除，该用户的事件数据不会被删除。

# 三、数据限制

  • 事件类型及属性数量限制

出于性能考虑，TA 后台会默认地对项目的事件类型及属性的数量进行限制：

限制 事件种类上限 事件属性上限 用户属性上限
建议不超过 100 300 100
硬件上限 500 1000 500

管理员可以进入“项目管理”页面，可查询各项目已经使用的事件类型以及属性数，联系 TA 工作人员可申请上调事件种类、属性属性的上限。

  • 账号 ID(#account_id)、访客 ID(#distinct_id)长度限制

      * 3.1版本之前创建的项目：64个字符；如需扩大至128个字符，请联系TA工作人员

  * 3.1版本及之后创建的项目：128个字符

  • 事件、属性名称限制

      * 事件名：`String`类型，可以数字或字母开头，可包含数字，字母和下划线“\_”，长度最大为50个字符，对字母大小写不敏感

  * 属性名：`String`类型，以数字或字母开头，可包含数字，字母和下划线“\_”，长度最大为50个字符，对字母大小写不敏感。只有预置属性能以#号开头。

  • 字符串、数值、列表类型属性数据范围

      * 字符串：字符串上限是2KB

  * 数值：数据范围是-9E15至9E15

  * 列表：最多包含500个元素；每个元素为字符串类型，且上限为255字节

  • 数据接收时限

      * 服务端数据接收事件上限：相对服务器时间的前三年至后3天

  * 客户端数据接收事件上限：相对服务器时间的前10天至后3天

# 四、其他规则

  1. 请以 UTF-8 对数据进行编码，以避免乱码问题
  2. TA 后台的属性名与事件名不区分大小写，建议使用"_"作为分词分隔符
  3. TA 后台默认只接收最近三年的数据，超过三年的数据将无法录入，如需录入三年之前的数据，可联系 TA 工作人员放宽时限

# 五、常见问题

本节总结了由于数据不符合数据规则而引起的常见问题，如果出现了数据传输问题，可以先根据本节内容进行排查

# 5.1 TA 后台没有收到数据

如果使用的是 SDK 传输：

  1. 请确认 SDK 是否被成功集成
  2. 排查 APPID 与传输的 URL 是否设置正确，传输端口号及传输方式对应后缀有无遗漏

如果使用的是 LogBus 或 POST 方法传输：

  1. 请确认 APPID 与传输的 URL 是否设置正确，传输端口号及传输方式对应后缀有无遗漏
  2. 请检查数据是否以 JSON 格式传输，并确保一行一条 JSON 数据
  3. 请检查数据信息部分的 key 值是否以"#"开头，是否遗漏了必要字段
  4. 请检查数据信息部分的 value 值的类型与格式（时间格式）是否正确
  5. 请检查"#event_name"的 value 值是否符合规范，不包含汉字，空格等字符
  6. "properties"请不要以"#"开头

  • 另外，请注意用户属性设置并不会产生行为记录，因此如果只上传了user_set等数据，在后台的行为分析模型（除 SQL 查询外）中无法直接查询到数据

  • 请注意上传数据的时间，过早时间（超过三年）的数据将不会录入；如果上传数据为历史数据，则可能是查询时段没有涵盖上传数据的时间，请调整查询时段

# 5.2 数据有缺失，某些属性没有收到

  1. 请确认数据主体部分的属性 key 值符合规范，不包含汉字，空格等字符
  2. 请确认数据主体部分的属性中，以"#"开头 key 值属于预置属性
  3. 请检查缺失属性在上传时的类型是否与后台该属性的类型一致，可在后台的元数据管理中查看已收到属性的类型

# 5.3 数据传输有误，希望删除数据

  1. 私有化服务的用户，可使用数据删除工具自助式的删除数据；如果是云服务的用户，可联系 TA 工作人员进行数据删除
  2. 如果数据有较大改动，建议直接新建项目，建议用户在正式传输数据之前先在测试项目下进行完备的数据测试

← 预置属性与系统字段 →