# データルール

このドキュメントでは、TE (ThinkingEngine) のデータ構造、データフォーマット、およびデータの制約について詳しく説明します。またルールに準拠したデータを構築し、データ伝送の問題を調査する方法も説明します。

LogBus****またはRESTful APIを使用してデータ送信する場合は、このドキュメントのデータルールに従ってデータを整理する必要があります。

# データ構造

TEは、ルールに準拠したJSONデータを受け入れます。SDKが使用されている場合、データは送信用にJSONデータに変換されます。LogBusまたはPOSTメソッドを使用する場合、データは通常のJSONデータである必要があります。

JSONデータは行動単位であり、つまり、1行のJSONデータは、1つのデータに対応します。データの意味では、ユーザーが1つの行動を行うか、ユーザープロパティを設定したりすることを示します。

データのフォーマットと制約は次の通りです。（読みやすくするためにデータの体裁を整理してありますが、実際の環境では改行しないでください）

以下は、イベントデータのサンプルです。

{
  "#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データは2つの部分に分けることができます。

propertiesの同じレイヤーの他フィールドは、このデータの以下の基本情報を構成します。

ユーザーのAccount IDを表す#account_idとGuest IDを表す#distinct_id
時間(秒またはミリ秒まで)を表す#time
データタイプ(イベントまたはユーザープロパティ設定)を表す#type
イベント名(イベントデータのみ)を表す#event_name
ユーザIPを表す#ip
データの一意性を表す#uuid

上記の項目に加えて、"#"で始まるプロパティは、properties内のレイヤーに配置する必要があります。

properties内のレイヤーは、データの内容、つまりイベントの属性、または設定する必要のあるユーザー機能です。バックグラウンド分析中に属性または分析オブジェクトとして直接使用されます。

構造的に見ると、これらの2つの部分はヘッダとコンテンツに似ています。次は、これらの2つの部分の各フィールドの意味を詳しく説明します。

# 1.1 データ構造

次の図で赤枠で示したように、"properties"と同じ層のいくつかのフィールドがこのデータの情報部分を構成します。

これらのフィールドには、このデータのユーザーや時間を表す情報が含まれています。その特徴は、すべてのフィールドが "#" で始まることです。各フィールドの意味と構成方法を整理します。

# 1.1.1 ユーザー（#account_idと#distinct_id）

#account_idと#distinct_idはTEでユーザーを識別するための2つのフィールドであり、そのうち#account_idはユーザーがログイン状態でのIDであり、#distinct_idは未ログイン状態でユーザーを識別するIDです。TEではこの2つのフィールドに基づいて行動を起こすユーザーを判断します。その際に優先的に#account_idを用いて判断します。具体的なルールはユーザー識別ルールを参照ください。

#account_idと#distinct_id少なくとも1つを渡す必要があります。ユーザーがログインしたときにすべてのイベントがトリガーされる場合は、#account_idのみを渡すことが可能です。ユーザーがログインしていないときにトリガーされるイベントがある場合(登録前を含む)、両方のフィールドに入力することをお勧めします。

#account_idと#distinct_idは少なくとも1つを受信することが必要です。すべてのイベントはユーザーがログインしている状態で起こす場合は、#account_idのみを受信することも可能です。未ログイン状態(アカウントを作成していない状態を含む)でイベントを起こす場合、両方のフィールドを入力することをお勧めします。

# 1.1.2 データタイプ（#typeと#event_name）

#typeは、イベントデータとユーザープロパティの変更のどちらでも、データの種類を決定する際に用います。その選択は#typeで設定されます。#typeは2つのカテゴリに分けられます。Trackは、このデータがユーザーのイベント記録であることを意味します。user_を先頭とする場合にはユーザープロパティを操作することを意味します。具体的な意味は次のとおりです。

Track: イベントテーブルを操作、イベントはすべてトラックとしてアップロードされます。
user_set: ユーザーテーブルを操作、1つ以上のユーザープロパティを上書きし、プロパティに既に値がある場合は以前の値を上書きします。
user_setOnce: ユーザーテーブルを操作、1つ以上のユーザープロパティを初期化し、プロパティに既に値がある場合はこの操作は無視されます。
user_add: ユーザーテーブルを操作、1つ以上のユーザープロパティ（数値）を累積計算します。
user_unset: ユーザーテーブルを操作、1つ以上のユーザープロパティの値を空にします。
user_del: ユーザーテーブルを操作、そのユーザーを削除します。
user_append: ユーザープロパティのプロパティ値（list type）に要素を追加することで、ユーザーテーブルを操作します。

#typeの値がtrackの場合、データがイベントの場合、イベント名を**#event_name****で設定する必要があります**。これは文字で始まる必要があり、次の文字のみを含めることができます（大文字と小文字は区別されます）、数字、アンダースコア"_"で、最大50 charactersです。ユーザー機能を変更する操作の場合、#event_nameフィールドは不要です。

なお、ユーザープロパティは高い重要度を持ち、短期間で頻繁に変更することは推奨しません。頻繁に変更する必要があるプロパティについては、イベントプロパティとして入れることを推奨します。

# 1.1.3 タイム(#time)

#timeはイベントが生成された時刻であり必須フィールドです。その形式はミリ秒("yyyy-MM-dd HH:mm: ss.SSS")また("yyyy-MM-dd HH:mm:ss")でなければなりません。

ユーザーテーブルに格納されるデータも#timeを設定する必要がありますが、TEがデータを受信した順序で操作されます。

例えば、ユーザーが過去1日分のユーザーテーブル操作データを再送した場合は、プロパティの上書きと初期化は通常通りに行われます。そのため*#time**フィールドに応じた判定を行なわれません。*

# 1.1.4 ローケーション(#ip)

#ipはデバイスのIPアドレスであり任意のフィールドです。TEが受信すると、IPアドレスに基づいてユーザーの地理的な位置情報を計算します。しかしプロパティとして、#county、#province、#city、その他の地理的位置プロパティは、入力された値が優先されます。

# 1.1.5 データのユニーク性(#uuid)

#uuidはデータフィールドのユニーク性を示すために使用され任意のフィールドです。形式はuuidの標準フォーマットでなければなりません。TEでは、データ量に応じて受信側で短時間に同じ#uuid（＝重複データ）が出現するかどうかをチェックし、重複データは破棄して保存しません。

なお、#uuidで行う確認は、主に短期間のデータ重複によるネットワークジッターの問題を解決するために、最近の数時間に受信したデータのみをチェックし、受信データは全容量で確認できないことをご了承ください。データの重複排除が必要な場合は、別途お問い合わせください。

# 1.2 データ原則

その他の部分は、properties内レイヤーに含まれるデータです。propartiesはJSONオブジェクトで、データはキーと値がペアとして表されます。ユーザーイベントデータであれば、イベントプロパティとそれに該当する値を表します。これらのプロパティや値は、分析に直接利用することができます。ユーザープロパティの操作であれば、設定が必要なプロパティと値を表します。

キーはプロパティの名前で、タイプはstringです。カスタムプロパティは文字で始まらなければならず、文字（大文字と小文字は無視）、数字、アンダースコア"_"を含めることができます。また、#で始まるTEプリセットプロパティもあります。詳細についてはプリセットプロパティを参照してください。ただし、ほとんどの場合、カスタムのみの使用を推奨します。

値はプロパティの値であり、numeric value, text, time, Boolean, list, object, object groupを指定できます。データタイプは以下の通りです。

TEデータタイプ	サンプル	備考	JSONデータタイプ
Value	123,1.23	The data range is -9E15 to 9E15	Number
Text	"ABC", "Shanghai"	The default limit for characters is 2KB	String
Time	"2019-01-01 00:00:00","2019-01-01 00:00:00.000"	"Yyyy-MM-dd HH: mm: ss. SSS" or "yyyy-MM-dd HH: mm: ss", if you want to indicate the date, you can use "yyyy-MM-dd 00:00:00"	String
Boolean	true,false	-	Boolean
List	["a","1","true"]	All elements in the list will be converted to string type , up to 500 elements in the list	Array(String)
Object	{hero_name: "Liu Bei", hero_level: 22, hero_equipment: ["Male and Female Double Sword", "Lu"], hero_if_support: False}	Each child attribute (Key) in the object has its own data type. For value selection description, please refer to the general attributes of the corresponding type above Up to 100 child attributes within the object	Object
Object group	[{hero_name: "Liu Bei", hero_level: 22, hero_equipment: ["Male and Female Double Sword", "Lu"], hero_if_support: False}, {hero_name: "Liu Bei", hero_level: 22, hero_equipment: ["Male and Female Double Sword", "Lu"], hero_if_support: False}]	Each child attribute (Key) in the object group has its own data type. For value selection description, please refer to the general attributes of the corresponding type above Up to 500 objects in the object group	Array(Object)

すべてのプロパティタイプは、最初に受信した値のタイプによって決定されることに注意してください。その後のデータは、対応するプロパティと同じデータタイプでなければなりません。タイプと一致しないプロパティは破棄され、TEはタイプの変換を行いません。

# データ処理規則

TEはデータを受信した後、いくつかの処理を行います。実際の使用シナリオを用いて、TE処理ルールを説明します。

# 2.1 新規イベントの受信

新しいイベントのデータを受信した後、TEは自動的に新しいイベントとそのプロパティの関連モデルを作成します。新しいプロパティを受信した場合、そのプロパティを初めて受信した時のプロパティタイプをプロパティタイプに設定し、プロパティタイプはそれ以降変更できません。

# 2.2 イベントプロパティの追加

既存のイベントにプロパティを追加する必要がある場合は、データをアップロードする際に新しいプロパティを追加するだけです。TEはイベントと新しいプロパティを動的に連携するため、ほかの処理は必要ありません。

# 2.3 イベントプロパティの不一致

イベントデータを受信する際に、その中のあるプロパティタイプがTEに既にある該当のプロパティタイプに一致しない場合、そのプロパティ値は破棄されます（値はnullとなる）。

# 2.4 イベントプロパティの廃止

イベントプロパティを廃止したい場合は、TEのメタデータから非表示にすることができます。その後のデータ送信ではプロパティを送信することができません。一方、TEはプロパティのデータを削除せず、この非表示の操作は可逆的です。プロパティが非表示になった後にプロパティが通信された場合、プロパティの値は引き続き保持されます。

# 2.5 共通プロパティの設定

異なるイベントに対しての同名のプロパティは同じプロパティであると見做され、同じデータタイプであると見做されます。そのため、データタイプの違いによるプロパティ値の破棄を避けるために、すべての同名プロパティは、同じデータタイプである必要があります。異なる意味を持たせるためには、同じプロパティ名ではなく、異なるプロパティ名を設定してください。

# 2.6 ユーザープロパティデータの処理

ユーザーテーブル内のユーザーのデータを変更は、#typeフィールドがuser_set, user_setOnce,, user_add, user_unset, user_append, user_delである場合の処理方法です。操作の種類は#typeフィールドによって決定され、操作の内容はプロパティの属性によって決定されます。

# 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から操作するユーザを特定し、そのユーザーをユーザテーブルから削除します。ただし、そのユーザーのイベントデータは削除されません。

# データ制限

イベント数とプロパティ数の制限

パフォーマンス上の理由から、TEはプロジェクトのイベント数とプロパティ数をデフォルトで制限します。

Restrictions	Event type upper limit	Event property upper limit	User feature cap
Suggested no more than	100	300	100
Hardware cap	500	1000	500

管理者は「プロジェクト管理」ページから、各プロジェクトで使用されているイベント数とプロパティ数を照会できます。

Account_ID(#account_id)、Guest_ID(#distinct_id)の長さの制限

  * Projects created before Version 3.1: 64 characters; To expand to 128 characters, contact TE staff
  * Version 3.1 and subsequent projects: 128 characters

イベント、プロパティ名の制限

 * Event name: `String` type, beginning with a letter, may contain digits, upper and lower case letters and underscores'\', Maximum length 50 words
 * Attribute name: `String` type, beginning with a letter, may contain numbers, letters (ignore case) and underscores'\', Maximum length is 50 characters. Only preset properties can begin with #.

データタイプ別の制限

  * Text: The upper limit of the string is 2KB
  * Number: Data range -9E15 to 9E15
  * List: Up to 500 elements; Each element is a string type with an upper limit of 255 bytes
  * Object: Contains up to 100 sub-attributes
  * Object groups: up to 500 objects

データの可能受信時間の制限

  * Upper limit of server-side data reception events: three to three days prior to server time
  * Client Data Receiving Event Upper Limit: 10 to 3 days prior to server time

# その他のルール

スクランブルを避けるためにUTF-8でデータをコーディングしてください。
TEのプロパティ名とイベント名は大文字と小文字を区別しません。セパレータとして'_'を使用することをお勧めします。
TEはデフォルトで過去3年間のデータのみを受信します。3年以上のデータは入力できません。3年前のデータが必要な場合は、別途ご相談ください。

# FAQ

データの不整合によって発生する一般的な問題をまとめます。データ伝送の問題が発生した場合は、このセクションの内容を確認できます。

# TEがデータを受信しなかった

SDKを使用する場合:

SDKが正常に統合されていることを確認してください
SDKのAPPIDとURLが正しく設定されているか、トランスポートポート番号とモードに対応するサフィックスが欠落していないか確認してください。

LogBusやPOSTメソッドを使用する場合:

SDKのAPPIDとURLが正しく設定されているか、トランスポートポート番号とモードに対応するサフィックスが欠落していないか確認してください。
データがJSON形式で送信されているかどうかを確認し、JSONデータが行ごとに送信されていることを確認してください。
データ構造を改めて確認し、キーが「#」で始まっているか、必要なフィールドが欠落していないかを確認してください。
データ構造を改めて確認し、値の種類と形式（特に時間形式）が正しいか確認してください。
「#event_name」の値が仕様に準拠しており、漢字やスペースなどの文字が含まれていないか確認してください。
「proparties」が「#」で始まっていないか確認してください。

ユーザープロパティの操作ではイベントテーブルのレコードは生成されません。user_setなどのデータのみアクセスされている場合、SQLクエリを除く、イベント分析モデルで直接データを参照することはできません。
データのアップロード時間を確認ください。3年以上の先行した時刻のデータは保存されません。アップロードされたデータが過去データの場合、格納範囲がカバーしていない可能性があります。

# データが欠損、一部のプロパティが受信されない

プロパティ値が仕様に準拠し、漢字やスペースなどの文字を含まないようにしてください。
データ原則に準拠し、プリセットプロパティのみが"#"で始まるプロパティ名になっていることを確認してください。
欠損しているプロパティタイプがTEでのプロパティタイプと同じかどうかを確認してください。受信したプロパティの種類は、TEのメタデータ管理で確認できます。

# データ送信エラー、データを削除したい

個別構築でご利用の場合には、データ削除ツールを使用してデータを削除できます。SaaSでご利用の場合は、別途問い合わせてください。
データが大きく変更された場合は、新しいプロジェクトを直接作成することを推奨します。また、テストプロジェクトの下でデータ検証を行うことを推奨します。

← ユーザー識別ルールプリセットプロパティとシステムフィールド →