/ /

/ /

Librerías de clientes

Kotlin

Controlador de corrutinas de Kotlin

Conectar

Opciones de conexión

Stable API

Nota

La función API estable requiere MongoDB Server 5.0 o posterior.

Solo debe utilizar la función API estable si todos los servidores MongoDB a los que se conecta admiten esta función.

Overview

En esta guía, aprenderá a especificar la API estable al conectarse a una instancia o un conjunto de réplicas de MongoDB. Puede usar la función API estable para forzar al servidor a ejecutar operaciones con un comportamiento compatible con la versión de API especificada. Una versión de API define el comportamiento esperado de las operaciones que cubre y el formato de las respuestas del servidor. Si cambia a una versión de API diferente, no se garantiza la compatibilidad de las operaciones ni la similitud de las respuestas del servidor.

Cuando utiliza la función API estable con un controlador oficial de MongoDB, puede actualizar su controlador o servidor sin preocuparse por problemas de compatibilidad con versiones anteriores de los comandos cubiertos por la API estable.

Consulte la página de referencia de MongoDB en API estable para obtener más información, incluida una lista de comandos que cubre.

Las siguientes secciones describen cómo puede habilitar la API estable para su cliente MongoDB y las opciones que puede especificar.

Habilitar la API estable en un cliente MongoDB

Para habilitar la API estable, debe especificar una versión de la API en la configuración de su cliente MongoDB. Una vez que cree una instancia de MongoClient instancia con una versión de API específica, todos los comandos que ejecuta con ese cliente usan esa versión de la API estable.

Tip

Si necesita ejecutar comandos utilizando más de una versión de la API estable, cree una instancia de un cliente separado con esa versión.

Si necesita ejecutar comandos no contemplados por la API estable, asegúrese de que la opción "strict" esté deshabilitada. Consulte la sección "Opciones de la API estable" para obtener más información.

El siguiente ejemplo muestra cómo se puede crear una instancia de MongoClient que establece la versión de API estable y se conecta a un servidor realizando las siguientes operaciones:

Construya una instancia ServerApi utilizando la clase auxiliar ServerApi.Builder.
Especifique una versión de API estable utilizando una constante de la clase ServerApiVersion.
Construya una instancia MongoClientSettings utilizando la clase MongoClientSettings.Builder.
Especifique un servidor al que conectarse usando una instancia de ServerAddress.
Cree una instancia de MongoClient utilizando el método MongoClient.create() y pase su instancia de MongoClientSettings como parámetro.

val serverApi = ServerApi.builder()
    .version(ServerApiVersion.V1)
    .build()
// Replace the uri string placeholder with your MongoDB deployment's connection string
val uri = "<connection string>"
val settings = MongoClientSettings.builder()
    .applyConnectionString(ConnectionString(uri))
    .serverApi(serverApi)
    .build()
val client = MongoClient.create(settings)

Advertencia

Si especifica una versión de API y se conecta a un servidor MongoDB que no es compatible con la API estable, su aplicación podría generar una excepción al ejecutar un comando en su servidor MongoDB. Si usa un MongoClient que especifica la versión de API para consultar un servidor que no la admite, la consulta podría fallar con un mensaje de excepción con el siguiente texto:

'Unrecognized field 'apiVersion' on server...

Para obtener más información sobre los métodos y clases mencionados en esta sección, consulta la siguiente documentación de la API:

Opciones de Stable API

Puede habilitar o deshabilitar el comportamiento opcional relacionado con la API estable como se describe en la siguiente tabla.

Nombre de la opción	Descripción
Estricto	Optional. When set, if you call a command that is not part of the declared API version, the driver raises an exception. Default: false
Errores de desuso	Optional. When set, if you call a command that is deprecated in the declared API version, the driver raises an exception. Default: false

El siguiente ejemplo muestra cómo se pueden establecer las dos opciones en una instancia de ServerApi encadenando métodos en ServerApi.Builder:

val serverApi = ServerApi.builder()
    .version(ServerApiVersion.V1)
    .strict(true)
    .deprecationErrors(true)
    .build()

Para obtener más información sobre las opciones de esta sección, consulte la siguiente documentación de API:

Volver

Selección de servidores

Limite el tiempo de ejecución del servidor