# Data Ingestion API を使用したテーブルレコードのインポート Treasure Data は、TD データベース内の既存のテーブルにプログラムで行をインポートできる ingest API を提供しています。Data Ingestion API で使用できるエンドポイントは以下のとおりです： * US リージョン: [https://us01.records.in.treasuredata.com](https://us01.records.in.treasuredata.com) * EU01 リージョン: [https://eu01.records.in.treasuredata.com](https://eu01.records.in.treasuredata.com) * Tokyo リージョン: [https://ap01.records.in.treasuredata.com](https://ap01.records.in.treasuredata.com) * Korea リージョン: [https://ap02.records.in.treasuredata.com](https://ap02.records.in.treasuredata.com) * AP03 リージョン: [https://ap03.records.in.treasuredata.com](https://ap03.records.in.treasuredata.com) お使いのリージョンに対応するエンドポイントを選択してください。 ingest API 呼び出しを行うには、以下のデータが必要です： * レコードを取り込みたいテーブルを含むデータベースの名前 * テーブルの名前 * インポートしたい列名と値を含むリクエストオブジェクト。リクエストオブジェクト内の情報は JSON のキーと値のペアとして指定され、リクエストオブジェクト内の各エントリはテーブルの新しい行として入力されます。図 1 は単一レコードを取り込むための形式を示し、図 2 は単一のリクエストで複数のレコードを取り込むための形式を示しています。 リクエストオブジェクトを作成する際は、以下の API の動作に注意してください： * 取り込まれるレコードは現在のテーブルスキーマと一致する必要はありません。新しい列は取り込み時にテーブルスキーマに追加されます。 * time 列を指定する場合、値は UTC 秒単位（ミリ秒ではない）の Unix タイムスタンプとしてフォーマットする必要があります。time 列を指定しない場合、システムは現在の時刻を使用します。 * API は各レコードに UUID を割り当て、これは ingest パイプラインで使用されます。この UUID はレスポンスオブジェクトに含まれますが、テーブルには永続化されません。そのため、"uuid" という名前の列を指定することは避けてください。API は "uuid" 列の値が構文的に有効であれば指定できますが、レスポンスで返されるものの、その値はテーブルに保存されません。 # 制限事項 ストリーミング ingest API バッチエンドポイントパス records.in には以下の制限があります： * 1〜500 レコード * 最大レコードサイズ 1MB * 最大バッチサイズ 5MB この制限を超えると、API は 422 または 413 エラーを返します。 この制限は最新の JS SDK とモバイル SDK にも適用されます。ただし、iOS と Android SDK はこの制限を管理するため、これらの SDK を使用する際にこのエラーに遭遇することはないはずです。 # Ingestion API を使用した単一レコードの取り込み テーブルに単一レコードを取り込むには、図 1 に示すようなリクエストオブジェクトを作成する必要があります。さらに、以下の Content-Type ヘッダーを指定する必要があります： `application/vnd.treasuredata.v1.single+json` 以下は、wt_db データベースの simple_table という名前のテーブルに 1 つのレコードを取り込む呼び出しの例です。 ```bash $ curl -X POST 'https://us01.records.in.treasuredata.com/wt_db/simple_table' -H 'Authorization: TD1 1/123456789abcdef0123456789abcdef012345678' -H 'Content-Type: application/vnd.treasuredata.v1.single+json' -d '{ "time":1552689469, "name":"oliver", "favorite_color":"orange" }' ``` ``` {"time":1552689469,"uuid":"65509cab-8fc6-443e-a4a4-8d5b78d77a8b","favorite_color":"orange","name":"oliver"} ``` **図 1: singleRecordIngest.json のファイルリスト、単一レコードを取り込むためのリクエストオブジェクトの例** ```json { "time":1552689469, "name":"oliver", "favorite_color":"orange" } ``` # Ingestion API を使用した複数レコードの取り込み 単一の API 呼び出しで複数のレコードを取り込む場合は、図 2 に示すようなリクエストオブジェクトを作成する必要があります。追加したい個々のレコードは JSON の "records" 変数に割り当てられることに注意してください。つまり、個々のレコードは次のように "records" 配列でラップされます： ![](/assets/recordsarray.7c22654e1f3c3774893f1ad64cbfa6aa9984ff7293518ac3cd41a9847e067a14.ad50cbca.png) さらに、以下の Content-Type ヘッダーを指定する必要があります： ``` application/vnd.treasuredata.v1+json ``` 以下は、wt_db データベースの simple_table という名前のテーブルに複数のレコードを取り込む呼び出しの例です。リクエストオブジェクトには、図 2 に示す multipleRecordIngest.json ファイルを使用しています。 ```bash $ curl -X POST 'https://us01.records.in.treasuredata.com/wt_db/simple_table' -H 'Authorization: TD1 1/123456789abcdef0123456789abcdef012345678' -H 'Content-Type: application/vnd.treasuredata.v1+json' -d @multipleRecordIngest.json | jq . ``` ```json { "failures": 0, "receipts": [ { "uuid": "0139dc76-9a45-4aad-9df9-eaa06c98d632", "success": true }, { "uuid": "9ee5cf77-c32e-401f-9a16-b122b9faa43f", "success": true }, { "uuid": "08602567-ac62-49f4-b63a-8c3c1080e813", "success": true } ] } ``` 以下は、複数レコードを取り込んだ後の sample_table が Treasure コンソール でどのように表示されるかの例です： ![](/assets/tdconsoletableview6.6984060300e66dd22292996836f03a959d3a816b69c690680c0586533511ba24.ad50cbca.png) **図 2: multipleRecordIngest.json のファイルリスト、単一のリクエストで複数のレコードを取り込むためのリクエストオブジェクト** ```json { "records":[ { "time":1552689544, "name":"jerry", "favorite_number":13 }, { "time":1552689644, "name":"jack", "favorite_color":"yellow" }, { "time":1552689744, "name":"jill", "customer_number":"12345" } ] } ``` # 関連タスク Data Ingestion API を使用する際に、API やその他のツールで実行できる関連タスクがいくつかあります。 ## テーブル内のレコードの表示 テーブルレコードは以下の方法で表示できます： * Treasure コンソール を使用 * Treasure API の *table/tail* エンドポイントを呼び出す * SQL クエリを発行 状況によっては、Treasure コンソール や *table/tail* エンドポイントを使用して新しく取り込まれたレコードを表示できない場合があります。テーブルレコードを表示する最も確実な方法は、SQL クエリを発行することです。 ### Treasure コンソール でテーブルレコードを表示する Treasure コンソール を使用してテーブル内のレコードを表示するには： 1. **Data Workbench > Databases** に移動します。 2. データベースのリストをスクロールするか、データベース名を検索してデータベース名を見つけ、データベースを選択します。 3. テーブルのリストをスクロールするか、テーブル名を検索してテーブル名を見つけ、テーブルを選択します。 テーブル表示は次のようになります： ![](/assets/tdconsoletableview3.59e76ee07b3ff30b31a014e0d1cf09b7cb0b0228d992fc76e494567a1312517a.ad50cbca.png) 取り込まれたレコードが Treasure コンソール に表示されるまで数分かかる場合があります。新しいレコードが表示されるまで、画面を数回更新する必要があるかもしれません。数分経っても新しく取り込まれたレコードが表示されない場合は、SQL クエリを発行してレコードを確認する必要があります。 ### *table/tail* エンドポイントを呼び出してテーブルレコードを表示する *table/tail* エンドポイントを呼び出してテーブルの内容を表示できます。以下はその呼び出しの例です： ```bash $ curl GET 'https://api.treasuredata.com/v3/table/tail/wt_db/simple_table' -H 'Authorization: TD1 1/123456789abcdef0123456789abcdef012345678' -H 'Content-Type: application/json' | jq . ``` ```json [ { "favorite_number": "256", "favorite_color": null, "name": "Alyssa", "time": 1639079413 }, { "favorite_number": "7", "favorite_color": "red", "name": "Ben", "time": 1639079413 }, { "favorite_number": null, "favorite_color": "blue", "name": "Charlie", "time": 1639079413 } ] ``` API を使用して取り込まれたレコードが表示されるまで数分かかる場合があります。新しいレコードが表示されるまで、呼び出しを数回発行する必要があるかもしれません。数分経っても新しく取り込まれたレコードが表示されない場合は、SQL クエリを発行してレコードを確認する必要があります。 ### SQL クエリを発行してテーブルレコードを表示する テーブルレコードを表示するには、以下の SQL クエリを発行できます。テーブルに多数のレコードが含まれている場合は、LIMIT 句を追加することをお勧めします。 ```sql select * from ``` #### TD Toolbelt を使用して SQL クエリを発行する 以下は、TD コマンドラインインターフェースを使用してクエリを発行する例です。（td query コマンドの詳細については [td query](/tools/cli-and-sdks/api#td-query) を参照してください） ```bash $ td query -d wt_db -T presto -w 'select * from simple_table' ``` #### Treasure API を使用して SQL クエリを発行する Treasure API を使用して SQL クエリを発行するには、2 段階のプロセスが必要です： 1. *job/issue* エンドポイントを呼び出して、クエリを発行するジョブを作成する 2. *job/result* エンドポイントを呼び出して、ジョブの結果を確認する 以下は、Treasure API でクエリを発行する例です： ```bash $ curl -X POST 'https://api.treasuredata.com/v3/job/issue/presto/wt_db?query=select+*+from+simple_table' -H 'Authorization: TD1 1/123456789abcdef0123456789abcdef012345678' | jq . ``` ```json { "job": "1408208769", "job_id": "1408208769", "database": "wt_db" } ``` ```bash # 前の呼び出しの job_id を以下の呼び出しで使用します $ curl GET 'https://api.treasuredata.com/v3/job/result/1408208769' -H 'Authorization: TD1 1/123456789abcdef0123456789abcdef012345678' ``` ``` Alyssa,256,,,1639079413 Ben,7,red,,1639079413 Charlie,,blue,,1639079413 ``` ## データベース名の取得 データベース名は、Treasure コンソール を検索またはブラウジングして確認できます。また、*database/list* エンドポイントを呼び出してデータベース名を確認することもできます。以下は、Treasure API を使用して Treasure アカウント内のすべてのデータベース名を取得する例です： ```bash $ curl GET 'https://api.treasuredata.com/v3/database/list/' -H 'Authorization: TD1 1/123456789abcdef0123456789abcdef012345678' -H 'Content-Type: application/json' | jq . | grep '"name"\:' ``` ``` "name": "01_ca_database", "name": "demo_db", . . . "name": "wt_db", "name": "wt_db_test", ``` ## テーブル名の取得 テーブル名は、Treasure コンソール を検索またはブラウジングして確認できます。また、table/list エンドポイントを呼び出してテーブル名を確認することもできます。以下は、Treasure API を使用してデータベース内のすべてのテーブルをリストする例です： ```bash $ curl GET 'https://api.treasuredata.com/v3/table/list/wt_db' -H 'Authorization: TD1 1/123456789abcdef0123456789abcdef012345678' -H 'Content-Type: application/json' | jq . | grep '\"name\"\:' ``` ``` "name": "simple_table", "name": "test_db", "name": "wt_table13", ``` ## テーブルスキーマの表示 テーブル名を取得したら、*table/show* エンドポイントを呼び出してテーブルスキーマを取得できます。以下は、Treasure API を使用してテーブルのスキーマを表示する例です。 ```bash $ curl GET 'https://api.treasuredata.com/v3/table/show/wt_db/simple_table' -H 'Authorization: TD1 1/123456789abcdef0123456789abcdef012345678' -H 'Content-Type: application/json' | jq . ``` ```json { "id": 190562750, "name": "simple_table", "estimated_storage_size": 203, "counter_updated_at": "2022-03-24T03:55:00Z", "last_log_timestamp": "2021-12-09T19:50:13Z", "delete_protected": false, "created_at": "2021-12-09 19:50:10 UTC", "updated_at": "2022-05-27 14:57:50 UTC", "type": "log", "include_v": true, "count": 3, "schema": "[[\"name\",\"string\"],[\"favorite_number\",\"long\"],[\"favorite_color\",\"string\"]]", "expire_days": null } ``` 元のテーブルにない列を含むレコードを取り込むと、テーブルスキーマは新しい列を含むように更新されます。