You need to enable JavaScript to run this app.
导航
创建数据迁移任务
最近更新时间:2024.06.13 11:52:44首次发布时间:2024.05.06 15:18:33

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

迁移准备

已支持迁移数据源与迁移准备内容如下表所示。

源服务商准备内容文档地址
阿里云OSSAccess Key、Secret Key、Bucket迁移准备
腾讯云COSAccess Key、Secret Key、Bucket、Region迁移准备
七牛云KodoAccess Key、Secret Key、Bucket迁移准备
百度云BOSAccess Key、Secret Key、Bucket、Region迁移准备
华为云OBSAccess 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-TypeStringapplication/json请求头字段

Query

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

Body

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

Task

参数类型是否必选示例值描述
NameStringmigrate-test自定义迁移任务名称
SourceObject of Source-迁移源信息
TranscodeObject of Transcode-转码配置
DstObject of Dst-目的信息
RunStrategyObject of RunStrategy-迁移策略
CallbackCfgObject 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

Bucket 所在地区。仅当Vendor 非 URL/OSS/KODO/AWS时为必填。

  • 请参考云数据迁移准备获取对应阿里云OSS、腾讯云COS、七牛云KODO、百度云BOS、华为云OBS、 优刻得(Ucloud File)、AWS国际站的 Bucket 地区。
  • 对于其他 S3 协议存储的 Bucket 地区,请根据其具体源站信息填写。

Bucket

String

storage-test

源端 Bucket。

  • 仅当VendorURL时,需填写 URL 列表文件地址(公网 URL 地址)。

说明

支持指定迁移文件和转码后迁移文件进行重命名,详见 URL 列表迁移文件说明

  • Vendor为其他时,请填写对应云服务商所需迁移数据的 Bucket 名称。您可参考云数据迁移准备获取对应阿里云OSS、腾讯云COS、七牛云KODO、百度云BOS、华为云OBS、 优刻得(Ucloud File)、AWS国际站的 Bucket 名称。

Endpoint

String

https://s3.amazonaws.com

仅当VendorS3时必填。
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

Transcode

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

Adapt

Boolean

false

仅当转码/降级格式为 heic、webp、jpeg 时生效。
是否开启自适应转码。

  • true:开启。开启后,将根据 Format 或者 DemotionFmt 指定格式进行自适应转码处理。
  • false:(默认)关闭
FormatStringpng目标转码格式,仅针对静图执行转码策略。支持的格式有 png、jpeg、heic、avif、webp、vvic。
QualityInteger75转码质量参数,取值范围为 [1,100]。对于 PNG 为无损压缩,其他格式下其值越小,压缩率越高,画质越差。

AlphaDemotion

Boolean

true

包含透明通道的图片是否编码为降级格式。取值如下所示:

  • true:降级
  • false:(默认)不降级
DemotionFmtStringheic降级编码格式,仅当AlphaDemotiontrue时必填。支持的格式有 png、jpeg、heic、avif、webp、vvic。

EnableExif

Boolean

false

转码是否保留 exif 信息。取值如下所示:

  • true:保留
  • false:(默认)不保留

SkipCMYK

Boolean

false

对带有 CMYK 色彩空间的图片,是否跳过转码处理直接存储原图。取值如下所示:

  • 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 时,表示对应时间不允许迁移

CallbackCfg

参数类型是否必选示例值描述
MethodStringhttp回调方法。仅支持取值为 http
AddrStringhttp://test.com回调地址。Method取值http时,填写公网可访问的 URL 地址,任务结束将向该地址发送 HTTP POST 请求。具体回调参数请参考回调内容

IncludeEntry

Boolean

false

回调信息中是否包含具体迁移任务条目信息。取值如下所示:

  • true:包含。仅包含迁移成功的任务条目信息,迁移失败的任务列表请在迁移完成后调用 ExportFailedMigrateTask 接口获取。
  • false:(默认)不包含。

注意

若任务中包含的条目数量过多,会导致回调消息体过大,增加回调失败的风险。因此建议仅在任务中条目量级不超过十万时使用该参数。

CallbackArgsStringApp1任务维度自定义回调参数,最多可输入 1024 个任意类型字符,并在回调的 CallbackArgs 中返回。

返回参数

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

参数类型示例值描述
TaskIdString648c15f764f3c4abd95ad044创建成功的迁移任务 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。

回调参数

在新建迁移任务结束后 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 信息时有值。
CallbackArgsURL 列表文件里指定的自定义回调参数。

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":""
         }
      }
   ]
}