Exemplos de API de dados

O Atlas App Services atingiu seu status de fim de vida útil e não é mais suportado ativamente pelo MongoDB. Os gatilhos permanecem disponíveis na UI do Atlas . Consulte a página de descontinuação do para detalhes.

Os exemplos seguintes demonstram como enviar solicitações para a Atlas Data API.

Criar, ler, atualizar e excluir operações (CRUD)

Os exemplos seguintes demonstram como executar operações CRUD utilizando a Atlas Data API.

Encontrar um único 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"
    }
  }'

Localizar vários 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
  }'

Inserir um único 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"
    }
  }'

Insira vários 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"
      }
    ]
  }'

Atualizar um único 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" } }
      }
    }
  }'

Atualizar vários 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" } }
      }
    }
  }'

Substituir um único 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"
    }
  }'

Excluir um ú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" }
    }
  }'

Excluir vários 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"
    }
  }'

Execute um Pipeline de Agregação

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 de BSON em solicitações

As solicitações da API de dados podem especificar tipos de BSON que não existem em JSON usando o formato de dados EJSON no corpo da solicitação. Você pode usar o EJSON para combinar tipos BSON em filtros de consulta ou gravar tipos BSON em operações de inserção e atualização.

Para especificar que um corpo da solicitação usa EJSON, defina o cabeçalho Content-Type:

Content-Type: application/ejson

Binário

Para especificar um valor binário, utilize $binary com o valor codificado na Base64 e um subtipo BSON codificado como uma string hexadecimal de dois caracteres:

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"
        }
      }
    }
  }'

Data

Para especificar uma data, use um objeto $date. O valor depende de qual formato EJSON você deseja usar.

EJSON canônico

O valor é um carimbo de data/hora UNIX em milissegundos como um número inteiro de 64 bits:

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 descontraído

O valor é uma cadeia de caracteres de data ISO 8601 com um componente de tempo:

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 um decimal de 128 bits, use $numberDecimal com o valor decimal como uma 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": {
      "accountBalance": { "$numberDecimal": "128452.420523" }
    }
  }'

Double

Para especificar um valor de ponto instável com sinal de 64 bits (normalmente denominado "double"), use um $numberDouble canônico com o valor inteiro como uma 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": {
      "temperatureCelsius": { "$numberDouble": "23.847" }
    }
  }'

EJSON descontraído

Um valor EJSON que contém um JSON bruto number com um ponto decimal é automaticamente convertido em um 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 um valor inteiro assinado de $numberInt bits, utilize um objeto canônico com o valor inteiro como uma 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": {
      "coins": { "$numberInt": "2147483647" }
    }
  }'

EJSON descontraído

Um valor EJSON que contém um JSON bruto number sem um ponto decimal é convertido automaticamente em um 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
    }
  }'

Int64

Para especificar um valor inteiro assinado de 64 bits, use $numberLong com o valor inteiro como uma 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 um valor ObjectId, use $oid com o ID como uma cadeia 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" }
    }
  }'

Exemplos de consulta

Os trechos de código nesta seção demonstram padrões comuns que você pode usar em suas operações de leitura e escrita.

Localizar todos os documentos

Para corresponder a todos os documentos em uma coleção, use um objeto de consulta vazio:

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": {}
  }'

Encontrar um documento por ID

O MongoDB armazena cada documento com um identificador exclusivo no campo _id. Para a maioria das aplicações, este é um valor BSON ObjectID. Você pode corresponder a qualquer campo ObjectID, incluindo um documento usando um 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" }
    }
  }'

Encontrar por data

Você pode combinar documentos em uma data específica combinando um objeto EJSON $date com um campo que contém um valor de data:

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" }
    }
  }'

Você pode fazer query em um intervalo de datas com $gt, $gte, $lt e $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" }
      }
    }
  }'

Permissões de acesso a dados

Você pode proteger solicitações do Data API usando as permissões integradas baseadas em roles do seu aplicativo. Os exemplos nesta seção demonstram como configurar esquemas de permissões comuns. Você pode combinar esses e outros esquemas mais complexos para atender às necessidades da sua API. Para mais exemplos e informações sobre como as permissões funcionam, consulte Permissões baseadas em roles.

Definir permissões para chaves de API específicas

Você pode definir várias funções com diferentes permissões de acesso a dados e atribuir chaves de API específicas para cada função. Por exemplo, você pode criar uma função read-only que permite aos usuários ler todos os dados, mas não inserir, excluir ou modificar dados.

Você mapeia cada função para uma chave de API na expressão apply_when da função.

Cada chave de API corresponde a uma conta de usuário separada com um ID de conta exclusivo. Você pode acessar o ID da conta e outros dados do usuário que faz uma solicitação com a expansão %%user .

Para associar uma função a uma única chave de API, defina a expressão apply_when para corresponder ao ID da conta da chave de API:

apply_when - Um usuário por função

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

Para associar uma função a várias chaves de API, defina a expressão apply_when para corresponder a uma array de IDs de conta de chaves de API:

apply_when – Vários usuários por função

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

Você também pode usar um sistema personalizado para determinar se um usuário tem uma função. Por exemplo, você pode escrever uma função que procure funções de um usuário a partir de um Atlas cluster.

functions/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)
};

Em seguida, chame essa função a partir da expressão apply_when da função com o operador %function:

apply_when - Função 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 exemplo utiliza uma collection de dados de usuário customizada, mas você pode utilizar qualquer serviço externo para determinar se um usuário tem um role. O código da função e os argumentos que você passa são decisões suas.

Definir permissões para uma coleção específica

Você pode definir funções que controlam permissões de acesso aos dados para uma coleção específica em seu cluster. Por exemplo, você pode criar um papel read-only que permite aos usuários ler todos os dados em uma coleção, mas não inserir, excluir ou modificar quaisquer dados.

Para definir funções para uma collection específica, atualize o arquivo de configuração da collection com as configurações de role específicas da collection:

/data_sources/<data source>/<database>/<collection>/rules.json

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

Se nenhum role de collection corresponder, a solicitação também será avaliada em relação aos roles padrão da fonte de dados. Se você não quiser aplicar roles padrão , remova quaisquer roles e filtros do arquivo de configuração de regra padrão.

/data_sources/<data source>/default_rule.json

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

O que são os Serviços de Aplicativo Atlas?