# Restful API 利用ガイド

このガイドは、データインポート API を紹介します。データインポート API を使用すれば、インポートツールや SDK に頼らず、HTTP の POST メソッドを使用して ThinkingAnalytics プラットフォームに直接にデータをインポートすることができます。

インポートを開始する前に、データルールを参照し、TA のデータ形式とデータルールを理解したうえ、このガイドに沿ってインポートを行います。

POST メソッドによってアップロードされるデータは、TA のデータルールに準拠します。

# 1、データ形式の変換

データをアップロードする前に、まずデータの形式を TA のデータ形式に変換する必要があります。TA の各データは 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 型のデータの準備ができたら、データをアップロードすることができるようになります。TA プラットフォームは HTTP 標準の POST メソッドの呼び出し要求をサポートしています。すべてのインターフェイスのデータの文字コードは UTF-8 を使用します。具体的な呼び出し方法は次のとおりです

# 2.1 データ受信インタフェース（コミット方式は form-data）

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

http://ta-receiver.thinkingdata.io/sync_data

オンプレミスサービスを使用している場合は、次の URL を入力してください。

http://数据采集地址/sync_data

# 2.1.1 受信パラメーター（requestBody に書かれている）

json データの場合:
- パラメータ 1: appid=プロジェクトの APPID
- パラメータ 2: data=JSON データ、UTF-8 エンコード、urlencode エンコードが必要
複数のデータの場合:
- パラメータ 1: appid=プロジェクトの APPID
- パラメータ 2: data_list=JSONArray 形式のデータ、複数の JSON データ、UTF-8 エンコード、urlencode エンコードが必要

**注意:**異なる言語のライブラリは 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 パラメーターを追加することができます。(つまり、3 つのアップロードパラメータ、appid、data\data_list、debug がある) 追加は任意でデフォルトはオフです。

少量のテストデータをアップロードするときにのみ 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 を入力してください:

http://ta-receiver.thinkingdata.io/sync_json

オンプレミスサービスを使用している場合は、次の URL を入力してください：

http://数据采集地址/sync_json

# 2.2.1 受信パラメーター（requestBody に書かれている）

json データの場合:

{
  "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"
    },
    {
      "#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 をオンにします。本番環境では Debug をオンにしないでください。

debug=1 の場合、戻り値はエラーの詳細な原因が表示されます。

{
  "code": -1,
  "msg": "#timeフィールドのフォーマットが間違っている.[yyyy-MM-dd HH:mm:ss]または[yyyy-MM-dd HH:mm:ss.SSS]が必要"
}

# 3、よくある質問

データルールを参照して、データフォーマットの問題によるデータアップロードの異常を確認してください。