--- title: "创建一个批量变更任务" description: > 创建一个[批量变更任务](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/get-a-valid-bulk-task.md) 接口或 [批量任务状态更新](https://developer.shopline.com/zh-hans-cn/docs/webhook/batch-operation/bulk-task-status-updated.md) Webhook 获取具体变更结果。 doc_type: openapi doc_category: openapi doc_version: v20270301 source_url: html: 'https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/bulk-operations/create-a-bulk-mutation-task' md: 'https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/bulk-operations/create-a-bulk-mutation-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/get-a-valid-bulk-task.md) 接口或 [批量任务状态更新](https://developer.shopline.com/zh-hans-cn/docs/webhook/batch-operation/bulk-task-status-updated.md) Webhook 获取具体变更结果。 - **Base URL:** `https://{handle}.myshopline.com/admin/openapi` - **Required Scopes:** `write_bulkoperation` - **API Version:** v20270301 - **API Type:** Admin - **API Protocol:** RESTful ## Endpoint ```http POST /bulk_operation_run_mutation_general.json ``` ## Base URL * `https://{handle}.myshopline.com/admin/openapi` * `{handle}`: `handle` ：店铺的唯一标识符，值为店铺域名的前缀。例如，域名为 `open001.myshopline.com` 的店铺，其 `handle` 是 `open001` 。 ## Required Permissions * `write_bulkoperation` ## Request ### Request Headers * `Content-Type` string (required) 字段值固定为 `application/json; charset=utf-8`。 * `Authorization` string (required) 资源的访问令牌。参考 [应用授权](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/app-authorization.md?lang=zh-hans-cn) 获取访问令牌，然后将获取到的访问令牌以 Bearer 格式传入。 ### Request Body * `file_url` string 公网可访问 URL，用于存储批量变更任务数据。文件格式：[JSON Lines](https://jsonlines.org)。 ## Response ### Status Codes * `200` 更多状态码信息，参考 [HTTP 状态码](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/http-status-code.md?lang=zh-hans-cn)。 * `401` * `429` ### Response Headers * `traceId` 请求的全局唯一标识符。用于追踪请求在系统中的流转，以便于问题发生时进行定位和调试。 ### Response Body #### 200 * `completedCount` integer 批量操作的完成数量。 * `errorCode` string 批量任务错误码。有效枚举值包含： - `ACCESS_DENIED`: 无访问权限 - `TIMEOUT`: 处理超时 - `NO_DATA`: 没有找到数据 * `partialDataUrl` string 带有过期时间的文件 URL。文件格式：[JSON Lines](https://jsonlines.org)。 当 `status` 是 `COMPLETED` 时，该字段值与 `url` 值一致。其他状态下，可能包含部分任务处理结果。 * `reason` string 批量任务执行异常的原因。 * `status` string 批量任务状态。有效枚举值包含： - `CANCELED`：已取消 - `CANCELING`：取消中 - `COMPLETED`：已完成 - `CREATED`：已创建 - `EXPIRED`：已过期 - `FAILED`：已失败 - `RUNNING`：运行中 * `storeId` string 店铺 ID。 * `type` string 批量任务操作类型。有效枚举值包含： - `QUERY`：查询操作 - `MUTATION`：变更操作，指通过 [创建一个批量变更任务（待废弃）](https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/bulk-operations/create-a-change-type-bulk-task-to-be-deprecated.md) 接口执行的变更操作。 - `MUTATION_GENERAL`：变更操作 * `completedAt` string 批量任务的完成日期与时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。 * `createdAt` string 批量任务的创建日期与时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。 * `expiredAt` string 批量任务的过期时间，超过该时间文件将无法下载。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。 * `id` string 批量任务 ID。 * `url` string 带有过期时间的文件 URL，包含所有任务处理结果。文件格式：[JSON Lines](https://jsonlines.org)。 #### 401 * `errors` string 错误描述。 #### 429 * `errors` string 错误描述。 ## OpenAPI Definition ```json { "tags": [ "创建一个批量变更任务" ], "description": "创建一个[批量变更任务](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/get-a-valid-bulk-task.md) 接口或 [批量任务状态更新](https://developer.shopline.com/zh-hans-cn/docs/webhook/batch-operation/bulk-task-status-updated.md) Webhook 获取具体变更结果。", "externalDocs": { "description": "接口使用的权限点: `write_bulkoperation` ，更多权限点使用信息，请参考:", "url": "ec20/3cv5d7wpfgr6a8z5/xabczf5442284vkq?lang=zh-hans-cn", "errorTableDescription": "" }, "operationId": "DSAX1G4g", "parameters": [ { "name": "Content-Type", "in": "header", "description": "字段值固定为 `application/json; charset=utf-8`。", "required": true, "schema": { "name": "Content-Type", "type": "string", "example": "application/json; charset=utf-8" } }, { "name": "Authorization", "in": "header", "description": "资源的访问令牌。参考 [应用授权](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/app-authorization.md?lang=zh-hans-cn) 获取访问令牌，然后将获取到的访问令牌以 Bearer 格式传入。", "required": true, "style": "string", "schema": { "name": "Authorization", "description": "资源的访问令牌。参考 [应用授权](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/app-authorization.md?lang=zh-hans-cn) 获取访问令牌，然后将获取到的访问令牌以 Bearer 格式传入。", "type": "string", "example": "Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhcHBJZCI6MCwiYXBwS2V5IjoiNzU2ZjI1NWE2NjdlZTcwNTk1MzM0ZjVjYzk4NzU5MzBmN2E3NGZjMSIsImV4cCI6MTg3OTQ4MjA3NiwiaXNzIjoieXNvdWwiLCJzZWxsZXJJZCI6IjIwMDAyMzQ4ODAiLCJzdG9yZUlkIjoiMTY3MjM2OTcyOTYwNiIsInRpbWVzdGFtcCI6MTc4NDc4NzY3NjY2MSwidmVyc2lvbiI6IlYyIn0.3ZzbGAH4cLU1QR2VPEvMOQInUDvus-C4amkINSQIPuNVlXsFKj0sAt1c0KnUy9MWUOFV9cHlkf7J90r2y1FzpA" }, "example": "Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhcHBJZCI6MCwiYXBwS2V5IjoiNzU2ZjI1NWE2NjdlZTcwNTk1MzM0ZjVjYzk4NzU5MzBmN2E3NGZjMSIsImV4cCI6MTg3OTQ4MjA3NiwiaXNzIjoieXNvdWwiLCJzZWxsZXJJZCI6IjIwMDAyMzQ4ODAiLCJzdG9yZUlkIjoiMTY3MjM2OTcyOTYwNiIsInRpbWVzdGFtcCI6MTc4NDc4NzY3NjY2MSwidmVyc2lvbiI6IlYyIn0.3ZzbGAH4cLU1QR2VPEvMOQInUDvus-C4amkINSQIPuNVlXsFKj0sAt1c0KnUy9MWUOFV9cHlkf7J90r2y1FzpA" } ], "requestBody": { "content": { "application/json": { "schema": { "name": "body", "description": "body位置参数", "type": "object", "properties": { "file_url": { "name": "file_url", "description": "公网可访问 URL，用于存储批量变更任务数据。文件格式：[JSON Lines](https://jsonlines.org)。", "type": "string" } }, "example": { "file_url": null } }, "examples": { "创建一个批量变更任务": { "description": "`file_url` 必须提供合法的 [jsonl](https://jsonlines.org/) 文件，文件内容参考 [文档](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/bulk-operations/bulk-change-task.md#usage-example) ", "value": { "file_url": "https://example.com/data.jsonl" } } } } }, "required": true }, "responses": { "200": { "description": "更多状态码信息，参考 [HTTP 状态码](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/http-status-code.md?lang=zh-hans-cn)。", "headers": { "traceId": { "description": "请求的全局唯一标识符。用于追踪请求在系统中的流转，以便于问题发生时进行定位和调试。" } }, "content": { "application/json": { "schema": { "name": "body", "type": "object", "properties": { "completedCount": { "name": "completedCount", "description": "批量操作的完成数量。", "type": "integer" }, "errorCode": { "name": "errorCode", "description": "批量任务错误码。有效枚举值包含：\n\n- `ACCESS_DENIED`: 无访问权限\n- `TIMEOUT`: 处理超时\n- `NO_DATA`: 没有找到数据", "type": "string" }, "partialDataUrl": { "name": "partialDataUrl", "description": "带有过期时间的文件 URL。文件格式：[JSON Lines](https://jsonlines.org)。\n当 `status` 是 `COMPLETED` 时，该字段值与 `url` 值一致。其他状态下，可能包含部分任务处理结果。", "type": "string", "example": "https://sl-private-oss.oss-accelerate.example.com/task-jsonline/prod/1/9b0c0f04-53cb-4ae3-94db-79af6ec193bd.jsonl?Expires=1754059510" }, "reason": { "name": "reason", "description": "批量任务执行异常的原因。", "type": "string" }, "status": { "name": "status", "description": "批量任务状态。有效枚举值包含：\n\n- `CANCELED`：已取消 \n- `CANCELING`：取消中 \n- `COMPLETED`：已完成 \n- `CREATED`：已创建 \n- `EXPIRED`：已过期 \n- `FAILED`：已失败 \n- `RUNNING`：运行中 \n ", "type": "string" }, "storeId": { "name": "storeId", "description": "店铺 ID。", "type": "string" }, "type": { "name": "type", "description": "批量任务操作类型。有效枚举值包含： \n- `QUERY`：查询操作 \n- `MUTATION`：变更操作，指通过 [创建一个批量变更任务（待废弃）](https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/bulk-operations/create-a-change-type-bulk-task-to-be-deprecated.md) 接口执行的变更操作。 \n- `MUTATION_GENERAL`：变更操作\n", "type": "string" }, "completedAt": { "name": "completedAt", "description": "批量任务的完成日期与时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。", "type": "string", "example": "2023-04-07T10:48:29+08:00" }, "createdAt": { "name": "createdAt", "description": "批量任务的创建日期与时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。", "type": "string", "example": "2023-04-06T10:48:29+08:00" }, "expiredAt": { "name": "expiredAt", "description": "批量任务的过期时间，超过该时间文件将无法下载。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。", "type": "string", "example": "2023-04-07T10:48:29+08:00" }, "id": { "name": "id", "description": "批量任务 ID。", "type": "string" }, "url": { "name": "url", "description": "带有过期时间的文件 URL，包含所有任务处理结果。文件格式：[JSON Lines](https://jsonlines.org)。\n", "type": "string", "example": "https://sl-private-oss.oss-accelerate.example.com/task-jsonline/prod/1/9b0c0f04-53cb-4ae3-94db-79af6ec193bd.jsonl?Expires=1754059510" } }, "example": { "createdAt": "2023-04-06T10:48:29+08:00", "status": null, "storeId": null, "url": "https://sl-private-oss.oss-accelerate.example.com/task-jsonline/prod/1/9b0c0f04-53cb-4ae3-94db-79af6ec193bd.jsonl?Expires=1754059510", "completedAt": "2023-04-07T10:48:29+08:00", "completedCount": null, "errorCode": null, "expiredAt": "2023-04-07T10:48:29+08:00", "id": null, "partialDataUrl": "https://sl-private-oss.oss-accelerate.example.com/task-jsonline/prod/1/9b0c0f04-53cb-4ae3-94db-79af6ec193bd.jsonl?Expires=1754059510", "reason": null, "type": null } }, "examples": { "创建一个批量变更任务": { "description": "`file_url` 必须提供合法的 [jsonl](https://jsonlines.org/) 文件，文件内容参考 [文档](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/bulk-operations/bulk-change-task.md#usage-example) ", "value": { "status": "CREATED", "url": null, "completedAt": null, "createdAt": "2023-05-24T14:53:45+08:00", "errorCode": null, "id": "gid://shopline/BulkOperation/1", "partialDataUrl": null, "reason": null, "storeId": "xx", "type": "MUTATION_GENERAL", "completedCount": 0, "expiredAt": null } } } } } }, "401": { "headers": { "traceId": { "description": "请求的全局唯一标识符。用于追踪请求在系统中的流转，以便于问题发生时进行定位和调试。" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "错误描述。", "type": "string" } }, "required": [ "errors" ] } } } }, "429": { "headers": { "traceId": { "description": "请求的全局唯一标识符。用于追踪请求在系统中的流转，以便于问题发生时进行定位和调试。" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "错误描述。", "type": "string" } }, "required": [ "errors" ] } } } } }, "security": [ { "oauth2": [] } ], "method": "post", "path": "/bulk_operation_run_mutation_general.json", "servers": [ { "url": "https://{handle}.myshopline.com/admin/openapi", "variables": { "handle": { "default": "openapiceshidianpu", "description": "`handle` ：店铺的唯一标识符，值为店铺域名的前缀。例如，域名为 `open001.myshopline.com` 的店铺，其 `handle` 是 `open001` 。" } } } ], "info": { "title": "创建一个批量变更任务", "version": "v20270301" }, "authIndexes": [ "write_bulkoperation" ] } ```