Configurando o Atlas no Postman com a API de administração do Atlas
Avalie esse Tutorial
A API de administração do Atlasdo MongoDB é uma ótima maneira de executar tarefas administrativas para o Atlas programaticamente. A API de administração pode ser utilizada para gerenciar suas organizações, projetos, implementações e muito mais do Atlas. Isso permite que você automatize e integre suas tarefas administrativas em seus próprios sistemas.
Para explorar a API de administração do MongoDB Atlas, você pode usar o espaço detrabalho público da API de administração do MongoDB fornecido pela equipe de relações com desenvolvedores do MongoDB. Neste artigo, mostraremos como criar e gerenciar um cluster no MongoDB Atlas usando a API de administração do MongoDB e o Postman.
Para concluir este tutorial, você precisará de uma conta do Postman. Postman também recomenda a instalação do aplicativo de desktop para evitar problemas com o envio de solicitações do navegador da Web. Você precisará configurar seu cluster de Altas e bifurcar a coleção do Postman para começar a usá-lo. As seções a seguir fornecem instruções mais detalhadas sobre como fazer isso, se você precisar delas.
O primeiro passo é configurar uma conta MongoDB Atlas. Se você ainda não tiver uma conta, poderá obter uma gratuitamente. Para este tutorial, é necessária uma chave de API com a função
Organization Owner. Siga as instruções da documentação para obter instruções detalhadas sobre a concessão de acesso de programação. Certifique-se de acompanhar a chave de API pública e a chave de API privada, pois elas serão usadas posteriormente..png&w=3840&q=75){kind=logo}
No espaço detrabalho público da API de administração do MongoDB no Postman, você encontrará muitas coleções do Postman, uma para cada versão da API. A versão mais recente, que aparece na parte inferior da lista, é a versão em que estamos interessados. Clique nos três pontos ao lado do nome da coleção e selecione Criar uma bifurcação no menu pop-up.
Em seguida, siga as instruções na tela para adicionar esta coleção ao seu espaço de trabalho privado. Certifique-se de selecionar também o ambiente da API de administração do MongoDB Atlas no menu suspenso Ambientes para bifurcação.
Agora você precisará configurar o ambiente do Postman que acabou de bifurcar. Comece abrindo a aba Ambientes no lado esquerdo. Em seguida, localize o ambiente da API de administração do MongoDB Atlas.
Aqui, você encontra uma tabela de variáveis, ou seja,
digestAuthUsername e digestAuthPassword. Eles manterão os valores iniciais de {{vault:mongodb-public-api-key}} e {{vault:mongodb-private-api-key}}. Eles apontam para segredos no cofre do Postman, que você precisa criar.Para criar esses segredos, clique no botão do Vault no canto inferior direito da tela ou use o atalho control + shift + v. Crie dois campos denominados
mongodb-public-api-key e mongodb-private-api-key e insira as chaves públicas e privadas que você criou anteriormente. O valor dos segredos armazenados no cofre do Postman é armazenado localmente e criptografado usando o Advanced Encryption Standard (AES) com um comprimento de chave 256bits.Se você estiver usando o aplicativo web do Postman para enviar solicitações com referências a segredos do cofre, deverá usar o agente dodesktop do Postman ou o agente do navegador do Postman. Por padrão, as solicitações retornarão uma resposta 401 não autorizada. Recomendamos usar o aplicativo de desktop Postman para evitar problemas relacionados ao aplicativo da web e seus muitos agentes Postman.
Por fim, selecione MongoDB Atlas Administration API como o ambiente ativo na lista suspensa de ambientes.
Agora você está pronto para usar a API de administração do Atlas, navegue de volta para a coleção bifurcada selecionando a guia Coleção no lado esquerdo.
Para começar, use a barra de Pesquisa do Atlas para encontrar a solicitação chamada "Retorne o status deste aplicativo MongoDB ." Clique na solicitação GET com esse nome, que mostrará as opções para enviar a solicitação.
Para enviar essa solicitação, basta clicar em Enviar. Os parâmetros de autorização serão preenchidos automaticamente a partir do cofre usando o ambiente ativo. Isso deve resultar em uma resposta que exiba a chave de API pública que foi usada, bem como as funções que ela possui. O corpo da resposta deve ser semelhante ao abaixo:
1 { 2 "apiKey": { 3 "accessList": [], 4 "id": "36b340b5857d214ba750f9f1", 5 "publicKey": "bnamtsop", 6 "roles": [ 7 { 8 "orgId": "6a94e205a9936e310d07bed3", 9 "roleName": "ORG_OWNER" 10 } 11 ] 12 }, 13 "appName": "MongoDB Atlas", 14 "build": "b1d222c3c2c606eb64a7c0da856824b708a40fbb", 15 "links": [ 16 { 17 "href": "https://cloud.mongodb.com/api/atlas/v2", 18 "rel": "self" 19 }, 20 { 21 "href": "https://cloud.mongodb.com/api/atlas/v2/orgs/6a94e205a9936e310d07bed3/apiKeys/36b340b5857d214ba750f9f1", 22 "rel": "https://cloud.mongodb.com/apiKeys" 23 } 24 ], 25 "throttling": false 26 }
Se a solicitação falhar ou a chave API não tiver o role
ORG_OWNER, tente novamente as etapas anteriores.Copie o
orgId desta resposta, pois isso será usado na próxima solicitação.Um ótimo recurso do Postman é a capacidade de gerar trechos de código para qualquer solicitação. Ao clicar no ícone
</> no lado direito da tela, você pode gerar um trecho de código para a solicitação "Retornar o status deste aplicativo MongoDB" no cURL. Clicar no menu suspenso inicialmente rotulado como cURL oferece a opção de gerar código para a maioria das principais linguagens de programação.Agora que sabemos que todas as variáveis foram definidas corretamente e sabemos o ID da organização, vamos criar um projeto. Atlas Search para a solicitação denominada "Criar um projeto".
Esta é uma solicitação POST e requer um corpo para descrever o projeto que estamos criando. Navegue até a aba Corpo e cole o seguinte corpo na caixa de texto, substituindo
<orgID> pelo ID da organização copiado da resposta anterior.1 { 2 "name": "Postman Project", 3 "orgId": "<orgID>" 4 }
Agora, envie esta solicitação. Isso deve resultar na criação de um novo projeto e de um corpo de resposta semelhante ao abaixo:
1 { 2 "clusterCount": 0, 3 "created": "2024-08-08T16:06:12Z", 4 "id": "63b4acfac067b91e203b1e11", 5 "links": [...], 6 "name": "Postman Project", 7 "orgId": "6a94e205a9936e310d07bed3" 8 }
Copie o valor do campo "ID", pois este é o ID do seu projeto/grupo. Como você pode ver no campo
clusterCount, atualmente não há clusters neste projeto, então vamos criar um.Navegue até a solicitação denominada "Criar um cluster de um projeto" por meio da função Atlas Search. Essa solicitação POST usa variáveis de caminho na aba Params, bem como um corpo na aba Corpo.
Na aba Params, defina a variável
:groupId para o ID copiado do corpo da resposta anterior. Isto é usado para selecionar o projeto em que a operação está.Na guia Corpo, cole o seguinte corpo na caixa de texto.
1 { 2 "name": "MyFreeCluster", 3 "clusterType": "REPLICASET", 4 "replicationSpecs": [ 5 { 6 "regionConfigs": [ 7 { 8 "electableSpecs": { 9 "diskIOPS": 0, 10 "ebsVolumeType": "STANDARD", 11 "instanceSize": "M0", 12 "nodeCount": 1 13 }, 14 "priority": 7, 15 "providerName": "TENANT", 16 "backingProviderName":"AWS", 17 "regionName": "US_EAST_1" 18 } 19 ] 20 } 21 ] 22 }
Isto declara as opções de configuração para um clusterdo
M0 .Os clusters M0 são gratuitos para sempre e adequados para usuários que estão aprendendo MongoDB ou desenvolvendo pequenos aplicativos de prova de conceito.Clique em Enviar para criar o cluster.
Para visualizar uma descrição mais detalhada desse endpoint, bem como uma explicação detalhada do esquema do corpo da solicitação, clique no ícone Documentação e siga o link para a página de documentação de cada endpoint.
Navegue até a solicitação denominada "Carregar solicitação de conjunto de dados de amostra no cluster" por meio da função Atlas Search. Essa solicitação POST usa apenas variáveis de caminho na aba Params.
Insira o mesmo groupId das etapas anteriores. Para o campo de nome, insira "MyFreeCluster" ou o nome do cluster que acabou de ser criado se você tiver escolhido outro nome.
Clique em Enviar para carregar o conjunto de dados de amostra. Isso deve resultar em um corpo de resposta como:
1 { 2 "_id": "63b4acfac067b91e203b1e11", 3 "clusterName": "MyFreeCluster", 4 "completeDate": null, 5 "createDate": "2024-08-09T09:46:03Z", 6 "errorMessage": null, 7 "state": "WORKING" 8 }
Como você pode ver, o estado está definido como
WORKING. Para verificar se o conjunto de dados terminou de ser carregado, navegue até a página de solicitação "Verificar status da solicitação de conjunto de dados de amostra de cluster".Na página de parâmetros, insira seu groupId. O valor sampleDatasetId é o valor de
_id no corpo da resposta anterior.O envio desta solicitação GET fornecerá uma atualização sobre o progresso do carregamento do conjunto de dados. Depois que o conjunto de dados for carregado, o corpo da resposta será semelhante ao seguinte:
1 { 2 "_id": "63b4acfac067b91e203b1e11", 3 "clusterName": "MyFreeCluster", 4 "completeDate": "2024-08-09T09:47:19Z", 5 "createDate": "2024-08-09T09:46:03Z", 6 "errorMessage": null, 7 "state": "COMPLETED" 8 }
Agora que configuramos um cluster e carregamos alguns dados de exemplo, vamos recuperar algumas métricas sobre o cluster durante essa operação.
Primeiro, para recuperar as medições, precisamos dos IDs dos processos do MongoDB no cluster. Para fazer isso, navegue até a solicitação "Retornar todos os processos do MongoDB em um projeto".
Insira o groupId e clique em Enviar. Isso resultará em uma resposta contendo informações sobre todos os processos do projeto -- neste caso, apenas um cluster.
1 { 2 "links": [ ... ], 3 "results": [ 4 { ... 5 }, 6 { 7 "created": "2024-08-09T09:22:31Z", 8 "groupId": "63b4acfac067b91e203b1e11", 9 "hostname": "atlas-aaaaaa-shard-00-01.xpgisai.mongodb.net", 10 "id": "atlas-aaaaaa-shard-00-01.xpgisai.mongodb.net:27017", 11 "lastPing": "2024-08-09T11:00:33Z", 12 "links": [ ... ], 13 "port": 27017, 14 "replicaSetName": "atlas-aaaaaa-shard-0", 15 "typeName": "REPLICA_PRIMARY", 16 "userAlias": "bb-bbbbbbb-shard-00-01.xpgisai.mongodb.net", 17 "version": "7.0.12" 18 }, 19 { ... 20 } 21 ], 22 "totalCount": 3 23 }
Estamos interessados no processo com o campo
typeName sendo igual a REPLICA_PRIMARY pois este é o nó primário deste cluster. Copie o id deste processo, pois isso será utilizado na próxima solicitação.Por fim, navegue até a solicitação chamada "Medidas de retorno para um processo do MongoDB". Esta é uma solicitação GET com muitos parâmetros de caminho e consulta. Você pode consultar a documentação para obter uma explicação completa de cada um desses parâmetros, mas, para nossa solicitação, exigimos apenas os seguintes parâmetros de query. Clique na aba Params para ver esses parâmetros.
- m --- Lista de tipos de medições a serem solicitadas. Defina este campo como "CONNECTIONS".
- período — Duração no formato de duração ISO 8601 durante o qual o Atlas relata as métricas. Defina este campo como "PT1H."
- granularidade — Duração que especifica o intervalo no qual o Atlas relata as métricas. Defina este campo como "PT1M."
Certifique-se de que esses três parâmetros de query estejam habilitados com a caixa de seleção e que todos os outros estejam desabilitados. Esta consulta solicita o número de conexões em cada minuto durante a última hora.
Em seguida, defina as variáveis de caminho. Defina o
id copiado do corpo da solicitação anterior para o campo chamado ProcessId. O campo groupId deve ser definido com o mesmo valor das solicitações anteriores.O envio desta solicitação GET deve resultar em uma resposta com um corpo semelhante ao seguinte:
1 { 2 "end": "2024-08-09T11:24:06Z", 3 "granularity": "PT1M", 4 "groupId": "63b4acfac067b91e203b1e11", 5 "hostId": "atlas-aaaaaa-shard-00-01.xpgisai.mongodb.net:27017", 6 "links": [ ... ], 7 "measurements": [ 8 { 9 "dataPoints": [ 10 { 11 "timestamp": "2024-08-09T09:25:33Z", 12 "value": 0 13 }, 14 ... , 15 { 16 "timestamp": "2024-08-09T10:01:33Z", 17 "value": 11 18 }, 19 ... , 20 { 21 "timestamp": "2024-08-09T10:10:16Z", 22 "value": 0 23 }, 24 ], 25 "name": "CONNECTIONS", 26 "units": "SCALAR" 27 } 28 ], 29 "processId": "atlas-aaaaaa-shard-00-01.xpgisai.mongodb.net:27017", 30 "start": "2024-08-09T09:25:33Z" 31 }
Esses pontos de dados podem ser plotados para mostrar o número de conexões ao longo do tempo. Para saber mais em detalhes sobre as diferentes métricas que esse endpoint pode fornecer, clique no ícone Documentação e siga o link para a documentação da API de administração do Atlas.
E, assim, criamos um projeto, implantamos um cluster e solicitamos métricas sobre o cluster por meio da API de administração do Atlas usando o Postman. Se você quiser saber mais sobre como usar a API de administração do Atlas programaticamente, um ótimo lugar para começar é Chamando a API de administração do MongoDB Atlas: como fazer isso a partir do nó, Python e Ruby.
Principais comentários nos fóruns
Ainda não há comentários sobre este artigo.
Avalie esse Tutorial
Relacionado
Artigo
Colocando o RAG em produção com o chatbot de IA da documentação do MongoDB
Aug 29, 2024 | 11 min read
Tutorial
Além do básico: aprimorando a API Kotlin Ktor com pesquisa vetorial
Sep 18, 2024 | 9 min read