Stable API
Nesta página
- O que é a API estável e você deve usá-la?
- Garantia de compatibilidade com versões anteriores
- Declare a versão da API
- Verificando versões da API do cliente
- Criar um cliente rigoroso
- Migrar para comandos de API estáveis
- Como usar comandos e recursos fora da API estável
- Comandos de API estáveis
- Parâmetros
- Comportamento
- Respostas de erro de API estáveis
O que é a API estável e você deve usá-la?
A API estável MongoDB (anteriormente denominada API versionada) permite atualizar seu servidor MongoDB e garantir que as alterações de comportamento entre as versões MongoDB não quebrem seu aplicativo.
O MongoDB 5.0 introduz a API estável para aplicativos que se comunicam com produtos de servidor MongoDB. A API Stable permite que você especifique em qual versão da API do MongoDB seu aplicativo é executado.
A API estável oferece estabilidade de API a longo prazo para aplicativos e oferece suporte a versões mais frequentes e atualizações automáticas do servidor. Isso permite que seus aplicativos aproveitem os recursos lançados rapidamente sem correr o risco de alterações retrógradas.
O comportamento padrão da sua conexão de driver continuará funcionando como esperado, mesmo se você não especificar explicitamente uma apiVersion.
A Stable API engloba o subconjunto de comandos MongoDB que os aplicativos usam para ler e gravar dados, criar coleções e índices e executar outras tarefas comuns.
Observação
A partir de fevereiro de 2022, a terminologia "API versionada" foi alterada para "API estável". Todos os conceitos e funcionalidades permanecem os mesmos com essa mudança de nomenclatura.
Garantia de compatibilidade com versões anteriores
Seu aplicativo não sofrerá alterações significativas de comportamento resultantes de atualizações do servidor. Esta garantia é válida enquanto o novo servidor suportar a versão da API especificada.
Para garantir compatibilidade com versões anteriores, seu aplicativo deve:
Declare uma versão da API
Use apenas comandos e recursos suportados na versão da API especificada
Implemente com uma versão suportada de um driver oficial
Declare a versão da API
➤ Use o menu suspenso Selecione a linguagem no canto superior direito para definir a linguagem dos exemplos nesta página.
Para usar a API Stable, atualize para o driver mais recente e crie o MongoClient da sua aplicação:
mongosh --apiVersion 1
mongoc_client_t *client = NULL; mongoc_server_api_t *server_api = NULL; mongoc_server_api_version_t server_api_version; bson_error_t error; /* For a replica set, include the replica set name and a seedlist of the * members in the URI string; e.g. * uri_repl = "mongodb://mongodb0.example.com:27017,mongodb1.example.com:" \ * "27017/?replicaSet=myRepl"; * client = mongoc_client_new (uri_repl); * For a sharded cluster, connect to the mongos instances; e.g. * uri_sharded = * "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/"; * client = mongoc_client_new (uri_sharded); */ /* Create a mongoc_client_t without server API options configured. */ client = get_client_for_version_api_example (); mongoc_server_api_version_from_string ("1", &server_api_version); server_api = mongoc_server_api_new (server_api_version); assert (mongoc_client_set_server_api (client, server_api, &error));
using namespace mongocxx; uri client_uri{"mongodb://localhost"}; // Create an option set for API v1 const auto server_api_opts = options::server_api{options::server_api::version_from_string("1")}; // Store it in the set of client options const auto client_opts = options::client{} .server_api_opts(server_api_opts); // Set the version // Create a new client with the options mongocxx::client client{client_uri, client_opts};
var connectionString = "mongodb://localhost"; var serverApi = new ServerApi(ServerApiVersion.V1); var mongoClientSettings = MongoClientSettings.FromConnectionString(connectionString); mongoClientSettings.ServerApi = serverApi; var mongoClient = new MongoClient(mongoClientSettings);
// StableAPIExample is an example of creating a client with stable API. func StableAPIExample() { ctx := context.TODO() // For a replica set, include the replica set name and a seedlist of the members in the URI string; e.g. // uri := "mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017/?replicaSet=myRepl" // For a sharded cluster, connect to the mongos instances; e.g. // uri := "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/" uri := mtest.ClusterURI() serverAPIOptions := options.ServerAPI(options.ServerAPIVersion1) clientOpts := options.Client().ApplyURI(uri).SetServerAPIOptions(serverAPIOptions) client, err := mongo.Connect(clientOpts) if err != nil { panic(err) } defer func() { _ = client.Disconnect(ctx) }() }
MongoClient client = MongoClients.create( MongoClientSettings.builder() .applyConnectionString(new ConnectionString(<connection string>)) .serverApi( ServerApi.builder() .version(ServerApiVersion.V1) .build() ).build() ); return client;
from pymongo.server_api import ServerApi client = AsyncIOMotorClient(uri, server_api=ServerApi("1"))
client = new MongoClient(uri, { serverApi: { version: '1' } });
$serverApi = new \MongoDB\Driver\ServerApi('1'); $client = new \MongoDB\Client($uriString, [], ['serverApi' => $serverApi]);
from pymongo.server_api import ServerApi MongoClient(uri, server_api=ServerApi("1"))
client = Mongo::Client.new(uri_string, server_api: {version: "1"})
let mut options = ClientOptions::parse(&uri).await?; let server_api = ServerApi::builder().version(ServerApiVersion::V1).build(); options.server_api = Some(server_api); let client = Client::with_options(options)?;
let opts = MongoClientOptions( serverAPI: MongoServerAPI(version: .v1) ) let client = try MongoClient(uri, using: myEventLoopGroup, options: opts)
let opts = MongoClientOptions( serverAPI: MongoServerAPI(version: .v1) ) let client = try MongoClient(uri, options: opts)
"1"
atualmente é a única versão disponível da API.
Por padrão, os clientes são não rigorosos. Um cliente não rigoroso permite que você execute qualquer comando, independentemente de pertencer ou não à API estável.
Verificando versões da API do cliente
Use o comando serverStatus
para verificar a versão da API configurada do seu aplicativo. Para cada aplicativo conectado à instância do MongoDB, um appname
aparece no documento apiVersions
.
Consulte metrics.apiVersions para obter mais informações.
db.runCommand( { serverStatus: 1 } ).metrics.apiVersions
Criar um cliente rigoroso
Um cliente rigoroso rejeita todos os comandos fora da Stable API. As tentativas de usar comandos fora da Stable API receberão a resposta APIVersionError.
Um cliente estrito também ignora tipos de índice não suportados durante o planejamento da query e sua execução.
Use o código de amostra para criar um cliente rigoroso:
mongosh --apiVersion 1 --apiStrict
mongoc_client_t *client = NULL; mongoc_server_api_t *server_api = NULL; mongoc_server_api_version_t server_api_version; bson_error_t error; /* For a replica set, include the replica set name and a seedlist of the * members in the URI string; e.g. * uri_repl = "mongodb://mongodb0.example.com:27017,mongodb1.example.com:" \ * "27017/?replicaSet=myRepl"; * client = mongoc_client_new (uri_repl); * For a sharded cluster, connect to the mongos instances; e.g. * uri_sharded = * "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/"; * client = mongoc_client_new (uri_sharded); */ /* Create a mongoc_client_t without server API options configured. */ client = get_client_for_version_api_example (); mongoc_server_api_version_from_string ("1", &server_api_version); server_api = mongoc_server_api_new (server_api_version); mongoc_server_api_strict (server_api, true); assert (mongoc_client_set_server_api (client, server_api, &error));
using namespace mongocxx; uri client_uri{"mongodb://localhost"}; // Create an option set for API v1 const auto server_api_opts = options::server_api{options::server_api::version_from_string("1")} .strict(true); // Enable strict mode for the server API // Store it in the set of client options const auto client_opts = options::client{} .server_api_opts(server_api_opts); // Set the version and options // Create a new client with the options mongocxx::client client{client_uri, client_opts};
var connectionString = "mongodb://localhost"; var serverApi = new ServerApi(ServerApiVersion.V1, strict: true); var mongoClientSettings = MongoClientSettings.FromConnectionString(connectionString); mongoClientSettings.ServerApi = serverApi; var mongoClient = new MongoClient(mongoClientSettings);
// StableAPIStrictExample is an example of creating a client with strict stable API. func StableAPIStrictExample() { ctx := context.TODO() // For a replica set, include the replica set name and a seedlist of the members in the URI string; e.g. // uri := "mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017/?replicaSet=myRepl" // For a sharded cluster, connect to the mongos instances; e.g. // uri := "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/" uri := mtest.ClusterURI() serverAPIOptions := options.ServerAPI(options.ServerAPIVersion1).SetStrict(true) clientOpts := options.Client().ApplyURI(uri).SetServerAPIOptions(serverAPIOptions) client, err := mongo.Connect(clientOpts) if err != nil { panic(err) } defer func() { _ = client.Disconnect(ctx) }() }
MongoClient client = MongoClients.create( MongoClientSettings.builder() .applyConnectionString(new ConnectionString(<connection string>)) .serverApi( ServerApi.builder() .version(ServerApiVersion.V1) .strict(true) .build() ).build() ); return client;
client = AsyncIOMotorClient(uri, server_api=ServerApi("1", strict=True))
client = new MongoClient(uri, { serverApi: { version: '1', strict: true } });
$serverApi = new \MongoDB\Driver\ServerApi('1', true); $client = new \MongoDB\Client($uriString, [], ['serverApi' => $serverApi]);
MongoClient(uri, server_api=ServerApi("1", strict=True))
client = Mongo::Client.new(uri_string, server_api: {version: "1", strict: true})
let mut options = ClientOptions::parse(&uri).await?; let server_api = ServerApi::builder() .version(ServerApiVersion::V1) .strict(true) .build(); options.server_api = Some(server_api); let client = Client::with_options(options)?;
let opts = MongoClientOptions( serverAPI: MongoServerAPI(version: .v1, strict: true) ) let client = try MongoClient(uri, using: myEventLoopGroup, options: opts)
let opts = MongoClientOptions( serverAPI: MongoServerAPI(version: .v1, strict: true) ) let client = try MongoClient(uri, options: opts)
Migrar para comandos de API estáveis
Para migrar seu aplicativo para usar a API estável, você deve:
Execute o conjunto de testes da sua aplicação com as novas opções do MongoClient.
Determine quais comandos e recursos você está usando que estão fora da API estável.
Migre para comandos e recursos alternativos na API estável.
Depois que seu aplicativo usar apenas comandos e recursos definidos na API estável, você poderá implementá-lo novamente com as novas opções MongoClient e ter certeza de que futuras atualizações de servidor não afetarão negativamente seu aplicativo.
Como usar comandos e recursos fora da API estável
Para usar comandos e recursos fora da API estável, você pode se conectar à sua implantação com um cliente não rigoroso. Por padrão, os clientes são não rigorosos.
Para criar um cliente não rigoroso, use o seguinte código de amostra:
mongosh --apiVersion 1
mongoc_client_t *client = NULL; mongoc_server_api_t *server_api = NULL; mongoc_server_api_version_t server_api_version; bson_error_t error; /* For a replica set, include the replica set name and a seedlist of the * members in the URI string; e.g. * uri_repl = "mongodb://mongodb0.example.com:27017,mongodb1.example.com:" \ * "27017/?replicaSet=myRepl"; * client = mongoc_client_new (uri_repl); * For a sharded cluster, connect to the mongos instances; e.g. * uri_sharded = * "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/"; * client = mongoc_client_new (uri_sharded); */ /* Create a mongoc_client_t without server API options configured. */ client = get_client_for_version_api_example (); mongoc_server_api_version_from_string ("1", &server_api_version); server_api = mongoc_server_api_new (server_api_version); mongoc_server_api_strict (server_api, false); assert (mongoc_client_set_server_api (client, server_api, &error));
using namespace mongocxx; uri client_uri{"mongodb://localhost"}; // Create an option set for API v1 const auto server_api_opts = options::server_api{options::server_api::version_from_string("1")} .strict(false); // Explicitly disable strict mode for the server API // Store it in the set of client options const auto client_opts = options::client{} .server_api_opts(server_api_opts); // Set the version and options // Create a new client with the options mongocxx::client client{client_uri, client_opts};
var connectionString = "mongodb://localhost"; var serverApi = new ServerApi(ServerApiVersion.V1, strict: false); var mongoClientSettings = MongoClientSettings.FromConnectionString(connectionString); mongoClientSettings.ServerApi = serverApi; var mongoClient = new MongoClient(mongoClientSettings);
// StableAPINonStrictExample is an example of creating a client with non-strict stable API. func StableAPINonStrictExample() { ctx := context.TODO() // For a replica set, include the replica set name and a seedlist of the members in the URI string; e.g. // uri := "mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017/?replicaSet=myRepl" // For a sharded cluster, connect to the mongos instances; e.g. // uri := "mongodb://mongos0.example.com:27017,mongos1.example.com:27017/" uri := mtest.ClusterURI() serverAPIOptions := options.ServerAPI(options.ServerAPIVersion1).SetStrict(false) clientOpts := options.Client().ApplyURI(uri).SetServerAPIOptions(serverAPIOptions) client, err := mongo.Connect(clientOpts) if err != nil { panic(err) } defer func() { _ = client.Disconnect(ctx) }() }
MongoClient client = MongoClients.create( MongoClientSettings.builder() .applyConnectionString(new ConnectionString(<connection string>)) .serverApi( ServerApi.builder() .version(ServerApiVersion.V1) .strict(false) .build() ).build() );
client = AsyncIOMotorClient(uri, server_api=ServerApi("1", strict=False))
client = new MongoClient(uri, { serverApi: { version: '1', strict: false } });
$serverApi = new \MongoDB\Driver\ServerApi('1', false); $client = new \MongoDB\Client($uriString, [], ['serverApi' => $serverApi]);
MongoClient(uri, server_api=ServerApi("1", strict=False))
client = Mongo::Client.new(uri_string, server_api: {version: "1", strict: false})
let mut options = ClientOptions::parse(&uri).await?; let server_api = ServerApi::builder() .version(ServerApiVersion::V1) .strict(false) .build(); options.server_api = Some(server_api); let client = Client::with_options(options)?;
let opts = MongoClientOptions( serverAPI: MongoServerAPI(version: .v1, strict: false) ) let client = try MongoClient(uri, using: myEventLoopGroup, options: opts)
let opts = MongoClientOptions( serverAPI: MongoServerAPI(version: .v1, strict: false) ) let client = try MongoClient(uri, options: opts)
Usar esse cliente não rigoroso permite que você execute comandos fora da API estável. Por exemplo, este cliente não rigoroso permite a você executar o comando createUser
.
Importante
Os comandos e recursos fora da API estável não têm as mesmas garantias de compatibilidade com versões anteriores que as alternativas com controle de versão.
Comandos de API estáveis
Os comandos do banco de dados incluídos no Stable API V1 dependem da versão MongoDB que você está usando. Para exibir os comandos de banco de dados incluídos na API estável e na versão do MongoDB que foram introduzidos, consulte Log de alterações da API estável.
Parâmetros
Você pode especificar os parâmetros opcionais a seguir para API estável no código de conexão do driver MongoDB do seu aplicativo. Verifique a documentação do driver MongoDB para o driver que você usa em seu aplicativo para obter mais informações:
Parâmetro | Tipo | Descrição |
---|---|---|
string | Especifica a versão da API. | |
booleano |
Se você especificar apiStrict, também deverá especificar apiVersion. Se não for especificado, o padrão será | |
booleano |
Se não for especificado, o padrão será |
Comportamento
Parameter Validation
A partir do MongoDB 5.0, os comandos do banco de dados API V1 geram um erro se for passado um parâmetro não aceito explicitamente pelo comando.
Respostas de erro de API estáveis
Esta tabela mostra respostas de erro para solicitações problemáticas da API estável.
Resposta do servidor | Solicitar |
---|---|
Especifica | |
Especifica | |
Especifica uma apiVersion que o servidor não suporta. | |
Especifica |