データルール
この章では、AEのバックエンドのデータ構造、データタイプ、データ制限について詳しく説明します。この章を読むことで、ルールに沿ったデータの作成方法や、データ転送の問題の調査方法を理解できます。
LogBusまたはRESTful APIでデータをアップロードする場合は、この章のデータルールに従ってデータのフォーマットを処理する必要があります。
1. データ構造
AEのバックエンドが受け付けるのは、ルールに沿ったJSONデータです。SDKで接続している場合、データはJSONデータに変換されて転送されます。LogBusまたはPOSTメソッドでデータをアップロードする場合は、データがルールに沿ったJSONデータである必要があります。
JSONデータは行単位です。つまり1行が1件のJSONデータで、物理的には1件のデータに対応し、データの意味としてはユーザーの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"に置き換えられます
構造と機能の面から、1件のJSONデータは2つの部分に分けられます：
propertiesと同じ階層にあるその他のフィールドは、そのデータの基本情報を構成し、以下の項目のみが含まれます：
- トリガーしたユーザーを表すアカウントID
#account_idとゲストID#distinct_id - トリガー時間を表す
#time。秒またはミリ秒まで指定できます - データタイプ（イベントかユーザープロパティの設定か）を表す
#type - イベント名を表す
#event_name（イベントデータのみ） - ユーザーのIPを表す
#ip - データの一意性を表す
#uuid
以上の項目を除き、「#」で始まるその他のプロパティはすべてpropertiesの内側に配置する必要がありますのでご注意ください
propertiesの内側はそのデータの内容で、イベントのプロパティ、または設定するユーザープロパティです。バックエンドでの分析時に、プロパティまたは分析対象としてそのまま使用されます。
構造的には、この2つの部分はメッセージのヘッダー（Header）とボディ（Content）に似ています。以下では、この2つの部分の各フィールドの意味を詳しく説明します。
1.1 データ情報部分
上記のイベントデータのサンプルのとおり、"properties"と同じ階層にある複数のフィールドが、そのデータの情報部分を構成します。
これらのフィールドには、そのデータをトリガーしたユーザーやトリガー時間などのデータ情報が含まれ、すべてのフィールドが「#」で始まるのが特徴です。本節では、各フィールドの意味と設定方法を説明します。
1.1.1 ユーザー情報（#account_idと#distinct_id）
#account_idと#distinct_idは、AEのバックエンドがユーザーを識別するための2つのフィールドです。#account_idはログイン状態のユーザーのID、#distinct_idは未ログイン状態のユーザーの識別子です。AEのバックエンドはこの2つのフィールドに基づいてその行動をトリガーしたユーザーを判断し、#account_idが優先されます。具体的なルールはユーザー識別ルールの章を参照してください。
#account_idと#distinct_idは少なくとも一方を渡す必要があります。すべてのイベントがユーザーのログイン状態でトリガーされる場合は、#account_idのみを渡しても構いません。未ログイン状態（登録前を含む）でトリガーされるイベントがある場合は、両方のフィールドを入力することをお勧めします。
1.1.2 データタイプ情報（#typeと#event_name）
#typeはそのデータのタイプ、つまりユーザーの行動記録か、ユーザープロパティを変更する操作かを決定します。すべてのデータで#typeフィールドの設定が必要です。#typeの値は2種類に分かれ、trackはそのデータがユーザーの行動記録であることを、user_で始まる値はユーザープロパティに対する操作であることを表します。具体的な意味は以下のとおりです：
- track：イベントテーブルにイベントを1件渡します。イベントのアップロードはすべてtrackです
- user_set：ユーザーテーブルを操作し、1つまたは複数のユーザープロパティを上書きします。そのプロパティに既に値がある場合は、以前の値を上書きします
- user_setOnce：ユーザーテーブルを操作し、1つまたは複数のユーザープロパティを初期化します。そのプロパティに既に値がある場合は、今回の操作を無視します
- user_add：ユーザーテーブルを操作し、1つまたは複数の数値型ユーザープロパティを累積加算します
- user_unset：ユーザーテーブルを操作し、そのユーザーの1つまたは複数のユーザープロパティのプロパティ値をクリアします
- user_del：ユーザーテーブルを操作し、そのユーザーを削除します
- user_append：ユーザーテーブルを操作し、ユーザーのリスト型プロパティ値に要素を追加します
- user_uniq_append: ユーザーテーブルを操作し、ユーザーのリスト型プロパティ値に要素を追加したうえで、リスト全体の重複排除を1回行います（重複排除の前後で既存の要素の順序は変わりません）
#typeの値がtrackの場合、つまりそのデータが行動記録である場合は、イベント名#event_nameを必ず設定する必要があります。イベント名は英字で始まり、英小文字、数字、アンダースコア「_」のみを含めることができ、最大50文字です。設定時にスペースを含めないようご注意ください。そのデータがユーザープロパティを変更する操作である場合、#event_nameフィールドは不要です。
なお、ユーザープロパティはユーザーの節目となる意味を持つプロパティであるため、短時間に頻繁に変更することはお勧めしません。頻繁に変更が必要なプロパティは、イベントに含めてイベントプロパティとすることをお勧めします
1.1.3 トリガー時間（#time）
#timeはイベントが発生した時間で、必ず設定する必要があります。フォーマットは、ミリ秒まで（"yyyy-MM-dd HH:mm:ss.SSS"）または秒まで（"yyyy-MM-dd HH:mm:ss"）の文字列である必要があります
Userテーブルに対する操作データにも#timeの設定が必要ですが、ユーザープロパティに対する操作は、バックエンドがデータを受信した順に実行されます。
たとえば、ユーザーが過去のある日のUserテーブル操作データを再送した場合でも、プロパティの上書きと初期化はいずれも通常どおり実行され、#timeフィールドに基づく判断は行われません
1.1.4 トリガー場所（#ip）
#ipはデバイスのIPアドレスで、任意で設定します。AEはIPアドレスに基づいてユーザーの地理位置情報を算出します。"properties"で#country、#province、#cityなどの地理位置プロパティを渡した場合は、渡した値が優先されます
1.1.5 データの一意ID（#uuid）
#uuidはデータの一意性を表すフィールドで、任意で設定します。フォーマットはuuidの標準フォーマットである必要があります。AEはデータ量に応じて、一定期間内に同じ#uuidのデータ（つまり重複データ）が短時間に出現していないかを受信側で検証し、重複データはそのまま破棄して格納しません
なお、#uuidによる受信側の検証は直近数時間に受信したデータのみを対象としており、主にネットワークの揺らぎによる短時間のデータ重複を解決するためのものです。受信したデータを全量データと照合することはできません。データの重複排除が必要な場合は、ThinkingAIの担当者にお問い合わせください。
1.2 データ本体部分
データのもう一つの部分は、propertiesの内側に含まれるデータです。propertiesはJSONオブジェクトで、その中のデータはキーと値のペアで表されます。ユーザーの行動データの場合は、その行動のプロパティと指標（行動テーブルのフィールドに相当）を表し、これらのプロパティと指標は分析時にそのまま使用できます。ユーザープロパティに対する操作の場合は、設定するプロパティの内容を表します。
key値はそのプロパティの名前で、タイプは文字列です。カスタムプロパティは英字で始まり、英小文字、数字、アンダースコア「_」のみを含めることができ、最大50文字です。このほか、#で始まるAEのプリセットプロパティもあり、詳しくはプリセットプロパティの章を参照してください。ただし、ほとんどの場合はカスタムプロパティのみを使用し、#は使用しないことをお勧めします。
value値はそのプロパティの値で、数値、文字列、時間、ブール値、リスト、オブジェクト、オブジェクトグループのいずれかです。データタイプの表し方は次の表のとおりです：
| AEデータタイプ | 値の例 | 値の説明 | データタイプ |
|---|---|---|---|
| 数値 | 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"または"yyyy-MM-dd HH:mm:ss"。日付を表す場合は"yyyy-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) |
なお、すべてのプロパティのタイプは、そのプロパティの値を初めて受信したときのタイプによって決まります。以降のデータのタイプは対応するプロパティのタイプと一致している必要があり、タイプが一致しないプロパティは破棄されます（そのデータのうちタイプが一致するその他のプロパティは保持されます）。AEはタイプの互換変換を行いません。
2. データ処理ルール
AEのサーバーはデータを受信した後、いくつかの処理を行います。本節では、実際の使用シーンに沿って、AEのバックエンドの処理ルールを説明します：
2.1 新しいイベントデータの受信
新規イベントのデータを受信すると、AEのバックエンドは新規イベントとそのプロパティの関連モデルを自動的に作成します。新しいプロパティを受信した場合は、そのプロパティを初めて受信したときのプロパティタイプがそのプロパティのタイプとして設定され、以降プロパティのタイプは変更できません。
2.2 イベントプロパティの追加
既存のイベントにプロパティを追加する場合は、データのアップロード時に新しいプロパティを一緒に渡すだけで済みます。AEのバックエンドがイベントと新しいプロパティを動的に関連付けるため、その他の設定は不要です。
2.3 プロパティが一致しない場合の処理
受信したイベントデータのあるプロパティのタイプが、バックエンドに保存済みのそのプロパティのタイプと一致しない場合、そのプロパティの値は破棄されます（つまり値はnullになります）。
2.4 イベントプロパティの廃止
イベントのあるプロパティを廃止する場合は、AE管理画面のデータ管理モジュールでそのプロパティを非表示にするだけで済み、以降に転送するデータではそのプロパティを渡さなくても構いません。AEのバックエンドはそのプロパティのデータを削除せず、非表示の操作も元に戻せます。プロパティを非表示にした後もそのプロパティを転送した場合、そのプロパティの値は引き続き保持されます。
2.5 複数イベントの共通プロパティ
異なるイベントの同名プロパティは同じプロパティとみなされ、タイプも同じです。そのため、タイプの不一致によってプロパティ値が破棄されることがないよう、すべての同名プロパティのタイプを一致させる必要があります。
2.6 ユーザーテーブルの操作ロジック
ユーザーテーブル内のユーザーのデータを変更するデータ、つまり送信データの#typeフィールドがuser_set、user_setOnce、user_add、user_unset、user_appendまたはuser_delであるデータは、本質的には1つの命令とみなせます。つまり、そのデータが指すユーザーのユーザーテーブルのデータに対して操作を行うもので、操作のタイプは#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に基づいて操作対象のユーザーを特定し、そのユーザーをユーザーテーブルから削除します。そのユーザーのイベントデータは削除されません。
2.6.7 重複排除型リストのユーザープロパティへの要素の追加(user_uniq_append)
データ内のユーザーIDに基づいて操作対象のユーザーを特定し、properties内のプロパティに基づいて、リスト型のプロパティに要素を追加したうえで、リスト全体の重複排除を1回行います（重複排除の前後で既存の要素の順序は変わりません）
3. データ制限
- イベントタイプとプロパティ数の制限
パフォーマンスを考慮し、AEのバックエンドはデフォルトでプロジェクトのイベントタイプとプロパティの数を制限しています：
| 制限 | イベント種類の上限 | イベントプロパティの上限 | ユーザープロパティの上限 |
|---|---|---|---|
| 推奨上限 | 100 | 300 | 100 |
| ハード上限 | 500 | 1000 | 500 |
管理者は「プロジェクト管理」ページで、各プロジェクトで使用済みのイベントタイプとプロパティの数を確認できます。イベントの種類数とプロパティ数の上限の引き上げは、ThinkingAIの担当者に連絡して申請できます。
-
アカウントID(#account_id)、ゲストID(#distinct_id)の長さの制限
- バージョン3.1より前に作成されたプロジェクト：64文字。128文字に拡張する場合は、ThinkingAIの担当者にお問い合わせください
- バージョン3.1以降に作成されたプロジェクト：128文字
-
イベント名・プロパティ名の制限
- イベント名：
String型。英字で始まり、数字、英小文字、アンダースコア“_”を含めることができ、最大50文字 - プロパティ名：
String型。英字で始まり、数字、英小文字、アンダースコア“_”を含めることができ、最大50文字。#で始めることができるのはプリセットプロパティのみです。
- イベント名：
-
文字列・数値・リスト・オブジェクト・オブジェクトグループ型プロパティのデータ範囲
- 文字列：文字列の上限は2KB
- 数値：データ範囲は-9E15～9E15
- リスト：最大500個の要素を含められます。各要素は文字列型で、上限は255バイト
- オブジェクト：最大100個のサブプロパティを含められます。
- オブジェクトグループ：最大500個のオブジェクトを含められます。
-
データの受信期限
- サーバー側データの受信時間範囲：サーバー時間を基準に3年前から3日後まで
- クライアント側データの受信時間範囲：サーバー時間を基準に10日前から3日後まで
4. その他のルール
- 文字化けを防ぐため、データはUTF-8でエンコードしてください
- AEのバックエンドのプロパティ名は小文字のみに対応しています。単語の区切り文字には"_"を使用することをお勧めします
- AEのバックエンドはデフォルトで直近3年間のデータのみを受信し、3年を超えるデータは登録できません。3年より前のデータを登録する必要がある場合は、ThinkingAIの担当者に連絡して期限を緩和してもらえます
5. よくある質問
本節では、データがデータルールに適合していないことが原因で起こるよくある問題をまとめています。データ転送の問題が発生した場合は、まず本節の内容に沿って調査してください
5.1 AEのバックエンドがデータを受信していない
SDKで転送している場合：
- SDKが正常に統合されているか確認してください
- APPIDと転送先URLが正しく設定されているか、転送ポート番号や転送方式に対応するサフィックスが抜けていないかを確認してください
LogBusまたはPOSTメソッドで転送している場合：
- APPIDと転送先URLが正しく設定されているか、転送ポート番号や転送方式に対応するサフィックスが抜けていないかを確認してください
- データがJSONフォーマットで転送されているか、1行に1件のJSONデータになっているかを確認してください
- データ情報部分のkey値が"#"で始まっているか、必須フィールドが抜けていないかを確認してください
- データ情報部分のvalue値のタイプとフォーマット（時間フォーマット）が正しいかを確認してください
- "#event_name"のvalue値が規則に沿っており、漢字やスペースなどの文字を含んでいないかを確認してください
- "properties"というkey自体を"#"で始めないでください（"#properties"とは書かないでください）
- また、ユーザープロパティの設定では行動記録は生成されないため、
user_setなどのデータのみをアップロードした場合、バックエンドの行動分析モデル（SQL IDEを除く）ではデータを直接クエリできませんのでご注意ください - アップロードするデータの時間にご注意ください。古すぎる（3年を超える）データは登録されません。アップロードしたデータが履歴データの場合は、クエリの期間がアップロードしたデータの時間をカバーしていない可能性があるため、クエリの期間を調整してください
5.2 データが欠落していて、一部のプロパティが受信されていない
- データ本体部分のプロパティのkey値が規則に沿っており、漢字やスペースなどの文字を含んでいないかを確認してください
- データ本体部分のプロパティのうち、"#"で始まるkey値がプリセットプロパティに含まれているかを確認してください
- 欠落したプロパティのアップロード時のタイプが、バックエンドにあるそのプロパティのタイプと一致しているかを確認してください。受信済みのプロパティのタイプは、管理画面のメタデータ管理で確認できます
5.3 データ転送に誤りがあり、データを削除したい
- オンプレミス版のユーザーは、データ消去ツールでセルフサービスでデータを削除できます。クラウド版のユーザーは、ThinkingAIの担当者に連絡してデータを削除してもらえます
- データに大きな変更がある場合は、新しいプロジェクトを直接作成することをお勧めします。また、本番のデータ転送を行う前に、テストプロジェクトで十分なデータテストを行うことをお勧めします