Uma introdução ao MongoDB Atlas Data API
Avalie esse Artigo
Há muitas opções para se conectar ao MongoDB Atlas como desenvolvedor de aplicativos. Uma das opções mais recentes é a Atlas Data API. A Atlas Data API oferece uma maneira leve de se conectar ao MongoDB Atlas que pode ser considerada semelhante a uma REST API. Este tutorial mostrará como habilitar a Atlas Data API e executar operações CRUD básicas usando curl. É o primeiro de uma série que mostra diferentes usos para a Atlas Data API e como você pode usá-la para criar aplicativos e serviços centralizados em dados com mais rapidez.
Esta publicação pressupõe que você já tem um Atlas cluster. Você pode usar um existente ou pode se inscrever em uma conta da nuvem e criar seu primeiro cluster de banco de dados seguindo as instruções.
Habilitar o Atlas Data API é muito fácil quando você tem um cluster no Atlas.
Primeiro, clique em "Data API" na barra à esquerda do seu sistema Atlas.
Em seguida, selecione a fonte ou fontes de dados às quais você deseja que a API de dados tenha acesso. Para este exemplo, estou selecionando apenas o cluster padrão0.
Em seguida, selecione o botão grande "Ativar API de dados".
Em seguida, você terá uma tela confirmando quais clusters habilitou para a API de dados.
Na coluna "MongoDB Atlas Data API", selecione "Leitura e gravação" por enquanto e clique no botão no canto superior esquerdo que diz "Criar chave de API". Escolha um nome. Não é importante o nome que você escolhe, desde que seja útil para você.
Por fim, clique em "Gerar chave de API" e anote a chave exibida em um local seguro, pois você não poderá vê-la novamente no Atlas. Você pode clicar no botão "Copy" para copiá-lo em sua área de transferência. Colei o meu em um arquivo .envrc arquivo no meu projeto.
Se quiser testar um comando simples, você pode selecionar uma de suas coleções de banco de dados nos menus suspensos e copiar e colar algum código em seu terminal para ver alguns resultados. Ao escrever esta postagem, fiz isso apenas para verificar se obtive alguns resultados. Quando terminar, clique em "Fechar" para voltar à tela API de dados. Se precisar gerenciar as chaves que criou, clique na aba "Chaves de API" nesta tela.
Agora você está pronto para chamar a API de dados!
A chave de API que você acabou de criar nunca deve ser compartilhada com ninguém ou enviada para o navegador. Qualquer pessoa que tenha a chave pode usá-la para fazer alterações nos dados do seu banco de dados! Na verdade, o Atlas Data API bloqueia o acesso do navegador porque, atualmente, não há uma maneira segura de fazer solicitações ao Atlas Data API com segurança sem compartilhar uma chave de API.
Todos os endpoints da API de dados usam HTTPS POST. Embora possa parecer lógico usar GET ao ler dados, as solicitações GET devem ser armazenadas em cache e muitas plataformas farão isso automaticamente. Para garantir que você nunca tenha resultados de query obsoletos, todos os endpoints da API usam POST. Hora de começar!
Para adicionar documentos ao MongoDB, você usará os pontos de extremidade de ação InsertOne ou InsertMany.
Ao inserir um documento com a API, você deve fornecer o "dataSource" (que é o nome do cluster), "database", "collection" e "document" como parte de um documento de carga útil JSON. Para autenticação, você precisará passar a chave API como cabeçalho. A API sempre usa HTTPS, portanto, isso é seguro e protegido contra interceptação de rede.
Para chamar com curl, use o seguinte comando:
Por exemplo, minha chamada se parece com isto:
Observe que o URL que estou usando é meu endpoint de URL do MongoDB Atlas Data API, com
/action/insertOne anexado. Quando executei esse comando com meus valores para YOUR_ID e YOUR_API_KEY, o curl imprimiu o seguinte:Isso significa que você adicionou um novo documento a uma coleção chamada “pets” em um banco de dados chamado “household.”. Devido ao modelo dinâmico flexível do MongoDB, nem o banco de dados nem a coleção precisaram ser definidos com antecedência.
Essa chamada de API retornou um JSON document com o ID do novo documento. Como não forneci explicitamente nenhum valor para ID (a chave primária no MongoDB), um foi criado para eu e era do tipo ObjectId. A API retorna JSON padrão por padrão, então isso é exibido como uma string.
Para procurar o documento que acabou de adicionar por _id, precisarei fornecer o _id que acabou de ser impresso por curl. No documento que foi impresso, o valor parece uma string, mas não é. É um ObjectId, que é o tipo de valor criado pelo MongoDB quando nenhum valor é fornecido para o _id.
Ao executar query do valor ObjectId, é necessário encapsular essa string como um tipo deObjectId EJSON, da seguinte forma:
{ "$oid" : <String Value> }. Se você não fornecer esse wrapper, o MongoDB acreditará erroneamente que você está procurando um valor de string, não o ObjectId que realmente está lá.A query findOne se parece muito com a query insertOne, exceto pelo fato de que o nome da ação na URL agora é findOne, e essa chamada usa um campo "filter" em vez de um campo "document".
Isso imprimiu o seguinte JSON para mim:
Observe que, na saída acima, o _id está sendo novamente convertido para JSON "simples", e, portanto, o valor "_id" está sendo convertido em uma string. Às vezes, é útil manter as informações de tipo, para que você possa especificar que deseja a saída EJSON para qualquer chamada da Atlas Data API, fornecendo um cabeçalho " Accept ", com o valor de " application/ejson ":
Quando executei isso, o valor "_id" foi fornecido com o encapsulador "$oid", para declarar que é um valor ObjectId:
Se você estiver inserindo vários documentos em uma collection, é muito mais eficiente fazer uma única chamada HTTPS com a ação insertMany. Esse endpoint funciona de forma muito semelhante à ação InsertOne, mas usa um campo " documents " em vez de um único campo " document ", contendo uma matriz de documentos:
Quando executei isso, a saída ficou assim:
Este endpoint retorna JSON com uma array dos valores para _id para os documentos que foram adicionados.
A query de mais de um documento é feita com o endpoint find, que retorna uma array de resultados. A query a seguir procura todos os Labradores que têm dois anos ou mais, classificados por idade:
Quando executei isso, enviei documentos para os dois cães mais antigos, Colheita eBrea:
Esse objeto contém um campo "documentos", que é uma array de tudo o que correspondeu. Se eu quisesse buscar um subconjunto dos resultados em páginas, poderia usar o parâmetro skip e limit para definir em qual resultado começar e quantos retornar.
Como isso correspondeu a um documento e alterou seu conteúdo, meu resultado ficou assim:
Eu só queria atualizar um único documento (porque eu só esperava encontrar um documento para o Harvest). Para alterar todos os documentos correspondentes, eu chamaria updateMany com os mesmos parâmetros.
Você também pode executar pipelines de agregação. Como um exemplo simples de como chamar o endpoint agregado, vamos determinar a contagem e a idade média de cada cor de labrador .
Os pipelines de agregação são a parte mais poderosa da API de query do MongoDB. Além de procurar documentos, um pipeline permite calcular valores agregados em vários documentos. O exemplo a seguir extrai todos os documentos do labrador da coleção "animais de estimação", agrupa-os pelo campo "cor" e, em seguida, calcula o número de cães ($sum de 1 para cada documento de cão) e a idade média do cão (usando $avg) para cada cor.
Quando executei a query acima, o resultado ficou assim:
É importante observar que existem algumas limitações ao executar aggregation pipelines por meio da API de dados.
Quando se trata de autenticação e autorização, ou apenas de proteção do acesso à API de dados em geral, você tem algumas opções. Esses recursos usam um recurso interessante do MongoDB Atlas Data API, que é que seu MongoDB Atlas Data API é um aplicativo MongoDB Atlas Application Services nos bastidores!
Você pode acessar o aplicativo clicando em "Configurações avançadas" na página do console da API de dados:
O restante desta seção usará os recursos deste aplicativo Atlas App Services, em vez das páginas de alto nível da MongoDB Atlas Data API.
Restringir o acesso ao seu endpoint de API somente dos servidores que deveriam ter acesso é uma forma relativamente simples, mas eficaz, de bloquear sua API. Você pode alterar a lista de endereços IP clicando em " Configurações do aplicativo " na barra de navegação à esquerda e, em seguida, clicando na guia " IP Access List " no painel de configurações.
Por padrão, todos os endereços IP têm permissão para acessar seu endpoint da API (é isso que 0.0.0.0 significa). Se você quiser bloquear o acesso à sua API, exclua essa entrada e adicione entradas para servidores que devem ser capazes de acessar seus dados. Há um botão conveniente para adicionar seu endereço IP atual quando você estiver escrevendo código no endpoint da API.
Em todos os exemplos desta publicação, mostrei como usar uma chave de API para acessar seus dados. Mas ao usar o aplicativo Atlas Application Services, você pode bloquear o acesso aos seus dados usando JSON web tokens (ou JWTs) e credenciais de e-mail/senha. O JWT tem o benefício de que você pode usar um serviço de autenticação externo ou fornecedores de identidade, como Auth0 ou Okta, para autenticar usuários do seu aplicativo. O serviço de autenticação pode fornecer um JSON web token que seu aplicativo pode usar para fazer consultas autenticadas usando a MongoDB Atlas Data API e fornece um URL JWK (JSON Web Keys) que pode ser usado pela MongoDB Atlas Data API para garantir que todas as solicitações recebidas tenham sido autenticadas pelo serviço de autenticação.
Meu colega Jesse (você deve conhece-lo como codeSTACKr) escreveu um ótimo tutorial para colocar isso em funcionamento com a API de dados e o Auth0, e o mesmo processo se aplica para aceitar JWTs com a API de dados. Ao clicar primeiro em "Configurações avançadas" para acessar a configuração do aplicativo que fornece os pontos de extremidade da API de dados nos atrás dos palcos e entrar em "Authentication, ", você pode habilitar o provedor com a chave de assinatura e o algoritmo apropriados.
No entanto, em vez de configurar um trigger para criar um novo documento de usuário quando um novo JSON web token for encontrado, defina "Criar usuário após autenticação" no painel Configurações do usuário na configuração da API de dados do Atlas como "ativado".
Para cada cluster, você pode definir permissões de acesso de alto nível, como acesso somente leitura, acesso de gravação em leitura & ou Sem acesso. No entanto, você também pode dar um passo adiante definindo o controle de acesso baseado em função personalizado com as Regras do Serviço de Aplicativo.
A seleção de Acesso personalizado permitirá que você configure funções adicionais sobre quem pode acessar quais dados, seja no nível do cluster, da coleção, do documento ou do campo.
Por exemplo, você pode restringir determinados detentores de chaves de API para que apenas possam inserir documentos, mas não excluí-los. Esses campos user.id estão associados a cada chave de API criada:
A MongoDB Atlas Data API fornece os endpoints básicos de CRUD e aggregation que descrevi acima. Ao acessar e manipular os dados em seu MongoDB database, como a MongoDB Atlas Data API é fornecida por um Atlas App Services, você obtém todas as vantagens correspondentes, incluindo a capacidade de adicionar mais pontos de extremidade de API que podem usar toda a energia disponível às MongoDB Atlas Functions.
Por exemplo, eu poderia escrever uma função sem servidor que procuraria os tuítes de um usuário usando a API do Twitter, combiná-los com um documento pesquisado no MongoDB e retornar o resultado:
Ao configurar isso como um endpoint HTTPS, posso definir coisas como o
- rota da API.
- método HTTPS.
- Lógica de autenticação ou autorização personalizada.
Neste exemplo, disponibilizei essa função por meio de uma solicitação HTTPS GET simples.
Dessa forma, você pode criar uma API para lidar com todos os requisitos de serviço de dados do seu aplicativo, tudo em um só lugar. O endpoint acima pode ser acessado com o seguinte comando curl:
E os resultados ficariam mais ou menos assim:
A MongoDB Atlas Data API é uma nova funcionalidade poderosa do MongoDB Atlas, que oferece a capacidade de executar query de seu banco de dados a partir de qualquer ambiente compatível com HTTPS. Ele também oferece suporte a poderosas possibilidades de autenticação social usando as tecnologias padrão JWT e JWK. E, finalmente, você pode estender sua API usando todos os recursos, como regras, autenticação e HTTPS endpoints.