Ejemplos de API de datos

Atlas App Services ha llegado al final de su ciclo de vida y MongoDB ya no ofrece soporte activo. Los activadores siguen disponibles en la interfaz de usuario de Atlas. Consulte Página de desuso para más detalles.

Los siguientes ejemplos demuestran cómo enviar solicitudes a la API de datos de Atlas.

Operaciones de creación, lectura, actualización y eliminación (CRUD)

Los siguientes ejemplos demuestran cómo realizar operaciones CRUD utilizando la API de datos Atlas.

Buscar un solo documento

curl -s "https://data.mongodb-api.com/app/$CLIENT_APP_ID/endpoint/data/v1/action/findOne" \
  -X POST \
  -H "apiKey: $API_KEY" \
  -H 'Content-Type: application/ejson' \
  -H "Accept: application/json" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "learn-data-api",
    "collection": "tasks",
    "filter": {
      "text": "Do the dishes"
    }
  }'

Encuentra varios documentos

curl -s "https://data.mongodb-api.com/app/$CLIENT_APP_ID/endpoint/data/v1/action/find" \
  -X POST \
  -H "apiKey: $API_KEY" \
  -H 'Content-Type: application/ejson' \
  -H "Accept: application/json" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "learn-data-api",
    "collection": "tasks",
    "filter": {
      "status": "complete"
    },
    "sort": { "completedAt": 1 },
    "limit": 10
  }'

Inserta un solo documento

curl -s "https://data.mongodb-api.com/app/$CLIENT_APP_ID/endpoint/data/v1/action/insertOne" \
  -X POST \
  -H "apiKey: $API_KEY" \
  -H 'Content-Type: application/ejson' \
  -H "Accept: application/json" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "learn-data-api",
    "collection": "tasks",
    "document": {
      "status": "open",
      "text": "Do the dishes"
    }
  }'

Inserta varios documentos

curl -s "https://data.mongodb-api.com/app/$CLIENT_APP_ID/endpoint/data/v1/action/insertMany" \
  -X POST \
  -H "apiKey: $API_KEY" \
  -H 'Content-Type: application/ejson' \
  -H "Accept: application/json" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "learn-data-api",
    "collection": "tasks",
    "documents": [
      {
        "status": "open",
        "text": "Mop the floor"
      },
      {
        "status": "open",
        "text": "Clean the windows"
      }
    ]
  }'

Actualiza un solo documento

curl -s "https://data.mongodb-api.com/app/$CLIENT_APP_ID/endpoint/data/v1/action/updateOne" \
  -X POST \
  -H "apiKey: $API_KEY" \
  -H 'Content-Type: application/ejson' \
  -H "Accept: application/json" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "learn-data-api",
    "collection": "tasks",
    "filter": {
      "_id": { "$oid": "64224f4d089104f1766116a5" }
    },
    "update": {
      "$set": {
        "status": "complete",
        "completedAt": { "$date": { "$numberLong": "1680105272788" } }
      }
    }
  }'

Actualiza varios documentos

curl -s "https://data.mongodb-api.com/app/$CLIENT_APP_ID/endpoint/data/v1/action/updateMany" \
  -X POST \
  -H "apiKey: $API_KEY" \
  -H 'Content-Type: application/ejson' \
  -H "Accept: application/json" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "learn-data-api",
    "collection": "tasks",
    "filter": {
      "status": "open"
    },
    "update": {
      "$set": {
        "status": "complete",
        "completedAt": { "$date": { "$numberLong": "1680105287069" } }
      }
    }
  }'

Reemplazar un solo documento

curl -s "https://data.mongodb-api.com/app/$CLIENT_APP_ID/endpoint/data/v1/action/replaceOne" \
  -X POST \
  -H "apiKey: $API_KEY" \
  -H 'Content-Type: application/ejson' \
  -H "Accept: application/json" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "learn-data-api",
    "collection": "tasks",
    "filter": {
      "text": "Clean the windows"
    },
    "replacement": {
      "status": "open",
      "text": "Re-clean the windows"
    }
  }'

Borrar un único documento

curl -s "https://data.mongodb-api.com/app/$CLIENT_APP_ID/endpoint/data/v1/action/deleteOne" \
  -X POST \
  -H "apiKey: $API_KEY" \
  -H 'Content-Type: application/ejson' \
  -H "Accept: application/json" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "learn-data-api",
    "collection": "tasks",
    "filter": {
      "_id": { "$oid": "64224f3cd79f54ad342dd9b2" }
    }
  }'

Borra varios documentos

curl -s "https://data.mongodb-api.com/app/$CLIENT_APP_ID/endpoint/data/v1/action/deleteMany" \
  -X POST \
  -H "apiKey: $API_KEY" \
  -H 'Content-Type: application/ejson' \
  -H "Accept: application/json" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "learn-data-api",
    "collection": "tasks",
    "filter": {
      "status": "complete"
    }
  }'

Ejecuta una pipeline de agregación

curl -s "https://data.mongodb-api.com/app/$CLIENT_APP_ID/endpoint/data/v1/action/aggregate" \
  -X POST \
  -H "apiKey: $API_KEY" \
  -H 'Content-Type: application/ejson' \
  -H "Accept: application/json" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "learn-data-api",
    "collection": "tasks",
    "pipeline": [
      {
        "$match": { "status": "complete" }
      },
      {
        "$group": {
          "_id": "$status",
          "count": { "$sum": 1 },
          "tasks": { "$push": "$text" }
        }
      },
      {
        "$sort": { "count": -1 }
      }
    ]
  }'

Especificar tipos BSON en las solicitudes

Las solicitudes de la API de datos pueden especificar tipos BSON que no existen en JSON, utilizando el formato de datos EJSON en el cuerpo de la solicitud. Puede usar EJSON para buscar coincidencias con tipos BSON en filtros de consulta o escribir tipos BSON en operaciones de inserción y actualización.

To specify that a request body uses EJSON, set the Content-Type header:

Content-Type: application/ejson

Binario

To specify a binary value, use $binary with the value encoded in Base64 and a BSON subtype encoded as a two-character hexadecimal string:

curl -s "https://data.mongodb-api.com/app/$CLIENT_APP_ID/endpoint/data/v1/action/insertOne" \
  -X POST \
  -H "apiKey: $API_KEY" \
  -H 'Content-Type: application/ejson' \
  -H "Accept: application/json" \
  -d '{
    "dataSource": "<cluster name>",
    "database": "<database name>",
    "collection": "<collection name>",
    "document": { "_id": { "$oid":"645404f4ee8583002fc5a77e" },
      "data": {
        "$binary": {
          "base64": "46d989eaf0bde5258029534bc2dc2089",
          "subType": "05"
        }
      }
    }
  }'

fecha

Para especificar una fecha, utilice un objeto $date. El valor depende del formato EJSON que desee utilizar.

EJSON canónico

El valor es una marca de tiempo UNIX en milisegundos como un entero de 64bits:

curl -s https://data.mongodb-api.com/app/$CLIENT_APP_ID/endpoint/data/v1/action/insertOne \
  -X POST \
  -H "apiKey: $API_KEY" \
  -H 'Content-Type: application/ejson' \
  -H "Accept: application/json" \
  -d '{
    "dataSource": "<cluster name>",
    "database": "<database name>",
    "collection": "<collection name>",
    "document": {
      "createdAt": { "$date": { "$numberLong": "1638551310749" } }
    }
  }'

EJSON relajado

El valor es una cadena 8601 de fecha ISO con un componente de hora:

curl -s https://data.mongodb-api.com/app/$CLIENT_APP_ID/endpoint/data/v1/action/insertOne \
  -X POST \
  -H "apiKey: $API_KEY" \
  -H 'Content-Type: application/ejson' \
  -H "Accept: application/json" \
  -d '{
    "dataSource": "<cluster name>",
    "database": "<database name>",
    "collection": "<collection name>",
    "document": {
      "createdAt": { "$date": "2021-12-03T17:08:30.749Z" }
    }
  }'

Decimal128

Para especificar un decimal de 128bits, utilice $numberDecimal con el valor decimal como una cadena:

curl -s https://data.mongodb-api.com/app/$CLIENT_APP_ID/endpoint/data/v1/action/insertOne \
  -X POST \
  -H "apiKey: $API_KEY" \
  -H 'Content-Type: application/ejson' \
  -H "Accept: application/json" \
  -d '{
    "dataSource": "<cluster name>",
    "database": "<database name>",
    "collection": "<collection name>",
    "document": {
      "accountBalance": { "$numberDecimal": "128452.420523" }
    }
  }'

Double

Para especificar un valor de punto flotante con signo de 64bits (comúnmente denominado "doble"), utilice un $numberDouble canónico con el valor entero como una cadena:

curl -s https://data.mongodb-api.com/app/$CLIENT_APP_ID/endpoint/data/v1/action/insertOne \
  -X POST \
  -H "apiKey: $API_KEY" \
  -H 'Content-Type: application/ejson' \
  -H "Accept: application/json" \
  -d '{
    "dataSource": "<cluster name>",
    "database": "<database name>",
    "collection": "<collection name>",
    "document": {
      "temperatureCelsius": { "$numberDouble": "23.847" }
    }
  }'

EJSON relajado

Un valor EJSON que contiene un JSON sin formato number con un punto decimal se convierte automáticamente en un objeto $numberDouble:

curl -s https://data.mongodb-api.com/app/$CLIENT_APP_ID/endpoint/data/v1/action/insertOne \
  -X POST \
  -H "apiKey: $API_KEY" \
  -H 'Content-Type: application/ejson' \
  -H "Accept: application/json" \
  -d '{
    "dataSource": "<cluster name>",
    "database": "<database name>",
    "collection": "<collection name>",
    "document": {
      "temperatureCelsius": 23.847
    }
  }'

Int32

Para especificar un valor entero con signo de 32bits, utilice un objeto canónico $numberInt con el valor entero como una cadena:

curl -s https://data.mongodb-api.com/app/$CLIENT_APP_ID/endpoint/data/v1/action/insertOne \
  -X POST \
  -H "apiKey: $API_KEY" \
  -H 'Content-Type: application/ejson' \
  -H "Accept: application/json" \
  -d '{
    "dataSource": "<cluster name>",
    "database": "<database name>",
    "collection": "<collection name>",
    "document": {
      "coins": { "$numberInt": "2147483647" }
    }
  }'

EJSON relajado

Un valor EJSON que contiene un JSON sin formato number sin punto decimal se convierte automáticamente en un objeto $numberInt:

curl -s https://data.mongodb-api.com/app/$CLIENT_APP_ID/endpoint/data/v1/action/insertOne \
  -X POST \
  -H "apiKey: $API_KEY" \
  -H 'Content-Type: application/ejson' \
  -H "Accept: application/json" \
  -d '{
    "dataSource": "<cluster name>",
    "database": "<database name>",
    "collection": "<collection name>",
    "document": {
      "coins": 2147483647
    }
  }'

Entero64

Para especificar un valor entero con signo de 64 bits, utiliza $numberLong con el valor entero como string:

curl -s https://data.mongodb-api.com/app/$CLIENT_APP_ID/endpoint/data/v1/action/insertOne \
  -X POST \
  -H "apiKey: $API_KEY" \
  -H 'Content-Type: application/ejson' \
  -H "Accept: application/json" \
  -d '{
    "dataSource": "<cluster name>",
    "database": "<database name>",
    "collection": "<collection name>",
    "document": {
      "population": { "$numberLong": "8047923148" }
    }
  }'

ObjectId

Para especificar un valor ObjectId, utilice $oid con el ID como una cadena de bytes:

curl -s https://data.mongodb-api.com/app/$CLIENT_APP_ID/endpoint/data/v1/action/insertOne \
  -X POST \
  -H "apiKey: $API_KEY" \
  -H 'Content-Type: application/ejson' \
  -H "Accept: application/json" \
  -d '{
    "dataSource": "<cluster name>",
    "database": "<database name>",
    "collection": "<collection name>",
    "document": {
      "_id": { "$oid": "61f02ea3af3561e283d06b91" }
    }
  }'

Ejemplos de consultas

Los fragmentos de código de esta sección demuestran patrones comunes que puede utilizar en sus operaciones de lectura y escritura.

Encuentre todos los documentos

Para hacer coincidir todos los documentos de una colección, utilice un objeto de consulta vacío:

curl --request POST \
  'https://data.mongodb-api.com/app/<App ID>/endpoint/data/v1/action/find' \
  --header 'Content-Type: application/ejson' \
  --header 'apiKey: <API Key>' \
  --data-raw '{
    "dataSource": "<cluster name>",
    "database": "<database name>",
    "collection": "<collection name>",
    "filter": {}
  }'

Buscar un documento por ID

MongoDB almacena cada documento con un identificador único en el campo _id. Para la mayoría de las aplicaciones, este es un valor BSON ObjectID. Puedes hacer coincidir cualquier campo ObjectID, incluido un documento que use un objeto EJSON $oid:

curl --request POST \
  'https://data.mongodb-api.com/app/<App ID>/endpoint/data/v1/action/find' \
  --header 'Content-Type: application/ejson' \
  --header 'apiKey: <API Key>' \
  --data-raw '{
    "dataSource": "<cluster name>",
    "database": "<database name>",
    "collection": "<collection name>",
    "filter": {
      "_id": { "$oid": "630e51b3f4cd7d9e606caab6" }
    }
  }'

Buscar por fecha

Puede hacer coincidir documentos en una fecha específica haciendo coincidir un objeto EJSON $date con un campo que contenga un valor de fecha:

curl --request POST \
  'https://data.mongodb-api.com/app/<App ID>/endpoint/data/v1/action/find' \
  --header 'Content-Type: application/ejson' \
  --header 'apiKey: <API Key>' \
  --data-raw '{
    "dataSource": "<cluster name>",
    "database": "<database name>",
    "collection": "<collection name>",
    "filter": {
      "createdAt": { "$date": "2022-08-30T17:52:05.033Z" }
    }
  }'

Puede consultar un rango de fechas con $gt, $gte, $lt y $lte:

curl --request POST \
  'https://data.mongodb-api.com/app/<App ID>/endpoint/data/v1/action/find' \
  --header 'Content-Type: application/ejson' \
  --header 'apiKey: <API Key>' \
  --data-raw '{
    "dataSource": "<cluster name>",
    "database": "<database name>",
    "collection": "<collection name>",
    "filter": {
      "createdAt": {
        "$gte": { "$date": "2022-01-01T00:00:00.000Z" },
        "$lt": { "$date": "2023-01-01T00:00:00.000Z" }
      }
    }
  }'

Permisos de acceso a datos

Puedes asegurar las solicitudes Data API usando los permisos integrados de tu aplicación basados en roles. Los ejemplos en esta sección demuestran cómo configurar esquemas comunes de permisos. Puedes combinar estos y esquemas más complejos para satisfacer las necesidades de tu API. Para más ejemplos e información sobre cómo funcionan los permisos, consulta Permisos basados en roles.

Definir permisos para claves API específicas

Puede definir varios roles con diferentes permisos de acceso a datos y asignar claves API específicas a cada uno. Por ejemplo, puede crear un rol read-only que permita a los usuarios leer todos los datos, pero no insertarlos, eliminarlos ni modificarlos.

Asigna cada rol a una clave API en la expresión apply_when del rol.

Cada clave API corresponde a una cuenta de usuario independiente con un ID de cuenta único. Puede acceder al ID de cuenta y a otros datos del usuario que realiza una solicitud con la %%user expansión.

Para asociar un rol con una sola clave API, configure la expresión apply_when para que coincida con el ID de cuenta de la clave API:

apply_when - Un usuario por rol

{
  "database": "<database>",
  "collection": "<collection>",
  "roles": [
    {
      "name": "SpecificUser",
      "apply_when": {
        "%%user.id": "61f9a5e69cd3c0199dc1bb88"
      },
      "insert": true,
      "delete": true,
      "read": true,
      "write": true
    }
  ],
  "filters": []
}

Para asociar un rol con múltiples claves API, configure la expresión apply_when para que coincida con una matriz de ID de cuenta de clave API:

apply_when - Múltiples usuarios por rol

{
  "database": "<database>",
  "collection": "<collection>",
  "roles": [
    {
      "name": "MultipleUsers",
      "apply_when": {
        "%%user.id": {
          "$in": [
            "61f9a5e69cd3c0199dc1bb88",
            "61f9a5e69cd3c0199dc1bb89"
          ]
        }
      },
      "insert": true,
      "delete": true,
      "read": true,
      "write": true
    }
  ],
  "filters": []
}

También puede usar un sistema personalizado para determinar si un usuario tiene un rol. Por ejemplo, puede crear una función que busque los roles de un usuario en un clúster de Atlas.

funciones/hasRole.js

exports = async function hasRole({
  userId, // The user account ID, e.g. "60d0c1bdee9d3c23b677f929"
  roleName, // The name of a role the user might have, e.g. "admin"
}) {
  // 1. Get a reference to a custom user data collection
  const users = context.services.get("mongodb-atlas").db("app").collection("users")
  // 2. Query the user's document and make sure it exists
  const user = await users.findOne({ userId })
  if(!user) {
    console.error(`User.id ${userId} not found in custom user data collection`)
    return false
  }
  // 3. Decide if the user has the role we're checking
  return user.roles.includes(roleName)
};

Y luego llama a esa función desde apply_when la expresión del rol %function con el operador:

apply_when - Función personalizada

{
  "database": "<database>",
  "collection": "<collection>",
  "roles": [
    {
      "name": "SomeCustomRole",
      "apply_when": {
        "%%true": {
          "%function": {
            "name": "hasRole",
            "arguments": [{
              "userId": "%%user.id",
              "roleName": "SomeCustomRole"
            }]
          }
        }
      },
      "insert": true,
      "delete": true,
      "read": true,
      "write": true
    }
  ],
  "filters": []
}

Este ejemplo utiliza una colección de datos de usuario personalizada, pero puedes usar cualquier servicio externo para determinar si un usuario tiene un rol. El código de la función y los argumentos que se pasen son decisión del usuario.

Definir permisos para una colección específica

Puede definir roles que controlen los permisos de acceso a los datos de una colección específica en su clúster. Por ejemplo, puede crear un rol read-only que permita a los usuarios leer todos los datos de una colección, pero no insertar, eliminar ni modificar ningún dato.

Para definir roles para una colección específica, actualiza el archivo de configuración de la colección con las configuraciones de roles específicas de la colección:

/data_sources/<data source>/<database><collection>/<colección>/rules.json

{
  "database": "<database>",
  "collection": "<collection>",
  "roles": [
    {
      "name": "IsOwner",
      "apply_when": { "owner_id": "%%user.id" },
      "insert": false,
      "delete": false,
      "read": true,
      "write": true
    }
  ],
  "filters": []
}

Si no hay roles de recopilación coincidentes, la solicitud también se evalúa con los roles predeterminados de la fuente de datos. Si no desea aplicar los roles predeterminados, elimine todos los roles y filtros del archivo de configuración de reglas predeterminadas.

/data_sources/<data source>/default_rule.json

{
  "roles": [],
  "filters": []
}

¿Qué son los servicios de aplicación Atlas?