La API de datos te permite leer y guardar datos de forma segura utilizando solicitudes HTTPS estándar. La API incluye endpoints generados automáticamente que representan cada uno una operación de MongoDB. Puedes usar los endpoints para crear, leer, actualizar, borrar y agregar documentos en una fuente de datos de MongoDB.
Por ejemplo, esto publicación La solicitud almacena un documento en un clúster vinculado llamando al insertOne punto final:
curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/insertOne" \ -X POST \ -H "Content-Type: application/ejson" \ -H "Accept: application/json" \ -H "apiKey: TpqAKQgvhZE4r6AOzpVydJ9a3tB1BLMrgDzLlBLbihKNDzSJWTAHMVbsMoIOpnM6" \ -d '{ "dataSource": "mongodb-atlas", "database": "learn-data-api", "collection": "hello", "document": { "text": "Hello, world!" } }'
{ "insertedId": "5f1a785e1536b6e6992fd588" }
Para obtener una referencia API detallada de todos los puntos finales disponibles, consulte la Referencia OpenAPI de la API de datos.
Nota
Los puntos de conexión de Data API no son compatibles con nodos privados.
Cuándo utilizar la API de datos
Puedes usar la API de datos para integrarte con cualquier aplicación o servicio que soporte solicitudes HTTPS. Por ejemplo, puedes:
Consultar Atlas desde una aplicación móvil
Acceder a datos de prueba y registrar eventos en un flujo de trabajo de CI/CD
Integrar Atlas en una puerta de enlace API federada
Conectarse desde un entorno que actualmente no es compatible a través de un controlador MongoDB o Realm SDK
Una operación llamada a través de un punto final de API probablemente tardará más que la operación MongoDB correspondiente llamada a través de un controlador MongoDB conectado. Para casos de uso con alta carga y aplicaciones sensibles a la latencia, recomendamos conectarse directamente a su base de datos con un controlador MongoDB. Para obtener más información, consulte la documentación de los controladores MongoDB.
URL base
Los puntos finales de la API de datos de una aplicación comparten una URL base. Esta URL usa el ID de la aplicación para dirigirse de forma única a la aplicación y especifica la versión de la API de datos a la que se debe llamar. Cada punto final tiene una URL única que se forma añadiendo su ruta a la URL base de la aplicación.
Las aplicaciones distribuidas globalmente emplean el siguiente formato:
https://data.mongodb-api.com/app/<App ID>/endpoint/data/<API Version>
Los puntos finales de una aplicación implementada localmente utilizan una URL base específica para la región de implementación de la aplicación (porus-east-1.aws ejemplo,):
https://<Region>.<Cloud>.data.mongodb-api.com/app/<App ID>/endpoint/data/<API Version>
Configurar la API de datos
Puedes configurar la API de datos para tu aplicación desde la Interfaz de usuario Realm o implementando archivos de configuración con App Services CLI:
Haga clic HTTPS Endpoints en el menú de navegación de la izquierda y luego seleccione la pestaña Data API.
Habilita la API de datos para tu aplicación. Esto genera puntos finales que pueden acceder a cualquier fuente de datos de MongoDB vinculada a tu aplicación.
Elija un método de autenticación y habilite los proveedores de autenticación.
Elige un tipo de respuesta.
Guardar la configuración de la API de datos.
Configure permisos de acceso definiendo reglas para colecciones en sus fuentes de datos vinculadas para permitir que las solicitudes lean y escriban datos de forma segura.
Guarde e implemente su aplicación.
Extrae la última versión de tu aplicación.
appservices pull --remote="<Your App ID>" Definir un archivo de configuración de API de datos.
https_endpoints/data_api_config.json{ "disabled": false, "versions": ["v1"], "can_evaluate": {}, "return_type": <"JSON" | "EJSON"> } Implementa tu aplicación.
appservices push
Autenticación
Los puntos finales de la API de datos se ejecutan en el contexto de un usuario específico, lo que permite que su aplicación aplique reglas y valide esquemas de documentos para cada solicitud.
Por defecto, los endpoints usan autenticación de la aplicación, lo que requiere que cada solicitud incluya credenciales para uno de tus usuarios de la aplicación, como una clave de API o JWT. También puedes configurar otros esquemas de autenticación personalizados para adaptarlos a las necesidades de tu aplicación.
Para obtener ejemplos de cómo autenticar solicitudes, consulte Autenticar solicitudes de API de datos.
La autenticación de la aplicación requiere que los usuarios inicien sesión con un proveedor de autenticación que haya habilitado para su aplicación. Las solicitudes pueden incluir un token de acceso otorgado por el proveedor de autenticación o las credenciales con las que el usuario iniciaría sesión (por ejemplo, su clave API o correo electrónico y contraseña).
La autenticación de ID de usuario ejecuta todas las solicitudes como un único usuario de aplicación preseleccionado. Esto resulta útil si todas las solicitudes deben tener los mismos permisos, independientemente de quién haya llamado al endpoint.
Para seleccionar el usuario, especifique su ID de cuenta de usuario en la configuración de la API de datos de su aplicación.
{ "run_as_user_id": "628e47baf4c2ac2796fc8a91" }
La autenticación de scripts llama a una función para determinar el usuario de la aplicación al que se ejecuta una solicitud. Puede usar esto para implementar esquemas de autenticación y autorización personalizados.
La función debe devolver el ID de cuenta de usuario de aplicación existente como una string o { "runAsSystem": true } para ejecutar la solicitud como un usuario del sistema que tenga acceso completo a los API de MongoDB CRUD y de agregación y que no esté afectado por ninguna regla, rol o permiso.
Para definir la función, especifica el código fuente en la configuración de API de datos de la aplicación.
[ { ..., "run_as_user_id_script_source": "exports = () => {return \"628e47baf4c2ac2796fc8a91\"}" } ]
Autorización
Puedes exigir que los usuarios autenticados proporcionen información de autorización adicional en cada solicitud. Defines el esquema de autorización para todos los endpoints generados de la API de datos en tu configuración de la API de datos.
Los endpoints admiten de forma nativa un conjunto de esquemas de autorización integrados que utilizan una cadena secreta para demostrar que la solicitud está autorizada. También puede definir un esquema de autorización personalizado que pueda usar junto con los esquemas integrados o en lugar de ellos.
Esquemas de autorización integrados
Los endpoints admiten los siguientes esquemas de autorización incorporados:
Esquemas de autorización personalizados
Puedes definir una expresión de autorización personalizada para determinar si se permite la ejecución de una solicitud autenticada entrante. La expresión se evalúa para cada solicitud y debe dar true como resultado para permitirla. Si da como false resultado, la solicitud no se autoriza y falla con un error. Las solicitudes que no superan la autorización no se contabilizan para el uso facturado de tu aplicación.
Las expresiones de autorización pueden usar variables como %%user para autorizar en función de los datos del usuario que llama o %%request para tomar decisiones basadas en los detalles de cada solicitud entrante.
Para definir un esquema de autorización personalizado, especifique la expresión en la configuración de la API de datos de su aplicación:
{ ..., "can_evaluate": { "%%request.requestHeaders.x-secret-key": "my-secret" } }
Tipo de respuesta
Los puntos finales pueden devolver datos en uno de dos formatos de datos, JSON o EJSON.
De forma predeterminada, los endpoints devuelven JSON, un formato de datos estándar ampliamente compatible con lenguajes y plataformas modernas. Sin embargo, JSON no puede representar todos los tipos de datos que se pueden almacenar en MongoDB y, en algunos casos, pierde información de tipo.
También puede configurar puntos finales para que devuelvan EJSON, que utiliza objetos JSON estructurados para representar completamente los tipos compatibles con MongoDB. Esto conserva la información de tipo en las respuestas, pero requiere que su aplicación comprenda cómo analizar y usar EJSON.
Tip
The official MongoDB drivers include methods for working with EJSON. You can also download a standalone parser like bson on npm.
{ "return_type": "JSON" }
{ "return_type": "EJSON" }
Permisos de acceso
La API de datos utiliza reglas de acceso a los datos de tu aplicación para determinar si un usuario puede leer y escribir datos. Para permitir que las solicitudes de Data API accedan a una colección específica, primero debes definir reglas para la colección.
También puede configurar una lista de acceso IP para mayor seguridad.
Versiones de API
La API de datos utiliza un sistema de control de versiones integrado para actualizar los endpoints con el tiempo, manteniendo la compatibilidad con versiones anteriores. Las solicitudes entrantes pueden especificar la versión de un endpoint que se usará en la URL de la solicitud, y la API de datos puede procesar cualquier versión que tenga habilitada.
Debe habilitar una nueva versión para que los usuarios puedan llamar a los endpoints con esa versión. Siempre puede habilitar la versión más reciente de la API de datos. Sin embargo, no puede habilitar una versión anterior después de que se haya publicado una versión más reciente.
Actualmente se admiten las siguientes versiones:
betav1
Llamar a un punto final de API de datos
Puedes llamar a un endpoint de API de datos desde cualquier cliente estándar de HTTP. Cada solicitud puede incluir encabezados de configuración y argumentos en el cuerpo de la solicitud.
Se requiere HTTP/1.1 o superior al realizar solicitudes.
Elija una versión de API
Las solicitudes Data API especifican qué versión de la API se utilizará en la URL de la solicitud. Una solicitud puede especificar cualquier versión que esté habilitada para tu aplicación.
https://data.mongodb-api.com/app/<App ID>/endpoint/data/<API Version>
Especifique el formato de los datos de la solicitud
Las solicitudes de API de datos deben incluir un Content-Type encabezado para especificar el formato de datos utilizado en el cuerpo de la solicitud.
Usa
Content-Type: application/jsonpara representar los tipos estándar de JSON en el cuerpo de una solicitud a la API de datos.Utilice
Content-Type: application/ejsonpara representar tipos JSON estándar y tipos EJSON adicionales en un cuerpo de solicitud de API de datos.
curl -X GET \ https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/insertOne \ -H 'apiKey: <API Key>' \ -H 'Content-Type: application/ejson' \ -H 'Accept: application/ejson' \ --data-raw '{ "dataSource": "mongodb-atlas", "database": "learn-data-api", "collection": "hello", "document": { "_id": { "$oid": "629971c0d71aad65bd59c595" }, "greeting": "Hello, EJSON!", "date": { "$date": { "$numberLong": "1654589430998" } } } }'
{ "insertedId": { "$oid": "629971c0d71aad65bd59c595" } }
curl -X POST \ https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/updateOne \ -H 'apiKey: <API Key>' \ -H 'Content-Type: application/json' \ --data-raw '{ "dataSource": "mongodb-atlas", "database": "learn-data-api", "collection": "hello", "filter": { "greeting": "Hello, world!" }, "update": { "$set": { "greeting": "Hello, universe!" } } }'
{ "matchedCount": 1, "modifiedCount": 1 }
Elija un formato de datos de respuesta
Una solicitud puede incluir un Accept encabezado para solicitar un formato de datos específico para el cuerpo de la respuesta, ya sea JSON o EJSON. Si una solicitud no incluye un Accept encabezado válido, la respuesta utiliza el formato de datos especificado en la configuración de la API de datos.
curl -X GET \ https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne \ -H 'apiKey: <API Key>' \ -H 'Content-Type: application/json' \ -H 'Accept: application/ejson' \ --data-raw '{ "dataSource": "mongodb-atlas", "database": "learn-data-api", "collection": "hello", "projection": { "greeting": 1, "date": 1 } }'
{ "_id": { "$oid": "629971c0d71aad65bd59c545"}, "greeting": "Hello, Leafie!", "date": { "$date": { "$numberLong": "1654589430998" } } }
curl -X POST \ https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne \ -H 'apiKey: <API Key>' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ --data-raw '{ "dataSource": "mongodb-atlas", "database": "learn-data-api", "collection": "hello", "projection": { "greeting": 1, "date": 1 } }'
{ "_id": "629971c0d71aad65bd59c545", "greeting": "Hello, Leafie!", "date": "2022-06-07T08:10:30.998Z" }
Autenticar la solicitud
Si un punto final está configurado para usar la autenticación de aplicaciones, debe incluir un token de acceso de usuario válido o credenciales de inicio de sesión con cada solicitud.
En general, la autenticación de portador con un token de acceso ofrece mayor rendimiento y es más segura que los encabezados de credenciales. Utilice un token de acceso en lugar de encabezados de credenciales siempre que sea posible. El token permite ejecutar múltiples solicitudes sin tener que volver a autenticar al usuario. También permite enviar solicitudes desde un navegador web que implemente CORS.
Para usar un token de acceso, primero autentique al usuario mediante un proveedor de autenticación de App Services. Luego, obtenga el token de acceso devuelto por App Services e inclúyalo en el encabezado de autorización de la solicitud mediante un esquema de token de portador. Para obtener más información sobre cómo adquirir y usar un token de acceso,consulte Autenticación de token de portador.
curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne" \ -X POST \ -H "Accept: application/json" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -d '{ "dataSource": "mongodb-atlas", "database": "sample_mflix", "collection": "movies", "filter": { "title": "The Matrix" } }'
Otra opción es incluir credenciales de inicio de sesión válidas para el usuario en las cabeceras de la solicitud.
curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne" \ -X POST \ -H "Accept: application/json" \ -H "email: bob@example" \ -H "password: Pa55w0rd!" \ -d '{ "dataSource": "mongodb-atlas", "database": "sample_mflix", "collection": "movies", "filter": { "title": "The Matrix" } }'
curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne" \ -X POST \ -H "Accept: application/json" \ -H "apiKey: TpqAKQgvhZE4r6AOzpVydJ9a3tB1BLMrgDzLlBLbihKNDzSJWTAHMVbsMoIOpnM6" \ -d '{ "dataSource": "mongodb-atlas", "database": "sample_mflix", "collection": "movies", "filter": { "title": "The Matrix" } }'
curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne" \ -X POST \ -H "Accept: application/json" \ -H "jwtTokenString: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJteWFwcC1hYmNkZSIsInN1YiI6IjEyMzQ1Njc4OTAiLCJuYW1lIjoiSm9obiBEb2UiLCJleHAiOjIxNDU5MTY4MDB9.E4fSNtYc0t5XCTv3S8W89P9PKLftC4POLRZdN2zOICI" \ -d '{ "dataSource": "mongodb-atlas", "database": "sample_mflix", "collection": "movies", "filter": { "title": "The Matrix" } }'
Importante
No uses claves API en clientes orientados al usuario
Si se autentica desde un navegador u otra aplicación cliente, evite usar una clave API para iniciar sesión. En su lugar, utilice otro proveedor de autenticación que acepte las credenciales proporcionadas por el usuario. Nunca almacene localmente claves API ni otras credenciales confidenciales.
Autorizar la solicitud
Dependiendo de la configuración de autorización de tu API de datos, es posible que tus solicitudes deban incluir información adicional de autorización.