Restful API 利用ガイド

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

インポート開始前に、データルールを参照し、TEのデータ形式とデータルールを理解した上で、当ガイドの案内に沿ってインポートを行ってください。

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

データ形式の変換

データをアップロードする前に、データの送信フォーマットを指定の形式へ変換する必要があります。TEの各データは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
  }
}

具体的なデータ形式のルールは、データルールをご参照ください。

データアップロード

JSON型のデータの準備ができましたら、データのアップロードが可能な状態となります。TEシステムはHTTP標準のPOSTメソッドの呼び出し要求をサポートしています。すべてのインターフェイスのデータの文字コードはUTF-8を使用します。具体的な呼び出し方法は次のとおりです

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

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

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

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

http://データ受信URL/sync_data

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

• jsonデータの場合:
  • パラメータ1: appid=プロジェクトのAPPID
  • パラメータ2: data=JSONデータ、UTF-8エンコード、urlencodeエンコードが必要
  • パラメータ3: client=0、デフォルトは０、1を設定する際にデータ送信側ipを#ipを取得（強制書き替え）
• 複数のデータの場合:
  • パラメータ1: appid=プロジェクトのAPPID
  • パラメータ2: data_list=JSONArray形式のデータ、複数のJSONデータ、UTF-8エンコード、urlencodeエンコードが必要
  • パラメータ3: client=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パラメーターを追加することができます。(つまり、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://データ受信URL/sync_json

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

• 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",
        "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",
        "debug": 0,
        "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をオンにします。本番環境では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=gzip、サーバ側はgzipを使ってデータを解凍します。現在サポート圧縮方法：gzip、lzo、lz4とsnappy。デフォルトでは圧縮しません。

2.2.5 送信側ipを取得

RequestHeaderにclient=1を追加し、サーバ側は送信ipを#ipフィールドに記入（強制書き替え）。デフォルトは0となります。

よくある質問

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