You need to enable JavaScript to run this app.
导航
veImageX
  • 文档首页
    • /
  • veImageX

创建数据迁移任务

最近更新时间：2023.11.14 14:50:50

首次发布时间：2023.06.16 18:19:08

我的收藏

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

迁移准备

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

源服务商准备内容文档地址
阿里云OSSAK、SK、Bucket迁移准备
腾讯云COSAK、SK、Bucket、Region迁移准备
七牛云KodoAK、SK、Bucket迁移准备
百度云BOSAK、SK、Bucket、Region迁移准备
华为云OBSAK、SK、Bucket、Region迁移准备
优刻得（Ucloud File）AK、SK、Bucket、Region迁移准备
AWS国际站AK、SK、Bucket迁移准备
其他 S3 协议存储AK、SK、Bucket、Region、Endpoint请根据实际源站获取
URL迁移 URL 列表文件（.txt）公网访问地址-

注意事项

  • 请求频率：单用户请求频率限制为 10 次/秒。

  • 超时时间：接口超时时间约为 10 秒。

  • 迁移后文件名自定义规则：
    • 不支持空格，如果中间有空格将会导致自定义命名失败。
    • 不支持以/开头或结尾，不支持/连续出现，最大长度限制为 180 个字节。
    • 若开头或结尾存在/，则/将被自动删除；若连续存在多个/，则会被缩减仅保留一个/。

  • 服务地址：veImageX 在全球多个区域部署，每个区域有自己对应的 OpenAPI 域名，不支持跨区域调用。具体详情请查看服务地址。

请求说明

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

请求参数

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

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

Query

参数类型是否必选示例值描述
ActionString是CreateImageMigrateTask接口名称。当前 API 的名称为 CreateImageMigrateTask。
VersionString是2018-08-01接口版本。当前 API 的版本为 2018-08-01。

Body

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

Task

参数类型是否必选示例值描述
NameString是migrate-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。

  • 仅当Vendor为URL时，需填写 URL 列表文件地址（公网 URL 地址）。文件中为待迁移的 URL 列表，每行一个。

    注意

    若您需要对迁移后文件批量重命名，请在 URL 的同一行内增加指定迁移后文件的 StoreKey，URL 和对应的 StoreKey 之间使用;分隔。StoreKey 填写规则详见自定义迁移文件名规则。

- 当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。

Transcode

参数类型是否必选示例值描述
FormatString是png目标转码格式，仅针对静图执行转码策略。支持的格式有 png、jpeg、heic、avif、webp、vvic。
QualityInteger是75转码质量参数，取值范围为 [1,100]。对于 PNG 为无损压缩，其他格式下其值越小，压缩率越高，画质越差。

AlphaDemotion

Boolean

否

true

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

  • true：降级
  • false：（默认）不降级
DemotionFmtString否heic降级编码格式，仅当AlphaDemotion为true时必填。支持的格式有 png、jpeg、heic、avif、webp、vvic。

EnableExif

Boolean

否

false

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

  • 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

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

IncludeEntry

Boolean

否

false

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

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

注意

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

返回参数

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

参数类型示例值描述
TaskIdString648c15f764f3c4abd95ad044创建成功的迁移任务 ID

示例

请求示例

POST https://imagex.volcengineapi.com/?Action=CreateImageMigrateTask&Version=2018-08-01
{
   "Task":{
      "Name":"test",
      "Source":{
         "Vendor":"URL",
         "Bucket":"https://example.com/imagex-common/101b***18c~tplv-obj.image"
      },
      "Dst":{
         "UploadConf":1,
         "ServiceId":"yk****fd"
      }
   }
}

返回示例

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

错误码

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

服务端 SDK

为了方便您快速开发，veImageX 提供了配套的服务端 SDK，同时支持多种编程语言。建议您使用服务端 SDK 来调用 API，当前已提供了Java SDK供您调试使用。

回调参数

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

回调参数说明
TaskId迁移任务 ID
TaskName迁移任务名称
AccountId账号 ID

Status

任务状态，取值如下所示：

  • Done：全部迁移完成
  • Partial：部分迁移完成
  • Failed：迁移失败
Progress迁移数据，具体内容参考 Progress。
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 信息时有值。

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

{
   "TaskId":"648c15f764f3c4abd95ad044",
   "TaskName":"test",
   "AccountId":"89380**9273u09",
   "Status":"Partial",
   "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"
         }
      }
   ]
}