Para agentes de IA: hay un índice de documentación disponible en https://www.mongodb.com/es/docs/llms.txt — versiones en markdown de todas las páginas están disponibles agregando .md a cualquier ruta URL.

Crear un clúster efímero de Atlas

Compila y prueba con MongoDB usando un clúster efímero de Atlas, un clúster gratuito temporal (M0) que puedes crear y al que puedes conectarte sin una cuenta de Atlas ni claves de API. Un clúster efímero es una buena solución cuando un agente de codificación de IA, o un desarrollador que trabaja con uno, necesita una base de datos on-demand para iniciar un nuevo proyecto, crear un prototipo de una aplicación o probar una idea.

Para crear un clúster efímero y obtener una cadena de conexión lista para usar en menos de un minuto, envía una solicitud POST al siguiente endpoint:

https://cloud.mongodb.com/api/atlas/v2/unauth/ephemeralClusters:create

Para conocer el flujo de trabajo completo, los encabezados necesarios y los detalles de la respuesta, consulte la Guía de inicio rápido.

A menos que reclames el cúmulo efímero, Atlas lo pausa 48 horas después de la creación y lo elimina 7 días después de la creación. Para reclamar el clúster, abre el claimUrl desde la respuesta create e inicia sesión en Atlas. Reclamar convierte el clúster efímero en un clúster libre estándar sin fecha de caducidad. Un agente puede crear y conectarse al clúster de forma autónoma, pero solo un humano puede reclamarlo.

Un clúster efímero es un clúster de Atlas Free (M0) con una vida útil limitada. Para leer y guardar sus datos, puede conectarse al clúster con la cadena de conexión devuelta por la respuesta de creación. Hasta que reclame el clúster, no puede escalar el nivel de clúster, agregar usuario de base de datos, restringir el acceso IP ni realizar otras operación administrativas.

Un clúster efímero no reclamado tiene las siguientes especificaciones fijas:

  • Nivel de clúster: Gratuito (M0).

  • Proveedor de nube y región: AWS us-east-1.

  • Acceso IP: El clúster permite las conexiones desde cualquier dirección IP (0.0.0.0/0).

  • Vida útil limitada: A menos que reclames el clúster, Atlas lo pausa 48 horas después de la creación y lo elimina 7 días después de la creación. Mientras está pausado, el clúster es inaccesible.

Dado que un clúster efímero es un clúster gratuito, también se aplican todos los límites de los clústeres gratuitos, entre los que se incluyen:

  • Almacenamiento: máximo de 512 MB, incluidos los índices.

  • Versión del servidor MongoDB: 8.0.

  • Rendimiento: máximo de 100 operaciones totales de lectura y guardado por segundo.

  • Conexiones: máximo de 500 conexiones simultáneas.

Para obtener una lista completa de las limitaciones del clúster gratuito, consulta Límites del clúster gratuito de Atlas.

Utilice el siguiente flujo de trabajo API para crear un clúster efímero con una sola solicitud POST y conectarse a él con la cadena de conexión devuelta. Este flujo de trabajo funciona sin claves API ni cuenta Atlas. Un agente de codificación IA puede completar todos los pasos necesarios sin intervención humana.

1

Envíe una solicitud POST al siguiente punto de conexión:

https://cloud.mongodb.com/api/atlas/v2/unauth/ephemeralClusters:create

La solicitud requiere el siguiente encabezado Accept:

Accept: application/vnd.atlas.preview+json

La siguiente solicitud de ejemplo crea un clúster efímero llamado Cluster0:

ejemplo de solicitud de creación

curl -sS -X POST 'https://cloud.mongodb.com/api/atlas/v2/unauth/ephemeralClusters:create' \ -H 'Accept: application/vnd.atlas.preview+json' \ -H 'Content-Type: application/json' \ -d '{"clusterName": "Cluster0"}'

El endpoint de creación devuelve una respuesta en el siguiente formato:

ejemplo de respuesta de creación

{ "claimUrl": "https://account.mongodb.com/account/register?claimId={claimId}", "clusterId": "{clusterId}", "connectionString": "mongodb+srv://{username}:{password}@{host}/", "expiresAt": "{timestamp}", "status": "PROVISIONING", "termsOfService": "By using this API and any resources provisioned through it, you agree to be bound by MongoDB's Cloud Terms of Service at https://www.mongodb.com/legal/terms-and-conditions/cloud; and Privacy Policy at https://www.mongodb.com/legal/privacy/privacy-policy."}

La respuesta incluye los siguientes campos:

  • claimUrl: URL única para reclamar este clúster efímero. Una persona debe abrir esta URL en un navegador. Válido por 7 días después de que se cree el clúster.

  • clusterId: Identificador único del clúster efímero. Para recuperar el status, claimUrl y otros detalles del clúster, envía una solicitud GET al siguiente endpoint, reemplazando {clusterId} con este valor:

    https://cloud.mongodb.com/api/atlas/v2/unauth/ephemeralClusters/{clusterId}

    Para aprender más, consulta Devolver un clúster de Atlas efímero.

  • connectionString: Cadena de conexión que utiliza el protocolo mongodb+srv:// para conectarse al clúster Ephemeral. Incluye el nombre de usuario y la contraseña de un usuario de base de datos generado automáticamente que puede leer y escribir datos en el clúster. Cualquier cliente que utilice esta cadena de conexión se autentica como este usuario de base de datos. La respuesta create es la única vez que Atlas devuelve la contraseña sin censurar.

  • expiresAt: Fecha y hora en que Atlas pausa el clúster si no se reclama. Un clúster efímero en pausa es inaccesible hasta que lo reclame. La marca de tiempo utiliza el ISO 8601 formato en UTC.

  • status: Estado del clúster efímero. Uno de PROVISIONING, ACTIVE o PAUSED.

  • termsOfService: Tenga en cuenta que al usar esta API, usted acepta los Términos de servicio de la nube y la Política de privacidad de MongoDB. Incluye un enlace a los términos completos.

Para obtener más información sobre el punto final de creación, consulte Crear un clúster de Atlas efímero.

2

Desde la respuesta de creación, guarde connectionString, claimUrl y clusterId. Los necesita para conectarse al clúster, reclamarlo y recuperar sus detalles.

Advertencia

Trata el connectionString, claimUrl y clusterId como secretos. Cualquier persona con el connectionString puede leer y guardar datos del clúster. Cualquier persona con el claimUrl puede reclamar el clúster en su propia cuenta de Atlas, y cualquier persona con el clusterId puede recuperar el claimUrl del punto final de obtención. El soporte de MongoDB no puede recuperar estos valores ni transferir la propiedad de un clúster reclamado.

Guarda los tres valores en una ubicación segura donde la persona que reclama el clúster pueda recuperarlos. Por ejemplo, utiliza un administrador de secretos compartido o un archivo .env local ignorado por git. No sobrescribas los secretos existentes en esa ubicación.

3

Utilice el valor connectionString de la respuesta de creación para conectarse al clúster efímero desde un entorno compatible, como:

  • Código de la aplicación: Proporcione la cadena de conexión al driver de MongoDB para su lenguaje de programación cuando inicialice el objeto cliente que se conecta al clúster. Esta es la opción típica al conectarse desde una aplicación. Para aprender más, consultar Conectarse a un clúster a través de Librerías de clientes.

  • Línea de comandos: Proporcione la cadena de conexión como argumento a MongoDB Shell (mongosh) para conectarse y ejecutar comandos de forma interactiva:

    Ejemplo de conexión de línea de comandos

    mongosh "<connectionString>"

Para aprender más sobre los métodos de conexión disponibles, consulte Consideraciones.

Nota

El clúster efímero permite conexiones desde cualquier dirección IP (0.0.0.0/0). Puede restringir el acceso por IP cuando reclame el clúster.

4

Reclamar el cúmulo efímero es opcional. Si no reclamas el clúster, Atlas lo pausa 48 horas después de la creación y lo elimina 7 días después de la creación. Cuando reclamas el clúster, Atlas lo convierte en un clúster gratuito estándar sin fecha de caducidad. El clúster reclamado conserva todos sus datos, y la cadena de conexión que guardaste sigue funcionando con las mismas credenciales. Para obtener más información sobre los efectos de reclamar, consulta Reclamar un clúster efímero.

Para reclamar el clúster, una persona debe iniciar sesión en Atlas en un navegador. Elige una de las siguientes opciones:

  • Reclamar ahora: Comparta claimUrl solo con la persona que reclamará el clúster. Pueden seguir el procedimiento en Reclamar un clúster efímero para reclamar el clúster.

  • Reclamar más tarde: guarde la claimUrl en una ubicación segura que permanezca disponible para la persona que reclamará el clúster. Esa persona puede reclamar el clúster en cualquier momento dentro de los 7 días posteriores a su creación.

  • Nunca reclamar: no realizar ninguna acción. Atlas borra el clúster 7 días después de su creación.

Utilice el siguiente flujo de trabajo de la CLI de Atlas para crear un clúster efímero con un solo comando y conectarse a él mediante la cadena de conexión devuelta. Este flujo de trabajo funciona sin una cuenta de Atlas, claves API ni atlas auth login. Una vez instalada la CLI de Atlas, un agente de codificación de IA puede completar cada paso sin intervención humana.

Para crear el clúster efímero con una solicitud HTTP en su lugar, consulte el Inicio rápido.

1

Ejecuta el siguiente comando:

atlas --version

Si la salida muestra la versión 1.59.0 o posterior, continúe con el siguiente paso. Si no se encuentra el comando o la versión es anterior a 1.59.0, instale o actualice la CLI de Atlas para su sistema operativo. Para saber cómo, consulte Instalar o actualizar la CLI de Atlas.

Después de instalar o actualizar, ejecuta atlas --version de nuevo. Debes ver la versión 1.59.0 o posterior antes de continuar.

2

Ejecute el siguiente comando, que envía el cuerpo de la solicitud desde la entrada estándar:

Ejemplo de comando create

echo '{"clusterName": "Cluster0"}' | \ atlas api ephemeralClusters createEphemeralCluster \ --version preview

La CLI requiere un cuerpo de solicitud. Para usar el nombre predeterminado del clúster, envía en su lugar un objeto JSON vacío ({}).

La bandera --version preview fija la versión de la API. El endpoint está disponible solo en la versión preview .

El comando imprime la misma respuesta JSON que el flujo de trabajo de la API, incluyendo el connectionString, claimUrly clusterId. Para aprender sobre cada campo de respuesta, consulte Crear un clúster de Atlas Efímero.

3

Desde la salida del comando, guarda el connectionString, claimUrly clusterId. Trata los tres como secretos.

Para aprender cómo guardar los valores de respuesta, conectarse al clúster y, opcionalmente, reclamar el clúster, complete los pasos 2 a través de 4 del menú de inicio rápido. Omita el paso 1.

Reclamar un cúmulo efímero es opcional. Si no reclamas el cúmulo, Atlas lo pausa 48 horas después de la creación y lo elimina 7 días después de la creación.

Cuando reclama un clúster efímero, Atlas realiza los siguientes cambios:

  • Extiende la vida útil del clúster: Atlas convierte el clúster efímero en un clúster gratuito estándar sin fecha de vencimiento. El clúster reclamado permanece disponible hasta que lo borres o hasta que Atlas lo pause debido a 30 días de inactividad.

  • Conserva los datos y la cadena de conexión del clúster: el clúster reclamado conserva todos sus datos y la cadena de conexión de la respuesta de creación sigue funcionando con las mismas credenciales.

  • Agrega el clúster a un Proyecto y una organización: En Atlas, cada clúster pertenece a un Proyecto y cada Proyecto pertenece a una organización. Atlas coloca el clúster reclamado en un nuevo Proyecto dentro de una organización nueva o existente propiedad de la cuenta que reclama el clúster.

  • Otorga acceso completo al clúster: La cuenta que reclama el clúster es un Organization Owner de la organización del clúster, lo que también otorga el rol Project Owner en cada proyecto de esa organización. Como Project Owner, tiene acceso a la base de datos para leer y guardar los datos del clúster, y acceso administrativo para gestionar el clúster y su proyecto mediante la Interfaz de Usuario de Atlas, Atlas CLI o Atlas Administration API.

Un agente de codificación de IA no puede reclamar un clúster efímero. Para reclamar el clúster, una persona debe completar el siguiente flujo de trabajo en un navegador web:

1
  1. En un navegador web, abra la claimUrl que guardó de la respuesta de creación para llegar a la página de inicio de sesión de Atlas. La URL de solicitud tiene el siguiente formato, donde {claimId} es un identificador único para el clúster efímero:

    https://account.mongodb.com/account/register?claimId={claimId}

  2. En la página de inicio de sesión, inicia sesión en Atlas con una cuenta existente o crea una cuenta nueva. Cuando reclames el clúster en el siguiente paso, esta cuenta obtendrá acceso tanto a la base de datos como acceso administrativo al clúster.

    Si creas una cuenta nueva, verifica tu correo electrónico antes de continuar.

Nota

La URL de reclamación es la única forma de reclamar el clúster. Caduca 7 días después de que se cree el clúster. Si pierde la URL de reclamación, recupérela con uno de los siguientes métodos:

  • Envíe una solicitud GET al siguiente endpoint, reemplazando {clusterId} con el valor clusterId de la respuesta de creación:

    https://cloud.mongodb.com/api/atlas/v2/unauth/ephemeralClusters/{clusterId}

    La respuesta incluye el claimUrl. Para aprender más, consulta Devolver un clúster de Atlas efímero.

  • Si un agente de IA de codificación creó el clúster, busque una ubicación segura donde pueda haber guardado el claimUrl, como el archivo .env local de su proyecto.

2

Después de iniciar sesión, Atlas muestra la página de reclamación. En esta página, haga lo siguiente:

  1. En el menú desplegable, seleccione una organización existente o seleccione Create new org for this cluster para crear una. Cuando reclama el clúster, Atlas lo traslada a la organización seleccionada y crea un Proyecto para él allí.

    Importante

    El menú desplegable solo enumera las organizaciones donde su cuenta de Atlas tiene el rol Organization Owner. Cuando reclama el clúster, cada Organization Owner en la organización seleccionada puede gestionar el clúster y sus datos.

  2. Configurar el acceso IP. Para restringir el acceso, remover 0.0.0.0/0 y permita solo su dirección IP actual (recomendado). Para permitir conexiones desde cualquier dirección IP, mantenga 0.0.0.0/0. Puede restringir el acceso IP más adelante en la configuración de Network Access del Proyecto.

  3. Haz clic en Claim Cluster. Esta es una acción única que no se puede deshacer.

3

Después de reclamar el clúster, Atlas muestra una página de confirmación con los nombres de la organización y el Proyecto, los detalles del clúster y la configuración de acceso IP que haya elegido.

Haga clic en Go To Project Overview para ver el clúster reclamado en la Interfaz de Usuario de Atlas.

4

Puedes reconfigurar el clúster reclamado y su Proyecto mediante la interfaz de usuario de Atlas, Atlas CLI o la Atlas Administration API. A nivel de clúster, puedes escalar el clúster a un nivel superior para aumentar el almacenamiento. A nivel de proyecto, puedes gestionar usuario de base de datos y restringir el acceso IP para aumentar la seguridad. Para obtener más información, consulta Gestión de clústeres.

Para crear un clúster efímero, envíe una solicitud POST o ejecute el comando CLI equivalente de Atlas, como se describe en Crear un clúster Atlas Efímero. Para recuperar su estado, conexión y detalles de reclamación, envíe una solicitud GET o ejecute el comando CLI equivalente de Atlas, como se describe en Devolver un clúster Atlas Efémero.

La CLI de Atlas establece los encabezados de la solicitud por ti. A diferencia del endpoint de la API, la CLI de Atlas requiere un cuerpo de solicitud.

Para obtener la especificación completa de la Atlas Administration API, consulta Crear un clúster de Atlas efímero y Devolver un clúster de Atlas efímero.

Nota

Solo puede crear un clúster efímero a través de la Atlas Administration API o la Atlas CLI. HashiCorp Terraform MongoDB Atlas proveedor y todas las demás interfaces no admiten esta operación.

Crea un clúster efímero y devuelve sus detalles de conexión y reclamación.

Método: POST

Punto final: https://cloud.mongodb.com/api/atlas/v2/unauth/ephemeralClusters:create

Comando Atlas CLI: atlas api ephemeralClusters createEphemeralCluster. Proporcione el nombre del clúster en el cuerpo de la solicitud con entrada --file <path> o estándar. Para obtener más información, consulte Atlas API ephemeralClusters createEphemeralCluster.

Parámetros de ruta: Ninguno.

Parámetros de query: Ninguno.

Encabezados de solicitud API:

Encabezado
Requerido
Valor

Accept

Sí

application/vnd.atlas.preview+json

Content-Type

Solo con un cuerpo de solicitud

application/json

Cuerpo de la solicitud de la API:

El cuerpo de la solicitud es opcional. Si envía un cuerpo, incluya el siguiente campo:

Campo
Tipo
Requerido
Descripción

clusterName

string

No

Etiqueta legible por humanos que identifica el clúster efímero. Se establece por defecto en Cluster0. Debe coincidir con el patrón ^[a-zA-Z0-9][a-zA-Z0-9-]*$.

ejemplo de solicitud:

ejemplo de solicitud de creación

curl -sS -X POST 'https://cloud.mongodb.com/api/atlas/v2/unauth/ephemeralClusters:create' \ -H 'Accept: application/vnd.atlas.preview+json' \ -H 'Content-Type: application/json' \ -d '{ "clusterName": "my-ephemeral-cluster" }'

Código de estado de éxito: 201 Created

Campos de respuesta de éxito:

Devuelve los detalles del nuevo clúster en los siguientes campo:

Campo
Tipo
Descripción

claimUrl

string (URI)

URL única para reclamar este clúster efímero. Redirige a la página de inicio de sesión o registro de Atlas, donde un usuario inicia sesión o crea una cuenta para reclamar el clúster. Válido por 7 días después de que se cree el clúster.

clusterId

string

Identificador único del clúster Ephemeral. Utilice este ID para recuperar el estado y los detalles del clúster en una solicitud GET.

connectionString

string

Cadena de conexión que utiliza el protocolo mongodb+srv:// para conectarse al clúster Ephemeral. Esta string incluye las credenciales SCRAM sin redactar (nombre de usuario y contraseña) para un usuario de base de datos generado automáticamente al que Atlas otorga la funcionalidad incorporada de rol readWriteAnyDatabase.

expiresAt

string (ISO 8601, UTC)

Fecha y hora en que el clúster se pausará y dejará de ser accesible hasta que se reclame. Este parámetro expresa su valor en el ISO 8601 formato de marca de tiempo en UTC.

status

string (enum)

Estado del clúster efímero. Uno de PROVISIONING, ACTIVE o PAUSED.

termsOfService

string

Tenga en cuenta que al utilizar esta API, acepta los Términos de servicio de la nube y la Política de privacidad de MongoDB. Incluye un enlace a los términos completos.

Encabezados de respuesta:

Encabezado
Devuelto con
Descripción

RateLimit-Limit

201, 429

El número máximo de solicitud que un usuario puede realizar dentro de una ventana de tiempo específica.

RateLimit-Remaining

201, 429

El número de solicitudes que quedan en la ventana de límite de tasa actual antes de que se alcance el límite.

Retry-After

429

El tiempo mínimo que debes esperar, en segundos, antes de volver a intentar la solicitud de la API.

Códigos de estado de error:

Nota

Si recibe un error 429, significa que se ha alcanzado el límite compartido para la creación de clústeres efímeros. En su lugar, puede implementar un clúster gratuito estándar, que ofrece el mismo nivel de clúster sin fecha de caducidad. Para aprender a crear y conectarse a un clúster gratuito a través de Atlas CLI, consulte Primeros pasos.

Estado
Descripción

400

Solicitud incorrecta.

429

Demasiadas solicitudes.

500

Error interno del servidor.

Devuelve los detalles de un clúster efímero.

Método: GET

Punto final: https://cloud.mongodb.com/api/atlas/v2/unauth/ephemeralClusters/{clusterId}

Comando Atlas CLI: atlas api ephemeralClusters getEphemeralCluster. Proporcione al ID del clúster con --clusterId <clusterId>. Para obtener más información, consulte atlas api ephemeralClusters getEphemeralClusters.

Parámetros de ruta:

Parameter
Tipo
Requerido
Descripción

clusterId

string

Sí

ID único del clúster efímero que se va a buscar.

Parámetros de query: Ninguno.

Encabezados de solicitud API:

Encabezado
Requerido
Valor

Accept

Sí

application/vnd.atlas.preview+json

Cuerpo de la solicitud API: Ninguno.

ejemplo de solicitud:

Ejemplo de solicitud get

curl -sS -X GET 'https://cloud.mongodb.com/api/atlas/v2/unauth/ephemeralClusters/{clusterId}' \ -H 'Accept: application/vnd.atlas.preview+json'

Código de estado de éxito: 200 OK

Campos de respuesta de éxito:

Devuelve el estado actual y los detalles del clúster en los siguientes campo:

Campo
Tipo
Descripción

claimUrl

string (URI)

URL única para reclamar este clúster efímero. Redirige a la página de inicio de sesión o registro de Atlas, donde un usuario inicia sesión o crea una cuenta para reclamar el clúster. Válido por 7 días después de que se cree el clúster.

clusterId

string

Identificador único del clúster Ephemeral. Utilice este ID para recuperar el estado y los detalles del clúster en una solicitud GET.

connectionString

string

Cadena de conexión que utiliza el protocolo mongodb+srv:// para conectarse al clúster efímero. Esta string incluye el nombre de usuario SCRAM de un usuario de base de datos generado automáticamente, pero reemplaza la contraseña con un marcador de posición. Atlas devuelve la contraseña solo en la respuesta de creación.

expiresAt

string (ISO 8601, UTC)

Fecha y hora en que el clúster se pausará y dejará de ser accesible hasta que se reclame. Este parámetro expresa su valor en el ISO 8601 formato de marca de tiempo en UTC.

status

string (enum)

Estado del clúster efímero. Uno de PROVISIONING, ACTIVE o PAUSED.

termsOfService

string

Tenga en cuenta que al utilizar esta API, acepta los Términos de servicio de la nube y la Política de privacidad de MongoDB. Incluye un enlace a los términos completos.

Encabezados de respuesta:

Encabezado
Devuelto con
Descripción

RateLimit-Limit

200, 429

El número máximo de solicitud que un usuario puede realizar dentro de una ventana de tiempo específica.

RateLimit-Remaining

200, 429

El número de solicitudes que quedan en la ventana de límite de tasa actual antes de que se alcance el límite.

Retry-After

429

El tiempo mínimo que debes esperar, en segundos, antes de volver a intentar la solicitud de la API.

Códigos de estado de error:

Estado
Descripción

400

Solicitud incorrecta.

404

No se ha encontrado.

429

Demasiadas solicitudes.

500

Error interno del servidor.