数据规则

本章节将会详细介绍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.数据信息部分

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

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

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.2 数据类型信息（`#type`与`#event_name`）

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

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

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

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

1.3 触发时间（`#time`）

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

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

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

1.4 触发地点（`#ip`）

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

1.5 数据唯一ID（`#uuid`）

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

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

2. 数据主体部分

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

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

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

TA数据类型	取值样例	取值说明	JSON数据类型
数值	123,1.23	数据范围是-9E15至9E15，小数点最多保留3位	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工作人员可申请上调事件种类、属性属性的上限。

事件、属性名称限制

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

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

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

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

  * 数值：数据范围是-9E15至9E15，小数点最多保留3位

数据接收时限

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

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

四、其他规则

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

五、常见问题

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

5.1 TA后台没有收到数据

如果使用的是SDK传输：

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

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

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

另外，请注意用户属性设置并不会产生行为记录，因此如果只上传了user_set等数据，在后台的分析模型中不会有数据展示
请注意上传数据的时间，过早时间（超过三年）的数据将不会录入；如果上传数据为历史数据，则可能是查询时段没有涵盖上传数据的时间，请调整查询时段

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

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

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

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

数据规则

数据规则

一、数据结构

1.数据信息部分

1.1 用户信息（`#account_id`与`#distinct_id`）

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

1.3 触发时间（`#time`）

1.4 触发地点（`#ip`）

1.5 数据唯一ID（`#uuid`）

2. 数据主体部分

二、数据处理规则

2.1 收到新事件数据

2.2 增添事件的属性

2.3 属性不一致的处理

2.4 弃用事件属性

2.5 多事件共有属性

2.6 用户表操作逻辑

2.6.1 覆盖用户属性(user_set)

2.6.2 初始化用户属性(user_setOnce)

2.6.3 累加用户属性(user_add)

2.6.4 清空用户属性值(user_unset)

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

2.6.6 删除用户(user_del)

三、数据限制

四、其他规则

五、常见问题

5.1 TA后台没有收到数据

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

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

results matching ""

No results matching ""

数据规则

一、数据结构

1.数据信息部分

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

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

1.3 触发时间（#time）

1.4 触发地点（#ip）

1.5 数据唯一ID（#uuid）

2. 数据主体部分

二、数据处理规则

2.1 收到新事件数据

2.2 增添事件的属性

2.3 属性不一致的处理

2.4 弃用事件属性

2.5 多事件共有属性

2.6 用户表操作逻辑

2.6.1 覆盖用户属性(user_set)

2.6.2 初始化用户属性(user_setOnce)

2.6.3 累加用户属性(user_add)

2.6.4 清空用户属性值(user_unset)

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

2.6.6 删除用户(user_del)

三、数据限制

四、其他规则

五、常见问题

5.1 TA后台没有收到数据

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

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

results matching ""

No results matching ""

1.1 用户信息（`#account_id`与`#distinct_id`）

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

1.3 触发时间（`#time`）

1.4 触发地点（`#ip`）

1.5 数据唯一ID（`#uuid`）