--- title: "一括書き込みジョブの作成" url: https://docs.catalyst.zoho.com/ja/api/code-reference/cloud-scale/data-store/bulk-write-rows/create-bulk-write-job/ description: "このAPIは、Stratus内のCSVファイルからData Store内のテーブルにレコードを書き込む一括書き込み操作をトリガーします。" last_updated: 2026-02-23T12:39:41Z service: Cloud Scale type: api --- # レコードの一括書き込み 一括書き込み操作は、[Stratus](https://docs.catalyst.zoho.com/ja/cloud-scale/help/stratus/introduction)のバケットにアップロードされたCSVファイルから数千のレコードを取得し、[Data Store](https://docs.catalyst.zoho.com/ja/cloud-scale/help/data-store/introduction)内の特定のテーブルに挿入します。このデータ集約型の操作は、単一のAPI実行で実行できます。 一括書き込み操作が正常に実行された後、ジョブ実行の詳細を含むCSVレポートファイルがダウンロードURLに生成されます。 Catalystは一括書き込み操作用に3つのAPIをサポートしています：一括書き込み作成API、ジョブ実行のステータスを手動で確認するための[一括書き込みステータス確認API](https://docs.catalyst.zoho.com/ja/api/code-reference/cloud-scale/data-store/bulk-write-rows/create-bulk-write-job/#CheckBulkWriteStatus)、および結果をダウンロードするための[一括書き込み結果ダウンロードAPI](https://docs.catalyst.zoho.com/ja/api/code-reference/cloud-scale/data-store/bulk-write-rows/create-bulk-write-job/#DownloadBulkWriteResult)です。コールバックURLを設定して、ジョブステータスのレスポンスを自動的に送信することもできます。 > **注意:** Catalyst CLIを使用して一括書き込み操作を実行することもできます。[Data Storeインポート・エクスポートCLIドキュメント](https://docs.catalyst.zoho.com/ja/cli/v1/data-store-import-and-export/introduction/)を参照してください。 # 一括書き込みジョブの作成 ### 説明 このAPIは、Stratusに保存されたCSVファイルからレコードを取得し、入力JSONで指定した条件に基づいてData Store内のテーブルにエクスポートする一括書き込み操作をトリガーします。CSVファイルはStratusでの[オブジェクトURL](https://docs.catalyst.zoho.com/ja/cloud-scale/help/stratus/objects/introduction/#object-url)を使用して参照され、テーブルは一意のテーブルIDまたはテーブル名を使用して参照されます。 > **注意:** * この操作の実行を開始する前に、必要なCSVファイルをStratusにアップロードしていることを確認してください。 * CSVファイルの最初の行はヘッダー行（カラム名がヘッダー行として存在する必要があります）でなければなりません。 * CSVファイルにはCSVファイル標準に準拠した形式のデータが含まれている必要があります。ファイルが標準形式でない場合、テーブルに書き込まれるデータが破損する可能性があります。 * このAPIを使用して、[開発環境](https://docs.catalyst.zoho.com/ja/deployment-and-billing/environments/introduction)では各プロジェクトのテーブルごとに5,000件のレコードを挿入できます。CSVファイルにそれ以上のレコードが含まれている場合、最初の5,000件のレコードがテーブルに書き込まれます。その他のレコードは開発環境ではスキップされます。本番環境ではテーブルへの挿入に制限はありません。ただし、一括書き込みAPIは本番環境でも1回のAPIコールでCSVファイルから最大100,000件のレコードを挿入できます。それ以上のレコードを書き込む必要がある場合、それに応じて複数の一括書き込みAPIリクエストを送信し、100,000件のレコードごとにバッチで実行できます。 このAPIを使用して実行できる操作は3つあります： * **Insert:** CSVファイルからテーブルにデータの新しい行を挿入します * **Update:** テーブル内の既存のデータ行を更新します。レコードはテーブル内の一意のカラム、またはData Storeで生成された[ROWID](https://docs.catalyst.zoho.com/ja/cloud-scale/help/data-store/records/)を使用して識別されます。 * **Upsert:** 挿入と更新の両方の操作を同時に実行できます。レコードが既に存在する場合、行は更新されます。レコードが存在しない場合、そのデータの新しい行が挿入されます。 ### リクエスト詳細 #### リクエストURL `POST` {api-domain}/baas/v1/project/{projectId}/bulk/write - **api-domain** (URL): Catalyst APIにアクセスするためのDC固有のドメイン - **project_id** (Numerical): プロジェクトの[一意のID](https://docs.catalyst.zoho.com/ja/getting-started/set-up-a-catalyst-project/general-settings/) #### リクエストヘッダー **Authorization:** Zoho-oauthtoken {oauth_token} **任意のヘッダー** **CATALYST-ORG:** {org_id} **Environment:** Development #### スコープ ZohoCatalyst.tables.bulk.CREATE #### リクエストJSONプロパティ 一括書き込みAPIリクエストの入力はJSON形式で送信する必要があります。リクエストパラメーターを以下に説明します。 - **table_identifier** (string, mandatory): テーブルの[一意のID](https://docs.catalyst.zoho.com/ja/cloud-scale/help/data-store/tables/#create-a-new-table)またはテーブル名。テーブルIDはData Storeから、またはコンソールでテーブルを開いた際のURLから取得できます。 - **operation** (string, optional): APIを使用して実行する操作を指定します。 許可される値: `insert`、`update`、`upsert` デフォルトの操作: `insert` - **object_details** (JSON, mandatory): [bucket_name](https://docs.catalyst.zoho.com/ja/cloud-scale/help/stratus/buckets/name-bucket/#ideal-practices-to-name-a-bucket)、object_key（オブジェクトの[パス](https://docs.catalyst.zoho.com/ja/cloud-scale/help/stratus/objects/introduction/#path)または[オブジェクトURL](https://docs.catalyst.zoho.com/ja/cloud-scale/help/stratus/objects/introduction/#object-url)）、および[version_id](https://docs.catalyst.zoho.com/ja/cloud-scale/help/stratus/stratus-config/general-settings/#versioning)（バージョニングが有効な場合）を含みます。 - **find_by** (string, mandatory (update, upsert), optional (insert)): レコードの識別に使用する一意のカラム。 例えば、「EmployeeID」という一意のカラムを`find_by`値として指定すると、CatalystはData Storeテーブル内のレコードをEmployeeID値を使用して検索します。更新操作の場合、CatalystはCSVファイルのEmployeeIDに一致する行を更新します。アップサート操作の場合、Catalystは既存の行を更新し、EmployeeID値が一致するレコードがない場合は新しい行を挿入します。 Update: Data Storeで設定された一意の値を持つカラム、またはCatalystがレコードに対して生成した[ROWID](https://docs.catalyst.zoho.com/ja/cloud-scale/help/data-store/records/)を指定できます。 Upsert: Data Storeで設定された一意の値を持つカラムのみ指定できます。ROWIDを`find_by`値として指定することはできません。これは、アップサートでは一致するものが見つからない場合に新しい行を挿入するため、Data Storeに存在しない行のROWID値は利用できないためです。 Insert: 挿入操作に`find_by`カラムを指定した場合、CSVファイルのカラム値に一致するレコードはスキップされ、Data Storeテーブルに挿入されません。これは、挿入では特定のレコードが既に存在する場合に更新できないためです。 - **fk_mapping** (json, optional): 他のテーブルで主キーとなっているカラムの外部キーマッピング。CSVファイルからインポートされたカラムを外部キーとして設定する必要がある場合に指定します。 外部キーは以下の形式でマッピングする必要があります： *{* *"local_column" : "local_column_name_1",* *"reference_column" : "reference_column_name_1"* *}* ここで`local_column`は一括書き込み操作が処理されるテーブル内のカラム名、`reference_column`はそのカラムが主キーであるテーブル内のカラム名です。 サンプルリクエストコードを参照してください。 - **callback** (json, optional): ジョブステータスの自動JSONレスポンスが送信されるコールバックURLのプロパティを定義するセクション。 - - **url** (string, mandatory (if specifying callback)): ジョブステータスが変更されるたびに、HTTP POSTメソッドを使用して自動レスポンスが送信されるURL。ジョブ詳細に関する情報はJSONレスポンスの本文に含まれます。 コールバックURLを設定しない場合、必要な時に[一括書き込みステータス確認API](https://docs.catalyst.zoho.com/ja/api/code-reference/cloud-scale/data-store/bulk-write-rows/check-bulk-write-status/#CheckBulkWriteStatus)を使用してジョブ処理のステータスを手動で確認する必要があります。 - - **headers** (string, optional): コールバックURLへのJSONレスポンスで渡す必要があるヘッダー ヘッダーは以下の形式で指定する必要があります： *{* *"{header_name_1}" : "{header_value_1}",* *"{header_name_2}" : "{header_value_2}"* *}* 以降同様。サンプルリクエストコードを参照してください。 - - **params** (string, optional): コールバックURLに付加するパラメーター パラメーターは以下の形式で指定する必要があります： *{* *"{param_name_1}" : "{param_value_1}",* *"{param_name_2}" : "{param_value_2}"* *}* 以降同様。サンプルリクエストコードを参照してください。 ### レスポンス詳細 ジョブ処理には3つの状態があり、それぞれ異なるレスポンスが生成されます： * **処理中:** APIを実行すると、Catalystはジョブの実行が処理中であることを示すレスポンスを即座に自動的に送信します。リクエストでコールバックURLを設定した場合、レスポンスは定義した形式でそのURLにも送信されます。 レスポンスには`job_id parameter`が含まれ、コールバックURLを設定していない場合に、後続のレスポンスの[ジョブ実行ステータスの確認](https://docs.catalyst.zoho.com/ja/api/code-reference/cloud-scale/data-store/bulk-write-rows/create-bulk-write-job/#CheckBulkWriteStatus)に使用できます。 * **成功:** 成功状態のレスポンスには、ジョブ実行の詳細を含むCSVレポートファイルを[ダウンロード](https://docs.catalyst.zoho.com/ja/api/code-reference/cloud-scale/data-store/bulk-write-rows/create-bulk-write-job/#DownloadBulkReadResult)できるダウンロードURLが含まれます。書き込みがスキップされたすべてのレコードとその理由がリストされます。コールバックURLを設定していない場合、このレスポンスはCatalystから自動的に送信されません。 * **失敗:** 失敗状態のレスポンスには、発生したエラーの説明と詳細が含まれます。コールバックURLを設定していない場合、このレスポンスはCatalystから自動的に送信されません。 **リクエスト例** ```bash curl -X POST https://api.catalyst.zoho.com/baas/v1/project/4000000006007/bulk/write \ -H "Authorization: Zoho-oauthtoken 1000.910***************************16.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" } ] }' ``` **レスポンス例：ジョブ処理中** ```json { "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" } } ``` **レスポンス例：ジョブ成功** ```json { "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 } ] } } } ``` **レスポンス例：ジョブ失敗** ```json { "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": [ ] } } } ```