开始使用 Atlas Administration API
重要
每个 Atlas Administration API 都有自己的资源，需要进行初始设置。
您只能通过公共互联网访问 Atlas Administration API 服务器。Atlas Administration API 不适用于使用网络对等互连或私有端点的连接。
要了解更多信息，请参阅 Atlas 编程访问权限。
Atlas Administration API 遵循 REST 架构风格的原则，以开放大量内部资源，从而能够以编程方式访问 Atlas 的功能。要了解更多信息，请参阅 Atlas Administration API 参考文档。
授予 Atlas 的编程访问权限
您可以使用以下两种身份验证方法之一向组织或项目授予编程访问权限：
API 密钥 | 服务帐户（预览版） |
|---|---|
使用 HTTP 摘要式身份验证验证 Atlas 的旧版方法。 | |
Atlas 使用一个称为 nonce 的唯一值对公钥和私钥进行哈希化处理。根据 HTTP 摘要式身份验证规范，nonce 的有效期很短。这是为了防止重放攻击，因此您不能缓存 nonce 并永远使用它。 | 创建服务帐号后，您将使用其客户端 ID 和机密生成访问令牌，用于对您的 API 请求进行身份验证。根据 OAuth 2.0 规范，访问令牌的有效期仅为 1 小时（3600 秒）。访问令牌过期可以防止重放攻击；在重放攻击中，可以不受时间限制地使用泄露的访问令牌。 |
Atlas 角色限制 API 密钥可以执行的操作。您必须向 API 密钥授予角色，就像为用户授予角色一样，以确保 API 密钥可以毫无错误地调用 API 端点。 | Atlas 角色限制了服务帐户使用其访问令牌可以执行的操作。必须向服务帐户授予角色，就像向用户授予角色一样，以确保访问令牌可以调用 API 端点而不会出错。 |
Atlas将许多资源绑定到一个项目。 许多API资源URL都遵循 | |
每个 API 密钥仅属于一个组织，但您可以授予多个 API 密钥访问权限，以访问该组织中任意数量的项目。 | 每个服务帐号仅属于一个组织，但您可以授予服务帐号访问权限，以访问该组织中任意数量的项目。 |
您无法使用 API 密钥通过 Atlas 用户界面登录 Atlas。 | 您无法使用服务帐户或其访问令牌通过 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 访问列表，请执行以下步骤：
在 Atlas 中，转到 Organization Settings（项目集成）页面。
如果尚未显示，组织从导航栏中的Organizations菜单。
单击 Organizations 菜单旁边的 Organization Settings 图标。
显示“组织设置”页面。
为组织授予编程访问权限
使用以下过程通过 API 密钥或服务帐号向组织授予编程访问权限。要了解有关这两种身份验证方法的更多信息，请参阅 Atlas 管理 API 身份验证。
重要
服务帐户当前处于预览状态。要了解更多信息，请参阅服务帐户概述。
必需的访问权限
要执行以下操作，您必须拥有 Atlas 的 Organization Owner 访问权限。
创建 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。
在 Atlas 中，转到 Organization Access Manager（项目设置）页面。
如果尚未显示，组织从导航栏中的Organizations菜单。
执行以下步骤之一：
从导航栏的Access Manager菜单中选择Organization Access 。
单击侧边栏中的 Access Manager（支持）。
显示“组织访问经理”页面。
输入 API Key Information（密钥保管库凭证）。
输入一个 Description。
在 Organization Permissions 菜单中选择 API 密钥 的一个或多个新角色。
在 Atlas 中，转到 Organization Access Manager（项目设置）页面。
如果尚未显示，组织从导航栏中的Organizations菜单。
执行以下步骤之一：
从导航栏的Access Manager菜单中选择Organization Access 。
单击侧边栏中的 Access Manager（支持）。
显示“组织访问经理”页面。
输入服务帐户信息。
输入一个 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 管理 API 身份验证。
重要
服务帐户当前处于预览状态。要了解更多信息，请参阅服务帐户概述。
必需的访问权限
要给予 API 密钥访问某个项目的权限，您必须拥有该项目 Project Owner 权限。
要给予服务帐户访问项目的权限，您必须对拥有该项目的组织具有 Organization Owner 访问权限。
为现有组织分配项目访问权限
如果您已经为组织创建了 API 密钥或服务帐户，则可以将其分配给某个项目，以授予该项目访问 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 密钥 的一个或多个新角色。
警告
如果为项目指定了组织服务帐户，则组织 Project Owner 可以管理服务帐户，包括轮换机密和更新 IP 访问列表。
您可以使用 Atlas 管理 API 授予现有服务帐户访问项目的权限。
从项目添加项目访问权限
如果您尚未为组织创建 API 密钥或服务帐户，则可以为项目创建它们，以授予该项目访问 Atlas 管理 API 的权限。为项目创建的 API 密钥或服务帐户会自动添加到父组织中，权限为 Organization Member。
要使用 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 密钥 的一个或多个新角色。
要使用 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}" } ] }%
提出 API 请求
Atlas 管理 API 使用以下两种身份验证方法之一来验证请求：API 密钥或服务帐户。您需要在配置首选身份验证方法时保存的密钥或机密才能完成以下过程。
重要
服务帐户当前处于预览状态。要了解更多信息，请参阅服务帐户概述。
所有 Atlas Administration API 端点均有以下基本 URL：
https://cloud.mongodb.com/api/atlas/<version>
您的请求应类似于以下示例，其中，{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" }'
要使用服务帐户发出 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" }'
或者，您可以使用任何支持 OpenAPI v3 规范 的工具来生成代码示例或模拟服务器。例如，可以将 Atlas Admin API 规范导入 Postman，生成 curl 命令。要使用 Postman 生成 curl 命令：
在 MongoDB Atlas 管理 API 文档中，右键单击下载按钮并复制链接。
后续步骤
要了解有关 Atlas Administration API 的更多信息，请参阅 Atlas Administration API 参考资料。
要管理对 Atlas Administration API 的编程访问，请参阅以下任一过程：