SPIRAL ver.2 APIでは、複数のレコードを操作する方法として「bulk」と「batch」の2つの方式が提供されています。これらの違いを理解することで、適切なAPIを選択し、効率的なデータ処理を実現できます。
bulkとbatchの基本的な違い
bulk API: 同期処理で即時実行される一括操作
batch API: 非同期処理で依頼を作成し、バックグラウンドで実行される一括操作
batch API: 非同期処理で依頼を作成し、バックグラウンドで実行される一括操作
両方のAPIは複数レコードを一度に操作するという目的は同じですが、処理方法と適用ケースが異なります。
処理方式の違い
| 特性 | bulk API | batch API |
|---|---|---|
| 処理方式 | 同期処理（リクエスト中に完了） | 非同期処理（バックグラウンドで実行） |
| レスポンス | 処理結果を即時返却 | 依頼IDを即時返却、結果は別途取得 |
| 処理件数 | 最大1,000件 | 大量データ（ファイルサイズ上限あり） |
| データ形式 | JSONオブジェクト | CSVまたはTSVファイル |
| エラー処理 | 即時エラー通知 | ステータス確認で結果取得 |
bulk APIの特徴と使用例
主な特徴
- 最大1,000件のレコードを一括で操作可能
- JSONフォーマットでデータを送信
- リクエスト完了時に処理結果が即時返却される
- パスワード型フィールド、ファイル型フィールド、ユーザフィールドは対象外
- 処理が完了するまでクライアントは待機状態
APIリクエスト例
コピー{
"records": [
{
"(textField)": "text",
"(emailField)": "spiral@example.com",
"(phoneField)": "+81 80-1111-2222",
"(integerField)": "100",
"(dateField)": "2020-04-30"
},
{
"(textField)": "別のテキスト",
"(emailField)": "info@example.com",
"(phoneField)": "+81 90-3333-4444",
"(integerField)": "200",
"(dateField)": "2020-05-15"
}
]
}
レスポンス例
コピー{
"ids": ["1", "2"]
}
適したユースケース
- 少量〜中量のデータ処理（数十〜数百件）
- 即時処理結果が必要な場合
- プログラムからの自動処理
- APIを直接呼び出すクライアントアプリケーション
batch APIの特徴と使用例
主な特徴
- 大量データの一括処理に対応（ファイルサイズ上限あり）
- CSVまたはTSVファイルでデータを送信（multipart/form-data形式）
- 非同期処理で依頼IDが即時返却され、処理はバックグラウンドで実行
- 処理状況や結果は別APIで確認可能
- エラー発生時の処理方法を指定可能（rollbackまたはignore）
処理フロー
- CSVまたはTSVファイルを準備（1行目にフィールドの識別名）
- 一括処理依頼を作成（multipart/form-dataでファイルをアップロード）
- 依頼IDを受け取る
- 依頼状況確認APIで処理状況を確認
- 処理完了後、結果を確認
CSVファイル例
コピーname,email,phone,gender,age,birthday,mailGroup,registration,lastAccess 山田 太郎,taro.yamada@example.com,+81 90-1234-5678,1,30,01-01,"1,2",2020-01-01,2020-01-01T00:00:00Z 田中 次郎,jiro.tanaka@example.com,090-1234-5678,1,25,1-1,3,2020-1-1,2020-01-01T12:00:00+09:00 鈴木 花子,hanako.suzuki@example.com,9012345678,2,20,12-20,,2020-12-20,2020-12-30T12:00:00Z
レスポンス例（依頼作成時）
コピー{
"id": "100",
"operatedFrom": "ui",
"status": "waiting",
"errors": [],
"onError": "rollback",
"fileName": "content.csv",
"fileSize": 104857600,
"numberRows": 100,
"numberRowsSuccessful": 0,
"numberRowsFailed": 0,
"rowsFailed": "",
"createdAt": "2019-08-24T14:15:22Z",
"finishedAt": null
}
適したユースケース
- 大量データの処理（数百〜数万件）
- 処理に時間がかかる可能性がある場合
- バックグラウンド処理が望ましい場合
- CSVやTSVからのデータインポート
- ユーザーインターフェースからの操作
どちらを選ぶべきか？
bulk APIを選ぶ場合
以下の条件に当てはまる場合は、bulk APIが適しています：
- 処理するレコード数が1,000件以下
- 処理結果をすぐに取得したい
- JSONフォーマットでデータを扱いたい
- プログラムから直接APIを呼び出す
- シンプルな実装で済ませたい
batch APIを選ぶ場合
以下の条件に当てはまる場合は、batch APIが適しています：
- 処理するレコード数が多い（1,000件超）
- 処理に時間がかかっても問題ない
- CSVやTSVファイルからデータをインポートしたい
- ユーザーインターフェースからの操作
- エラー発生時の処理方法を細かく制御したい
注意点
共通の制限事項：
- パスワード型フィールド、ファイル型フィールド、ユーザフィールドは両方のAPIで対象外
- 適切なアプリロールと権限が必要
- ファイルは UTF-8 エンコードが必須
- ファイルサイズは100MB以下
大量データを処理する場合は、batch APIを使用することで、クライアント側の待機時間を短縮し、サーバー負荷を分散させることができます。一方、即時処理が必要な少量データの場合は、bulk APIがシンプルで効率的です。
APIの選択は、データ量、処理タイミング、実装の複雑さなどを考慮して行いましょう。適切なAPIを選択することで、効率的なデータ処理が可能になります。
