请求副本集主节点降级

注意

注意：群组和项目是同义词。您的 {PROJECT-ID} 与您的项目 ID 相同。对于现有群组，群组/项目 ID 保持不变。当引用说明时，此页面将使用“群组”这个更为人熟知的术语。终结点仍如文档中所述。

使用此端点请求副本集的当前主节点 (primary node in the replica set)退出，从而触发新的选举。 Ops Manager将背景作业排队，以便目标主机的自动化代理在下次签入时运行。

如果在代理运行作业时目标进程不是可写主节点 (primary node in the replica set)，则作业将以空操作完成，而不是失败。主节点 (primary node in the replica set)节点降级后，在 stepDownSecs 指定的时间内没有资格重新当选。

基本 URL： https://{OPSMANAGER-HOST}:{PORT}/api/public/v1.0

Resource

POST /groups/{GROUP-ID}/replicaSets/{RS-ID}/process/{HOST-PORT}:stepDown

所需角色

发出此请求的API密钥必须具有 Project Automation Admin角色。

请求路径参数

名称	类型	必要性	说明
群组 ID（group ID）	字符串	必需	标识项目的唯一 24 位十六进制数字字符串。
RS- ID	字符串	必需	包含目标进程的副本集名称。
HOST-PORT	字符串	必需	目标进程，如 `hostname:port`。此进程当前必须是副本集的主节点 (primary node in the replica set)。

请求查询参数

以下查询参数为可选参数：

名称	类型	必要性	说明	默认
pretty	布尔	Optional	指示响应正文是否采用美观打印格式的标志。	`false`
envelope	布尔	Optional	指示是否将响应包装在信封中的标志。某些 API 客户端无法访问 HTTP 响应标头或状态代码。要解决这个问题，可在查询中设置 envelope=true。对于返回一个结果的端点，响应体包括： `status`： HTTP响应代码 `content`：预期响应正文	`false`

请求正文参数

请求正文接受以下可选可调参数。如果发送空正文，请使用 {}。

名称	类型	说明	默认
StepDownSecs	整型	降级的主节点 (primary node in the replica set)没有资格重新选举的秒数。必须大于 `0`。	`60`
secondaryCatchUpPeriodSecs	整型	在主节点 (primary node in the replica set)节点降级之前等待滞后的从从节点(secondary node from replica set)赶上的秒数。必须大于或等于 `0`。如果省略此字段，`mongod` 将应用自己的默认。	无
expiresAfterSeconds	整型	在作业到期之前，请求保持排队等待自动化代理接收的秒数。必须大于 `0`。	`300`

响应

Ops Manager返回带有 Location 标头的202 Accepted，该标头指向获取一个重选作业端点，以及响应正文中的重选作业文档。

名称	类型	说明
id	字符串	唯一的 24-十六进制数字字符串，用于标识重选作业。
groupId	字符串	用于标识项目的唯一的 24 位十六进制数字字符串。
操作	字符串	此作业执行的操作。返回 `STEP_DOWN`。
ReplicaSetName	字符串	目标副本集的名称。
主机名	字符串	目标进程的主机名。
端口	整型	目标进程的端口。
状态	字符串	作业状态。返回以下值之一：`QUEUED`、`RUNNING`、`COMPLETED`、`FAILED` 或 `EXPIRED`。
noOp	布尔	指示操作是否作为无操作完成的标志。如果在代理运行作业时目标进程已经是从从节点(secondary node from replica set)，则返回 `true`。
message	字符串	有关作业的人类可读详细信息。 Ops Manager在代理报告结果后填充此字段。
已创建	字符串	Ops Manager创建作业的时间戳，采用 ISO 8601 UTC 格式。
lastUpdated	字符串	Ops Manager上次更新作业的时间戳，采用 ISO 8601 UTC 格式。
expires	字符串	时间戳，采用 ISO 8601 UTC 格式，超过该时间后自动化代理将不再接收此作业。

请求示例

1 curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
2      --header "Accept: application/json" \
3      --header "Content-Type: application/json" \
4      --include \
5      --request POST "https://<OpsManagerHost>:<Port>/api/public/v1.0/groups/{GROUP-ID}/replicaSets/{RS-ID}/process/{HOST-PORT}:stepDown?pretty=true" \
6      --data '{
7        "stepDownSecs": 60,
8        "secondaryCatchUpPeriodSecs": 10
9      }'

响应示例

响应标头

HTTP/1.1 202 Accepted
Vary: Accept-Encoding
Content-Type: application/json
Location: https://<OpsManagerHost>:<Port>/api/public/v1.0/groups/{GROUP-ID}/replicaSets/{RS-ID}/reElectionJobs/{REELECTION-JOB-ID}
Strict-Transport-Security: max-age=300
Date: {dateInUnixFormat}
Connection: keep-alive
Content-Length: {requestLengthInBytes}
X-MongoDB-Service-Version: gitHash={gitHash}; versionString={ApplicationVersion}

响应体

1 {
2   "id": "665a1234567890abcdef1234",
3   "groupId": "5c8100bcf2a30b12ff88258f",
4   "action": "STEP_DOWN",
5   "replicaSetName": "rs0",
6   "hostname": "node1.example.com",
7   "port": 27017,
8   "status": "QUEUED",
9   "noOp": false,
10   "message": null,
11   "created": "2026-08-11T05:37:59Z",
12   "lastUpdated": "2026-08-11T05:37:59Z",
13   "expires": "2026-08-11T05:42:59Z"
14 }

响应代码

HTTP Status	错误代码	说明
202	--	请求已接受。返回重选作业文档。
400	INVALID_PARAMETER	可调参数超出范围，或者请求正文包含 `freezeSecs`。
400	AUTOMATION_AGENT_VERSION_NOT_SUPPORTED	目标主机的自动化代理早于 `109.0.0.9226-1`。
401	USER_UNAUTHORIZED	API密钥没有 `Project Automation Admin`角色。
401	USER_CANNOT_ACCESS_ORG	调用者在项目组织之外。
404	AUTOMATION_CONFIG_NOT_FOUND	项目没有已发布的自动化配置。
404	CLUSTER_NOT_FOUND	`RS-ID` 与项目部署中的副本集不匹配。
404	PROCESS_NOT_IN_CLUSTER	`HOST-PORT` 不是指定副本集的成员。
409	REELECTION_AGENT_NOT_RESPONDING	目标主机的自动化代理最近未对Ops Manager执行 ping 操作。
409	REELECTION_ALREADY_IN_PROGRESS	该副本集的重选作业已排队或运行。

1	curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
2	--header "Accept: application/json" \
3	--header "Content-Type: application/json" \
4	--include \
5	--request POST "https://<OpsManagerHost>:<Port>/api/public/v1.0/groups/{GROUP-ID}/replicaSets/{RS-ID}/process/{HOST-PORT}:stepDown?pretty=true" \
6	--data '{
7	"stepDownSecs": 60,
8	"secondaryCatchUpPeriodSecs": 10
9	}'

1	{
2	"id": "665a1234567890abcdef1234",
3	"groupId": "5c8100bcf2a30b12ff88258f",
4	"action": "STEP_DOWN",
5	"replicaSetName": "rs0",
6	"hostname": "node1.example.com",
7	"port": 27017,
8	"status": "QUEUED",
9	"noOp": false,
10	"message": null,
11	"created": "2026-08-11T05:37:59Z",
12	"lastUpdated": "2026-08-11T05:37:59Z",
13	"expires": "2026-08-11T05:42:59Z"
14	}