Python SDK 使用指南

本指南将会为您介绍如何使用 Python SDK 接入您的项目，您可以在访问GitHub (opens new window)获取 Python SDK 的源代码。

最新版本为：1.8.0

更新时间为：2022-04-26

一、初始化 SDK

1.通过pip获取 Python SDK

pip install ThinkingDataSdk

升级命令：

pip install --upgrade ThinkingDataSdk

2.初始化 SDK

请在程序初始化代码中引入 SDK，import方式有两种

from tgasdk.sdk import TGAnalytics, LoggingConsumer
ta = TGAnalytics(LoggingConsumer(log_directory))

或

import tgasdk.sdk
ta = tgasdk.TGAnalytics(tgasdk.LoggingConsumer(log_directory))

初始化获得 SDK 实例

# 初始化SDK两种方式，Consumer包括(LoggingConsumer,BatchConsumer,AsyncBatchConsumer,DebugConsumer)
#默认
ta = TGAnalytics(Consumer)
# 添加UUID去重
ta = TGAnalytics(Consumer, enable_uuid=True)

您可以通过四种方法获得 SDK 实例：

(1)LoggingConsumer： 批量实时写本地文件，文件以天为分隔，需要与 LogBus 搭配使用进行数据上传，默认缓存数据每6条数据会写一次文件，可设置buffer_size更改该大小，如果需要立刻写入，可调用flush()方法。

#默认按日切分
ta = TGAnalytics(LoggingConsumer(log_directory))

如果您想按小时切分文件，可如下初始化：

ta = TGAnalytics(LoggingConsumer(log_directory, rotate_mode = ROTATE_MODE.HOURLY))

如果您想按大小切分文件，可如下初始化：

#按照1G切分文件
ta = TGAnalytics(LoggingConsumer(log_directory, log_size= 1024))

如果您想文件自定义前缀名，可如下初始化：

#自定义文件前缀
ta = TGAnalytics(LoggingConsumer(log_directory, file_prefix="xx"))

log_directory为写入本地的文件夹地址，您只需将 LogBus 的监听文件夹地址设置为此处的地址，即可使用 LogBus 进行数据的监听上传。

(2)BatchConsumer： 批量实时地向 TA 服务器传输数据（同步阻塞），不需要搭配传输工具，因网络问题发送失败时会把数据存入缓存区，可设置缓存区大小，默认50，即缓存区保留的数据总数最大为50*20（20为每次上传的batch值，可设置）。在长时间网络中断情况下，有数据丢失的风险。

ta = TGAnalytics(BatchConsumer(SERVER_URI,APP_ID))

如果你想内网传输，您可以初始化如下：

# compress默认值True,代表gzip压缩
batchConsumer = BatchConsumer(server_uri="url", appid="appid",
                              compress=False)
ta = TGAnalytics(batchConsumer)

SERVER_URI为传输数据的 URL，APP_ID为您的项目的 APP ID

如果您使用的是云服务，请输入以下 URL:

https://global-receiver-ta.thinkingdata.cn

如果您使用的是私有化部署的版本，请输入以下 URL:

http://数据采集地址

注：1.3.0 版本之前输入以下 URL:

https://global-receiver-ta.thinkingdata.cn/logagent
http://数据采集地址/logagent

(3)AsyncBatchConsumer： 批量实时地向 TA 服务器传输数据（异步非阻塞），不需要搭配传输工具，网络原因导致失败时会重试3次，不建议在生产环境中使用

ta = TGAnalytics(AsyncBatchConsumer(SERVER_URI,APP_ID,flush_size=200,queue_size=100000))

SERVER_URI为传输数据的 URL，APP_ID为您的项目的 APP ID

如果您使用的是云服务，请输入以下 URL:

https://global-receiver-ta.thinkingdata.cn

如果您使用的是私有化部署的版本，请输入以下 URL:

http://数据采集地址

flush_size为队列缓存的阈值，超过此值将立即进行发送。

queue_size为缓存队列的大小，超过queue_size的数据将会丢失。

(4)DebugConsumer： 逐条实时地向 TA 服务器传输数据，不需要搭配传输工具，如果数据出现错误，整条数据都将不会入库，并且返回详细的错误说明，不建议在生产环境中使用

ta = TGAnalytics(DebugConsumer(SERVER_URI, APP_ID))

如果您希望DebugConsumer只校验数据，不写入 TA 库，可如下初始化：

#write_data值默认为True，代表写入TA库
ta = TGAnalytics(DebugConsumer(server_uri="SERVER_URI", appid="APP_ID",write_data=False))

SERVER_URI为传输数据的 URL，APP_ID为您的项目的 APP ID

如果您使用的是云服务，请输入以下 URL:

https://global-receiver-ta.thinkingdata.cn

如果您使用的是私有化部署的版本，请输入以下 URL:

http://数据采集地址

二、发送事件

在 SDK 初始化完成之后，您就可以调用track来上传事件，一般情况下，您可能需要上传十几到上百个不同的事件，如果您是第一次使用 TA 后台，我们推荐您先上传几个关键事件。

如果您对需要发送什么样的事件有疑惑，可以查看快速使用指南了解更多信息。

2.1 发送事件

您可以调用track来上传事件，建议您根据先前梳理的文档来设置事件的属性以及发送信息的条件，此处以用户付费作为范例：

distinct_id = "ABCDEF123456"

account_id = "TA10001"

properties = {
    "#time":datetime.datetime.now(),
    # 设置这条event发生的时间，如果不设置的话，则默认是当前时间
    "#ip":"192.168.1.1",
    # 设置用户的IP，tda会自动根据该IP解析省份、城市
    #"#uuid":uuid.uuid1(),#选填，如果上面enable_uuid开关打开，不需要填
    "Product_Name":"商品名",
    "Price":30,
    "OrderId":"订单号abc_123"
}

# 上传事件，包含账号ID与访客ID
try:
   ta.track(distinct_id,account_id,"Payment",properties)
   # 您也可以只上传访客ID
   # ta.track(distinct_id = distinct_id, event_name = "Payment", properties = properties)
   # 或者只上传账号ID
   # ta.track(account_id = account_id, event_name = "Payment", properties = properties)
except Exception as e:
    #异常处理
    print(e)

注： 为了保证访客 ID 与账号 ID 能够顺利进行绑定，如果您的游戏中会用到访客 ID 与账号 ID，我们极力建议您同时上传这两个 ID，

否则将会出现账号无法匹配的情况，导致用户重复计算，具体的 ID 绑定规则可参考用户识别规则一章。

• 事件的名称只能以字母开头，可包含数字，字母和下划线“_”，长度最大为 50 个字符，对字母大小写不敏感。
• 事件的属性是一个dict对象，其中每个元素代表一个属性。
• Key 的值为属性的名称，为str类型，规定只能以字母开头，包含数字，字母和下划线“_”，长度最大为 50 个字符，对字母大小写不敏感。
• Value 为该属性的值，支持str、int、float、bool、datetime.datetime、datetime.date、list、dict;dict中的内容可以为int、float、bool、datetime.datetime、datetime.date、list(内容为字符串);list中的内容可以为dict和str

三、用户属性

TA 平台目前支持的用户属性设置接口为 user_set、user_setOnce、user_add、user_unset、user_append、user_del。

3.1 user_set

对于一般的用户属性，您可以调用user_set来进行设置，使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性，类型与传入属性的类型一致：

properties = {"user_name":"ABC"}
# 上传用户属性，"user_name"的值为"ABC"
try:
    ta.user_set(account_id = account_id, distinct_id = distinct_id, properties = properties)
    properties = {"user_name":"XYZ"}
    # 再次上传用户属性，此时"user_name"的值会被覆盖为"XYZ"
    ta.user_set(account_id = account_id, distinct_id = distinct_id, properties = properties)
except Exception as e:
    #异常处理
    print(e)

属性格式要求与事件属性保持一致。

3.2 user_setOnce

如果您要上传的用户属性只要设置一次，则可以调用user_setOnce来进行设置，当该属性之前已经有值的时候，将会忽略这条信息：

properties = {"user_name":"ABC"}
# 上传用户属性，"user_name"的值为"ABC"
try:
    ta.user_setOnce(account_id = account_id, distinct_id = distinct_id, properties = properties)
except Exception as e:
    #异常处理
    print(e)
properties = {
    "user_name":"XYZ",
    "user_age":18
    }
# 再次上传用户属性，此时"user_name"已存在值，因此不进行修改，仍为"ABC"；"user_age"的值为18
try:
    ta.user_setOnce(account_id = account_id, distinct_id = distinct_id, properties = properties)
except Exception as e:
    #异常处理
    print(e)

属性格式要求与事件属性保持一致。

3.3 user_add

当您要上传数值型的属性时，您可以调用user_add来对该属性进行累加操作，如果该属性还未被设置，则会赋值 0 后再进行计算，可传入负值，等同于相减操作。

properties = {
    "total_revenue":30,
    "vip_level":1
}
# 上传用户属性，此时"total_revenue"的值为30,"vip_level"的值为1
ta.user_add(account_id = account_id, distinct_id = distinct_id, properties = properties)

properties = {"total_revenue":60}
# 上传用户属性，此时"total_revenue"的值为90,"vip_level"的值为1
try:
    ta.user_add(account_id = account_id, distinct_id = distinct_id, properties = properties)
except Exception as e:
    #异常处理
    print(e)

设置的属性key为字符串，Value 只允许为数值。

3.4 user_unset

当您要清空用户的用户属性值时，您可以调用user_unset来对指定属性进行清空操作，如果该属性还未在集群中被创建，则user_unset不会创建该属性

try:
    ta.user_unset(account_id, distinct_id, ["string1", "lasttime"])
except Exception as e:
    #异常处理
    print(e)

user_unset的传入值为被清空属性的 Key 值。

3.5 user_append

当您要为 list 类型追加用户属性值时，您可以调用user_append来对指定属性进行追加操作，如果该属性还未在集群中被创建，则user_append创建该属性

list1 = []
list1.append('Google')
list1.append('Runoob')
properties = {'arrkey1': list1, 'arrkey2': ['11','22']}#//为arrkey1,arrkey2的数组类型追加属性
try:
    ta.user_append(account_id=account_id, distinct_id=distinct_id, properties=properties)
except Exception as e:
    #异常处理
    print(e)

3.6 user_del

如果您要删除某个用户，可以调用user_del将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到

try:
    ta.user_del(account_id = account_id, distinct_id = distinct_id)
except Exception as e:
    #异常处理
    print(e)

3.6 user_uniq_append

从 v1.8.0开始，您可以通过user_uniq_append为Array添加元素，和user_append不同的是，user_uniq_append会对Array内元素进行去重处理。

list = []
list.append('Google')
list.append('Runoob')
list.append('True')
list.append('2.222')
properties = {'arrkey4': list, 'arrkey3': ['appendList', '222'], 'dict1': {'name': 'Tom', 'Age': 28}}
try:
# 执行之后用户属性arrkey4为['Google', 'Runoob', True, 2.222], arrkey3为['appendList', '222']
    tga.user_append(account_id=account_id, distinct_id=distinct_id, properties=properties)
except Exception as e:
    # 异常处理
    raise TGAIllegalDataException(e)

properties = {'arrkey4': ['addValue','True'], 'arrkey3': ['appendList', '222']}
try:
# 执行之后用户属性arrkey4为['Google', 'Runoob', True, 2.222, 'addValue'], arrkey3为['appendList', '222']
    tga.user_uniq_append(account_id=account_id, distinct_id=distinct_id, properties=properties)
except Exception as e:
    # 异常处理
    raise TGAIllegalDataException(e)

四、其他操作

4.1 立即提交数据

ta.flush()

立即提交数据到相应的接收器

4.2 关闭 sdk

ta.close()

关闭并退出 sdk，请在关闭服务器前调用本接口，以避免缓存内的数据丢失

五、相关预置属性

5.1 所有事件带有的预置属性

以下预置属性，是 Python SDK 中所有事件（包括自动采集事件）都会带有的预置属性

属性名	中文名	说明
#ip	IP 地址	用户的 IP 地址，需要进行手动设置，TA 将以此获取用户的地理位置信息
#country	国家	用户所在国家，根据 IP 地址生成
#country_code	国家代码	用户所在国家的国家代码(ISO 3166-1 alpha-2，即两位大写英文字母)，根据 IP 地址生成
#province	省份	用户所在省份，根据 IP 地址生成
#city	城市	用户所在城市，根据 IP 地址生成
#lib	SDK 类型	您接入 SDK 的类型，如 Python 等
#lib_version	SDK 版本	您接入 Python SDK 的版本

六、进阶功能

从 v1.4.0 开始，SDK 支持上报两种特殊类型事件: 可更新事件、可重写事件。这两种事件需要配合 TA 系统 2.8

及之后的版本使用。由于特殊事件只在某些特定场景下适用，所以请在数数科技的客户成功和分析师的帮助下使用特殊事件上报数据。

6.1 可更新事件

您可以通过可更新事件实现特定场景下需要修改事件数据的需求。可更新事件需要指定标识该事件的 ID，并在创建可更新事件对象时传入。TA 后台将根据事件名和事件 ID 来确定需要更新的数据。

# 示例： 上报可被更新的事件，假设事件名为 UPDATABLE_EVENT
distinct_id="65478cc0-275a-4aeb-9e6b-861155b5aca7"
account_id = "123"
event_name = "UPDATABLE_EVENT"
event_id = "123"
properties = {
    "price": 100,
    "status": 3
 }
# 上报后事件属性 status 为 3, price 为 100
ta.track_update(distinct_id=distinct_id, account_id=account_id, event_name=event_name, event_id=event_id, properties=properties)

// 上报后同样event_name + event_id 的事件属性 status 被更新为 5, price 不变
_new_proterties = {
 "status": 5
}
ta.track_update(distinct_id=distinct_id, account_id=account_id, event_name=event_name, event_id=event_id, properties=_new_proterties)

6.2 可重写事件

可重写事件与可更新事件类似，区别在于可重写事件会用最新的数据完全覆盖历史数据，从效果上看相当于删除前一条数据，并入库最新的数据。TA 后台将根据事件名和事件 ID 来确定需要更新的数据。

# 示例： 上报可被重写的事件，假设事件名为 OVERWRITE_EVENT
distinct_id="65478cc0-275a-4aeb-9e6b-861155b5aca7"
account_id = "123"
event_name = "OVERWRITE_EVENT"
event_id = "123"
properties = {
    "price": 100,
    "status": 3
 }
# 上报后事件属性 status 为 3, price 为 100
ta.track_overwrite(distinct_id=distinct_id, account_id=account_id, event_name=event_name, event_id=event_id, properties=properties)

//上报后事件属性 status 被更新为 5, price 属性被删除
_new_proterties = {
 "status": 5
}
ta.track_overwrite(distinct_id=distinct_id, account_id=account_id, event_name=event_name, event_id=event_id, properties=_new_proterties)

6.3 首次事件

首次事件是指针对某个设备或者其他维度的 ID，只会记录一次的事件。例如在一些场景下，您可能希望记录在某个设备上第一次发生的事件，则可以用首次事件来上报数据。

# 调用首次事件
try:
    tga.track_first(account_id=account_id, distinct_id=distinct_id, event_name='first_event', first_check_id=None, properties=properties)
except Exception as e:
    # 异常处理
    raise TGAIllegalDataException(e)

首次事件默认使用distinct_id作为维度ID，如果您想设置其他维度ID可以通过参数来传入指定的first_check_id。

# 调用首次事件
try:
    tga.track_first(account_id=account_id, distinct_id=distinct_id, event_name='first_event', first_check_id='your_first_check_id', properties=properties)
except Exception as e:
    # 异常处理
    raise TGAIllegalDataException(e)

ChangeLog

v1.8.0 2022/04/26

• 支持动态公共属性
• 支持首次事件
• 新增user_uniq_append事件

v1.7.0 2021/12/29

• 增加支持复杂结构类型

v1.6.2 2021/08/05

• 修复flush方法没有刷新文件日期的问题

v1.6.1 2021/06/04

• 修改LoggingConsumer默认写文件的条件为5条数据写入一次
• 修改BatchConsumer默认最大缓存区上限为50批次

v1.6.0 2021/03/22

• 新增网络失败重试机制
• 增加缓存区，重试3次发送失败的数据将存入缓存区中，缓存数据超过上限将会丢弃早期数据
• 支持 #app_id 属性

v1.5.0 2020/11/21

• LoggingConsumer 支持自动创建目录

v1.4.0 2020/08/27

• 新增 track_update 接口，支持可更新事件
• 新增 track_overwrite 接口，支持可重写事件

v1.3.3 2020/08/12

• 修复 AsyncBatchConsumer 在特殊情况下线程不释放的问题

v1.3.2 2020/08/03

• 支持 LoggingConsumer 配置文件前缀名
• 新增 UUID 配置开关

v1.3.1 2020/02/26

• 兼容 python2 的 DebugConsumer 错误日志打印

v1.3.0 2020/02/11

• 数据类型支持 list 类型
• 新增 user_append 接口，支持用户的数组类型的属性追加
• 新增 user_unset 接口，支持删除用户属性
• BatchConsumer 性能优化：支持选择是否压缩；移除 Base64 编码
• DebugConsumer 优化: 在服务端对数据进行更完备准确地校验

v1.2.0 2019/09/25

• 支持 DebugConsumer
• 支持日志文件按小时切分
• BatchConsumer 支持多线程
• 修复 AsyncBatchConsumer 批量发送不生效的问题
• 优化数据上报返回码处理逻辑
• LoggingConsumer: 默认不限制单个日志文件大小