对于 AI 代理:可在 https://www.mongodb.com/zh-cn/docs/llms.txt 获取文档索引—通过在任何 URL 路径后添加 .md 可获取所有页面的 Markdown 版本。

请求副本集主节点降级

注意

注意:群组和项目是同义词。您的 {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

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

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

名称
类型
必要性
说明

群组 ID(group ID)

字符串

必需

标识项目的唯一 24 位十六进制数字字符串。

RS-ID

字符串

必需

包含目标进程的副本集的名称。

托管-端口

字符串

必需

目标进程,作为 hostname:port。此过程目前必须是副本集的主节点 (primary node in the replica set)。

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

名称
类型
必要性
说明
默认

pretty

布尔

Optional

指示响应正文是否采用 pretty-print 格式的标志。

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 返回 202 Accepted 以及一个以 获取单个重新选举作业 终结点为指向点的 Location 标头,响应正文中包含重新选举作业文档。

名称
类型
说明

id

字符串

用于标识重新选举作业的唯一 24 位十六进制数字 string。

groupId

字符串

用于标识项目的唯一的 24 位十六进制数字字符串。

操作

字符串

此作业执行的操作。返回 STEP_DOWN。

ReplicaSetName

字符串

目标副本集的名称。

主机名

字符串

目标进程的主机名。

端口

整型

目标进程的端口。

状态

字符串

作业的状态。返回以下值之一:QUEUED、RUNNING、COMPLETED、FAILED 或 EXPIRED。

noop

布尔

指示操作是否作为无操作 (no-op) 完成的标志。如果代理运行作业时目标进程已经是从节点(secondary node from replica set),则返回 true。

message

字符串

关于该作业的人类可读详细信息。代理报告结果后,MongoDB Ops Manager 会填充此字段。

已创建

字符串

Ops Manager创建作业的时间戳,采用 ISO 8601 UTC 格式。

最后更新

字符串

MongoDB Ops Manager 最后更新作业的时间戳(ISO 8601 UTC 格式)。

expires

字符串

ISO 8601 UTC 格式的时间戳,在此时间之后,自动化代理将不再执行此作业。

curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --include \ --request POST "https://<OpsManagerHost>:<Port>/api/public/v1.0/groups/{GROUP-ID}/replicaSets/{RS-ID}/process/{HOST-PORT}:stepDown?pretty=true" \ --data '{ "stepDownSecs": 60, "secondaryCatchUpPeriodSecs": 10 }'
HTTP/1.1 202 AcceptedVary: Accept-EncodingContent-Type: application/jsonLocation: https://<OpsManagerHost>:<Port>/api/public/v1.0/groups/{GROUP-ID}/replicaSets/{RS-ID}/reElectionJobs/{REELECTION-JOB-ID}Strict-Transport-Security: max-age=300Date: {dateInUnixFormat}Connection: keep-aliveContent-Length: {requestLengthInBytes}X-MongoDB-Service-Version: gitHash={gitHash}; versionString={ApplicationVersion}
{ "id": "665a1234567890abcdef1234", "groupId": "5c8100bcf2a30b12ff88258f", "action": "STEP_DOWN", "replicaSetName": "rs0", "hostname": "node1.example.com", "port": 27017, "status": "QUEUED", "noOp": false, "message": null, "created": "2026-08-11T05:37:59Z", "lastUpdated": "2026-08-11T05:37:59Z", "expires": "2026-08-11T05:42:59Z"}
HTTP Status
错误代码
说明

202

--

请求已接受。返回重新选举作业文档。

400

INVALID_PARAMETER

可调参数超出范围,或者请求正文包含 freezeSecs。

400

AUTOMATION_AGENT_VERSION_NOT_SUPPORTED

目标托管的自动化代理版本低于 109.0.0.9226-1。

401

用户未授权

该 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

目标主机的自动化代理最近没有向 MongoDB Ops Manager 发送网络探测(ping)。

409

REELECTION_ALREADY_IN_PROGRESS

此副本集已有重新选举作业在排队或运行中。