创建数据迁移任务--veImageX-火山引擎

文档中心

导航

创建数据迁移任务

最近更新时间：2024.09.29 17:36:07首次发布时间：2024.05.06 15:18:33

本接口支持您通过自定义迁移源信息和具体迁移策略等配置，创建从源存储至 veImageX 的数据迁移任务。

迁移准备

您需要在迁移前根据迁移方式在源存储服务商处获取以下配置参数。

源服务商	准备内容	文档地址
阿里云OSS	桶遍历方式：Access Key、Secret Key、Bucket	迁移准备
腾讯云COS	桶遍历方式：Access Key、Secret Key、Bucket、Region 桶清单方式：Access Key、Secret Key、Bucket、Region、BucketInventoryDir、BucketInventorySchema 说明桶清单方式完整迁移流程详见使用桶清单方式进行数据迁移。	迁移准备
七牛云Kodo	桶遍历方式：Access Key、Secret Key、Bucket	迁移准备
百度云BOS	桶遍历方式：Access Key、Secret Key、Bucket、Region	迁移准备
华为云OBS	桶遍历方式：Access Key、Secret Key、Bucket、Region	迁移准备
优刻得（Ucloud File）	桶遍历方式：Access Key、Secret Key、Bucket、Region	迁移准备
AWS国际站	桶遍历方式：Access Key、Secret Key、Bucket	迁移准备
其他 S3 协议存储	桶遍历方式：Access Key、Secret Key、Bucket、Region、Endpoint	请根据实际源站获取
URL	迁移 URL 列表文件（.txt）的公网访问地址	URL 列表迁移说明

注意事项

请求频率限制：单用户请求频率限制为 10 次/秒。
超时时间：约为 10 秒。
迁移源中单个迁移文件大小不超过 10 GB。
URL 迁移文本文件大小不超过 500MB。
服务地址：veImageX 在全球多个区域部署，每个区域有自己对应的 OpenAPI 域名，不支持跨区域调用。具体详情请查看服务地址。

请求说明

请求方式：POST
请求地址：https://imagex.volcengineapi.com/?Action=CreateImageMigrateTask&Version=2023-05-01

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共请求参数。

参数	类型	是否必选	示例值	描述
Content-Type	String	是	`application/json`	请求头字段

Query

参数	类型	是否必选	示例值	描述
Action	String	是	`CreateImageMigrateTask`	接口名称。当前 API 的名称为 `CreateImageMigrateTask`。
Version	String	是	`2023-05-01`	接口版本。当前 API 的版本为 `2023-05-01`。

Body

参数	类型	是否必选	示例值	描述
Task	Object of Task	是	`-`	任务信息

Task

参数	类型	是否必选	示例值	描述
Name	String	是	`migrate-test`	自定义迁移任务名称
Source	Object of Source	是	`-`	迁移源信息
Transcode	Object of Transcode	否	`-`	转码配置
Dst	Object of Dst	是	`-`	目的信息
RunStrategy	Object of RunStrategy	否	`-`	迁移策略
CallbackCfg	Object of CallbackCfg	否	`-`	回调信息。配置后，当任务执行完成时，将往该回调配置地址发送任务回调信息。

Source

参数	类型	是否必选	示例值	描述
Vendor	String	是	`OSS`	迁移云服务商。取值如下所示： `OSS`：阿里云 `COS`：腾讯云 `KODO`：七牛云 `BOS`：百度云 `OBS`：华为云 `Ucloud`：Ucloud file `AWS`：AWS 国际站 `S3`：其他 S3 协议存储 `URL`：以上传 URL 列表的方式迁移
AK	String	否	`AKTP8shJDSYGbi8*****`	仅当`Vendor` 非 `URL`时，为必填。 Access Key，与 Secret Key 同时填写，为了保证有访问源数据桶的权限。请参考云数据迁移准备获取对应阿里云OSS、腾讯云COS、七牛云KODO、百度云BOS、华为云OBS、优刻得（Ucloud File)、AWS国际站的账号 AK/SK。对于其他 S3 协议存储的AK/SK，请根据其具体源站信息填写。
SK	String	否	`PJDJSAJNNNCbE1E****`	仅当`Vendor` 非 `URL`时，为必填。 Secret Key，与 Access Key 同时填写，为了保证有访问源数据桶的权限。请参考云数据迁移准备获取对应阿里云OSS、腾讯云COS、七牛云KODO、百度云BOS、华为云OBS、优刻得（Ucloud File)、AWS国际站的账号 AK/SK。对于其他 S3 协议存储的AK/SK，请根据其具体源站信息填写。
Region	String	否	`cn-beijing`	仅当`Vendor` 非 `URL/OSS/KODO/AWS`时，为必填。 Bucket 所在地区。请参考云数据迁移准备获取对应阿里云OSS、腾讯云COS、七牛云KODO、百度云BOS、华为云OBS、优刻得（Ucloud File)、AWS国际站的 Bucket 地区。对于其他 S3 协议存储的 Bucket 地区，请根据其具体源站信息填写。
Bucket	String	是	`storage-test`	仅当`Vendor`为`URL`时，需填写 URL 列表文件地址（公网 URL 地址）。说明支持指定迁移文件和转码后迁移文件进行重命名，详见 URL 列表迁移文件说明。当`Vendor`为其他时，需填写对应云服务商所需迁移数据的 Bucket 名称。您可参考云数据迁移准备获取对应阿里云OSS、腾讯云COS、七牛云KODO、百度云BOS、华为云OBS、优刻得（Ucloud File)、AWS国际站的 Bucket 名称。
Endpoint	String	否	`https://s3.amazonaws.com`	仅当`Vendor`为`S3`时，为必填。 S3 协议 Endpoint，需以`http://`或`https://`开头。请根据源站信息填写。
CdnHost	String	否	`my-bucket.oss-cn-hangzhou.aliyuncs.com`	仅当`Vendor` 非 `URL`时，为选填。迁移源云服务商 CDN 域名，若不为空将使用该 CDN 域名下载三方云厂商的资源。
SkipHeader	Boolean	否	`false`	是否丢弃源 Header。取值如下所示： `true`：丢弃源 Header `false`：（默认）保留源 Header
Prefix	Array of String	否	`["home/aaaa"]`	仅迁移匹配的前缀列表文件。文件路径前缀无需包含桶名称，但需要完整路径。默认为空，表示对该存储 Bucket 内资源执行全量迁移。若不为空，表示仅做部分迁移，即指定迁移的文件路径前缀。
Regex	Array of String	否	`[".png"]`	仅迁移匹配的正则表达式列表的文件。默认为空，表示对该存储 Bucket 内资源执行全量迁移。说明多条正则表达式之间是"或"的关系，即源文件匹配任何一条正则表达式即视为符合迁移条件。正则过滤规则需要遍历源桶中的全部文件，如果源桶中文件数量较多会降低迁移速度。
TimeStart	String	否	`2019-06-02T00:00:00+08:00`	迁移文件起始时间点。仅迁移该查询时间段内新增或变更的文件。默认为空。日期格式按照 ISO8601 表示法，格式为：YYYY-MM-DDThh:mm:ss±hh:mm，比如`2019-06-02T00:00:00+08:00`。
TimeEnd	String	否	`2019-06-03T00:00:00+08:00`	迁移文件结束时间点。默认为空。仅迁移该查询时间段内新增或变更的文件。日期格式按照 ISO8601 表示法，格式为：YYYY-MM-DDThh:mm:ss±hh:mm，比如`2019-06-02T00:00:00+08:00`。
BucketInventoryDir	String	否	`cos_bucket_inventory/1311434967/test/buctet1/20240924_145226/1311434967/test/buctet1_instant_20240924_145226/data/`	仅当 `Vendor` 取值 `COS` 时，为选填。不为空，表示使用桶清单方式进行数据迁移；若为空，将遍历指定 `Bucket` 内的文件后再进行迁移。桶清单 csv 文件在第三方云存储 Bucket 中的存储目录路径。该路径不携带域名和 csv 清单文件信息，需要以`/`结尾。您可参考获取桶清单文件存储路径获取。
BucketInventorySchema	Array of String	否	`["", "", "Key", "Size", "", "ETag"]`	仅当 `BucketInventoryDir` 不为空时，为必填。桶清单文件的表头信息，需要传入实际桶清单文件内每列数据对应字段名称，并遵循原字段位置进行填写。您可参考获取桶清单文件解析位置获取解析 csv 文件所需的字段信息。 Key ：【必填】表示待迁移的资源存储 Key。 Size ：【推荐】表示待迁移的资源大小。 ETag ：【可选】表示待迁移资源的 ETag 值。说明 veImageX 按照该字段顺序对 csv 文件进行解析，获取待迁移文件详细信息。若位置填写错误，可能导致迁移失败。示例：若 csv 文件内 Key、Size和 ETag 分别位于整张数据表的第 3 列、第 4 列和第 6 列。那么，此时 `BucketInventorySchema取值应为` `["", "", "Key", "Size", "", "ETag"]`；若 csv 文件内 Key、Size和 ETag 分别位于整张数据表的第 2 列、第 4 列和第 5 列。那么，此时 `BucketInventorySchema取值应为` `["", "Key", "", "Size", "ETag", ""]`。注意 csv 文件内数据的位置可能会因为您配置桶清单时选择的清单内容而产生差异，具体请以实际为准。

Transcode

参数	类型	是否必选	示例值	描述
Adapt	Boolean	否	`false`	仅当转码/降级格式为 heic、webp、jpeg 时生效。是否开启自适应转码。 `true`：开启。开启后，将根据 `Format` 或者 `DemotionFmt` 指定格式进行自适应转码处理。 `false`：（默认）关闭
Format	String	是	`png`	目标转码格式，仅针对静图执行转码策略。支持的格式有 png、jpeg、heic、avif、webp、vvic。
Quality	Integer	是	`75`	转码质量参数，取值范围为 [1,100]。对于 PNG 为无损压缩，其他格式下其值越小，压缩率越高，画质越差。
AlphaDemotion	Boolean	否	`true`	包含透明通道的图片是否编码为降级格式。取值如下所示： `true`：降级 `false`：（默认）不降级
DemotionFmt	String	否	`heic`	降级编码格式，仅当`AlphaDemotion`为`true`时必填。支持的格式有 png、jpeg、heic、avif、webp、vvic。
EnableExif	Boolean	否	`false`	转码是否保留 exif 信息。取值如下所示： `true`：保留 `false`：（默认）不保留
SkipCMYK	Boolean	否	`false`	对带有 CMYK 色彩空间的图片，是否跳过转码处理直接存储原图。取值如下所示： `true`：是 `false`：（默认）否
ReserveJpegSize	Boolean	否	`false`	当 jpeg 原图在迁移中指定转码为 heic 图时， heic 图是否需要存储原图大小的数据。 `true`：是 `false`：（默认）否

Dst

参数	类型	是否必选	示例值	描述
ServiceId	String	是	`uh**7j`	迁移目标服务 ID，请提前新建服务。您可以在 veImageX 控制台服务管理页面，在创建好的图片服务中获取服务 ID。您也可以通过 OpenAPI 的方式获取服务 ID，具体请参考获取所有服务信息。
SkipBucket	Boolean	否	`true`	源 Bucket 名称保留规则。取值如下所示： `true`：不保留，迁移后资源访问 URI 中，不保留迁移源的 Bucket 名称。 `false`：（默认）保留，迁移后资源访问 URI 中，会保留迁移源的 Bucket 名称。
Prefix	String	否	`aaa/bbb/ccc/`	目标 key 前缀，即保存到到指定目录下。如需多重目录，请使用`/`分割，并以`/`结尾。默认为空，表示迁移到根目录。使用非 URL 方式迁移到根目录时：迁移后存储 Key 与源存储 Bucket 的文件存储 Key 相同。使用 Url 方式迁移到根目录时：迁移后存储 Key 与源 URL 中 Path 值相同。
UploadConf	Integer	否	`0`	同名文件覆盖规则配置。取值如下所示： `0`：（默认）直接覆盖同名文件 `1`：增加文件名后缀，后缀为任务 ID `2`：跳过同名文件，即不做迁移说明同名文件指文件在对象存储中的访问 Key 相同的文件，调用 veImageX 服务时会用到文件访问 Key。

RunStrategy

参数类型是否必选示例值描述

参数	类型	是否必选	示例值	描述
ReadQps	Array of Integer	否	`[100, 200, 300, 400, 500, 600, 700, 800, 900, 1000, 1100, 1200, 1300, 1400, 1500, 1600, 1700, 1800, 1900, 2000, 2100, 2200, 2300, 2400]`	源下载 QPS 限制。如取值不为空，则长度必须为 24，表示一天 24 小时内各小时的 QPS 限制值。默认无限制。取值为负值时，表示无限制取值为 0 时，表示对应时间不允许迁移
ReadRate	Array of Integer	否	`[100, 200, 300, 400, 500, 600, 700, 800, 900, 1000, 1100, 1200, 1300, 1400, 1500, 1600, 1700, 1800, 1900, 2000, 2100, 2200, 2300, 2400]`	源下载流量限制。单位为 Byte。如取值不为空，则长度必须为24，表示一天 24 小时内各小时的流量限制值。默认无限制。取值为负值时，表示无限制取值为 0 时，表示对应时间不允许迁移

ReadQps

Array of Integer

否

[100, 200, 300, 400, 500, 600, 700, 800, 900, 1000, 1100, 1200, 1300, 1400, 1500, 1600, 1700, 1800, 1900, 2000, 2100, 2200, 2300, 2400]

源下载 QPS 限制。如取值不为空，则长度必须为 24，表示一天 24 小时内各小时的 QPS 限制值。默认无限制。

取值为负值时，表示无限制
取值为 0 时，表示对应时间不允许迁移

ReadRate

Array of Integer

否

[100, 200, 300, 400, 500, 600, 700, 800, 900, 1000, 1100, 1200, 1300, 1400, 1500, 1600, 1700, 1800, 1900, 2000, 2100, 2200, 2300, 2400]

源下载流量限制。单位为 Byte。如取值不为空，则长度必须为24，表示一天 24 小时内各小时的流量限制值。默认无限制。

取值为负值时，表示无限制
取值为 0 时，表示对应时间不允许迁移

CallbackCfg

参数	类型	是否必选	示例值	描述
Method	String	是	`http`	回调方法。仅支持取值为 `http`。
Addr	String	是	`http://test.com`	回调地址。`Method`取值`http`时，填写公网可访问的 URL 地址，任务结束将向该地址发送 HTTP POST 请求。具体回调参数请参考回调内容。
IncludeEntry	Boolean	否	`false`	回调信息中是否包含具体迁移任务条目信息。取值如下所示： `true`：包含。仅包含迁移成功的任务条目信息，迁移失败的任务列表请在迁移完成后调用 ExportFailedMigrateTask 接口获取。 `false`：（默认）不包含。注意若任务中包含的条目数量过多，会导致回调消息体过大，增加回调失败的风险。因此建议仅在任务中条目量级不超过十万时使用该参数。
CallbackArgs	String	否	`App1`	任务维度自定义回调参数，最多可输入 1024 个任意类型字符，并在回调的 `CallbackArgs` 中返回。

返回参数

下表仅列出本接口特有的返回参数。更多信息请见公共返回参数。

参数	类型	示例值	描述
TaskId	String	`648c15f764f3c4abd95ad044`	创建成功的迁移任务 ID

请求示例

POST https://imagex.volcengineapi.com/?Action=CreateImageMigrateTask&Version=2023-05-01
{
    "Task": {
        "Name": "migrate-test",
        "Source": {
            "Vendor": "OSS",
            "AK": "AKTP8shJDSYGbi8*****",
            "SK": "PJDJSAJNNNCbE1E****",
            "Region": "cn-beijing",
            "Bucket": "storage-test",
            "Endpoint": "https://s3.amazonaws.com",
            "CdnHost": "my-bucket.oss-cn-hangzhou.aliyuncs.com",
            "SkipHeader": true,
            "Prefix": [
                "home/aaaa"
            ],
            "Regex": [
                "creases"
            ],
            "TimeStart": "2019-06-02T00:00:00+08:00",
            "TimeEnd": "2019-06-03T00:00:00+08:00"
        },
        "Transcode": {
            "Format": "png",
            "Quality": 75,
            "AlphaDemotion": true,
            "DemotionFmt": "heic",
            "EnableExif": true
        },
        "Dst": {
            "ServiceId": "uh**7j",
            "SkipBucket": true,
            "Prefix": "aaa/bbb/ccc/",
            "UploadConf": 0
        },
        "RunStrategy": {
            "ReadQps": [
                828
            ],
            "ReadRate": [
                187
            ]
        },
        "CallbackCfg": {
            "Method": "http",
            "Addr": "http://test.com",
            "IncludeEntry": true
        }
    }
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "2023061615574388A72E74B3D53A0B790E",
        "Action": "CreateImageMigrateTask",
        "Version": "2023-05-01",
        "Service": "imagex",
        "Region": "cn-north-1"
    },
    "Result": {
        "TaskId": "648c15f764f3c4abd95ad044"
    }
}

错误码

本接口无特有的错误码。更多信息请见公共错误码以及 veImageX 错误码。

服务端 SDK

veImageX 提供了配套的开发工具集 SDK，支持多种编程语言，帮助您更方便的调用 API。

历史版本

2018-08-01 版本 CreateImageMigrateTask 接口文档现已停止维护，建议您参考本文档使用最新版本。

回调参数

在新建迁移任务结束后 veImageX 将会把迁移任务结果以固定格式回调至您的自定义回调 URL中。您可以通过回调内容，进行后续的文件处理操作，具体如下所示：

回调参数	说明
TaskId	迁移任务 ID
TaskName	迁移任务名称
AccountId	账号 ID
Status	任务状态，取值如下所示： Done：全部迁移完成 Partial：部分迁移完成 Failed：迁移失败
Progress	迁移数据，具体内容参考 Progress。
CallbackArgs	新建任务时指定的任务维度自定义回调参数。
SuccessEntries	迁移成功的任务条目数据，仅当新建任务参数 CallbackCfg.IncludeEntry 为 true 时有值，数组长度等于 Progress.SuccessCnt。具体内容参考 SuccessEntries。

Progress

回调参数	说明
SuccessCnt	迁移成功文件数
SuccessAmount	迁移成功文件量，单位为 byte。
FailCnt	迁移失败文件数
TotalCnt	迁移文件总数
TotalAmount	迁移文件总量，单位为 byte。
ErrCode	错误码，仅当 Status 值为 Failed 时有值。
ErrMsg	错误信息，仅当 Status 值为 Failed 时有值。

SuccessEntries

回调参数	说明
Src	迁移文件源 key
FSize	文件大小，单位为 byte。
DstUri	迁移后存储至 veImageX 服务的文件存储 URI
ImgW	图片宽，仅当迁移文件为图片时有值。
ImgH	图片高，仅当迁移文件为图片时有值。
ImgFmt	图片格式，仅当迁移文件为图片时有值。
FrameCnt	图片帧数，仅当迁移文件为图片时有值。
ImgDur	动图时长，仅当图片为动图时有值。
Exif	图片 Exif 信息，仅当图片有 Exif 信息时有值。
CallbackArgs	URL 列表文件里指定的自定义回调参数。

JSON 类型回调示例如下所示：

{
   "TaskId":"648c15f764f3c4abd95ad044",
   "TaskName":"test",
   "AccountId":"89380**9273u09",
   "Status":"Partial",
   "CallbackArgs":"",
   "Progress":{
      "SuccessCnt":5,
      "SuccessAmount":87756112,
      "FailCnt":1,
      "TotalCnt":6,
      "TotalAmount":87756112,
      "ErrCode":0,
      "ErrMsg":""
   },
   "SuccessEntries":[
      {
         "Src":"example",
         "FSize":87090,
         "DstUri":"tos-cn-i-5s**fo/Example/imagex.png",
         "ImgW":900,
         "ImgH":3000,
         "ImgFmt":"png",
         "FrameCnt":80,
         "ImgDur":1,
         "Exif":{
            "ColorSpace":"sRGB",
            "ExifVersion":"Exif Version 2.1",
            "FlashPixVersion":"FlashPix Version 1.0",
            "Orientation":"Top-left",
            "PhotometricInterpretation":"RGB",
            "PixelXDimension":"1063",
            "PixelYDimension":"800",
            "ResolutionUnit":"Inch",
            "XResolution":"72",
            "YResolution":"72"
         },
         "CallbackArgs":""
      }
   ]
}