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

Restful API使用ガイド

最終更新 2026/10/03

このガイドでは、データ連携APIの使い方を説明します。データ連携APIを使用すると、転送ツールやSDKに依存せずに、HTTPのPOSTメソッドでThinkingAnalyticsのバックエンドに直接データを送信できます。

接続を始める前に、まずデータルールを読んでください。AEのデータ形式とデータルールを理解したうえで、このガイドを読んで接続を行ってください。

POSTメソッドでアップロードするデータはAEのデータ形式に従う必要があります

1. データ形式の変換​

データをアップロードする前に、まずデータの形式をAEのデータ形式に変換する必要があります。AEのデータは1件ごとに1つのJSONです。データの例は次のとおりです（読みやすくするため、データは整形してあります）：

{
  "#account_id": "ABCDEFG-123-abc",
  "#distinct_id": "F53A58ED-E5DA-4F18-B082-7E1228746E88",
  "#type": "track",
  "#ip": "192.168.171.111",
  "#time": "2017-12-18 14:37:28.527",
  "#event_name": "test",
  "properties": {
    "#lib": "LogBus",
    "#lib_version": "1.0.0",
    "#screen_height": 1920,
    "#screen_width": 1080,
    "argString": "abc",
    "argNum": 123,
    "argBool": true
  }
}

具体的なデータ形式の仕様については、データ形式の章を参照してください。

2. データ送信​

JSONデータの準備ができたら、データを送信できます。AEのバックエンドはHTTP標準のPOST方式による呼び出しリクエストを受け付けます。すべてのインターフェースのデータの文字コードはUTF-8です。具体的な呼び出し方法は次のとおりです：

2.1 データ受信インターフェース（送信方式はform-data）​

クラウドサービスをご利用の場合は、次のURLを入力してください:

https://global-receiver-ta.thinkingdata.cn/sync_data

プライベートデプロイ版をご利用の場合は、次のURLを入力してください:

http://データ収集アドレス/sync_data

2.1.1 受信パラメーター（requestBodyに記述）​

  • 1件のjsonデータの場合：

    • パラメーター1：appid=プロジェクトのAPPID
    • パラメーター2：data=JSONデータ。UTF-8エンコードで、urlencodeが必要です
    • パラメーター3：client=0。デフォルトは0です。1に設定すると、送信元のipを#ipフィールドとして使用します（強制的に置き換え）

  • 複数件のデータの場合：

    • パラメーター1：appid=プロジェクトのAPPID
    • パラメーター2：data_list=JSONArray形式のデータ。複数のJSONデータを含み、UTF-8エンコードで、urlencodeが必要です
    • パラメーター3：client=0。デフォルトは0です。1に設定すると、送信元のipを#ipフィールドとして使用します（強制的に置き換え）

注意 : 言語によってはライブラリがurlencodeを自動で行う場合があり、その場合は再度urlencodeする必要はありません。例えば、Python3のrequestsライブラリ、postmanでのリクエストテストなどです

以下では、curlでRESTful APIを呼び出す方法を示します。次のデータが元データです

{
  "#account_id": "testing",
  "#time": "2019-01-01 10:00:00.000",
  "#type": "track",
  "#event_name": "testing",
  "properties": {
    "test": "test"
  }
}

上記のデータは、まずurlencodeする必要があります

%7b%22%23account_id%22%3a%22testing%22%2c%22%23time%22%3a%222019-01-01+10%3a00%3a00.000%22%2c%22%23type%22%3a%22track%22%2c%22%23event_name%22%3a%22testing%22%2c%22properties%22%3a%7b%22test%22%3a%22test%22%7d%7d

パラメーターを追加して、データを送信します

curl "http://receiver:9080/sync_data" --data "appid=test-sdk-appid&data=%7b%22%23account_id%22%3a%22testing%22%2c%22%23time%22%3a%222019-01-01+10%3a00%3a00.000%22%2c%22%23type%22%3a%22track%22%2c%22%23event_name%22%3a%22testing%22%2c%22properties%22%3a%7b%22test%22%3a%22test%22%7d%7d"

2.1.2 レスポンスパラメーター​

レスポンスパラメーターとしてcode: 0を受け取った場合は、データ転送に成功したことを表します

2.1.3 Debugモード​

アップロードパラメーターにdebugパラメーターを追加できます（つまり、アップロードパラメーターはappid、data\data_list、debugの3つになります）。省略可能で、デフォルトはオフです

Debugモードは少量のテストデータをアップロードする場合にのみオンにしてください。本番環境ではDebugモードをオンにしないでください

debug=1の場合、レスポンスには詳細なエラー原因が表示されます。例：

{"code":-1,"msg":"#time字段格式不对,需传递[yyyy-MM-dd HH:mm:ss]或者[yyyy-MM-dd HH:mm:ss.SSS]格式"}

2.2 データ受信インターフェース（送信方式はraw）​

クラウドサービスをご利用の場合は、次のURLを入力してください：

https://global-receiver-ta.thinkingdata.cn/sync_json

プライベートデプロイ版をご利用の場合は、次のURLを入力してください:

http://データ収集アドレス/sync_json

2.2.1 受信パラメーター（requestBodyに記述）​

  • 1件のjsonデータの場合:
{
  "appid": "debug-appid",
  "debug": 0,
  "data": {
    "#type": "track",
    "#event_name": "test",
    "#time": "2019-11-15 11:35:53.648",
    "properties": { "a": "123", "b": 2 },
    "#distinct_id": "1111"
  }
}
  • 複数件のデータの場合：
[
    {
        "appid": "debug-appid",
        "data": {
          "#type": "track",
          "#event_name": "test",
          "#time": "2019-11-15 11:35:53.648",
          "properties": { "a": "123", "b": 2 },
          "#distinct_id": "1111"
        }
    },
    {
        "appid": "debug-appid",
        "data": {
          "#type": "track",
          "#event_name": "test",
          "#time": "2019-11-15 11:35:53.648",
          "properties": { "a": "123", "b": 2 },
          "#distinct_id": "1111"
        }
    }
]

2.2.2 レスポンスパラメーター：​

レスポンスパラメーターとしてcode: 0を受け取った場合は、データ転送に成功したことを表します

2.2.3 Debugモード​

アップロードパラメーターにdebugパラメーターを追加できます（つまり、jsonにdebugパラメーターを追加します。現在、debugに対応しているのは1件ずつのデータのアップロードのみです）。省略可能で、デフォルトはオフです

Debugモードは少量のテストデータをアップロードする場合にのみオンにしてください。本番環境ではDebugモードをオンにしないでください

debug=1の場合、レスポンスには詳細なエラー原因が表示されます。例：

{
  "code": -1,
  "msg": "#time字段格式不对,需传递[yyyy-MM-dd HH:mm:ss]或者[yyyy-MM-dd HH:mm:ss.SSS]格式"
}

2.2.4 データ圧縮​

RequestHeaderにcompressフィールドを追加すると、圧縮したデータをアップロードできます。例えばcompress=gzipを渡すと、サーバー側はgzipでデータを解凍します。現在対応している圧縮方式はgzipとsnappyで、デフォルトは圧縮なしです。

2.2.5 送信元ipの取得​

RequestHeaderにclient=1を追加すると、サーバー側は送信元のipを#ipフィールドとして使用します（強制的に置き換え）。デフォルト値は0で、送信元のipによる置き換えは行いません

3. よくある質問​

データルールのよくある質問を参照して、データ形式の問題によるデータ転送の異常を調査してください。

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