On this page

Show all

Help Center/ Distributed Message Service for RocketMQ/ API Reference/ APIs V2 (Recommended)/ Metadata Migration/ Creating a Metadata Migration Task

Creating a Metadata Migration Task

Updated on 2025-04-01 GMT+08:00

View PDF

Function

This API is used to create a metadata migration task.

URI

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

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID. For details, see Obtaining a Project ID.
instance_id	Yes	String	Instance ID.

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
overwrite	Yes	String	true: Configurations in the metadata file with the same name as the uploaded file will be overwritten. false: An error is reported when a topic or group already exists.
name	Yes	String	Migration task name. For details about the naming rules, see the API for creating an instance.
type	Yes	String	Migration task type. The value can be rocketmq or rabbitToRocket.

Request Parameters

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
topicConfigTable	No	Map<String,MigrationRocketMqTopicConfig>	RocketMQ instance topic metadata. The topic name is the key and the topic configuration is the value. This parameter is mandatory for rocketmq migration tasks (from self-built RocketMQ instances to DMS for RocketMQ).
subscriptionGroupTable	No	Map<String,MigrationRocketMqSubscriptionGroup>	RocketMQ consumer group metadata. The consumer group name is the key and the configuration is the value. This parameter is mandatory for rocketmq migration tasks (from self-built RocketMQ instances to DMS for RocketMQ).
vhosts	No	Array of MigrationRabbitVhostMetadata objects	RabbitMQ virtual host metadata list. This parameter is mandatory for rabbitToRocket migration tasks (from self-built RabbitMQ instances to DMS for RocketMQ).
queues	No	Array of MigrationRabbitQueueMetadata objects	RabbitMQ queue metadata list. This parameter is mandatory for rabbitToRocket migration tasks (from self-built RabbitMQ instances to DMS for RocketMQ).
exchanges	No	Array of MigrationRabbitExchangeMetadata objects	RabbitMQ exchange metadata list. This parameter is mandatory for rabbitToRocket migration tasks (from self-built RabbitMQ instances to DMS for RocketMQ).
bindings	No	Array of MigrationRabbitBindingMetadata objects	RabbitMQ binding metadata list. This parameter is mandatory for rabbitToRocket migration tasks (from self-built RabbitMQ instances to DMS for RocketMQ).

**Table 4** MigrationRocketMqTopicConfig
Parameter	Mandatory	Type	Description
topicName	No	String	Topic name.
topic_name	No	String	Topic name.
order	No	Boolean	Indicates whether a message is an ordered message.
perm	No	Integer	Topic permission.
readQueueNums	No	Integer	Number of read queues.
read_queue_nums	No	Integer	Number of read queues.
writeQueueNums	No	Integer	Number of write queues.
write_queue_nums	No	Integer	Number of write queues.
topicFilterType	No	String	Topic filtering type. SINGLE_TAG: single tag MULTI_TAG: multiple tags
topic_filter_type	No	String	Topic filtering type. SINGLE_TAG: single tag MULTI_TAG: multiple tags
topicSysFlag	No	Integer	Topic system flag.
topic_sys_flag	No	Integer	Topic system flag.

**Table 5** MigrationRocketMqSubscriptionGroup
Parameter	Mandatory	Type	Description
groupName	No	String	Consumer group name.
group_name	No	String	Consumer group name.
consumeBroadcastEnable	No	Boolean	Indicates whether to enable broadcast.
consume_broadcast_enable	No	Boolean	Indicates whether to enable broadcast.
consumeEnable	No	Boolean	Indicates whether to enable consumption.
consume_enable	No	Boolean	Indicates whether to enable consumption.
consumeFromMinEnable	No	Boolean	Indicates whether to enable consumption from the earliest offset.
consume_from_min_enable	No	Boolean	Indicates whether to enable consumption from the earliest offset.
notifyConsumerIdsChangedEnable	No	Boolean	Indicates whether to notify consumer ID changes.
notify_consumer_ids_changed_enable	No	Boolean	Indicates whether to notify consumer ID changes.
retryMaxTimes	No	Integer	Maximum number of consumption retries.
retry_max_times	No	Integer	Maximum number of consumption retries.
retryQueueNums	No	Integer	Number of retry queues.
retry_queue_nums	No	Integer	Number of retry queues.
whichBrokerWhenConsumeSlow	No	Long	ID of the broker selected for slow consumption.
which_broker_when_consume_slow	No	Long	ID of the broker selected for slow consumption.

**Table 6** MigrationRabbitVhostMetadata
Parameter	Mandatory	Type	Description
name	No	String	Virtual host name.

**Table 7** MigrationRabbitQueueMetadata
Parameter	Mandatory	Type	Description
vhost	No	String	Virtual host name.
name	No	String	Queue name.
durable	No	Boolean	Indicates whether to enable data persistence.

**Table 8** MigrationRabbitExchangeMetadata
Parameter	Mandatory	Type	Description
vhost	No	String	Virtual host name.
name	No	String	Switch name.
type	No	String	Exchange type.
durable	No	Boolean	Indicates whether to enable data persistence.

**Table 9** MigrationRabbitBindingMetadata
Parameter	Mandatory	Type	Description
vhost	No	String	Virtual host name.
source	No	String	Message source.
destination	No	String	Message target.
destination_type	No	String	Message target type.
routing_key	No	String	Routing key.

Response Parameters

Status code: 200

**Table 10** Response body parameters
Parameter	Type	Description
task_id	String	Task ID.

Example Requests

Creating a metadata migration task to migrate the metadata from other vendors' or self-built RocketMQ instances to DMS for RocketMQ.

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

{
  "topicConfigTable" : {
    "topic-test1" : {
      "order" : false,
      "perm" : 6,
      "readQueueNums" : 3,
      "topicFilterType" : "SINGLE_TAG",
      "topicName" : "topic-test1",
      "topicSysFlag" : 0,
      "writeQueueNums" : 3
    }
  },
  "subscriptionGroupTable" : {
    "group-test1" : {
      "consumeBroadcastEnable" : true,
      "consumeEnable" : true,
      "consumeFromMinEnable" : true,
      "groupName" : "group-test1",
      "notifyConsumerIdsChangedEnable" : true,
      "retryMaxTimes" : 2,
      "retryQueueNums" : 1,
      "whichBrokerWhenConsumeSlow" : 1
    }
  }
}

Creating a metadata migration task to migrate the metadata of RabbitMQ instances to DMS for 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"
  } ]
}

Example Responses

Status code: 200

Successful

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

Status Codes

Status Code	Description
200	Successful

Error Codes

See Error Codes.

Parent Topic: Metadata Migration

Previous topic: Metadata Migration

Next topic: Querying All Migration Tasks or a Specified Migration Task of an Instance

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel