レコードの一括書き込み
一括書き込み操作は、StratusのバケットにアップロードされたCSVファイルから数千のレコードを取得し、Data Store内の特定のテーブルに挿入します。このデータ集約型の操作は、単一のAPI実行で実行できます。
一括書き込み操作が正常に実行された後、ジョブ実行の詳細を含むCSVレポートファイルがダウンロードURLに生成されます。
Catalystは一括書き込み操作用に3つのAPIをサポートしています：一括書き込み作成API、ジョブ実行のステータスを手動で確認するための一括書き込みステータス確認API、および結果をダウンロードするための一括書き込み結果ダウンロードAPIです。コールバックURLを設定して、ジョブステータスのレスポンスを自動的に送信することもできます。
一括書き込みジョブの作成
説明
このAPIは、Stratusに保存されたCSVファイルからレコードを取得し、入力JSONで指定した条件に基づいてData Store内のテーブルにエクスポートする一括書き込み操作をトリガーします。CSVファイルはStratusでのオブジェクトURLを使用して参照され、テーブルは一意のテーブルIDまたはテーブル名を使用して参照されます。
注意:
-
この操作の実行を開始する前に、必要なCSVファイルをStratusにアップロードしていることを確認してください。
-
CSVファイルの最初の行はヘッダー行（カラム名がヘッダー行として存在する必要があります）でなければなりません。
-
CSVファイルにはCSVファイル標準に準拠した形式のデータが含まれている必要があります。ファイルが標準形式でない場合、テーブルに書き込まれるデータが破損する可能性があります。
-
このAPIを使用して、開発環境では各プロジェクトのテーブルごとに5,000件のレコードを挿入できます。CSVファイルにそれ以上のレコードが含まれている場合、最初の5,000件のレコードがテーブルに書き込まれます。その他のレコードは開発環境ではスキップされます。本番環境ではテーブルへの挿入に制限はありません。ただし、一括書き込みAPIは本番環境でも1回のAPIコールでCSVファイルから最大100,000件のレコードを挿入できます。それ以上のレコードを書き込む必要がある場合、それに応じて複数の一括書き込みAPIリクエストを送信し、100,000件のレコードごとにバッチで実行できます。
このAPIを使用して実行できる操作は3つあります：
- Insert: CSVファイルからテーブルにデータの新しい行を挿入します
- Update: テーブル内の既存のデータ行を更新します。レコードはテーブル内の一意のカラム、またはData Storeで生成されたROWIDを使用して識別されます。
- Upsert: 挿入と更新の両方の操作を同時に実行できます。レコードが既に存在する場合、行は更新されます。レコードが存在しない場合、そのデータの新しい行が挿入されます。
リクエスト詳細
リクエストURL
{api-domain}/baas/v1/project/{projectId}/bulk/write
リクエストヘッダー
Authorization: Zoho-oauthtoken {oauth_token}
任意のヘッダー
CATALYST-ORG: {org_id}
Environment: Development
スコープ
ZohoCatalyst.tables.bulk.CREATE
リクエストJSONプロパティ
一括書き込みAPIリクエストの入力はJSON形式で送信する必要があります。リクエストパラメーターを以下に説明します。
APIを使用して実行する操作を指定します。
許可される値: insert、update、upsert
デフォルトの操作: insert
レコードの識別に使用する一意のカラム。
例えば、「EmployeeID」という一意のカラムをfind_by値として指定すると、CatalystはData Storeテーブル内のレコードをEmployeeID値を使用して検索します。更新操作の場合、CatalystはCSVファイルのEmployeeIDに一致する行を更新します。アップサート操作の場合、Catalystは既存の行を更新し、EmployeeID値が一致するレコードがない場合は新しい行を挿入します。
Update: Data Storeで設定された一意の値を持つカラム、またはCatalystがレコードに対して生成したROWIDを指定できます。
Upsert: Data Storeで設定された一意の値を持つカラムのみ指定できます。ROWIDをfind_by値として指定することはできません。これは、アップサートでは一致するものが見つからない場合に新しい行を挿入するため、Data Storeに存在しない行のROWID値は利用できないためです。
Insert: 挿入操作にfind_byカラムを指定した場合、CSVファイルのカラム値に一致するレコードはスキップされ、Data Storeテーブルに挿入されません。これは、挿入では特定のレコードが既に存在する場合に更新できないためです。
他のテーブルで主キーとなっているカラムの外部キーマッピング。CSVファイルからインポートされたカラムを外部キーとして設定する必要がある場合に指定します。
外部キーは以下の形式でマッピングする必要があります：
{
“local_column” : “local_column_name_1”,
“reference_column” : “reference_column_name_1”
}
ここでlocal_columnは一括書き込み操作が処理されるテーブル内のカラム名、reference_columnはそのカラムが主キーであるテーブル内のカラム名です。
サンプルリクエストコードを参照してください。
ジョブステータスの自動JSONレスポンスが送信されるコールバックURLのプロパティを定義するセクション。
ジョブステータスが変更されるたびに、HTTP POSTメソッドを使用して自動レスポンスが送信されるURL。ジョブ詳細に関する情報はJSONレスポンスの本文に含まれます。
コールバックURLを設定しない場合、必要な時に一括書き込みステータス確認APIを使用してジョブ処理のステータスを手動で確認する必要があります。
コールバックURLへのJSONレスポンスで渡す必要があるヘッダー
ヘッダーは以下の形式で指定する必要があります：
{
"{header_name_1}" : “{header_value_1}”,
"{header_name_2}" : “{header_value_2}”
}
以降同様。サンプルリクエストコードを参照してください。
コールバックURLに付加するパラメーター
パラメーターは以下の形式で指定する必要があります：
{
"{param_name_1}" : “{param_value_1}”,
"{param_name_2}" : “{param_value_2}”
}
以降同様。サンプルリクエストコードを参照してください。
レスポンス詳細
ジョブ処理には3つの状態があり、それぞれ異なるレスポンスが生成されます：
-
処理中: APIを実行すると、Catalystはジョブの実行が処理中であることを示すレスポンスを即座に自動的に送信します。リクエストでコールバックURLを設定した場合、レスポンスは定義した形式でそのURLにも送信されます。
レスポンスにはjob_id parameterが含まれ、コールバックURLを設定していない場合に、後続のレスポンスのジョブ実行ステータスの確認に使用できます。
-
成功: 成功状態のレスポンスには、ジョブ実行の詳細を含むCSVレポートファイルをダウンロードできるダウンロードURLが含まれます。書き込みがスキップされたすべてのレコードとその理由がリストされます。コールバックURLを設定していない場合、このレスポンスはCatalystから自動的に送信されません。
-
失敗: 失敗状態のレスポンスには、発生したエラーの説明と詳細が含まれます。コールバックURLを設定していない場合、このレスポンスはCatalystから自動的に送信されません。
curl -X POST https://api.catalyst.zoho.com/baas/v1/project/4000000006007/bulk/write
-H “Authorization: Zoho-oauthtoken 1000.91016.2f*57”
-d ‘{
“table_identifier”: “3376000000165511”,
“operation”: “insert”,
“object_details”: {
“bucket_name”: “zylker-emp”,
“object_key”: “employees/emp_rec.csv”,
“version_id”: “3546576879809”
},
“callback”: {
“url”: “https://hr.zylker.com/ja/EmpRecords/_callback.php",
“headers”: {
“src”: “ZCatalyst”,
“operation”: “bulkwriteAPI”
},
“params”: {
“project_name”: “EmployeeDatabase”
}
},
“find_by”: “EmpID”,
“fk_mapping”: [
{
“local_column”: “EmployeeID”,
“reference_column”: “EmpID”
},
{
“local_column”: “DepartmentID”,
“reference_column”: “DeptID”
}
]
}’
{
"status": "success",
"data": {
"job_id": 2000000110044,
"status": "In-Progress",
"operation": "insert",
"project_details": {
"project_name": "ShipmentTracking",
"id": 4000000006007
},
"query": [
{
"table_id": 3376000000165511,
"object_details": {
"bucket_name": "zylker-emp",
"object_key" : "employees/emp_rec.csv",
"version_id":"3546576879809"
}
}
],
"callback": {
"url": "https://hr.zylker.com/ja/EmpRecords/_callback.php",
"headers": {
"src": "ZCatalyst",
"operation": "bulkwriteAPI"
},
"params": {
"project_name": "EmployeeDatabase"
}
},
"created_by": {
"zuid": 3000000006111,
"is_confirmed": true,
"email_id": "emma@zylker.com",
"first_name": "Amelia",
"last_name": "Burrows",
"user_id": 671930409
},
"created_time": "Oct 05, 2020 07:33 PM"
}
}
{
"status": "success",
"data": {
"job_id": 2000000110044,
"status": "Completed",
"operation": "insert",
"project_details": {
"project_name": "ShipmentTracking",
"id": 4000000006007
},
"query": [
{
"table_id": 3376000000165511,
"details": {
"object_url" : "https://zylker-emp-development.zohostratus.com/employees/emp_rec.csv"
}
}
],
"callback": {
"url": "https://hr.zylker.com/ja/EmpRecords/_callback.php",
"headers": {
"src": "ZCatalyst",
"operation": "bulkwriteAPI"
},
"params": {
"project_name": "EmployeeDatabase"
}
},
"created_by": {
"zuid": 3000000006111,
"is_confirmed": true,
"email_id": "emma@zylker.com",
"first_name": "Amelia",
"last_name": "Burrows",
"user_id": 671930409
},
"created_time": "Oct 05, 2020 07:25 PM",
"results": {
"download_url": "https://api.catalyst.zoho.com/baas/v1/bulk/write/2000000110013/download",
"description": "Bulk WRITE job completed. ",
"details": [
{
"table_id": 3376000000165511,
"records_processed": 176
}
]
}
}
}
{
"status": "success",
"data": {
"job_id": 2000000110044,
"status": "Failed",
"operation": "insert",
"project_details": {
"project_name": "ShipmentTracking",
"id": 4000000006007
},
"query": [
{
"table_id": 3376000000165511,
"details": {
"object_url" : "https://zylker-emp-development.zohostratus.com/employees/emp_rec.csv"
}
}
],
"callback": {
"url": "https://hr.zylker.com/ja/EmpRecords/_callback.php",
"headers": {
"src": "ZCatalyst",
"operation": "bulkwriteAPI"
},
"params": {
"project_name": "EmployeeDatabase"
}
}
"created_by": {
"zuid": 3000000006111,
"is_confirmed": true,
"email_id": "emma@zylker.com",
"first_name": "Amelia",
"last_name": "Burrows",
"user_id": 671930409
},
"created_time": "Oct 05, 2020 07:25 PM",
"results": {
"description": "The reference_column 'DeptID' in fk_mapping of table 3376000000165511 is not a unique column",
"details": [ ]
}
}
}
Yes
No
Thank you for your feedback!
Send your feedback to us