Para agentes de IA: um índice de documentação está disponível em https://www.mongodb.com/pt-br/docs/llms.txt — as versões de markdown de todas as páginas estão disponíveis anexando .md a qualquer caminho de URL.

Solicitação de promoção de um secundário de conjunto de réplicas

Observação

Grupos e projetos são termos sinônimos. Seu {PROJECT-ID} é igual ao ID do seu projeto. Para grupos existentes, o ID do grupo/projeto permanece o mesmo. Esta página usa o termo grupo, que é mais familiar, ao se referir a descrições. O ponto de extremidade permanece conforme indicado no documento.

Use este ponto de extremidade para solicitar que um secundário específico de um conjunto de réplicas seja promovido a primário. O MongoDB Ops Manager congela os outros secundários elegíveis para que o processo de destino, e não outro nó, vença a eleição. O agente de automação do host de destino executa o procedimento de congelamento e rebaixamento em seu próximo check-in.

Se o processo de destino não for um secundário elegível quando o agente executar a tarefa, por exemplo, porque já é primário, ou é um árbitro, oculto ou nó sem direito a voto, a tarefa falhará com uma mensagem descritiva.

URL base: https://{OPSMANAGER-HOST}:{PORT}/api/public/v1.0

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

A chave de API que faz esta solicitação deve ter a função Project Automation Admin.

Nome
Tipo
necessidade
Descrição

ID do grupo

string

Obrigatório

String única de 24 dígitos hexadecimais que identifica seu projeto.

RS-ID

string

Obrigatório

Nome do conjunto de réplicas que contém o processo de destino.

hospedar-PORTA

string

Obrigatório

Processo de destino, como hostname:port. Este processo deve ser atualmente um secundário ativo e elegível.

Os seguintes parâmetros de query são opcionais:

Nome
Tipo
necessidade
Descrição
Default

pretty

booleano

Opcional

Sinalizador que indica se o corpo da resposta está em um formato pretty-print.

false

envelope

booleano

Opcional

Sinalizador que indica se deve envolver a resposta em um envelope.

Alguns clientes de API não podem acessar os cabeçalhos de resposta HTTP ou o código de status. Para corrigir isso, defina envelope=true na query.

Para endpoints que retornam um resultado, o corpo da resposta inclui:

  • status: Código de resposta HTTP

  • content: Corpo de resposta esperado

false

O corpo da solicitação aceita os seguintes ajustes opcionais. Se você enviar um corpo vazio, use {}.

Nome
Tipo
Descrição
Default

stepDownSecs

inteiro

Número de segundos que o primário de saída permanece inelegível para reeleição. Deve ser maior que 0.

60

secondaryCatchUpPeriodSecs

inteiro

Número de segundos a aguardar por um secundário com atraso para recuperar antes que o primário seja rebaixado. Deve ser maior ou igual a 0. Se você omitir este campo, mongod aplica seu próprio padrão.

none

freezeSecs

inteiro

Número de segundos que o MongoDB Ops Manager congela os outros secundários elegíveis para que o destino vença a eleição. Deve ser maior que 0 e maior ou igual a stepDownSecs.

O maior entre 120 e stepDownSecs

expiresAfterSeconds

inteiro

Número de segundos que a solicitação permanece na fila para um agente de automação coletar antes que a tarefa expire. Deve ser maior que 0.

O maior entre 300 e freezeSecs

Importante

Durante a janela de congelamento, todos os outros secundários elegíveis são congelados e não podem se candidatar à eleição. Mantenha freezeSecs o mais curto que seu ambiente permitir. Se o host de destino ficar inacessível durante o congelamento, o conjunto de réplicas poderá ficar sem um primário até que o congelamento expire.

O MongoDB Ops Manager retorna 202 Accepted com um cabeçalho Location que aponta para o ponto de extremidade obter uma tarefa de reeleição e o documento da tarefa de reeleição no corpo da resposta.

Nome
Tipo
Descrição

id

string

String única de 24dígitos hexadecimais que identifica a tarefa de reeleição.

groupId

string

String única de 24 dígitos hexadecimais que identifica o projeto.

ação

string

Ação que esta tarefa executa. Retorna STEP_UP.

ReplicaSetName

string

Nome do conjunto de réplicas de destino.

nome do host

string

Nome de host do processo de destino.

Porta

inteiro

Porta do processo de destino.

Status

string

Status da tarefa. Retorna um dos seguintes valores: QUEUED, RUNNING, COMPLETED, FAILED ou EXPIRED.

noop

booleano

Sinalizador que indica se a operação foi concluída como um no-op.

mensagem

string

Detalhes legíveis por humanos sobre a tarefa. O MongoDB Ops Manager preenche este campo após o agente relatar um resultado.

Criado

string

Timestamp, no formato ISO 8601 UTC, quando o Ops Manager criou o tarefa.

lastUpdated

string

Carimbo de data/hora, no formato ISO 8601 UTC, quando o MongoDB Ops Manager atualizou a tarefa pela última vez.

expira

string

Carimbo de data/hora, no formato ISO 8601 UTC, após o qual um agente de automação não seleciona mais esta tarefa.

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}:stepUp?pretty=true" \ --data '{ "stepDownSecs": 60, "freezeSecs": 120 }'
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_UP", "replicaSetName": "rs0", "hostname": "node2.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:39:59Z"}
HTTP Status
Código de erro
Descrição

202

--

Solicitação aceita. Retorna o documento da tarefa de reeleição.

400

INVALID_PARAMETER

Um parâmetro ajustável está fora da faixa, ou freezeSecs é menor que stepDownSecs.

400

AUTOMATION_AGENT_VERSION_NOT_SUPPORTED

O agente de automação do hospedar de destino é mais antigo que 109.0.0.9226-1.

401

USER_UNAUTHORIZED

A chave de API não tem a função Project Automation Admin.

401

USUÁRIO_NÃO_PODE_ACESSAR_ORGANIZAÇÃO

O chamador está fora da organização do projeto.

404

AUTOMAÇÃO_CONFIGURAÇÃO_NÃO_ENCONTRADA

O projeto não tem nenhuma configuração de automação publicada.

404

CLUSTER_NOT_FOUND

RS-ID não corresponde a um conjunto de réplicas na implantação do projeto.

404

PROCESS_NOT_IN_CLUSTER

HOST-PORT não é um nó do conjunto de réplicas nomeado.

409

REELECTION_AGENT_NOT_RESPONDING

O agente de automação do host de destino não enviou um ping ao MongoDB Ops Manager recentemente.

409

REELECTION_ALREADY_IN_PROGRESS

Uma tarefa de reeleição já está na fila ou em execução para este conjunto de réplicas.