--- title: "批量变更任务" doc_type: static doc_category: static doc_version: v20270301 source_url: html: 'https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/bulk-operations/bulk-change-task' md: 'https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/bulk-operations/bulk-change-task.md' --- # 批量变更任务 你可以调用 [创建一个批量变更任务](https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/bulk-operations/create-a-bulk-mutation-task.md) 接口向 SHOPLINE 提交复杂的数据变更请求。一个批量变更任务中只能使用一种 HTTP 方法，如 `POST`、`PUT`、`PATCH` 和 `DELETE`。由于该变更任务是异步任务，结果不会立刻返回。任务执行时间取决于变更的复杂度。任务执行完毕后，系统会生成一份包含变更结果的 [JSONL](https://jsonlines.org/) 格式临时文件，文件有效期为 12 小时。 变更任务提交后，你可以调用 [查询一个有效批量任务](https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/bulk-operations/get-a-valid-bulk-task.md) 接口获取批量变更任务的执行状态和结果文件 URL。通过该 URL 下载文件即可获取变更结果数据。 ------ ## 使用限制 批量变更操作有如下使用限制： - **并发限制**：批量变更任务按店铺维度串行执行。同一时刻，每个店铺只能拥有一个正在执行的批量变更任务。若当前已有任务执行中，SHOPLINE 将拒收该店铺的其他批量变更任务（无论是否来自同一应用），直至当前任务完成。 - **权限要求**：应用必须拥有 `write_bulkoperation` 和 `read_bulkoperation` 权限点。关于如何申请权限，参考 [应用授权](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/app-authorization.md)。 - **文件限制**：请求参数 `file_url` 中传入的 URL 对应的文件不能超过 10 MB。该文件须为 JSONL 格式且文件内的数据行数不能超过 10,000 行。 - **API 版本要求**：须使用 `v20220901` 或更高版本的 API 版本。 > **注意** > > 若你的应用在批量变更任务完成后未及时调用 [查询一个有效批量任务](https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/bulk-operations/get-a-valid-bulk-task.md) 接口获取变更结果，且在此期间该店铺的其他应用提交了新的批量变更任务，后续你的应用调用接口获取结果数据时将得到该新任务的执行结果。因此建议你在批量变更任务结束后及时调用 [查询一个有效批量任务](https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/bulk-operations/get-a-valid-bulk-task.md) 拉取结果数据。 ------ ## 操作流程 按如下步骤进行批量变更操作： 1. **文件准备**：准备好需要使用的变更文件。 2. **提交任务**：使用准备好的变更文件调用 [创建一个批量变更任务](https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/bulk-operations/create-a-bulk-mutation-task.md) 接口提交任务。 3. **轮询状态**：调用 [查询一个有效批量任务](https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/bulk-operations/get-a-valid-bulk-task.md) 接口获取变更任务的状态和结果文件 URL。 4. **获取结果**：当任务执行完毕后，通过结果文件 URL 下载并解析 JSONL 文件，以获取变更结果并进行相应数据处理工作。若任务被中断，则返回的结果文件不完整，你需要解析该结果的最后一行的行号并重新提交 [创建一个批量变更任务](https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/bulk-operations/create-a-bulk-mutation-task.md)。 ------ ## 场景示例：导入一批商品数据 如果你想在 SHOPLINE 店铺导入一批商品数据，可采用如下步骤： ### 前提条件 确保你的应用已拥有 `write_products`、`read_bulkoperation` 和 `write_bulkoperation` 权限点。 ### 步骤一：准备变更文件 {#c6s8h0} 根据 [创建商品](https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/product/product/create-a-product.md) 所需的参数创建 JSONL 文件，文件中每一行数据即对应一个商品创建请求的具体信息。如下示例包含两条商品创建请求的数据记录，其中 `url`、`method` 和 `payload` 分别对应商品创建请求中的接口地址、HTTP 方法和请求体： ```json {"url":"https://goodgoods.myshopline.com/admin/openapi/v20230901/products/products.json","method":"post","payload":{"product":{"published_scope":"web","body_html":"

Classic T-shirt - Red

","images":[{"src":"https://img-va.myshopline.com/image/store/2000986376/1663054163488/Hbe20374eba504af8b3b088a2f5d87658h.jpg?w=1000&h=1000","alt":"Classic T-shirt - Red"}],"vendor":"Demo Brand","subtitle":"Red classic cotton T-shirt","options":[{"values_images":{"Red":"https://img-va.myshopline.com/image/store/2000986376/1663054163488/Hbe20374eba504af8b3b088a2f5d87658h.jpg?w=1000&h=1000"},"name":"Color"}],"handle":"classic-t-shirt-red","variants":[{"image":{"src":"https://img-va.myshopline.com/image/store/2000986376/1663054163488/Hbe20374eba504af8b3b088a2f5d87658h.jpg?w=1000&h=1000","alt":"Classic T-shirt - Red"},"required_shipping":true,"compare_at_price":"11","taxable":true,"option5":"","weight":"1.2","inventory_policy":"deny","weight_unit":"kg","price":"10.11","option3":"","option4":"","inventory_tracker":true,"option1":"Red","option2":"","sku":"TSHIRT-RED-001","barcode":"6900000000001"}],"title":"Classic T-shirt - Red","product_category":"T-shirt","status":"active","tags":["t-shirt","red","bulk-import"]}}} {"url":"https://goodgoods.myshopline.com/admin/openapi/v20230901/products/products.json","method":"post","payload":{"product":{"published_scope":"web","body_html":"

Classic T-shirt - Blue

","images":[{"src":"https://img-va.myshopline.com/image/store/2000986376/1663054163488/Hbe20374eba504af8b3b088a2f5d87658h.jpg?w=1000&h=1000","alt":"Classic T-shirt - Blue"}],"vendor":"Demo Brand","subtitle":"Blue classic cotton T-shirt","options":[{"values_images":{"Blue":"https://img-va.myshopline.com/image/store/2000986376/1663054163488/Hbe20374eba504af8b3b088a2f5d87658h.jpg?w=1000&h=1000"},"name":"Color"}],"handle":"classic-t-shirt-blue","variants":[{"image":{"src":"https://img-va.myshopline.com/image/store/2000986376/1663054163488/Hbe20374eba504af8b3b088a2f5d87658h.jpg?w=1000&h=1000","alt":"Classic T-shirt - Blue"},"required_shipping":true,"compare_at_price":"11","taxable":true,"option5":"","weight":"1.2","inventory_policy":"deny","weight_unit":"kg","price":"10.11","option3":"","option4":"","inventory_tracker":true,"option1":"Blue","option2":"","sku":"TSHIRT-BLUE-001","barcode":"6900000000002"}],"title":"Classic T-shirt - Blue","product_category":"T-shirt","status":"active","tags":["t-shirt","blue","bulk-import"]}}} ``` ### 步骤二：提交变更任务 调用 [创建一个批量变更任务](https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/bulk-operations/create-a-bulk-mutation-task.md) 接口提交变更任务，在请求体的 `file_url` 字段中传入上一步创建的 JSONL 文件的 URL。 请求示例： ```json curl --location -g --request POST 'https://{handle}.myshopline.com/admin/openapi/v20260901/bulk_operation_run_mutation_general.json' \ --header 'Authorization: Bearer {accessToken}' \ --header 'Content-Type: application/json; charset=utf-8' \ --data-raw '{ "file_url": "https://xxx.com/products.jsonl" }' ``` 若返回的 HTTP 状态码为 `200`，代表任务提交成功。 > **注意** > > 请求参数 `file_url` 传入的文件 URL 必须支持公网免鉴权直接访问，否则任务会执行失败。 ### 步骤三：查询任务状态和结果 调用 [查询一个有效批量任务](https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/bulk-operations/get-a-valid-bulk-task.md) 接口查询上一步提交的变更任务状态和结果。 > **提示** > > 你也可以订阅 [批量任务状态更新](https://developer.shopline.com/zh-hans-cn/docs/webhook/batch-operation/bulk-task-status-updated.md) Webhook 通知。当有批量变更任务的状态更新时，系统会触发此 Webhook 通知，你可以根据通知信息中的以下字段了解相应的任务信息和获取结果文件 URL： > > - `status`：该任务的状态。 > - `type`：该任务的类型。 > - `url`：该任务的结果文件 URL。 请求示例： ```http curl --location -g --request GET 'https://{handle}.myshopline.com/admin/openapi/v20260901/current_bulk_operation.json?type=MUTATION_GENERAL' \ --header 'Authorization: Bearer {accessToken}' \ --header 'Content-Type: application/json; charset=utf-8' \ --data-raw '' ``` > **注意** > > 请求路径中需添加 `type=MUTATION_GENERAL`，表示请求的是批量变更任务。 返回示例： ```json { "partialDataUrl": null, "createdAt": "2023-05-24T14:53:45+08:00", "expiredAt": null, "reason": null, "completedAt": null, "errorCode": null, "id": "gid://shopline/BulkOperation/XX", "type": "MUTATION_GENERAL", "completedCount": 0, "storeId": "xx", "url": null, "status": "CREATED" } ``` ### 步骤四：下载并解析 JSONL 文件 若调用 [查询一个有效批量任务](https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/bulk-operations/get-a-valid-bulk-task.md) 接口或 [批量任务状态更新](https://developer.shopline.com/zh-hans-cn/docs/webhook/batch-operation/bulk-task-status-updated.md) Webhook 通知返回的 `status` 字段为 `COMPLETED`，代表批量变更任务已完成。此时，可通过返回的 `url` 字段下载 JSONL 文件。该文件中每一行数据都是有效的 JSON 值，例如： ```json {"product":{"image":{"src":"https://img-va.myshopline.com/image/store/2000986376/1663054163488/Hbe20374eba504af8b3b088a2f5d87658h.jpg?w=1000&h=1000","alt":"sdf","id":"5949197836163148889"},"body_html":"sdf","images":[{"src":"https://img-va.myshopline.com/image/store/2000986376/1663054163488/Hbe20374eba504af8b3b088a2f5d87658h.jpg?w=1000&h=1000","alt":"sdf","id":"5949197836163148889"}],"created_at":"2023-05-24T19:32:12+08:00","template_path":null,"handle":"t-shirt-2","variants":[{"inventory_quantity":0,"image":{"src":"https://img-va.myshopline.com/image/store/2000986376/1663054163488/Hbe20374eba504af8b3b088a2f5d87658h.jpg?w=1000&h=1000","alt":"sdf","id":"5949197836163148889"},"required_shipping":true,"compare_at_price":"11.00","taxable":true,"option5":null,"created_at":"2023-05-24T19:32:12+08:00","weight":"1.20","title":"Red","inventory_policy":"deny","updated_at":"2023-05-24T19:32:12+08:00","weight_unit":"kg","inventory_item_id":"5949197838801706542","price":"10.11","product_id":"16059491978375601928251954","option3":null,"option4":null,"inventory_tracker":true,"option1":"Red","id":"18059491978379292915831954","option2":null,"sku":"2111341123434","barcode":"1111111123434"}],"title":"sdf","tags":"sdfsdf3","published_scope":"web","product_type":"NORMAL","updated_at":"2023-05-24T19:32:12+08:00","vendor":"sdf","subtitle":"sdf","options":[{"product_id":"16059491978375601928251954","values":["Red"],"values_images":{"Red":"https://img-va.myshopline.com/image/store/2000986376/1663054163488/Hbe20374eba504af8b3"},"name":"Color","id":"16159491978379292915851954"}],"spu":null,"id":"16059491978375601928251954","published_at":"2023-05-24T19:32:12+08:00","product_behavior":"","product_category":"sdf","status":"active"}} {"product":{"image":{"src":"https://img-va.myshopline.com/image/store/2000986376/1663054163488/Hbe20374eba504af8b3b088a2f5d87658h.jpg?w=1000&h=1000","alt":"sdf","id":"5949197836163148889"},"body_html":"sdf","images":[{"src":"https://img-va.myshopline.com/image/store/2000986376/1663054163488/Hbe20374eba504af8b3b088a2f5d87658h.jpg?w=1000&h=1000","alt":"sdf","id":"5949197836163148889"}],"created_at":"2023-05-24T19:32:12+08:00","template_path":null,"handle":"t-shirt-2","variants":[{"inventory_quantity":0,"image":{"src":"https://img-va.myshopline.com/image/store/2000986376/1663054163488/Hbe20374eba504af8b3b088a2f5d87658h.jpg?w=1000&h=1000","alt":"sdf","id":"5949197836163148889"},"required_shipping":true,"compare_at_price":"11.00","taxable":true,"option5":null,"created_at":"2023-05-24T19:32:12+08:00","weight":"1.20","title":"Red","inventory_policy":"deny","updated_at":"2023-05-24T19:32:12+08:00","weight_unit":"kg","inventory_item_id":"5949197838801706542","price":"10.11","product_id":"16059491978375601928251954","option3":null,"option4":null,"inventory_tracker":true,"option1":"Red","id":"18059491978379292915831954","option2":null,"sku":"2111341123434","barcode":"1111111123434"}],"title":"sdf","tags":"sdfsdf3","published_scope":"web","product_type":"NORMAL","updated_at":"2023-05-24T19:32:12+08:00","vendor":"sdf","subtitle":"sdf","options":[{"product_id":"16059491978375601928251954","values":["Red"],"values_images":{"Red":"https://img-va.myshopline.com/image/store/2000986376/1663054163488/Hbe20374eba504af8b3"},"name":"Color","id":"16159491978379292915851954"}],"spu":null,"id":"16059491978375601928251954","published_at":"2023-05-24T19:32:12+08:00","product_behavior":"","product_category":"sdf","status":"active"}} ``` 你可以用任意编程语言解析该 JSONL 文件，以便后续处理数据。 ### 步骤五：处理中断任务 当批量变更任务因某种原因被中断时，将无法完成全部数据的处理，生成的 JSONL 文件只包含任务中断时已执行的变更对应的部分结果数据。你可以通过 [查询一个有效批量任务](https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/bulk-operations/get-a-valid-bulk-task.md) 接口返回的 `partialDataUrl` 字段获取该部分结果数据的 JSONL 文件 URL 并下载文件。 > **注意** > > `url` 和 `partialDataUrl` 字段对应的 JSONL 文件有效期均为 12 小时，到期后将被清除。 批量变更任务被中断后，你可以通过返回的部分结果文件继续提交变更任务，步骤如下： 1. 解析部分结果文件的最后一行的行号。 2. 在 [步骤一：准备变更文件](#c6s8h0) 中创建的变更文件中定位到该行号位置。 3. 删除小于该行号的数据行。 4. 保存文件，然后使用该文件调用 [创建一个批量变更任务](https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/bulk-operations/create-a-bulk-mutation-task.md) 接口再次提交请求。 ------ ## 故障排查 SHOPLINE 可能会终止批量变更任务的执行，常见原因如下： - **权限不足**：你的应用没有修改目标资源的权限，需先申请相应权限。 - **内部异常**：由于非预期原因导致系统无法处理你的应用提交的变更请求。可尝试重新提交请求。 - **Access token 过期**：在执行任务期间，你的应用的 access token 过期了。需使用有效 access token 重新提交请求。