开始使用 Atlas Administration API
在此页面上
重要
每个 Atlas Administration API 都有自己的资源，需要进行初始设置。
您只能通过公共互联网访问 Atlas Administration API 服务器。Atlas Administration API 不适用于使用 网络对等互连或私有端点的连接。
要了解更多信息，请参阅 Atlas 编程访问权限。
Atlas Administration API 遵循 REST 架构风格的原则，以开放大量内部资源，从而能够以编程方式访问 Atlas 的功能。要了解更多信息，请参阅 Atlas Administration API 参考文档。
授予 Atlas 的编程访问权限
您可以使用以下两种身份验证方法之一向组织或项目授予编程访问权限：
服务帐户 | API 密钥 |
|---|---|
创建服务帐号后，您将使用其客户端 ID 和机密生成访问令牌，用于对您的 API 请求进行身份验证。根据 OAuth 2.0 规范，访问令牌的有效期仅为 1 小时（3600 秒）。访问令牌过期可以防止重放攻击；在重放攻击中，可以不受时间限制地使用泄露的访问令牌。 | Atlas 使用一个称为 nonce 的唯一值对公钥和私钥进行哈希化处理。根据 HTTP 摘要式身份验证规范，nonce 的有效期很短。这是为了防止重放攻击，因此您不能缓存 nonce 并永远使用它。 |
Atlas 角色限制了服务帐户使用其访问令牌可以执行的操作。必须向服务帐户授予角色，就像向用户授予角色一样，以确保访问令牌可以调用 API 端点而不会出错。 | Atlas 角色限制 API 密钥可以执行的操作。您必须向 API 密钥授予角色，就像为用户授予角色一样，以确保 API 密钥可以毫无错误地调用 API 端点。 |
Atlas将许多资源绑定到一个项目。许多API资源URL都遵循 | Atlas将许多资源绑定到一个项目。许多API资源URL都遵循 |
每个服务帐号仅属于一个组织，但您可以授予服务帐号访问权限，以访问该组织中任意数量的项目。 | 每个 API 密钥仅属于一个组织，但您可以授予多个 API 密钥访问权限，以访问该组织中任意数量的项目。 |
您无法使用服务帐户或其访问令牌通过 Atlas 用户界面登录 Atlas。 | 您无法使用 API 密钥通过 Atlas 用户界面登录 Atlas。 |
可选：需要针对 Atlas Administration API 的 IP 访问列表
使用 Atlas 用户界面创建组织时，Atlas 默认启用 API IP 访问列表功能。这会将 API 请求限制为仅来自您在 IP 访问列表中指定的基于位置的 IP 或 CIDR 地址的那些请求。如果您在没有 IP 访问列表条目的情况下向 Atlas Administration API 发出请求，服务器则会返回 403 状态码。
如果您禁用该功能，则只要 IP 访问列表为空，您便可从互联网上的任意地址发出 API 请求。一旦您添加了 IP 访问列表条目，则只有来自该 IP 地址的请求才会被处理。
要将您的组织设置为在创建组织后要求为每个 Atlas Administration API 请求提供 IP 访问列表，请执行以下步骤：
为组织授予编程访问权限
使用以下过程，通过服务帐户或API密钥向组织授予编程访问权限。要学习；了解有关这两种身份验证方法的更多信息，请参阅Atlas Administration API身份验证。
必需的访问权限
要执行以下操作，您必须拥有 Atlas 的 Organization Owner 访问权限。
输入服务帐户信息。
输入一个 Name。
输入一个 Description。
从 Client Secret Expiration（客户端密钥到期）菜单中选择持续时间。
从Organization Permissions（组织权限）菜单中，为服务帐户选择一个或多个新角色。
您可以使用 Atlas 管理 API 为您的组织创建服务帐户。
创建服务帐号后，复制并保存输出中的 {CLIENT-ID} 和 {CLIENT-SECRET}，这应该与以下示例类似。只有在这个时候，您才能查看完整的客户机密。您在提出 API 请求时需要这些信息。
{ "createdAt" : "2024-04-23T17:47:17Z", "description" : "Service account for my organization.", "clientId" : "{CLIENT-ID}", "name" : "My Service Account", "roles" : [ "ORG_MEMBER" ], "secrets" : [ { "createdAt" : "2024-04-23T17:47:17Z", "expiresAt" : "2024-12-01T00:00:00Z", "id" : "6627f7259d39d858378c9e30", "lastUsedAt" : null, "secret" : "{CLIENT-SECRET}" } ] }%
创建 API 密钥
要使用 Atlas CLI 在组织中创建 API 密钥，请运行以下命令：
atlas organizations apiKeys create [options]
要了解有关命令语法和参数的更多信息，请参阅 Atlas CLI 文档中的 atlas organizations apiKeys create。
为API密钥添加API访问列表条目
要使用 Atlas CLI 创建 API 密钥的 IP 访问列表条目，请运行以下命令：
atlas organizations apiKeys accessLists create [options]
要了解有关命令语法和参数的更多信息，请参阅 Atlas CLI 文档中的 atlas organizations apiKeys accessLists create。
输入 API Key Information（密钥保管库凭证）。
输入一个 Description。
在 Organization Permissions 菜单中选择 API 密钥 的一个或多个新角色。
授予对项目的编程访问权限
使用以下过程，通过服务帐户或API密钥授予对项目的编程访问权限。要学习；了解有关这两种身份验证方法的更多信息，请参阅Atlas Administration API身份验证。
必需的访问权限
要给予服务帐户访问项目的权限，您必须对拥有该项目的组织具有 Organization Owner 访问权限。
要给予 API 密钥访问某个项目的权限，您必须拥有该项目 Project Owner 权限。
为现有组织分配项目访问权限
如果您已经为组织创建了服务帐户或API密钥，则可以将它们分配给项目，以授予该项目访问权限Atlas Administration API 的权限。
警告
如果为项目指定了组织服务帐户，则组织 Project Owner 可以管理服务帐户，包括轮换机密和更新 IP 访问列表。
您可以使用 Atlas 管理 API 授予现有服务帐户访问项目的权限。
要使用 Atlas CLI 将 API 密钥分配给项目，请运行以下命令：
atlas projects apiKeys assign <ID> [options]
要了解有关命令语法和参数的更多信息，请参阅 Atlas CLI 文档中的 atlas projects apiKeys assign 部分。
要使用 Atlas 用户界面将组织 API 密钥分配给项目，请执行以下操作：
在 Atlas 中，转到 Project Access Manager（项目设置）页面。
如果尚未显示，组织从导航栏中的Organizations菜单。
如果尚未显示，请从导航栏的Projects菜单中选择所需的项目。
执行以下步骤之一：
从导航栏的Access Manager菜单中选择Project Access 。
在 Projects 菜单旁边，展开 Options 菜单，单击 Project Settings，然后单击侧栏中的 Access Manager。
将显示项目访问管理器页面。
将 API 密钥添加到项目中。
将公钥键入到字段中。
在 Project Permissions 菜单中选择 API 密钥 的一个或多个新角色。
从项目添加项目访问权限
如果您尚未为组织创建服务帐户或 API 密钥，则可以为项目创建服务帐户或 API 密钥，以授予该项目对 Atlas Administration API 的访问权限。您为项目创建的服务帐户或 API 密钥会自动添加到具有 Organization Member 权限的父组织。
要使用 Atlas 用户界面为项目创建服务帐户，请执行以下操作：
在 Atlas 中，转到 Project Access Manager（项目设置）页面。
如果尚未显示，组织从导航栏中的Organizations菜单。
如果尚未显示，请从导航栏的Projects菜单中选择所需的项目。
执行以下步骤之一：
从导航栏的Access Manager菜单中选择Project Access 。
在 Projects 菜单旁边，展开 Options 菜单，单击 Project Settings，然后单击侧栏中的 Access Manager。
将显示项目访问管理器页面。
输入服务帐户信息。
输入一个 Name。
输入一个 Description。
从 Client Secret Expiration（客户端密钥到期）菜单中选择持续时间。
从项目权限菜单中，为服务帐户选择一个或多个新角色。
您可以使用 Atlas 管理 API 为项目创建服务帐户。
创建服务帐号后，复制并保存输出中的 {CLIENT-ID} 和 {CLIENT-SECRET}，这应该与以下示例类似。只有在这个时候，您才能查看完整的客户机密。您在提出 API 请求时需要这些信息。
{ "createdAt" : "2024-04-23T17:47:17Z", "description" : "Service account for my organization.", "clientId" : "{CLIENT-ID}", "name" : "My Service Account", "roles" : [ "ORG_MEMBER" ], "secrets" : [ { "createdAt" : "2024-04-23T17:47:17Z", "expiresAt" : "2024-12-01T00:00:00Z", "id" : "6627f7259d39d858378c9e30", "lastUsedAt" : null, "secret" : "{CLIENT-SECRET}" } ] }%
要使用 Atlas CLI 创建项目的 API 密钥，请运行以下命令：
atlas projects apiKeys create [options]
要了解有关命令语法和参数的更多信息，请参阅 Atlas CLI 文档中的 atlas projects apiKeys create。
为项目创建 API 密钥后，使用 Atlas UI 添加 API 访问列表条目。在设置 API 访问列表之前，您无法使用项目的 API 密钥。
注意
Atlas CLI 限制
您无法使用 Atlas CLI 编辑项目 API 密钥的 API 访问列表。
要使用 Atlas 用户界面添加 API 访问列表条目，请执行以下操作：
要使用 Atlas 用户界面为项目创建 API 密钥：
在 Atlas 中，转到 Project Access Manager（项目设置）页面。
如果尚未显示，组织从导航栏中的Organizations菜单。
如果尚未显示，请从导航栏的Projects菜单中选择所需的项目。
执行以下步骤之一：
从导航栏的Access Manager菜单中选择Project Access 。
在 Projects 菜单旁边，展开 Options 菜单，单击 Project Settings，然后单击侧栏中的 Access Manager。
将显示项目访问管理器页面。
输入 API Key Information（密钥保管库凭证）。
在 Create API Key 页面中：
输入一个 Description。
在 Project Permissions 菜单中选择 API 密钥 的一个或多个新角色。
提出 API 请求
Atlas Administration API使用两种身份验证方法之一对请求进行身份验证：服务帐户或API密钥。你将需要在配置首选身份验证方法时保存的密钥或密钥，以完成以下过程。
所有 Atlas Administration API 端点均有以下基本 URL：
https://cloud.mongodb.com/api/atlas/<version>
要使用服务帐户发出 API 请求，请使用该服务帐户生成访问令牌，然后在请求中使用访问令牌：
检索您的服务帐户的客户端机密。
找到以 mdb_sa_sk_ 开头的客户机密；这是创建服务帐户后立即保存的客户机密，当时也是唯一一次可以查看客户机密的时机。如果未保存客户端机密，则必须生成新的客户端机密。
请求访问令牌。
将以下示例中的 {BASE64-AUTH} 替换为上一步的输出，然后运行：
1 curl --request POST \ 2 --url https://cloud.mongodb.com/api/oauth/token \ 3 --header 'accept: application/json' \ 4 --header 'cache-control: no-cache' \ 5 --header 'authorization: Basic {BASE64-AUTH}' \ 6 --header 'content-type: application/x-www-form-urlencoded' \ 7 --data 'grant_type=client_credentials'
{"access_token":"eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCIsImtpZCI6ImYyZjE2YmE4LTkwYjUtNDRlZS1iMWYwLTRkNWE2OTllYzVhNyJ9.eyJpc3MiOiJodHRwczovL2Nsb3VkLWRldi5tb25nb2RiLmNvbSIsImF1ZCI6ImFwaTovL2FkbWluIiwic3ViIjoibWRiX3NhX2lkXzY2MjgxYmM2MDNhNzFhNDMwYjkwNmVmNyIsImNpZCI6Im1kYl9zYV9pZF82NjI4MWJjNjAzYTcxYTQzMGI5MDZlZjciLCJhY3RvcklkIjoibWRiX3NhX2lkXzY2MjgxYmM2MDNhNzFhNDMwYjkwNmVmNyIsImlhdCI6MTcxMzkwNTM1OSwiZXhwIjoxNzEzOTA4OTU5LCJqdGkiOiI4ZTg1MTM3YS0wZGU1LTQ0N2YtYTA0OS1hMmVmNTIwZGJhNTIifQ.AZSFvhcjwVcJYmvW6E_K5UnDmeiX2sJgL27vo5ElzeBuPawRciKkn6ervZ6IpUTx2HHllGgAAMmhaP9B66NywhfjAXC697X9KcOzm81DTtvDjLrFeRSc_3vFmeGvfUKKXljEdWBnbmwCwtBlO5SJuBxb1V5swAl-Sbq9Ymo4NbyepSnF","expires_in":3600,"token_type":"Bearer"}%
重要
访问令牌的有效期为 1 小时（3600 秒）。您无法刷新访问令牌。当此访问令牌过期时，重复此步骤以生成新的访问令牌。
调用 API。
将以下示例中的 {ACCESS-TOKEN} 替换为上一步的输出。
以下示例 GET 请求返回组织中的所有项目：
curl --request GET \ --url https://cloud.mongodb.com/api/atlas/v2/groups \ --header 'Authorization: Bearer {ACCESS-TOKEN}' \ --header 'Accept: application/vnd.atlas.2023-02-01+json' \ --header 'Content-Type: application/json'
以下示例 POST 请求采用请求正文并在您的组织中创建一个名为 MyProject 的项目：
curl --header 'Authorization: Bearer {ACCESS-TOKEN}' \ --header "Content-Type: application/json" \ --header "Accept: application/vnd.atlas.2023-02-01+json" \ --include \ --request POST "https://cloud.mongodb.com/api/atlas/v2/groups" \ --data ' { "name": "MyProject", "orgId": "5a0a1e7e0f2912c554080adc" }'
您的请求应类似于以下示例，其中，{PUBLIC-KEY} 是您的 API 公钥，{PRIVATE-KEY} 是相应的私钥。要通过 Atlas Administration API 浏览可用的端点，您可以使用 MongoDB 的 Postman 工作空间。
以下示例 GET 请求返回组织中的所有项目：
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \ --header "Content-Type: application/json" \ --header "Accept: application/vnd.atlas.2024-08-05+json" \ --include \ --request GET "https://cloud.mongodb.com/api/atlas/v2/groups"
以下示例 POST 请求采用请求正文并在您的组织中创建一个名为 MyProject 的项目：
curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \ --header "Content-Type: application/json" \ --header "Accept: application/vnd.atlas.2024-08-05+json" \ --include \ --request POST "https://cloud.mongodb.com/api/atlas/v2/groups" \ --data ' { "name": "MyProject", "orgId": "5a0a1e7e0f2912c554080adc" }'
另请参阅：
或者，您可以使用任何支持 OpenAPI v3 规范 的工具来生成代码示例或模拟服务器。例如，可以将 Atlas Admin API 规范导入 Postman，生成 curl 命令。要使用 Postman 生成 curl 命令：
在 MongoDB Atlas 管理 API 文档中，右键单击下载按钮并复制链接。
轮换服务帐户密钥
服务帐户密钥将在创建时指定的期限（从 8 小时到 365 天不等）后过期。到了轮换密钥的时间， Atlas会返回警报Service Account Secrets are about to expire。
注意
要配置服务帐户警报，请参阅配置警报设置。
要轮换服务帐户密钥，请完成以下步骤以生成新的客户端密钥，使用新的客户端密钥更新应用程序，然后删除旧密钥。
您可以使用Atlas用户用户界面生成新的客户端密钥并删除旧密钥。
您可以使用Atlas Administration API执行以下操作：
重要
生成新的客户端端密钥后，旧客户端密钥将在 7 天内过期。此有效期可以更短，具体取决于旧密钥的原始到期日期。
如果将旧密钥设立为在新密钥创建后超过 7 天过期，则其过期时间将缩短为自新密钥创建之日起 7 天。
如果将旧密钥设立为自新密钥创建之日起不超过 7 天内过期，则保留原始过期日期。
为避免失去对Atlas Administration API 的访问权限，请尽快使用新的客户端密钥更新您的应用程序。
后续步骤
要了解有关 Atlas Administration API 的更多信息，请参阅 Atlas Administration API 参考资料。
要管理对 Atlas Administration API 的编程访问，请参阅以下任一过程：