Importante
Cada Atlas Administration API tem seus próprios recursos e requer configuração inicial.
Você pode acessar os servidores da API de administração do Atlas apenas pela internet pública. A API Atlas Administration não está disponível para conexões que usam emparelhamento de rede ou endpoints privados.
Para saber mais, consulte Atlas Programmatic Access.
A API de administração do Atlas segue os princípios do estilo de arquiteturaREST para expor uma série de recursos internos que permitem o acesso programático a recursos administrativos no Atlas. Para saber mais sobre a API de Administração do Atlas , consulte Referência da API de administração do Atlas .
A API de administração do Atlas não fornece acesso aos dados armazenados em seus clusters. Para ler ou escrever dados em um banco de dados, você deve autenticar no seu cluster usando as credenciais de um usuário de banco de dados com as funções de leitura ou gravação apropriadas. Você pode utilizar a API de Administração do Atlas para criar e gerenciar usuários do banco de dados .
Para usar a API de administração do Atlas para gerenciar seus clusters do Atlas , você deve autenticar suas solicitações de API com um dos seguintes métodos de autenticação:
Tokens de acesso à conta de serviço (OAuth) 2.0
Chaves de API (autenticação DigestHTTP)
Para saber mais sobre esses métodos, consulte Métodos de autenticação da API de administração do Atlas .
As seções a seguir descrevem como usar contas de serviço e chaves de API para configurar o acesso programático às suas organizações e projetos do Atlas .
Acesso necessário
Para criar uma conta de serviço ou chaves de API para uma organização, você deve ter acesso a essa Organization Owner organização.
Para conceder acesso de uma conta de serviço a um projeto, você deve ter acesso à organização que possui o Organization Owner projeto.
Para conceder acesso de chaves de API a um projeto, você deve ter acesso para esse Project Owner projeto.
Opcional: Exigir uma lista de acesso IP para a API de administração do Atlas
Quando você cria uma organização usando a IU do Atlas, o Atlas habilita o recurso de lista de acesso IP da API por padrão. Isso limita as solicitações de API apenas àquelas provenientes de endereços IP baseados em localização ou endereços CIDR que você especifica na lista de acesso IP. Se você fizer uma solicitação à API de Administração do Atlas sem uma entrada na lista de acesso IP, o servidor responderá com um código de status 403.
Se você desativar o recurso, poderá fazer solicitações de API de qualquer endereço na internet, desde que a lista de acesso IP esteja vazia. Depois que você adiciona uma entrada à lista de acesso IP, apenas solicitações originadas desse endereço IP podem ser feitas.
Para definir sua organização para exigir listas de acesso IP para cada solicitação da API de administração do Atlas após a criação da organização, siga estas etapas:
No Atlas, acesse a página Organization Settings.
Se ainda não estiver exibido, selecione sua organização desejada no Menu Organizations na barra de navegação.
Na barra lateral, clique em Organization Settings.
A página Configurações da organização é exibida.
Conceder acesso programático ao Atlas
Você pode conceder acesso programático a uma organização ou projeto usando um dos dois métodos de autenticação a seguir:
Importante
Recomendamos que você utilize contas de serviço em vez de chaves API para autenticar na API de administração do Atlas . As chaves de API são um método de autenticação legado .
Conta de serviço (recomendado) | Chaves de API (legadas) |
|---|---|
Novo método de autenticação no Atlas usando o protocolo-padrão da indústria OAuth 2.0 com o fluxo de credenciais do cliente. | Método legado de autenticação no Atlas que usa autenticação Digest HTTP. |
Uma conta de serviço permite gerenciar permissões e criar tokens de acesso. Uma conta de serviço tem um ID de cliente e um segredo que funciona como um nome de usuário e uma senha para criar tokens de acesso. Um token de acesso permite fazer solicitações de API para o Atlas. | As chavesde API têm duas partes: uma chave pública e uma chave privada. Essas duas partes têm a mesma função que um nome de usuário e uma senha quando você faz solicitações de API ao Atlas. |
Depois de criar uma conta de serviço, você usará o ID de cliente e o segredo para gerar um token de acesso que autentica suas solicitações de API. Os tokens de acesso são válidos apenas por 1 hora (3600 segundos) conforme a especificação OAuth.2.0 A expiração dos tokens de acesso evita ataques de repetição, em que um token de acesso vazado poderia ser usado sem restrição de tempo. | O Atlas faz o hash da chave pública e da chave privada usando um valor exclusivo chamado nonce. O nonce é válido apenas por um curto período de tempo, conforme a especificação de autenticação HTTP Digest. Isso é para evitar ataques de repetição, para que você não possa armazenar em cache um nonce e usá-lo para sempre. |
As funções do Atlas limitam quais operações uma conta de serviço pode realizar com seu token de acesso. Você deve atribuir roles às contas de serviço, como faria com os usuários, para garantir que a conta de serviço gere tokens de acesso com as permissões necessárias para as chamadas de API desejadas. | As funções do Atlas limitam quais operações as chaves de API podem executar. Você deve atribuir funções às chaves de API, como faria com os usuários, para garantir que as chaves de API tenham as permissões necessárias para as chamadas de API desejadas. |
Cada conta de serviço pertence a apenas uma organização e pode conceder acesso a qualquer número de projetos nessa organização. Para conceder acesso a uma conta de serviço em nível de organização a um projeto, consulte Conceder acesso a uma conta de serviço existente a um projeto. | Cada par de chaves de API pertence a apenas uma organização e pode conceder acesso a qualquer quantidade de projetos nessa organização. Para conceder acesso a chaves de API em nível de organização a um projeto, consulte Conceder acesso a uma conta de serviço existente a um projeto. |
O Atlas vincula muitos recursos a um projeto. Muitos URLs de recursos da APIseguem o formato | O Atlas vincula muitos recursos a um projeto. Muitos URLs de recursos da APIseguem o formato |
Você não pode usar uma conta de serviço ou seu token de acesso para fazer login no Atlas por meio da interface do usuário do Atlas . As contas de serviço só concedem acesso à API de administração do Atlas , que não inclui acesso à UI ou acesso a dados do cluster. | Você não pode usar chaves de API para fazer login no Atlas por meio da interface do usuário do Atlas . As chaves deAPI concedem apenas acesso à API de administração do Atlas , que não inclui acesso à UI ou acesso a dados do cluster. |
Gerenciar Acesso Programático a uma Organização
Faça os procedimentos a seguir para conceder acesso programático a uma organização por meio de uma conta de serviço ou de chaves de API. Para saber mais sobre esses dois métodos de autenticação, consulte Métodos de autenticação da API de administração do Atlas .
Conceder acesso de programação a um projeto
Faça os procedimentos a seguir para conceder acesso programático a um projeto por meio de uma conta de serviço ou de chaves de API. Para saber mais sobre esses dois métodos de autenticação, consulte Métodos de autenticação da API de administração do Atlas .
Adicionar acesso ao projeto de um projeto
Se você ainda não criou uma conta de serviço ou chaves de API para uma organização, pode criá-las para um projeto e conceder a esse projeto acesso à API de Administração do Atlas. A conta de serviço ou as chaves de API que você cria para um projeto são automaticamente adicionadas à organização pai com a permissão Organization Member.
Solicitação API: como fazer
A API de administração do Atlas usa um dos dois métodos de autenticação para autenticar solicitações: conta de serviço ou chaves de API. Você precisará das chaves ou do segredo que salvou ao configurar o método de autenticação preferido para concluir os procedimentos a seguir.
Todos os endpoints do Atlas Administration API têm a seguinte URL base:
https://cloud.mongodb.com/api/atlas/<version>
Importante
O MongoDB utiliza URLs HTTPS para aumentar a segurança. O uso de URLs HTTP retornará um código de status 301.
Alternativamente, você pode usar qualquer ferramenta que suporte a especificação OpenAPI v3 para gerar exemplos de código ou servidores de simulação. Por exemplo, você pode importar a Especificação da API Admin do Atlas para o Postman para gerar comandos curl.
Aviso
Usar uma URL HTTP com o Postman retornará um código de status 301 como esperado. No entanto, neste cenário, o Postman pode automaticamente tentar novamente a solicitação com HTTPS, mas ao mesmo tempo remover o cabeçalho e o corpo da solicitação de nova tentativa. Isso retornará um código de status 401 em vez de 301, tornando difícil determinar por que a solicitação falhou.
Para usar o Postman para gerar comandos curl:
Na documentação da API de Administração do MongoDB Atlas, clique com o botão direito em Baixar e copie o link.
Próximos passos
Para saber mais sobre a API de Administração do Atlas, consulte Referência da API de administração do Atlas.
Para gerenciar o acesso de programação à API de administração do Atlas, consulte qualquer um dos seguintes procedimentos: