Performs a master-replica switchover for an ApsaraDB for Redis instance to switch node roles. You can use this operation for disaster recovery drills. If the ApsaraDB for Redis instance is deployed across multiple zones, you can also use this operation to connect an application to the zone that is closest to the application.

Note For more information about nearby access for applications to connect to instances that are deployed across zones, see Manually switch workloads from a master node to a replica node.

When you call this operation for an instance, make sure that the instance is an ApsaraDB for Redis Community Edition instance or a performance-enhanced or hybrid-storage instance of the ApsaraDB for Redis Enhanced Edition (Tair). For more information about performance-enhanced instances and hybrid-storage instances, see Performance-enhanced instances and Hybrid-storage instances (phased out).

A call to this operation has the following impacts on your instance:

  • The data nodes in the instance may change to the Read-only state and experience transient connections for a few seconds. Make sure that your applications are configured to automatically reconnect to the instance.
  • If an instance enters the Switching state, you cannot manage this instance. For example, you cannot modify the instance configurations or migrate the instance to another zone.


OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes SwitchInstanceHA

The operation that you want to perform. Set the value to SwitchInstanceHA.

RegionId String No cn-hangzhou

The region ID of the instance. You can call the DescribeRegions operation to query the most recent region list.

InstanceId String Yes r-bp1zxszhcgatnx****

The ID of the instance. You can call the DescribeInstances operation to query the ID of the instance.

NodeId String No 56****19,56****20

The IDs of data nodes. You can call the DescribeRoleZoneInfo operation to obtain the value of the CustinsId parameter. Separate multiple node IDs with commas (,). all indicates that all data nodes are specified.

Note This parameter is valid and required only for read/write splitting instances or cluster instances of ApsaraDB for Redis.
SwitchMode Integer No 0

The time when to perform the switchover. Default value: 0. Valid values:

  • 0: immediately switches the roles.
  • 1: switches the roles during the maintenance window.
Note You can call the ModifyInstanceMaintainTime operation to modify the maintenance window of an ApsaraDB for Redis instance.
SwitchType String Yes AvailablePriority

The switching mode. Valid values:

  • AvailablePriority: prioritizes availability.
  • ReliabilityPriority: prioritizes reliability.
  • DataConsistency: prioritizes data consistency.
Note You must evaluate the requirements for data and services based on your business scenarios and then select a switching mode.

Response parameters

Parameter Type Example Description
RequestId String 5D622714-AEDD-4609-9167-F5DDD3D1****

The ID of the request.


Sample requests

&<Common request parameters>

Sample success responses

XML format

HTTP/1.1 200 OK


JSON format

HTTP/1.1 200 OK

  "RequestId" : "5D622714-AEDD-4609-9167-F5DDD3D1****"

Error codes

For a list of error codes, visit the API Error Center.