Python SDK 利用ガイド

このガイドは、Python SDK を使用してプロジェクトにデータをインポートする方法を説明します。GitHub (opens new window)で Python SDK のソースコードを入手することができます。

**最新バージョン：**1.7.0

更新時間： 2021-12-29

1、 SDK の初期化

1.pipで Python SDK を取得します。

pip install ThinkingDataSdk

コマンドアップグレード:

pip install --upgrade ThinkingDataSdk

2.SDK の初期化

プログラム初期化コードに SDK を導入してください。import 方法は 2 つあります。

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

または

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

SDK インスタンスの初期化

# SDK初期化の2つ方法，ConsumerはLoggingConsumer,BatchConsumer,AsyncBatchConsumer,DebugConsumerを含む.
#デフォルト
ta = TGAnalytics(Consumer)
# UUID重複除去を追加
ta = TGAnalytics(Consumer, enable_uuid=True)

次の 4 つの方法で 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 のため、キャッシュ保存のデータ総量は最大 5020(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://ta-receiver.thinkingdata.io

オンプレミスサービスを使用している場合は、次の URL を入力してください。

http://数据采集地址

注意:バージョン 1.3.0 以前は次の URL を入力してください:

http://ta-receiver.thinkingdata.io/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://ta-receiver.thinkingdata.io

オンプレミスサービスを使用している場合は、次の 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://ta-receiver.thinkingdata.io

オンプレミスサービスを使用している場合は、次の URL を入力してください。

http://数据采集地址

2、イベントの送信

SDK の初期化が完了した後、trackを呼び出してイベントをアップロードすることができます。通常、数十から数百の異なるイベントをアップロードする必要があります。TA を初めて使用する場合は、いくつかの重要なイベントをアップロードすることをお勧めします。

どのようなイベントを送信すれば良いかについて疑問がある場合、クイックガイドをご参照ください。

2.1 送信イベント

trackを呼び出してイベントをアップロードすることができます。前の内容をもとに、イベントのプロパティと情報送信の条件を設定することをお勧めします。ここでは、ユーザー支払いの例を示します。

distinct_id = "ABCDEF123456"

account_id = "TA10001"

properties = {
    "#time":datetime.datetime.now(),
    # イベント発生時間設定，設定しない場合，デフォルトで現在時間を使用
    "#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 紐づけルールはユーザー識別ルールをご参照ください。

• イベントの名前はアルファベットで始まり、数値、アルファベット、下線「_」を含むことができます。長さは最大 50 文字で大文字と小文字を区別しません。
• イベントのプロパティはdictオブジェクトで、各要素は 1 つのプロパティを表します。
• 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オブジェクトで、各要素は 1 つのプロパティを表します。
• 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 です。

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オブジェクトで、各要素は 1 つのプロパティを表します。
• Key の値はプロパティの名前であり、str型で、アルファベットで始まり、数値、アルファベット、下線「_」を含むことができます。長さは最大 50 文字で大文字と小文字を区別しません。
• Value はプロパティの値であり、str、int、float、bool、datetime.datetime、datetime.date、listを含むことができます。

3.2 user_setOnce

アップロードするユーザープロパティが 1 回しか設定しない場合、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_deleteを呼び出してユーザーを削除することができます。それ以降、このユーザーのユーザープロパティを参照することができなくなるが、発生したイベントを参照することができます。

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

4、その他の操作

4.1 データの即時提出

ta.flush()

即時に対応する受信機にデータを送信します。

4.2 SDK の終了

ta.close()

sdk を終了するには、キャッシュ内のデータの消去を避けため、サーバーをシャットダウンする前にこのインターフェイスを呼び出してください。

5、関連のプリセットプロパティ

5.1 すべてのイベントのプリセットプロパティ

次のプリセットプロパティは、Java SDK のすべてのイベント(自動収集イベントを含む)に含まれるプリセットプロパティです。

プロパティ名	日本語	説明
#ip	IPアドレス	ユーザーのIPアドレス。TAはユーザーの位置情報を取得。
#country	国	ユーザーの国。IPアドレスに基づいて生成。
# country_code	国コード	ユーザーがいる国の国コード(ISO 3166-1 alpha-2、2大文字のアルファベット)。IPアドレスに基づいて生成。
#province	省	ユーザーがいる省。IPアドレスに基づいて生成。
#city	都市	ユーザーがいる都市。IPアドレスに基づいて生成。
#lib	SDKタイプ	SDKのタイプ。Pythonなど。
#lib_version	SDKバージョン	Python SDKのバージョン。

6、高度な機能

v1.4.0 以降、SDK は更新可能なイベント、書き換え可能なイベントとの 2 つの特殊イベントのアップロードをサポートしています。この 2 つのイベントは、TA システム 2.8 以降のバージョンと併用する必要があります。特殊イベントは特定の場面でしか適用されないので、TA のクライアントとアナリストのもとに、特殊イベントのアップロードを行うようにしましょう。

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)

// イベントプロパティアップロード後に 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

省略します。詳細は中国語版をご参照ください。