Python SDK使用指南

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

最新版本为：1.4.0

更新时间为：2020-08-27

1. 初始化SDK

1.通过pip获取Python SDK

pip install ThinkingDataSdk

升级命令：

pip install --upgrade ThinkingDataSdk

2.初始化SDK

请在程序初始化代码中引入SDK，并初始化获得SDK实例

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

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

(1)LoggingConsumer：批量实时写本地文件，文件以天为分隔，需要与LogBus搭配使用进行数据上传，建议使用

#默认按日切分
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服务器传输数据（同步阻塞），不需要搭配传输工具，不建议在生产环境中使用

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://数据采集地址

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://数据采集地址

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

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://数据采集地址

2. 发送事件

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

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

a) 发送事件

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

distinct_id = "ABCDEF123456"

account_id = "TA10001"

properties = {
    "#time":datetime.datetime.now(),
    # 设置这条event发生的时间，如果不设置的话，则默认是当前时间
    "#ip":"192.168.1.1",
    # 设置用户的IP，tda会自动根据该IP解析省份、城市
    #"#uuid":uuid.uuid1(),#选填，如果上面enableUuid开关打开，不需要填
    "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

b) 设置公共事件属性

对于一些需要出现在所有事件中的属性属性，您可以调用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。

3. 用户属性

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

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

b) 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一致。

c) 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一致，但只对数值型的用户属性有效。

d) user_unset

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

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

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

f) user_del

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

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

4. 其他操作

a) 立即提交数据

ta.flush()

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

b) 关闭sdk

ta.close()

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

5. 相关预置属性

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

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

6. 进阶功能

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