새 버전이 지정된 Atlas 관리 API로 마이그레이션

이 페이지의 내용

버전이 지정된 Atlas 관리 API 소개

버전이 지정된 Atlas 관리 API 수명 주기
절차

버전이 지정된 Atlas Administration API( 여기서는 /v2 라고 함)가 도입됨에 따라 레거시 Atlas Administration API( /v1)에서 버전이 지정된 새 Atlas Administration API(/v2).

버전이 지정된 Atlas 관리 API 소개

새로운 버전의 Atlas 관리 API는 프로그래밍 방식으로 Atlas에 액세스할 때 전반적인 환경이 크게 향상되었습니다. 버전이 지정된 Atlas 관리 API는 API 변경 사항에 대해 예측 가능하고 일관된 환경을 제공하고 새로운 기능 및 변경 사항에 대한 더 나은 가시성을 제공합니다.

버전이 지정된 Atlas 관리 API 수명 주기

Atlas 가 API 엔드포인트의 현재 안정적인 버전에 Atlas 이 손상되는 변경을 도입할 때 기존 API 엔드포인트의 새 리소스 버전을 노출합니다. Atlas 가 새 리소스 버전을 노출하면 Atlas 는 이전 리소스 버전을 자동으로 더 이상 사용하지 않습니다. Atlas 는 사용 중단 후 12개월 후에 사용 중단된 리소스 버전을 자동으로 삭제합니다. Atlas 는 프로덕션 환경에서 사용할 수 있도록 이전 리소스 버전을 최대 12개월 동안 계속 지원 하지만, 가능한 한 빨리 새 버전의 API 엔드포인트 마이그레이션 해야 합니다. 학습 내용은 버전 관리 스키마의 예시 를 참조하세요.

리소스 수준 버전 관리를 사용하면 버전이 지정된 Atlas 관리 API의 각 리소스가 다른 리소스와 독립적으로 새 버전을 도입할 수 있습니다. 활용 중인 리소스가 더 이상 사용되지 않는 경우에만 조치를 취해야 합니다.

예시

Atlas에서 2023-06-01에 새로운 /serverless 리소스를 도입했지만 /backup 에 호환성이 손상되는 변경이 없으며 2023-02-01에도 유지된다고 가정합니다. /serverless 리소스를 활용하는 경우에만 2023-06-01로 마이그레이션해야 합니다. /serverless 리소스를 구현하지 않은 경우 아무런 조치를 취할 필요가 없습니다.

Atlas는 사용 중단된 리소스 버전이 제거될 때까지 최소 12개월 동안 지원하며, 이를 통해 새 버전을 계획하고 전환할 수 있는 시간을 확보할 수 있습니다. API 변경 로그 에서 각각의 새 리소스의 변경 사항을 확인하고 API 사양에서 API 버전에 대한 세부 정보를 확인할 수 있습니다.

절차

버전이 지정된 새로운 Atlas 관리 API로 마이그레이션하려면 다음을 수행해야 합니다.

리소스 의 기본 URL 에 버전이 지정된 API 를 나타내는 번호를 지정합니다.

기본 URL

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

예시

레거시 버전의 Atlas 관리 API 리소스에 대한 다음 기본 URL 을 고려하세요.

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

버전이 지정된 관리자 API가 도입되면서 앞의 기본 URL 은 버전이 지정되지 않은 리소스를 사용하고 있음을 나타냅니다. 버전이 지정된 Atlas 관리 API(/v2) 리소스에 요청을 보내려면 다음 기본 URL 로 요청을 보내야 합니다.

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

다양한 상태의 Atlas 관리 API 엔드포인트에 요청을 제출하는 방법을 알아보려면 버전 관리 스키마를 참조하세요.

요청에 버전 관리 `Accept` 헤더를 추가합니다.

버전이 지정된 Atlas 관리 API를 사용하려면 리소스에 대한 리소스 버전을 제공해야 합니다. 첫 번째 버전은 모든 리소스에서 동일하며, 버전이 없는 레거시 API에서 버전이 지정된 API로 처음 마이그레이션하는 경우 리소스 버전 날짜에 해당하는 버전 번호를 사용해야 합니다.

예시

다음 curl 명령은 헤더를 사용하여 버전이 지정된 Atlas 관리 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 관리 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 관리 API 헤더에 대해 자세히 알아보려면 버전 관리 스키마 아래의API 수명 주기를 참조하세요.

변경 로그를 검토하여 새 리소스 버전에서 Atlas 관리 API 엔드포인트에 대한 구문 변경 사항을 확인합니다.

API 엔드포인트의 새 리소스 버전에는 호환성이 손상되는 변경이 포함될 수 있습니다. 새 리소스에 대한 요청에 이러한 변경 사항이 포함되어 있고 요청 헤더에 요청을 보내는 엔드포인트의 상태가 포함되어 있는지 확인합니다.

참고

/v1.0/clusters 리소스를 버전이 지정된 데이터베이스로 마이그레이션하지 않는 한, 버전이 지정되지 않은 Atlas 관리 API에서 리소스 버전 2023-02-01 에서 버전이 지정된 Atlas 관리 API로의 초기 마이그레이션에 대해 API 변경 로그 를 확인할 필요가 없습니다. Atlas 관리 API(v2) /clusters 리소스입니다. 2023-02-01 버전이 지정된 Atlas 관리 API의 초기 릴리스에는 /clusters 리소스에 대한 구문 변경 사항만 포함되어 있습니다. 자세한 내용은 클러스터에 대한 API 사양을 참조하세요.

(선택 사항) 버전이 없는 Atlas 관리 API v1.0 cluster 리소스를 버전이 지정된 Atlas 관리 API(v2) cluster 리소스로 마이그레이션합니다.

버전이 지정된 Atlas 관리 API의 2023-02-01 릴리스에는 클러스터 리소스에 대한 다음과 같은 구문 변경 사항이 포함되어 있습니다.

버전이 지정된 Atlas 관리 API(v2) 엔드포인트 요청 유형	ChangeLog
POST	다음과 같은 변경 사항이 포함됩니다: 다음 요청 속성을 제거합니다: `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`
패치(1개)	다음과 같은 변경 사항이 포함됩니다: 응답에서 다음과 같은 선택적 속성을 제거합니다. `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 관리 API /clusters 리소스 를 사용하여 클러스터를 생성, 가져오기, 모두 가져오기, 하나 수정 또는 삭제 하나 의 클러스터 로 마이그레이션 하는 경우, 클러스터 생성, 가져오기, 모두 가져오기, 하나 수정 및 하나의 엔드포인트 삭제 로 마이그레이션합니다. 버전이 지정된 Atlas 관리 API (v2) 클러스터 리소스 입니다.

아직 2023-02-01 버전으로 마이그레이션하지 않으려면 2023-01-01 API 버전을 사용하는 절차의 1단계와 2단계만 수행합니다. 2023-01-01 는 더 이상 사용되지 않습니다.

돌아가기

Versioning Overview

API 업그레이드