Atlas Administration API 参考

HTTP 方法

所有资源都支持这些常用 HTTP 方法的子集：

JSON

所有实体都以 JSON 表示。以下规则和惯例适用：

• 内容类型请求标头

  通过POST或PUT向服务器发送JSON时，请确保指定正确的内容类型请求标头： Content-Type: application/json

• 无效字段

  无效字段会被拒绝，而不是被忽略。 例如，如果您尝试创建新实体并拼错其中一个字段，或尝试更新现有实体但包含无法修改的字段，则服务器会以 400 状态代码和错误消息进行响应，说明是哪个实体字段无效。

• ISO-8601 格式日期

  所有日期都返回为 ISO-8601 - 以 UTC 格式指定的字符串。将日期发送到服务器时（即作为查询参数或POST 或PATCH 请求实体中的字段），请使用 ISO-8601 格式的日期。如果不指定时区域，则假定为 UTC。但是，强烈建议您包含时区域标识符以避免任何歧义。

• BSON 时间戳

  在某些情况下，时间戳会以BSON timestamp的形式返回，尤其是在备份资源中。 它们在JSON文档中表示为具有两个字段的对象：date（以 UTC 为单位、粒度精确到秒的 ISO-8601 格式的日期string ）和 increment（一个 32 位整数）。

• 包含数字的字段的字段名称

  将命名包含特定单位数值的字段，以便消除所使用单位的歧义。

• 空字段

  没有当前值的字段将返回适当的默认值。

  将从实体中省略没有合理默认值的字段。

• 字段排序

  服务器返回的 JSON 文档中的字段没有特定的顺序，并且顺序可能会发生变化。不要依赖字段的顺序。

链接

每个资源都包括一个或多个指向子资源和/或相关资源的链接。 链接放置在实体的links字段中，该实体是链接关系对象的数组。 每个链接关系都有两个字段：

所有实体都至少包含一个名为self的链接关系，即实体自己的URL 。 当实体是列表的一部分时，它仅包含self链接关系。

有关详情，请参阅网络链接规范。请注意，尽管该规范描述了在 HTTP 响应标头中包含链接的格式，但这不是必需的。为了使 Atlas Administration API 易于浏览，它将链接包含在响应正文中，而不是在响应标头中。

列表

某些资源会返回实体列表。当响应中预期有实体列表时，将按以下查询参数分批返回结果：

响应实体包含三个字段：

如果您请求实体列表但没有结果，则 Atlas Administration API 将使用 200 状态代码进行响应，并且results数组为空。 在这种情况下，它不会以 404 进行响应，因为实体列表在将来的某个点可能不为空。但是，如果您在不存在的上下文中请求实体列表（例如，不存在的项目的主机列表），则会导致 404 响应状态。

信封

某些客户端可能无法访问HTTP响应标头和/或状态代码。 在这种情况下，您可以请求响应包含一个“信封”，它只是JSON文档中的额外信息层，包含通常位于响应标头中的任何相关详细信息。 默认情况下，Atlas Administration API不会将响应包含在信封中。 要请求一个，只需添加查询参数envelope=true即可。

对于包含单个实体的响应，信封包含两个字段：

对于包含实体列表的响应，已经有一个包装结果的信封，因此指定envelope=true仅将status字段添加到现有信封。

美观打印

默认情况下，会从服务器返回的JSON中去掉多余空格。 要请求美观打印的JSON ，只需将pretty=true查询参数附加到任何请求：

curl --user '{USERNAME}:{APIKEY}' --digest \
  --header 'Accept: application/json' \
  --include \
  --request GET "https://cloud.mongodb.com/api/atlas/v1.0?pretty=true"

响应代码

响应使用标准 HTTP 响应代码，包括：

Errors

当请求返回错误时，响应正文将包含 JSON 文档。本文档详细介绍了 Atlas Administration API 请求失败的原因。该文档包含五个参数：

1
{
2
  "detail" : "Cannot find resource /api/atlas/v1.0/softwareComponents/version.",
3
  "error" : 404,
4
  "errorCode" : "RESOURCE_NOT_FOUND",
5
  "parameters" : [ "/api/atlas/v1.0/softwareComponents/version" ],
6
  "reason" : "Not Found"
7
}

项目 ID

项目 ID 是一个字符串值，用于唯一标识 Atlas 项目。

Atlas 项目此前被确定为“群组”。 某些 Atlas 端点引用group或{GROUP-ID}作为请求路径、查询或正文参数的一部分。 对于需要{GROUP-ID}的任何端点，请改为指定您的项目 ID。

要检索项目 ID，请执行以下操作：

身份验证

Atlas Administration API使用两种方法之一对请求进行身份验证： API密钥或服务帐户。这可确保用提供服务户名和密码的密钥和访问权限令牌永远不会通过网络发送。要学习；了解更多信息，请参阅Atlas Administration API身份验证。

有关用法详情，请参阅发送发送 API 请求。

速率限制

某些资源会限制每分钟可以处理的请求数量。

对于这些资源， Atlas允许每个项目每分钟最多100个请求。 Atlas Administration API身份验证方法属于一个组织，但可以授予对多个项目的访问权限。

如果超过速率限制，Atlas Administration API 将返回429 （请求过多） HTTP 状态代码。

后续步骤

要开始使用，请参阅 Atlas Administration API 入门。

要管理对 Atlas Administration API 的编程访问，请参阅以下任一过程：

• 管理对组织的编程访问。

• 管理对多个组织的编程访问。

• 管理对项目的编程访问。