Data Ingestion API を使用したテーブルレコードのインポート

Treasure Data は、TD データベース内の既存のテーブルにプログラムで行をインポートできる ingest API を提供しています。Data Ingestion API で使用できるエンドポイントは以下のとおりです：

US リージョン: https://us01.records.in.treasuredata.com
EU01 リージョン: https://eu01.records.in.treasuredata.com
Tokyo リージョン: https://ap01.records.in.treasuredata.com
Korea リージョン: https://ap02.records.in.treasuredata.com
AP03 リージョン: 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 つのレコードを取り込む呼び出しの例です。

$ 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 のファイルリスト、単一レコードを取り込むためのリクエストオブジェクトの例

{
       "time":1552689469,
       "name":"oliver",
       "favorite_color":"orange"
}

Ingestion API を使用した複数レコードの取り込み

単一の API 呼び出しで複数のレコードを取り込む場合は、図 2 に示すようなリクエストオブジェクトを作成する必要があります。追加したい個々のレコードは JSON の "records" 変数に割り当てられることに注意してください。つまり、個々のレコードは次のように "records" 配列でラップされます：

さらに、以下の Content-Type ヘッダーを指定する必要があります：

application/vnd.treasuredata.v1+json

以下は、wt_db データベースの simple_table という名前のテーブルに複数のレコードを取り込む呼び出しの例です。リクエストオブジェクトには、図 2 に示す multipleRecordIngest.json ファイルを使用しています。

$ 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 .

{
  "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 コンソールでどのように表示されるかの例です：

図 2: multipleRecordIngest.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 コンソールを使用してテーブル内のレコードを表示するには：

Data Workbench > Databases に移動します。
データベースのリストをスクロールするか、データベース名を検索してデータベース名を見つけ、データベースを選択します。
テーブルのリストをスクロールするか、テーブル名を検索してテーブル名を見つけ、テーブルを選択します。

テーブル表示は次のようになります：

取り込まれたレコードが Treasure コンソールに表示されるまで数分かかる場合があります。新しいレコードが表示されるまで、画面を数回更新する必要があるかもしれません。数分経っても新しく取り込まれたレコードが表示されない場合は、SQL クエリを発行してレコードを確認する必要があります。

table/tail エンドポイントを呼び出してテーブルレコードを表示する

table/tail エンドポイントを呼び出してテーブルの内容を表示できます。以下はその呼び出しの例です：

$ curl GET 'https://api.treasuredata.com/v3/table/tail/wt_db/simple_table' -H 'Authorization: TD1 1/123456789abcdef0123456789abcdef012345678' -H 'Content-Type: application/json' | jq .

[
  {
    "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 句を追加することをお勧めします。

select * from <table_name>

TD Toolbelt を使用して SQL クエリを発行する

以下は、TD コマンドラインインターフェースを使用してクエリを発行する例です。（td query コマンドの詳細については td query を参照してください）

$ td query -d wt_db -T presto -w 'select * from simple_table'

Treasure API を使用して SQL クエリを発行する

Treasure API を使用して SQL クエリを発行するには、2 段階のプロセスが必要です：

job/issue エンドポイントを呼び出して、クエリを発行するジョブを作成する
job/result エンドポイントを呼び出して、ジョブの結果を確認する

以下は、Treasure API でクエリを発行する例です：

$ curl -X POST 'https://api.treasuredata.com/v3/job/issue/presto/wt_db?query=select+*+from+simple_table' -H 'Authorization: TD1 1/123456789abcdef0123456789abcdef012345678' | jq .

{
  "job": "1408208769",
  "job_id": "1408208769",
  "database": "wt_db"
}

# 前の呼び出しの 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 アカウント内のすべてのデータベース名を取得する例です：

$ 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 を使用してデータベース内のすべてのテーブルをリストする例です：

$ 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 を使用してテーブルのスキーマを表示する例です。

$ curl GET 'https://api.treasuredata.com/v3/table/show/wt_db/simple_table' -H 'Authorization: TD1 1/123456789abcdef0123456789abcdef012345678' -H 'Content-Type: application/json' | jq .

{
  "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
}

元のテーブルにない列を含むレコードを取り込むと、テーブルスキーマは新しい列を含むように更新されます。