# データルール

本章では、TAプラットフォームでのデータ構造、データ型、およびデータ制限について詳しく説明します。本章では、ルールに準拠したデータを構築し、データ転送の問題を調査する方法を学びます。

LogBus****またはRESTful APIを使用してデータをアップロードする場合は、本章のデータルールに従ってデータを初期化する必要があります。

# 1、データ構造

TAプラットフォームは、ルールに準拠した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の同層の他のフィールドは、このデータの以下の基本情報を構成します。

ユーザーのアカウントIDを表す#account_idとゲスト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はTAプラットフォームでユーザーを識別するための2つのフィールドであり、そのうち#account_idはユーザーがログイン状態でのIDであり、#distinct_idは未ログイン状態でユーザーを識別するIDです。TAプラットフォームではこの2つのフィールドに基づいて行動を起こすユーザーを判断します。その際に優先的に#account_idを用いて判断します。具体的なルールはユーザー識別ルールを参照します。

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

# 1.1.2 データ型情報（#typeと#event_name）

#typeは、このデータの種類が決定され、ユーザーの行動記録であり、ユーザーのプロパティを修正する操作です。すべてのデータには#typeフィールド****を構成する必要があります。#typeの値は2種類に分けられ、trackはこのデータがユーザー行動記録であるこを表し、user_で始まる値はユーザープロパティを操作することを表します。具体的な意味は次の通りです。

track:イベントをイベントテーブルに渡します。イベントのアップロードはtrack
user_set:ユーザーテーブルを操作し、1つまたは複数のユーザープロパティを上書きする。そのプロパティに値が存在する場合、前の値を上書きする
user_setOnce:ユーザーテーブルを操作し、1つまたは複数のユーザープロパティを初期化する。プロパティに値が存在する場合は、この操作を無視する
user_add:ユーザーテーブルを操作し、1つまたは複数の数値型ユーザープロパティの累積計算を行う
user_unset:ユーザーテーブルを操作して、そのユーザーの1つまたは複数ののユーザープロパティの値を削除する
user_del:ユーザテーブルを操作し、そのユーザを削除する
user_append:ユーザーテーブルを操作し、ユーザーのリスト型のプロパティ値に要素を加える

#typeの値がtrack、つまりこのデータが行動記録の場合、イベントの名前#event_name**を構成****しなければなりません。**必ずアルファベットで始まり、アルファベット(大文字、小文字を区別)、数字と下線「_」のみ含むことができます。長さは最大50文字です。スペースがないことにご注意ください。一方、このデータはユーザープロパティを変更する操作を示すならば、#event_nameフィールドが必要ありません。

なお、ユーザープロパティはユーザーのノードの意味を持つプロパティであり、頻繁に修正することは推奨されず、頻繁に変更する必要があるプロパティについてはイベントプロパティとしてイベントに入れることを推奨します。

# 1.1.3 時間トリガー（#time）

#timeはイベントが発生する時間であるため、必須フィールドになります**。**形式はミリ秒("yyyy-MM-dd HH: mm: ss.SSS"）または秒("yyyy-MM-ddHH: mm: ss")の文字列でなければなりません。

ユーザーテーブルの操作データにも#timeを構成する必要があるが、ユーザープロパティに対する操作はバックグラウンドでデータを受信した順序で行われます。

例えば、ユーザーが過去のある日のUserテーブル操作データを再送した場合、プロパティの上書きも初期化も通常通りに行われ、#timeフィールドで判断**されません。

# 1.1.4 場所トリガー（#ip）

#ipはデバイスのIPアドレスであり、任意フィールドです。TAはIPアドレスに基づいてユーザーの地理的な位置情報を計算します。「properties」に#country、#province、#cityなどの地理的な位置プロパティを入力した場合、入力した値が優先されます。

# 1.1.5 データの一意ID（#uuid）

#uuidはデータの一意性を表すフィールドであり、任意フィールドです。形式はuuidの標準フォーマットでなければなりません。TAはデータ量に応じて、一定期間内、受信側で同じ#uuidのデータ(つまり重複データ)が短時間に現れるどうかをチェックし、重複データを廃棄し、格納しません。

#uuidによる受信側のチェックは、直近の数時間に受信したデータのみで行われ、主にネットワークのジッターによる短時間のデータ重複を解決します。受信したデータをすべてのデータとチェックすることはできないことをご注意ください。データの重複を除去するには、TAスタッフにご連絡ください。

# 1.2 データの本体部分

データのもう一つ部分はproperties内層に含まれるデータです。propertiesはJSONオブジェクトであり、データはキー値ペアとして表示されます。ユーザの行動データであれば、その行動のプロパティと指標(行動表のフィールドに相当)を表し、これらのプロパティと指標は分析時に直接に使用することができます。一方、ユーザプロパティの操作処理であれば、設定すべきのプロパティ内容を表します。

key値はこのプロパティの名前です。形式は文字列で、カスタムプロパティはアルファベットで始まる必要があり、アルファベット(大文字と小文字を区別しない)、数字と下線「_」で、長さは最大50文字です。また**#で始まるTAプリセットプロパティもあり、プリセットプロパティの章で詳しく知ることができますが、ほとんどの場合カスタムプロパティのみを使用し、#**を使用しません。

value値はこのプロパティの値であり、値は数値、テキスト、時間、ブール、リスト、オブジェクト、オブジェクトグループにすることができます。データ型の表記は以下のように示します。

TAデータ型	サンプル値	値の説明	データ型
数値	123,1.23	データ範囲は-9E15~9E15	Number
テキスト	"ABC","上海"	文字のデフォルトの上限は2KB	String
時間	"2019-01-01 00:00:00","2019-01-01 00:00:00.000"	"yyyy-MM-dd HH: mm: ss.SSS」または「yyy-MM-dd HH: mm: ss」。日付を表すには、「yyy-MM-dd 00: 00: 00」	String
ブール	true、false	-	Boolean
リスト	["a","1","true"]	リスト内のすべての要素は文字列型に変換。リスト内は最大500個の要素がある。	Array（String）
オブジェクト	{hero_name:"劉備", hero_level: 22, hero_equipment:["雌雄二股剣"," 的盧"], hero_if_support: False}	オブジェクト内の各サブプロパティ(Key)には独自のデータ型がある。値の説明は、上記に該当するデータ型の通常プロパティを参照。オブジェクト内は最大100個のサブプロパティがある。	Object
オブジェクトグループ	[{hero_name:"劉備", hero_level: 22, hero_equipment:["雌雄二股剣","的盧"], hero_if_support: False},{hero_name:"劉備", hero_level: 22, hero_equipment:["雌雄二股剣","的盧"], hero_if_support: False}]	オブジェクトグループ内の各サブプロパティ(Key)には独自のデータ型がある。値の説明は、上記に該当するデータ型の通常プロパティを参照。オブジェクトグループ内は最大500個のオブジェクトがある。	Array（Object）

すべてのプロパティタイプは、最初に受信したプロパティ値のデータ型をもとに決定され、後続のデータ型はプロパティタイプと一致しなければなりません。一致しないプロパティは破棄されます。（このデータの残りのプロパティタイプに一致するプロパティは保持されます）TAではプロパティタイプの変換を行いません。

# ２、データ処理ルール

TAサーバーはデータを受信した後、いくつかの処理を行います。本節では、実際の使用場面を使って、TAプラットフォームの処理ルールを説明します。

# 2.1 新規イベントデータの受信

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

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

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

# 2.3 プロパティ不一致の処理

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

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

イベントのあるプロパティを無効にする必要がある場合は、TAプラットフォームのメタデータ管理でそのプロパティを隠すだけでよく、それ以降に転送するデータはそのプロパティを渡さなくても良いです。TAプラットフォームはこのプロパティのデータを削除せず、非表示することも可逆的です。プロパティを非表示した後にこのプロパティを転送する場合、このプロパティの値が保持されます。

# 2.5 複数イベントの共有プロパティ

異なるイベントの同名プロパティは同一プロパティとみなされ、プロパティタイプが一致するため、すべての同名プロパティのプロパティタイプが一致しなければなりません。プロパティタイプが不一致するとプロパティ値が廃止されます。

# 2.6 ユーザーテーブルの操作ロジック

ユーザーテーブル内のユーザーデータ、つまり#typeフィールドがuser_set、user_add、user_unset、user_unset、user_appendまたはuser_delのアップロードデータの修正は、指示と見なすことができます。このデータが指すユーザーのユーザーテーブルのデータを操作し、操作タイプは#typeフィールドによって決定され、操作の内容はpropertiesのプロパティによって決定されます。

以下は、主なユーザーテーブルのプロパティ操作の具体的なロジックです。

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

# 3、データ制限

イベントタイプ及びプロパティ数の制限

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

制限	イベントタイプの上限	イベントプロパティの上限	ユーザープロパティの上限
推奨上限	100	300	100
ハードウェア上限	500	1000	500

管理者は「プロジェクト管理」ページに入り、各プロジェクトで既に使用しているイベントタイプとプロパティ数を照会します。TAスタッフに連絡して、イベントタイプ、プロパティの上限の拡張を申請することができます。

アカウントID(#account_id)、ゲストID(#distinct_id)長さの制限

  * 3.1版以前に作成したプロジェクト：64文字；128文字までに拡張したい場合、TAスタッフに連絡

  * 3.1版以降に作成したプロジェクト：128个文字

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

  * イベント名：`String`型，アルファベットで始まり，数値，アルファベット(大文字/小文字を区別)と下線“\_”を含むことができる。長さは50文字。
  * プロパティ名：`String`型，アルファベットで始まり，数値，アルファベット(大文字/小文字を区別しない)と下線“\_”を含むことができる。長さは50文字。プリセットプロパティのみ#で始まる。

テキスト、数値、リスト、オブジェクト、オブジェクトグループ型のプロパティデータ範囲

  * テキスト：文字列の上限は2KB

  * 数值：数値の範囲は-9E15～9E15

  * リスト：最大500個の要素を含む；各要素は文字列型で上限は255文字
  
  * オブジェクト：最大100個のサブプロパティを含む；
  
  * オブジェクトグループ：最大500個のオブジェクトを含む；

データ受信期限

  * サーバー側のイベント受信上限：システム時間の3年前から3日後

  * クライアント側のイベント受信上限：システム時間の10日前から3日後

# 4、その他のルール

文字化けを避けるためUTF-8でデータをエンコードしてください。
TAプラットフォームのプロパティ名とイベント名は大文字と小文字を区別しないので、"_"を区切り文字として使用します。
TAプラットフォームはデフォルトで直近3年分のデータしか受信しておらず、3年以上のデータは取り込めません。必要な場合、TAスタッフにご連絡ください。

# 5、よくある質問

本節では、データがデータルールに準拠していないことが原因で引き起こした一般的な問題をまとめます。データ転送に関する問題が発生した場合は、まず本節の内容に基づいて調査しましょう。

# 5.1 TAプラットフォームでデータが受信されなかった

SDKを使用して転送した場合:

SDKが正確に統合されているか
APPIDと転送のURLが正しく設定されているか、転送ポート番号と転送方式のサフィックスに欠落がないか

LogBusまたはPOSTを使用して転送した****場合:

APPIDと転送のURLが正しく設定されているか、転送ポート番号と転送方式のサフィックスに欠落がないか
データがJSON形式で転送されていること、JSONデータが1行に1つのみあること
データの情報部分のkey値が"#"で始まるか、必要なフィールドが欠落しているか
データの情報部分のvalue値の種類と形式(時間形式)が正しいか
"#event_name"のvalue値がルールに準拠しており、漢字、スペースなどが含まれていないか
"properties"が"#"で始まっていないか

また、ユーザープロパティの設定は行動記録が生成されないため、user_setなどのデータのみをアップロードした場合、プラットフォームの行動分析モデル(SQLクエリを除く)でデータを照会できません。
データのアップロード時間にご注意ください。早すぎる時間(3年以前)のデータは入力されません。アップロードしたデータは過去のデータの場合、照会期間がデータのアップロード時間をカバーしていない可能性があるので、照会期間を調整してください。

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

データの本体部分のプロパティkey値がルールに準拠しており、漢字、スペースなどが含まれていないか
データの本体部分のプロパティの中、"#"で始まるkey値はプリセットプロパティ。
欠落しているプロパティのアップロード時のタイプはプラットフォームでのプロパティタイプと一致するか。プラットフォームのメタデータ管理で受信したプロパティタイプを照会。

# 5.3 データ転送にエラーがあり、データを削除したい

オンプレミスサービスのユーザーは、データ削除ツールを使ってデータを削除することができます。クラウドサービスのユーザーは、TAスタッフに連絡してデータ削除ができます。
データに大きな変更がある場合、プロジェクトを新規作成することをお勧めします。ユーザーは、データを正式に転送する前に、テストプロジェクトで完備なデータテストを行うことをお勧めします。

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