--- title: "初始化文件分段上传任务" description: "启动多个文件的分阶段上传任务。此 API 将返回后续上传操作所需的上传凭据。" doc_type: openapi doc_category: openapi doc_version: v20270301 source_url: html: 'https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/product/files/initiate-a-file-staged-upload' md: 'https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/product/files/initiate-a-file-staged-upload.md' --- # 初始化文件分段上传任务 启动多个文件的分阶段上传任务。此 API 将返回后续上传操作所需的上传凭据。 - **Base URL:** `https://{handle}.myshopline.com/admin/openapi` - **Required Scopes:** `write_files` - **API Version:** v20270301 - **API Type:** Admin - **API Protocol:** RESTful ## Endpoint ```http POST /files/upload.json ``` ## Base URL * `https://{handle}.myshopline.com/admin/openapi` * `{handle}`: `handle` ：店铺的唯一标识符，值为店铺域名的前缀。例如，域名为 `open001.myshopline.com` 的店铺，其 `handle` 是 `open001` 。 ## Required Permissions * `write_files` ## 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_info` array 文件信息列表。 * `file_name` string 文件的名称，写入时需携带完整准确的文件后缀，用于识别文件格式。
最大长度限制：255 * `file_size` long 文件的大小（以字节为单位）。
当上传的资源为视频时必传。 * `mime_type` string 文件的 MIME 类型。有效枚举值包含： - `image/jpeg` - `image/png` - `image/bmp` - `image/webp` - `image/svg+xml` - `image/x-icon` - `video/mp4` - `video/webm` - `video/quicktime` - `application/pdf` - `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` - `text/csv` - `application/vnd.openxmlformats-officedocument.wordprocessingml.document` - `font/ttf` - `font/woff` - `font/otf` - `font/sfnt` - `application/font-sfnt` - `audio/mpeg` - `text/html` - `text/javascript` - `application/javascript` - `text/css` - `application/json` - `application/xml` - `text/xml` - `text/plain` - `application/octet-stream` - `application/x-rar-compressed` - `application/zip` ## 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 * `signs` array 文件签名信息列表。 * `access_id` string 文件的签名对应的 access key。 * `call_back` string 文件上传的回调参数。 * `host` string 文件上传的目标地址。 * `key` string 文件的相对路径，包含文件名。 * `policy` string 文件的签名策略信息。 * `signature` string 文件的签名。 * `url` string 预占文件访问链接。 #### 401 * `errors` string 错误描述。 #### 429 * `errors` string 错误描述。 ## OpenAPI Definition ```json { "tags": [ "初始化文件分段上传任务" ], "description": "启动多个文件的分阶段上传任务。此 API 将返回后续上传操作所需的上传凭据。", "externalDocs": { "description": "接口使用的权限点: `write_files` ，更多权限点使用信息，请参考:", "url": "ec20/3cv5d7wpfgr6a8z5/xabczf5442284vkq?lang=zh-hans-cn", "errorTableDescription": "| Error Code | HTTP Status Code | Error Description |\n|------------|------------------|-------------------|\n| SUCCESS | 200 | request success |\n" }, "operationId": "6MkTalBm", "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_info": { "name": "file_info", "description": "文件信息列表。", "type": "array", "items": { "type": "object", "properties": { "file_name": { "name": "file_name", "description": "文件的名称，写入时需携带完整准确的文件后缀，用于识别文件格式。
\n最大长度限制：255", "type": "string", "example": "file_name.jpg" }, "file_size": { "name": "file_size", "description": "文件的大小（以字节为单位）。
当上传的资源为视频时必传。", "type": "long", "example": 300 }, "mime_type": { "name": "mime_type", "description": "文件的 MIME 类型。有效枚举值包含：\n- `image/jpeg`\n- `image/png`\n- `image/bmp`\n- `image/webp`\n- `image/svg+xml`\n- `image/x-icon`\n- `video/mp4`\n- `video/webm`\n- `video/quicktime`\n- `application/pdf`\n- `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`\n- `text/csv`\n- `application/vnd.openxmlformats-officedocument.wordprocessingml.document`\n- `font/ttf`\n- `font/woff`\n- `font/otf`\n- `font/sfnt`\n- `application/font-sfnt`\n- `audio/mpeg`\n- `text/html`\n- `text/javascript`\n- `application/javascript`\n- `text/css`\n- `application/json`\n- `application/xml`\n- `text/xml`\n- `text/plain`\n- `application/octet-stream`\n- `application/x-rar-compressed`\n- `application/zip`", "type": "string", "example": "image/jpeg" } }, "required": [ "file_name", "mime_type" ], "example": { "file_name": "file_name.jpg", "file_size": 300, "mime_type": "image/jpeg" } }, "example": [ {} ] } }, "required": [ "file_info" ], "example": { "file_info": [ {} ] } }, "examples": { "初始化文件分段上传任务": { "description": "启动多个文件的分阶段上传任务。此 API 将返回后续上传操作所需的上传凭据。", "value": { "file_info": [ { "file_name": "my video.mp4", "file_size": "2000", "mime_type": "video/mp4" }, { "file_name": "my image.jpeg", "file_size": "50", "mime_type": "image/png" } ] } } } } }, "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": { "signs": { "name": "signs", "description": "文件签名信息列表。", "type": "array", "items": { "type": "object", "properties": { "access_id": { "name": "access_id", "description": "文件的签名对应的 access key。", "type": "string", "example": "LTAI5tRrVqCocJKdSpEovixm" }, "call_back": { "name": "call_back", "description": "文件上传的回调参数。", "type": "string", "example": "eyJjYWxsYmFja0JvZHkiOiJidWNrZXQ9JHtidWNrZXR9Jm9iamVjdD0ke29iamVjdH0mc2l6ZT0ke3NpemV9JmNvbnRlbnRUeXBlVHlwZT0ke2NvbnRlbnRUeXBlVHlwZX0mZm9ybWF0PSR7aW1hZ2VJbmZvLmZvcm1hdH0mYml6dHlwZT1cIm9wZW5hcGlTdGFzaENoYW5nZUxpbmtcIiIsImNhbGxiYWNrQm9keVR5cGUiOiJhcHBsaWNhdGl" }, "host": { "name": "host", "description": "文件上传的目标地址。", "type": "string", "example": "https://sl-resource-tmp-sg.s3.xxx.com" }, "key": { "name": "key", "description": "文件的相对路径，包含文件名。", "type": "string", "example": "temp/file/store/1626235806828/6991265004189666341/image.jpg" }, "policy": { "name": "policy", "description": "文件的签名策略信息。", "type": "string", "example": "eyJleHBpcmF0aW9uIjoiMjAyNi0wNS0xMlQwODo1Mjo1NloiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsMCwyMDk3MTUyMF0sWyJlcSIsIiRrZXkiLCJ0ZW1wL2ZpbGUvc3RvcmUvMTYyNjIzNTgwNjgyOC82OTkxMjY1MDA0MTg5NjY2MzQxLzAwMDQ5ZWEzNDQ4ZTQzMWM4YTRiYzVh" }, "signature": { "name": "signature", "description": "文件的签名。", "type": "string", "example": "6+YHcWnLhu0YofPIzAQUaZ9kKZI=" }, "url": { "name": "url", "description": "预占文件访问链接。", "type": "string", "example": "https://sl-resource-tmp-sg.s3-ap-southeast-1.xxx.com/temp%2Ffile%2Fstore%2F1672369729606%2F6995259736342668404%2Fimage.png?Expires=1747882880&OSSAccessKeyId=LTAI5tNjm7fr4EUCoEps4UPE&Signature=kLIWPCVwWTQMZcHUWyszjoH4DPM%3D" } }, "example": { "access_id": "LTAI5tRrVqCocJKdSpEovixm", "call_back": "eyJjYWxsYmFja0JvZHkiOiJidWNrZXQ9JHtidWNrZXR9Jm9iamVjdD0ke29iamVjdH0mc2l6ZT0ke3NpemV9JmNvbnRlbnRUeXBlVHlwZT0ke2NvbnRlbnRUeXBlVHlwZX0mZm9ybWF0PSR7aW1hZ2VJbmZvLmZvcm1hdH0mYml6dHlwZT1cIm9wZW5hcGlTdGFzaENoYW5nZUxpbmtcIiIsImNhbGxiYWNrQm9keVR5cGUiOiJhcHBsaWNhdGl", "host": "https://sl-resource-tmp-sg.s3.xxx.com", "key": "temp/file/store/1626235806828/6991265004189666341/image.jpg", "policy": "eyJleHBpcmF0aW9uIjoiMjAyNi0wNS0xMlQwODo1Mjo1NloiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsMCwyMDk3MTUyMF0sWyJlcSIsIiRrZXkiLCJ0ZW1wL2ZpbGUvc3RvcmUvMTYyNjIzNTgwNjgyOC82OTkxMjY1MDA0MTg5NjY2MzQxLzAwMDQ5ZWEzNDQ4ZTQzMWM4YTRiYzVh", "signature": "6+YHcWnLhu0YofPIzAQUaZ9kKZI=", "url": "https://sl-resource-tmp-sg.s3-ap-southeast-1.xxx.com/temp%2Ffile%2Fstore%2F1672369729606%2F6995259736342668404%2Fimage.png?Expires=1747882880&OSSAccessKeyId=LTAI5tNjm7fr4EUCoEps4UPE&Signature=kLIWPCVwWTQMZcHUWyszjoH4DPM%3D" } } } }, "example": { "signs": null } }, "examples": { "初始化文件分段上传任务": { "description": "启动多个文件的分阶段上传任务。此 API 将返回后续上传操作所需的上传凭据。", "value": { "signs": [ { "access_id": "LTAI5tNjm7fr4EUCoEps4UPE", "call_back": "eyJjYWxsYmFja0JvZHkiOiJidWNrZXQ9JHtidWNrZXR9Jm9iamVjdD0ke29iamVjdH0mbWltZVR5cGU9JHttaW1lVHlwZX0mc2l6ZT0ke3NpemV9JmNvbnRlbnRUeXBlVHlwZT0ke2NvbnRlbnRUeXBlVHlwZX0mZm9ybWF0PSR7aW1hZ2VJbmZvLmZvcm1hdH0mYml6dHlwZT1cIm9wZW5hcGlTdGFzaENoYW5nZUxpbmtcIiIsImNhbGxiYWNrQm9keVR5cGUiOiJhcHBsaWNhdGlvbi9qc29uIiwiY2FsbGJhY2tVcmwiOiJodHRwczovL2FwaS1vc3Nub3RpZnktc2ctcHJldmlldy5teXNob3BsaW5lLmNvbS9hcGkvc2lnbmF0dXJlL29zcy9wb3N0L25vdGlmeSJ9Cg==", "host": "https://sl-resource-tmp-sg.s3.xxx.com", "key": "temp/file/store/1672369729606/6995259736325891187/video.mp4", "policy": "eyJleHBpcmF0aW9uIjoiMjAyNS0wNS0yMlQwMzowMToyMFoiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsMCwyMDk3MTUyMF0sWyJlcSIsIiRrZXkiLCJ0ZW1wL2ZpbGUvc3RvcmUvMTY3MjM2OTcyOTYwNi82OTk1MjU5NzM2MzI1ODkxMTg3L3ZpZGVvLm1wNCJdLFsiaW4iLCIkY29udGVudC10eXBlIixbInZpZGVvL21wNCJdXSxbImVxIiwiJGNhbGxCYWNrIiwiZXlKallXeHNZbUZqYTBKdlpIa2lPaUppZFdOclpYUTlKSHRpZFdOclpYUjlKbTlpYW1WamREMGtlMjlpYW1WamRIMG1iV2x0WlZSNWNHVTlKSHR0YVcxbFZIbHdaWDBtYzJsNlpUMGtlM05wZW1WOUptTnZiblJsYm5SVWVYQmxWSGx3WlQwa2UyTnZiblJsYm5SVWVYQmxWSGx3WlgwbVptOXliV0YwUFNSN2FXMWhaMlZKYm1adkxtWnZjbTFoZEgwbVltbDZkSGx3WlQxY0ltOXdaVzVoY0dsVGRHRnphRU5vWVc1blpVeHBibXRjSWlJc0ltTmhiR3hpWVdOclFtOWtlVlI1Y0dVaU9pSmhjSEJzYVdOaGRHbHZiaTlxYzI5dUlpd2lZMkZzYkdKaFkydFZjbXdpT2lKb2RIUndjem92TDJGd2FTMXZjM051YjNScFpua3RjMmN0Y0hKbGRtbGxkeTV0ZVhOb2IzQnNhVzVsTG1OdmJTOWhjR2t2YzJsbmJtRjBkWEpsTDI5emN5OXdiM04wTDI1dmRHbG1lU0o5Q2c9PSJdLFsiaW4iLCIkeC1vc3MtY29udGVudC10eXBlIixbImZvcm0tZmllbGQtbnVsbCJdXV19Cg==", "signature": "yZ7+COvtdMCuVlTLJNcjZWsiONw=", "url": "https://sl-resource-tmp-sg.s3-ap-southeast-1.xxx.com/temp%2Ffile%2Fstore%2F1672369729606%2F6995259736325891187%2Fvideo.mp4?Expires=1747882880&OSSAccessKeyId=LTAI5tNjm7fr4EUCoEps4UPE&Signature=PfJxZps6aSlO7%2FROX3r9ePiBAls%3D" }, { "access_id": "LTAI5tNjm7fr4EUCoEps4UPE", "call_back": "eyJjYWxsYmFja0JvZHkiOiJidWNrZXQ9JHtidWNrZXR9Jm9iamVjdD0ke29iamVjdH0mbWltZVR5cGU9JHttaW1lVHlwZX0mc2l6ZT0ke3NpemV9JmNvbnRlbnRUeXBlVHlwZT0ke2NvbnRlbnRUeXBlVHlwZX0mZm9ybWF0PSR7aW1hZ2VJbmZvLmZvcm1hdH0mYml6dHlwZT1cIm9wZW5hcGlTdGFzaENoYW5nZUxpbmtcIiIsImNhbGxiYWNrQm9keVR5cGUiOiJhcHBsaWNhdGlvbi9qc29uIiwiY2FsbGJhY2tVcmwiOiJodHRwczovL2FwaS1vc3Nub3RpZnktc2ctcHJldmlldy5teXNob3BsaW5lLmNvbS9hcGkvc2lnbmF0dXJlL29zcy9wb3N0L25vdGlmeSJ9Cg==", "host": "https://sl-resource-tmp-sg.s3.xxx.com", "key": "temp/file/store/1672369729606/6995259736342668404/image.png", "policy": "eyJleHBpcmF0aW9uIjoiMjAyNS0wNS0yMlQwMzowMToyMFoiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsMCwxMDQ4NTc2MF0sWyJlcSIsIiRrZXkiLCJ0ZW1wL2ZpbGUvc3RvcmUvMTY3MjM2OTcyOTYwNi82OTk1MjU5NzM2MzQyNjY4NDA0L2ltYWdlLnBuZyJdLFsiaW4iLCIkY29udGVudC10eXBlIixbImltYWdlL3BuZyJdXSxbImVxIiwiJGNhbGxCYWNrIiwiZXlKallXeHNZbUZqYTBKdlpIa2lPaUppZFdOclpYUTlKSHRpZFdOclpYUjlKbTlpYW1WamREMGtlMjlpYW1WamRIMG1iV2x0WlZSNWNHVTlKSHR0YVcxbFZIbHdaWDBtYzJsNlpUMGtlM05wZW1WOUptTnZiblJsYm5SVWVYQmxWSGx3WlQwa2UyTnZiblJsYm5SVWVYQmxWSGx3WlgwbVptOXliV0YwUFNSN2FXMWhaMlZKYm1adkxtWnZjbTFoZEgwbVltbDZkSGx3WlQxY0ltOXdaVzVoY0dsVGRHRnphRU5vWVc1blpVeHBibXRjSWlJc0ltTmhiR3hpWVdOclFtOWtlVlI1Y0dVaU9pSmhjSEJzYVdOaGRHbHZiaTlxYzI5dUlpd2lZMkZzYkdKaFkydFZjbXdpT2lKb2RIUndjem92TDJGd2FTMXZjM051YjNScFpua3RjMmN0Y0hKbGRtbGxkeTV0ZVhOb2IzQnNhVzVsTG1OdmJTOWhjR2t2YzJsbmJtRjBkWEpsTDI5emN5OXdiM04wTDI1dmRHbG1lU0o5Q2c9PSJdLFsiaW4iLCIkeC1vc3MtY29udGVudC10eXBlIixbImZvcm0tZmllbGQtbnVsbCJdXV19Cg==", "signature": "yOdrzcc5TybeOmasArln98Z/Fi4=", "url": "https://sl-resource-tmp-sg.s3-ap-southeast-1.xxx.com/temp%2Ffile%2Fstore%2F1672369729606%2F6995259736342668404%2Fimage.png?Expires=1747882880&OSSAccessKeyId=LTAI5tNjm7fr4EUCoEps4UPE&Signature=kLIWPCVwWTQMZcHUWyszjoH4DPM%3D" } ] } } } } } }, "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": "/files/upload.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_files" ] } ```