# Python SDK 使用指南

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

最新版本为：1.7.0

更新时间为：2021-12-29

# 一、初始化 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 搭配使用进行数据上传，默认缓存数据超过8K会写一次文件，可设置buffer_size更改该大小，单位为Byte，如果需要立刻写入，可调用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_suffix="xx"))

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

(2)BatchConsumer： 批量实时地向 TA 服务器传输数据（同步阻塞），不需要搭配传输工具，因网络问题发送失败时会重试3次，仍然失败将会把数据存入缓存区，可设置缓存区大小，默认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:

http://receiver.ta.thinkingdata.cn

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

http://数据采集地址

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

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

(3)AsyncBatchConsumer： 批量实时地向 TA 服务器传输数据（异步非阻塞），不需要搭配传输工具，不建议在生产环境中使用

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

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

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

http://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:

http://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

# 2.2 设置公共事件属性

对于一些需要出现在所有事件中的属性属性，您可以调用set_super_properties来设置公共事件属性，我们推荐您在发送事件前，先设置公共事件属性。

# 设置公共事件属性
super_properties = {
    "server_version":"1.2.3",
    "server_name":"A1001"
}
ta.set_super_properties(super_properties)

distinct_id = "ABCDEF123456"
account_id = "TA10001"
properties = {
    "Product_Name":"商品A",
    "Price":60
}

# 上传事件，事件中将会带有公共事件属性以及该事件本身的属性
try:
    ta.track(distinct_id,account_id,"Payment",properties)
except Exception as e:
    #异常处理
    print(e)
'''
相当于进行下列操作
properties = {
    "server_version":"1.2.3",
    "server_name":"A1001",
    "Product_Name":"商品A",
    "Price":60

try:
    ta.track(distinct_id,account_id,"Payment",properties)
except Exception as e:
    #异常处理
    print(e)
'''

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

如果调用set_super_properties设置先前已设置过的公共事件属性，则会覆盖之前的属性值。如果公共事件属性和track上传事件中的某个属性的 Key 重复，则该事件的属性会覆盖公共事件属性：

super_properties = {
    "server_version":"1.2.3",
    "server_name":"A1001"
}
ta.set_super_properties(super_properties)

super_properties = {"server_name":"B9999"}

ta.set_super_properties(super_properties)
# 此时"server"的值变为"B9999"

distinct_id = "ABCDEF123456"
account_id = "TA10001"
properties = {
    # 覆盖"server_version"
    "server_version":"1.3.4",
    "Product_Name":"商品A",
    "Price":60
}

# 上传事件，此时"server_version"的值为"1.3.4","server_name"的值为"B9999"
try:
    ta.track(distinct_id,account_id,"Payment",properties)
except Exception as e:
    #异常处理
    print(e)

如果您想要清空所有公共事件属性，可以调用clear_super_properties。

# 三、用户属性

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)

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

# 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)

user_setOnce设置的用户属性类型及限制条件与user_set一致。

# 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)

user_add设置的用户属性类型及限制条件与user_set一致，但只对数值型的用户属性有效。

# 3.4 user_unset

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

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

# 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)

# 四、其他操作

# 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)

# ChangeLog

# 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: 默认不限制单个日志文件大小

← PHP SDK 使用指南 Ruby SDK 使用指南 →