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 Stable API somente se ele for suportado por todos os servidores do MongoDB aos quais você está se conectando.

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

Se você precisar executar comandos usando mais de uma versão da stable API, instancie um cliente separado com essa versão.

Se você precisar executar comandos não cobertos pela stable API, certifique-se de que a opção "strict" esteja desativada. Consulte a seção sobre opções destable 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:

← Habilitar TLS em uma conexão
Autenticação →

Nesta página