迁移到新版本的 Atlas Administration API

在此页面上

版本化 Atlas Administration API 简介
版本化 Atlas Administration API 生命周期
步骤

随着版本化 Atlas Administration API（此处称为/v2 ）的引入，我们建议您从旧版 Atlas Administration API（称为/v1 ）迁移到新版本化 Atlas Administration API ( /v2 )。。

版本化 Atlas Administration API 简介

新版本的 Atlas Administration API 在以编程方式访问 Atlas 方面提供了显着更好的整体体验。版本化的 Atlas Administration API 通过 API 更改提供可预测且一致的体验，并更好地了解新功能和更改。

版本化 Atlas Administration API 生命周期

当 Atlas 对 API 端点的当前稳定版本进行重大更改时，Atlas 会公开现有 API 端点的新资源版本。当 Atlas 公开新的资源版本时，Atlas 会自动弃用旧的资源版本。 Atlas 会在弃用后的十二个月自动删除已弃用的资源版本。尽管 Atlas 将继续支持旧资源版本在生产环境中使用长达十二个月，但您应尽快迁移到新版本的 API 端点。要了解更多信息，请参阅版本控制模式中的示例。

请注意，通过资源级版本控制，版本化 Atlas Administration API 中的每个资源都可以独立于其他资源引入新版本。只有当您正在使用的资源已被弃用时，您才需要采取行动。

例子

假设 Atlas 在2023-06-01中引入新的资源/serverless，但/backup没有任何破坏性变更 (breaking change)并保持在2023-02-01上。只有在利用/serverless资源时才必须迁移到2023-06-01 。如果您尚未实施/serverless资源，则无需执行任何操作。

Atlas 对已弃用资源版本的支持时间至少为 12 个月，直到被删除，这样您就有时间规划和过渡到新版本。您可以在API 变更日志中查看每个新资源的更改，并在 API 规范中查看 API 版本的详细信息。

步骤

要迁移到新的版本化 Atlas Administration API，您必须执行以下操作：

在资源的基本 URL 中指定代表版本化API的数字。

基本 URL

https://cloud.mongodb.com/api/atlas/<version-number>/

例子

考虑旧版 Atlas Administration API 资源的以下基本URL ：

https://cloud.mongodb.com/api/atlas/v1.0/

随着版本化管理 API 的引入，前面的基本URL表明您正在使用未进行版本化的资源。要将请求发送到版本化 Atlas Administration API ( /v2 ) 资源，您必须将请求发送到以下基本URL ：

https://cloud.mongodb.com/api/atlas/v2/

要了解如何在不同状态下向 Atlas Administration API 端点提交请求，请参阅版本控制模式。

将版本控制`Accept`标头添加到请求中。

要使用版本化 Atlas Administration API，您必须提供资源的资源版本。所有资源的第一个版本都是相同的，对于从未版本化的旧版 API 到版本化 API 的初始迁移，您必须使用与资源版本日期相对应的版本号。

例子

以下 curl 命令是向版本化 Atlas Administration API (v2) 端点发出的请求示例，其标头为：

curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
  --header "Accept: application/vnd.atlas.{yyyy-mm-dd}+json" \
  --request {GET|DELETE}
  "https://cloud.mongodb.com/api/atlas/v2/{RESOURCE}/{ENDPOINT}?{PARAMS}"

您还必须为POST 、 PUT或PATCH请求指定内容类型。内容类型的值可以是以下之一：

application/json
application/vnd.atlas.{yyyy-mm-dd}+json

例子

以下 curl 命令是向版本化 Atlas Administration API (v2) 端点发出的请求示例，其中包含标头和内容类型：

curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
  --header "Content-Type: application/vnd.atlas.{yyyy-mm-dd}+json" \
  --header "Accept: application/vnd.atlas.{yyyy-mm-dd}+json" \
  --request {POST|PUT|PATCH}
  "https://cloud.mongodb.com/api/atlas/v2/{RESOURCE}/{ENDPOINT}?{PARAMS}"

要了解有关版本化 Atlas Administration API 标头的更多信息，请参阅版本控制模式下的 API 生命周期。

查看变更日志以确定新资源版本中 Atlas Administration API 端点的语法更改。

API端点的新资源版本可能包含重大更改。确保您对新资源的请求包含这些更改，并且请求标头包含您要向其发送请求的端点的状态。

注意

您API 资源 AtlasAPIAtlasAPI到版本2023-02-01 /v1.0/clustersAtlasAPIv2 ）/clusters 资源。2023-02-01上版本化的 Atlas Administration API 的初始版本仅包含针对/clusters资源的语法更改。要了解更多信息，请参阅集群的 API 规范。

（可选）将未版本化的 Atlas Administration API v1.0 集群资源迁移到版本化的 Atlas Administration API (v2) 集群资源。

版本化 Atlas Administration API 的2023-02-01版本包含以下针对集群资源的语法更改：

版本化 Atlas Administration API (v2) 端点请求类型	变更日志
发布	包括以下更改：删除以下请求属性： `mongoURIWithOptions` `providerBackupEnabled` `mongoURIUpdated` `srvAddress` `replicationSpec` `mongoURI` `numShards` `autoScaling` `providerSettings` `replicationFactor` `replicationSpecs.regionsConfig` 添加请求属性`replicationSpecs.regionConfigs` 从响应中删除以下可选属性： `mongoURIWithOptions` `providerBackupEnabled` `mongoURIUpdated` `srvAddress` `replicationSpec` `mongoURI` `numShards` `autoScaling` `providerSettings` `replicationFactor` `replicationSpecs.regionsConfig` 添加响应属性`replicationSpecs.regionConfigs`
GET（全部）	包括以下更改：从响应中删除以下可选属性： `results.items.mongoURIWithOptions` `results.items.providerBackupEnabled` `results.items.mongoURIUpdated` `results.items.srvAddress` `results.items.replicationSpec` `results.items.mongoURI` `results.items.numShards` `results.items.autoScaling` `results.items.providerSettings` `results.items.replicationFactor` `results.items.replicationSpecs.regionsConfig` 添加响应属性`results.items.replicationSpecs.regionConfigs`
GET（一）	包括以下更改：从响应中删除以下可选属性： `mongoURIWithOptions` `providerBackupEnabled` `mongoURIUpdated` `srvAddress` `replicationSpec` `mongoURI` `numShards` `autoScaling` `providerSettings` `replicationFactor` `replicationSpecs.regionsConfig` 添加响应属性`results.items.replicationSpecs.regionConfigs`
PATCH（一）	包括以下更改：从响应中删除以下可选属性： `mongoURIWithOptions` `providerBackupEnabled` `mongoURIUpdated` `srvAddress` `replicationSpec` `mongoURI` `numShards` `autoScaling` `providerSettings` `replicationFactor` `replicationSpecs.regionsConfig` 添加响应属性`results.items.replicationSpecs.regionConfigs` 从响应中删除以下可选属性： `mongoURIWithOptions` `providerBackupEnabled` `mongoURIUpdated` `srvAddress` `replicationSpec` `mongoURI` `numShards` `autoScaling` `providerSettings` `replicationFactor` `replicationSpecs.regionsConfig` 添加响应属性`replicationSpecs.regionConfigs`

如果您使用未版本化的Atlas Administration API /clusters资源创建一个、获取一个、获取全部、修改一个或删除一个集群，请迁移到创建一个、获取一个、获取所有、修改一个和删除一个端点版本化的Atlas Administration API (v 2 )集群资源。

如果您还不想迁移到2023-02-01版本，则只需执行使用2023-01-01 API版本过程中的第 1 步和第 2 步。请注意， 2023-01-01已弃用。

后退

Versioning Overview

来年

API升级