# Restful API 利用ガイド
このガイドは、データインポートAPIを紹介します。データインポートAPIを使用すれば、インポートツールやSDKに頼らず、HTTPのPOSTメソッドを使用してThinkingAnalyticsプラットフォームに直接にデータをインポートすることができます。
インポートを開始する前に、データルールを参照し、TEのデータ形式とデータルールを理解した上で、このガイドに沿ってインポートを行います。
POSTメソッドによってアップロードされるデータは、TEのデータルールに準拠します。
# データ形式の変換
データをアップロードする前に、まずデータの形式を 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となります。
# くある質問
データルールを参照して、データフォーマットの問題によるデータアップロードの異常を確認してください。