Menu Docs
Página inicial do Docs
/
Idiomas
/
JavaScript
/
Node.js
/
Fundamentals

Stable API

Nesta página

  • Visão geral
  • Habilitar a API estável em um cliente MongoDB
  • Opções de API estáveis

Observação

O recurso API estável requer MongoDB Server 5.0 ou posterior.

Use o recurso API estável somente se todos os servidores MongoDB que você está conectando para suportar esse recurso.

Visão geral

Neste guia, você pode aprender a especificar a API estável ao se conectar a uma instância do MongoDB ou a um conjunto de réplicas. Você pode usar o recurso API estável para forçar o servidor a executar operações com comportamento compatível com a versão da API especificada. Uma versão da API define o comportamento esperado das operações que ela cobre e o formato das respostas do servidor. Se você alterar para uma versão de API diferente, as operações não terão garantia de serem compatíveis e as respostas do servidor não terão garantia de serem semelhantes.

Quando você usa o recurso API estável com um driver oficial do MongoDB, você pode atualizar seu driver ou servidor sem se preocupar com compatibilidade com versões anteriores problemas dos comandos cobertos pela API estável.

Consulte a página de referência do MongoDB na Stable API para obter mais informações, incluindo uma lista de comandos que ela abrange.

As seções a seguir descrevem como você pode habilitar a API estável para seu cliente MongoDB e as opções que você pode especificar.

Habilitar a API estável em um cliente MongoDB

Para habilitar a API estável, você deve especificar uma versão da API no MongoClientOptions passado para seu MongoClient. Depois de instanciar uma instância MongoClient com uma versão de API especificada, todos os comandos que você executa com essa versão da API estável.

Dica

Você deve criar um novo cliente para cada versão da API estável em
qual você deseja executar um comando.

Para executar comandos que não são cobertos pela Stable API, certifique-se de que a opção "strict" esteja desativada. Consulte a seção sobre Opções de Stable API para obter mais informações.

O exemplo abaixo mostra como você pode instanciar um MongoClient que define a versão da API estável e se conecta a um servidor executando as seguintes operações:

  • Especifique um URI do servidor ao qual se conectar.

  • Especifique uma versão de API estável no objeto MongoClientOptions, usando uma constante do objeto ServerApiVersion.

  • Instancie um MongoClient, passando o URI e o MongoClientOptions para o construtor.

const { MongoClient, ServerApiVersion } = require("mongodb");
const uri = "mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&w=majority";
const client = new MongoClient(uri, { serverApi: ServerApiVersion.v1 });

Aviso

Se você especificar uma versão da API e se conectar a um servidor MongoDB que não não suporta a API estável, seu aplicativo pode lançar um erro quando conectando-se ao seu servidor MongoDB com o seguinte texto:

MongoParseError: Invalid server API version=...

Para obter mais informações sobre os métodos e as classes mencionadas nesta seção, consulte a seguinte documentação da API:

Opções de API estáveis

Você pode habilitar ou desabilitar o comportamento opcional relacionado à API estável como descrito na tabela a seguir.

Nome da opção
Descrição
Versão
Required. Specifies the version of the Stable API.

Default: null
estrito
Optional. When set, if you call a command that is not part of the declared API version, the driver raises an exception.

Default: false
deprecationErrors
Optional. When set, if you call a command that is deprecated in the declared API version, the driver raises an exception.

Default: false

O exemplo a seguir mostra como você pode definir as opções da interface do ServerApi.

const { MongoClient, ServerApiVersion } = require("mongodb");
const uri = "mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&w=majority";
const client = new MongoClient(uri,
    {
        serverApi: {
            version: ServerApiVersion.v1,
            strict: true,
            deprecationErrors: true,
        }
    });

Para obter mais informações sobre as opções nesta seção, consulte a seguinte documentação da API:

Voltar

Habilitar TLS em uma conexão