メインコンテンツまでスキップ

接続前の準備

最終更新 2026/10/07
ヒント

基礎知識のセクションでは、接続前に理解しておく必要があるAEのデータルールについて説明します。

接続に必要な情報のセクションでは、接続前に準備しておく必要があるシステムパラメーターを示します。

AE (Agentic Engine) システムは、全プラットフォームに対応したデータ連携ソリューションを提供しています。

通常、AEへの接続は3つのステップで行います。まず業務要件を整理してデータ収集プランを策定します。この作業はThinkingAIのアナリストがサポートします。次に、開発者がデータ収集プランに基づいてデータ連携作業を行います。最後に、データ連携が正しく行われているかを検証します。接続の流れは次の図のとおりです：

元の画像を見る

データ連携の前に、AEシステムの基礎知識を理解しておくことは非常に重要です。このドキュメントでは、接続に必要な知識の全体像を紹介するとともに、関連する内容をさらに詳しく知りたい場合のサポートの受け方についても説明します。

このドキュメントの対象読者は、ビジネス担当者、開発者、テスト担当者など、接続に関わるすべての方です。

1. 概要​

AEは全プラットフォームに対応したデータ連携ソリューションを提供しています。主な接続方式は次のとおりです：

  • クライアントSDK：デバイス情報や、サーバーと通信しないユーザー行動データを収集でき、シンプルで使いやすい
  • サーバーSDK：収集内容がより正確で、コア業務データの収集に適している
  • データインポートツール：通常は履歴データのインポートに使用します。サーバーSDKとLogBusを組み合わせる方法も、サーバー側のデータ収集で広く使われている方式です

一般的なアプリとWeb開発向けに、次のものを提供しています：

ミニゲーム開発向けに、次のものを提供しています：

モバイルゲーム開発向けに、次のものを提供しています：

サーバー側の収集ソリューションとしては、サーバーSDK + Logbusの組み合わせをお勧めします。この方式は、データインポートの安定性、リアルタイム性、効率のいずれにおいても優れたパフォーマンスを発揮します。

異種の履歴データをインポートする必要がある場合や、一部のデータをAEシステムに追加で登録する必要がある場合は、DataXによるインポートを検討してください。Logbusとは異なり、DataXは常駐サービスではないため、新しいデータの発生を監視して即座にインポートすることはできず、データのリアルタイム性は保証できません。DataXの利点は、多様なデータソースからの異種データのインポートに対応し、操作が簡単なことです。

FilebeatとLogstashでログを収集していて、そのログデータをAEシステムにインポートしたい場合は、Filebeat +Logstashの方式を使用できます。

データ収集プランを設計する際は、業務の状況に応じて、製品の技術アーキテクチャと業務要件に合ったソリューションを選択してください。収集プランについて不明な点がある場合は、サポートグループで当社のアナリストまたはテクニカルサポート担当者にお問い合わせください。

2. 基礎知識​

2.1 AEのデータモデル​

データ連携を行う前に、まずAEにおけるデータとは何かを理解する必要があります。

データ収集プランの設計とは、業務分析の目標に基づいて、どのユーザー行動イベントを収集するかを決めるプロセスです。例えば、ユーザーのチャージ状況を分析する場合、収集するのはユーザーの支払い行動データになるでしょう。ユーザー行動データは、誰が (WHO)、いつ (WHEN)、どこで (WHERE)、どのような方法で (HOW)、チャージ行動を行ったか (WHAT) に分解できます。次の図のとおりです：

元の画像を見る

ユーザー行動データは、AEではユーザー関連データとイベント関連データに整理され、それぞれユーザーテーブルとイベントテーブルに保存されます。ユーザーデータは主に、ユーザーの状態や、頻繁には変化しないプロパティを表すために使われます。イベントデータは、具体的な行動イベントに関連する情報を表すために使われます。

データ収集プランでは、どのタイミングでユーザーデータの送信をトリガーし、どのタイミングでイベントの送信をトリガーするかを決める必要があります。

すべての接続ガイドで、イベントデータとユーザーデータの送信方法をそれぞれ説明しています。

2.2 ユーザー識別ルール​

ユーザーデータやイベントデータの1件1件について、そのデータがどのユーザーのものかを明確にする必要があります。アカウント体系がないシナリオでは、デバイスに関連するIDを使ってユーザーを一意に識別できます。しかし、アカウント体系があるシナリオでは、1人のユーザーが複数のデバイスでデータを生成する可能性があり、分析ではユーザーの複数端末のデータを結び付けて分析する必要があるため、デバイスに関連する一意のIDは適していません。

上記の2つのシナリオに対応するため、データ連携の過程では、2つのユーザーIDを組み合わせてユーザーを識別する必要があります：

  • ゲストID (#distinct_id)：デフォルトでは、クライアントがランダムなゲストIDを生成してユーザーを識別します。デフォルトのゲストIDを読み取ったり変更したりするためのインターフェースも提供しています。
  • アカウントID (#account_id)：ユーザーがログインしたときに、アカウントIDを設定できます。アカウントIDによって、複数のデバイスのデータを関連付けることができます。

各データには、ゲストIDまたはアカウントIDが含まれている必要があります。クライアントSDKはデフォルトでランダムなゲストIDを生成します。loginインターフェースを呼び出してアカウントIDを設定すると、以降はすべてのデータの送信時にゲストIDとアカウントIDの両方が付与されます。サーバー側から送信する場合は、少なくともどちらか一方のIDを渡す必要があります。

AEのバックエンドでは、ユーザーを識別する一意のIDはAEユーザーID（#user_idフィールド）です。データを受信すると、指定されたユーザー識別ルールに従って、新しいユーザーを作成するか、データを既存のユーザーに紐付けます。

ユーザー識別ルールは非常に重要な内容です。ユーザーIDを正しく設定しないと、データが誤ったユーザーに紐付けられ、分析結果に影響する可能性があります。接続前に必ずこのルールをよく理解し、データ収集プランでユーザー識別の方針を明確にしてください。

2.3 データ形式​

どの方式でデータを連携する場合でも、データ受信側に送信する際には、統一されたデータ形式と同じデータ制限が適用されます。データルールの章で、データ形式と対応するデータ制限について詳しく説明しています。

SDKでデータを連携する場合は、対応するインターフェースを呼び出すだけで、SDKがデータを必要な形式に整えて送信します。データインポートツールやRestful APIでデータを連携する場合は、データルールの説明に従ってデータ形式を整えてから送信する必要があります。

データ形式については、命名規則とデータ型に特に注意してください：

  • 命名規則：イベント名とプロパティ名には小文字の英字、数字、アンダースコア _ のみ使用でき、英字で始まり、50文字以内である必要があります
  • プロパティ値のデータ型：
AEデータタイプ値の例値の説明データタイプ
数値123,1.23データ範囲は-9E15～9E15Number
テキスト"ABC","上海"文字列のデフォルト上限は2KBString

時間

"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のバックエンドでは、プロパティ値のタイプは、そのプロパティ値を最初に受信したときのタイプによって決まります。その後、データ内のあるプロパティの値のタイプが以前に決まったタイプと一致しない場合、そのプロパティは破棄されます。

AEの管理画面では、一部のプロパティ名が#で始まっていることに気付くかもしれません。このようなプロパティはプリセットプロパティです。プリセットプロパティは特に設定する必要はなく、SDKがデフォルトで収集します。詳しくはプリセットプロパティとシステムフィールドを参照してください。

特に注意が必要なのは、データ形式やデータ型が正しく設定されていない場合、データを格納できないことです。そのため、接続段階と接続後には、データ収集プランモジュールでデータ送信が正しく行われているかを検証・確認し、問題があれば速やかに修正する必要があります。

1件のデータのサイズは1MBを超えることはできません。超えた場合、そのデータは格納できません。

3. 接続に必要な情報​

開発者が正式にデータ連携を始める前に、次の情報が準備できていることを確認してください：

  1. プロジェクトのAPP ID：AEの管理画面でプロジェクトを作成するときにプロジェクトのAPP IDが生成されます。「プロジェクト管理」ページでも確認できます

  2. データ受信先のアドレスを確定する

    • クラウドサービスを利用する場合、受信先のアドレスは次のとおりです: https://global-receiver-ta.thinkingdata.cn
    • プライベートデプロイの場合は、プライベートクラスター（またはアクセスポイント）にドメインをバインドし、SSL証明書を設定する必要があります

  3. 受信先のアドレスを検証する：ブラウザでhttps://YOUR_RECEIVER_URL/health-checkにアクセスし、ページにokが返されれば正しく設定されています

  4. データ収集プランには、次の内容を含める必要があります：

    • データ連携の方式：クライアントSDK、サーバーSDK、データインポートツール、またはいくつかの方式の組み合わせ
    • 連携するデータの内容とトリガーのタイミング

これで接続前の準備に関するドキュメントは終わりです。次は、選択した接続方式に応じて対応する接続ガイドを参照し、データ連携を始めましょう。

このページは役に立ちましたか？
このページの内容