文档首页/ 分布式消息服务RocketMQ版/ API参考（联盟区域）/ API V2（推荐）/ 元数据迁移/ 新建元数据迁移任务
更新时间：2026-04-03 GMT+08:00
在线调试
CLI示例
查看PDF
分享

新建元数据迁移任务

功能介绍

新建元数据迁移任务。

URI

POST /v2/{project_id}/instances/{instance_id}/metadata

表1 路径参数

参数

是否必选

参数类型

描述

project_id

是

String

参数解释：

项目ID，获取方式请参见获取项目ID。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

instance_id

是

String

参数解释：

实例ID。获取方法如下：调用“查询所有实例列表”接口，从响应体中获取实例ID。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。
表2 Query参数

参数

是否必选

参数类型

描述

overwrite

是

String

参数解释：

true开启同名覆盖，会对已有的同名元数据的配置进行修改，false时当Topic或group已存在则会报错。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

name

是

String

参数解释：

迁移任务名称，名称规则参考创建实例。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

type

是

String

参数解释：

迁移任务类型，分为自建RocketMQ上云(rocketmq)、自建RabbitMQ上云(rabbitToRocket)

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

请求参数

表3 请求Body参数

参数

是否必选

参数类型

描述

topic_config_table

否

Map<String,MigrationRocketMqTopicConfig>

参数解释：

RocketMQ Topic 元数据，键为Topic名，值为topic配置，迁移任务类型为自建RocketMQ上云(rocketmq)时必填。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

subscription_group_table

否

Map<String,MigrationRocketMqSubscriptionGroup>

参数解释：

RocketMQ消费组元数据，键为消费组名，值为消费组配置，迁移任务类型为自建RocketMQ上云(rocketmq)时必填。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

vhosts

否

Array of MigrationRabbitVhostMetadata objects

参数解释：

RabbitMQ vhost元数据列表，迁移任务类型为自建RabbitMQ上云(rabbitToRocket)时必填。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

queues

否

Array of MigrationRabbitQueueMetadata objects

参数解释：

RabbitMQ队列元数据列表，迁移任务类型为自建RabbitMQ上云(rabbitToRocket)时必填。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

exchanges

否

Array of MigrationRabbitExchangeMetadata objects

参数解释：

RabbitMQ交换机元数据列表，迁移任务类型为自建RabbitMQ上云(rabbitToRocket)时必填。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

bindings

否

Array of MigrationRabbitBindingMetadata objects

参数解释：

RabbitMQ binding元数据列表，迁移任务类型为自建RabbitMQ上云(rabbitToRocket)时必填。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。
表4 MigrationRocketMqTopicConfig

参数

是否必选

参数类型

描述

topic_name

否

String

参数解释：

Topic名称。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

order

否

Boolean

参数解释：

是否有序消息。

约束限制：

不涉及。

取值范围：

  • true：有序消息。

  • false：无序消息。

默认取值：

false。

perm

否

Integer

参数解释：

Topic权限。

约束限制：

不涉及。

取值范围：

  • PUB：拥有发布权限。

  • SUB：拥有订阅权限。

  • PUB|SUB：拥有发布订阅权限。

  • DENY：无权限。

默认取值：

6。

read_queue_nums

否

Integer

参数解释：

读队列个数。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

16。

write_queue_nums

否

Integer

参数解释：

写队列个数。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

16。

topic_filter_type

否

String

参数解释：

Topic过滤类型。

约束限制：

不涉及。

取值范围：

  • SINGLE_TAG：单标签

    • MULTI_TAG：多标签

    默认取值：

不涉及。

topic_sys_flag

否

Integer

参数解释：

Topic系统标志位。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

0。
表5 MigrationRocketMqSubscriptionGroup

参数

是否必选

参数类型

描述

group_name

否

String

参数解释：

消费组名。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

consume_broadcast_enable

否

Boolean

参数解释：

是否允许以广播模式消费。

约束限制：

不涉及。

取值范围：

  • true：允许以广播模式消费。

  • false：不允许以广播模式消费。

默认取值：

不涉及。

consume_enable

否

Boolean

参数解释：

是否允许消费。

约束限制：

不涉及。

取值范围：

  • true：允许消费。

  • false：不允许消费。

默认取值：

true。

consume_from_min_enable

否

Boolean

参数解释：

是否从最小偏移量开始消费。

约束限制：

不涉及。

取值范围：

  • true：是。

  • false：不是。

默认取值：

true。

notify_consumer_ids_changed_enable

否

Boolean

参数解释：

消费者ID变化时是否通知。

约束限制：

不涉及。

取值范围：

  • true：是。

  • false：不是。

默认取值：

true。

retry_max_times

否

Integer

参数解释：

消费最大重试次数。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

16。

retry_queue_nums

否

Integer

参数解释：

消费最大重试次数。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

1。

which_broker_when_consume_slow

否

Long

参数解释：

慢消费时选择的broker节点ID

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

1。
表6 MigrationRabbitVhostMetadata

参数

是否必选

参数类型

描述

name

否

String

参数解释：

vhost名称。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。
表7 MigrationRabbitQueueMetadata

参数

是否必选

参数类型

描述

vhost

否

String

参数解释：

vhost名称。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

name

否

String

参数解释：

队列名称。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

durable

否

Boolean

参数解释：

是否持久化。

约束限制：

不涉及。

取值范围：

  • true：持久化。

  • false：不进行持久化。

默认取值：

不涉及。
表8 MigrationRabbitExchangeMetadata

参数

是否必选

参数类型

描述

vhost

否

String

参数解释：

vhost名称。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

name

否

String

参数解释：

交换机名称。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

type

否

String

参数解释：

交换机类型。

约束限制：

不涉及。

取值范围：

  • topic：支持routing key的模糊匹配。

  • direct：按routing key精确匹配进行消息路由。

  • fanout：广播模式，消息会发送到所有绑定的队列，忽略routing key。

  • headers：根据消息头（headers）中的键值对进行路由，而不是routing key。

默认取值：

不涉及。

durable

否

Boolean

参数解释：

是否持久化。

约束限制：

不涉及。

取值范围：

  • true：持久化。

  • false：不进行持久化。

默认取值：

不涉及。
表9 MigrationRabbitBindingMetadata

参数

是否必选

参数类型

描述

vhost

否

String

参数解释：

vhost名称。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

source

否

String

参数解释：

消息的来源。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

destination

否

String

参数解释：

消息的目标。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

destination_type

否

String

参数解释：

目标的类型。

约束限制：

不涉及。

取值范围：

  • exchange：交换机。

  • queue：队列。

默认取值：

不涉及。

routing_key

否

String

参数解释：

路由键。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

响应参数

状态码：200

表10 响应Body参数

参数

参数类型

描述

task_id

String

参数解释：

任务ID。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

请求示例

  • 创建元数据迁移任务，迁移其他厂商或自建RocketMQ实例的元数据到云上RocketMQ实例。

    POST https://{endpoint}/v2/{project_id}/instances/{instance_id}/metadata?overwrite=true&name=task-123&type=rocketmq

{
  "topic_config_table" : {
    "topic-test1" : {
      "order" : false,
      "perm" : 6,
      "read_queue_nums" : 3,
      "topic_filter_type" : "SINGLE_TAG",
      "topic_name" : "topic-test1",
      "topic_sys_flag" : 0,
      "write_queue_nums" : 3
    }
  },
  "subscription_group_table" : {
    "group-test1" : {
      "consume_broadcast_enable" : true,
      "consume_enable" : true,
      "consume_from_min_enable" : true,
      "group_name" : "group-test1",
      "notify_consumer_ids_changed_enable" : true,
      "retry_max_times" : 2,
      "retry_queue_nums" : 1,
      "which_broker_when_consume_slow" : 1
    }
  }
}

  • 创建元数据迁移任务，迁移RabbitMQ的元数据到云上RocketMQ实例。

    POST https://{endpoint}/v2/{project_id}/instances/{instance_id}/metadata?overwrite=true&name=task-123&type=rabbitToRocket

{
  "vhosts" : [ {
    "name" : "DeleteVhost123"
  } ],
  "queues" : [ {
    "name" : "test-001",
    "vhost" : "/",
    "durable" : false
  } ],
  "exchanges" : [ {
    "name" : "direct",
    "vhost" : "/",
    "type" : "topic",
    "durable" : false
  } ],
  "bindings" : [ {
    "source" : "direct",
    "vhost" : "/",
    "destination" : "test-001",
    "destination_type" : "queue",
    "routing_key" : "test-001"
  } ]
}

响应示例

状态码：200

创建成功。

{
  "task_id" : "6cf4dcd3-8471-4139-8b5b-8a3a71f704c7"
}

状态码

状态码

描述

200

创建成功。

错误码

请参见错误码。

父主题： 元数据迁移