注意
注意:群组和项目是同义词。您的 {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 | 字符串 | 必需 | 包含目标进程的副本集的名称。 |
托管-端口 | 字符串 | 必需 | 目标进程,作为 |
请求查询参数
以下查询参数为可选参数:
名称 | 类型 | 必要性 | 说明 | 默认 |
|---|---|---|---|---|
pretty | 布尔 | Optional | 指示响应正文是否采用 pretty-print 格式的标志。 |
|
envelope | 布尔 | Optional | 指示是否将响应包装在信封中的标志。 某些 API 客户端无法访问 HTTP 响应标头或状态代码。要解决这个问题,可在查询中设置 envelope=true。 对于返回一个结果的端点,响应体包括:
|
|
请求正文参数
请求正文接受以下可选的可调参数。如果发送空正文,请使用 {}。
名称 | 类型 | 说明 | 默认 |
|---|---|---|---|
stepDownSecs | 整型 | 降级后的主节点 (primary node in the replica set) 在一段时间内无法重新参加选举的秒数。必须大于 |
|
secondaryCatchUpPeriodSecs | 整型 | 在主节点 (primary node in the replica set) 降级之前,等待滞后的从节点(secondary node from replica set)赶上的秒数。必须大于或等于 | 无 |
expiresAfterSeconds | 整型 | 请求在作业过期前排队等待自动化代理提取的秒数。必须大于 |
|
响应
Ops Manager 返回 202 Accepted 以及一个以 获取单个重新选举作业 终结点为指向点的 Location 标头,响应正文中包含重新选举作业文档。
名称 | 类型 | 说明 |
|---|---|---|
id | 字符串 | 用于标识重新选举作业的唯一 24 位十六进制数字 string。 |
groupId | 字符串 | 用于标识项目的唯一的 24 位十六进制数字字符串。 |
操作 | 字符串 | 此作业执行的操作。返回 |
ReplicaSetName | 字符串 | 目标副本集的名称。 |
主机名 | 字符串 | 目标进程的主机名。 |
端口 | 整型 | 目标进程的端口。 |
状态 | 字符串 | 作业的状态。返回以下值之一: |
noop | 布尔 | 指示操作是否作为无操作 (no-op) 完成的标志。如果代理运行作业时目标进程已经是从节点(secondary node from replica set),则返回 |
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 | 可调参数超出范围,或者请求正文包含 |
400 | AUTOMATION_AGENT_VERSION_NOT_SUPPORTED | 目标托管的自动化代理版本低于 |
401 | 用户未授权 | 该 API 密钥没有 |
401 | USER_CANNOT_ACCESS_ORG | 调用者不在项目的组织内。 |
404 | AUTOMATION_CONFIG_NOT_FOUND | 该项目没有已发布的自动化配置。 |
404 | CLUSTER_NOT_FOUND |
|
404 | PROCESS_NOT_IN_CLUSTER |
|
409 | REELECTION_AGENT_NOT_RESPONDING | 目标主机的自动化代理最近没有向 MongoDB Ops Manager 发送网络探测(ping)。 |
409 | REELECTION_ALREADY_IN_PROGRESS | 此副本集已有重新选举作业在排队或运行中。 |