Atlas 관리 API 참조

HTTP 메서드

모든 리소스는 다음과 같은 일반적인 HTTP 메서드의 하위 집합을 지원합니다.

JSON

모든 엔터티는 JSON 으로 표시됩니다. 다음 규칙과 관례가 적용됩니다.

• 콘텐츠 유형 요청 헤더

  POST 또는 PUT 을 통해 서버에 JSON 을 보낼 때는 올바른 콘텐츠 유형 요청 헤더 Content-Type: application/json를 지정해야 합니다.

• 잘못된 필드

  유효하지 않은 필드는 무시 되지 않고 거부 됩니다. 예를 들어 새 엔터티를 만들려고 할 때 필드 중 하나의 철자를 잘못하거나 기존 엔터티를 업데이트하려고 시도할 때 수정할 수 없는 필드를 포함하면 서버는 400 상태 코드와 다음을 나타내는 오류 메시지로 응답합니다. 필드가 유효하지 않습니다.

• ISO-8601 형식의 날짜

  모든 날짜는 UTC로 지정된ISO- 형식의 문자열로 반환됩니다.8601 서버 에 날짜를 보낼 때(예: POST 또는 PATCH 요청 엔터티의 쿼리 매개변수 또는 필드로) ISO8601형식의 날짜를 사용합니다. 구역 를 지정하지 않으면 UTC가 사용됩니다. 그러나 모호하지 않도록 표준 구역 지정자를 포함하는 것이 좋습니다.

• BSON 타임스탬프

  경우에 따라 타임스탬프가 BSON 타임스탬프 로 반환되는 경우가 있는데, 특히 백업 리소스에서 많이 나타납니다. 이는 문서에서 두 개의 필드가 있는 객체로 JSON 표시되며, 이 두 필드는date(초 단위로8601 string 세분화된 UTC의 ISO 형식의 날짜 increment 32) 및 ( 비트 정수)입니다.

• 숫자가 포함된 필드의 필드 이름

  특정 단위의 숫자 값이 포함된 필드는 사용 중인 단위를 명확히 구분할 수 있도록 이름이 지정됩니다.

• 빈 필드

  현재 값이 없는 필드는 적절한 기본값과 함께 반환됩니다.

  적절한 기본값이 없는 필드는 엔터티에서 생략됩니다.

• 필드 순서

  서버가 반환하는 JSON 문서의 필드는 특정한 순서가 없으며 순서는 변경될 수 있습니다. 필드의 순서에 의존하지 마세요.

연결

각 리소스에는 하위 리소스 및/또는 관련 리소스에 대한 링크가 하나 이상 포함되어 있습니다. 링크는 링크 관계 객체의 배열인 엔터티의 links 필드에 배치됩니다. 각 링크 관계에는 두 개의 필드가 있습니다.

모든 엔터티에는 자체 URL 인 self 이라는 링크 관계가 하나 이상 포함되어 있습니다. 엔터티가 목록의 일부인 경우에는 self 링크 관계만 포함됩니다.

자세한 내용은 웹 연결 사양 을 참조하세요. 사양에 HTTP 응답 헤더에 링크를 포함하는 형식이 설명되어 있지만, 반드시 링크를 포함해야 하는 것은 아닙니다. 쉽게 탐색할 수 있도록 Atlas 관리 API는 응답 헤더가 아닌 응답 본문에 링크를 포함합니다.

목록

일부 리소스는 엔터티 목록을 반환합니다. 응답에서 엔터티 목록이 예상되는 경우 결과는 다음 쿼리 매개변수에 의해 제한된 일괄 처리로 반환됩니다.

응답 엔터티에는 세 개의 필드가 포함되어 있습니다.

엔터티 목록을 요청했는데 결과가 없는 경우 Atlas 관리 API는 200 상태 코드로 응답하고 results 배열이 비어 있게 됩니다. 이 경우 404로 응답하지 않는데 , 이는 엔터티 목록이 나중에 비어 있지 않을 수도 있는 점 때문입니다. 그러나 존재하지 않는 컨텍스트의 엔터티 목록(예: 존재 하지 않는 프로젝트의 호스트 목록)을 요청하면 404 응답 상태가 됩니다.

Envelopes

일부 클라이언트는 HTTP 응답 헤더 및/또는 상태 코드에 액세스하지 못할 수 있습니다. 이 경우 응답에 '엔벨로프(envelope)'를 포함하도록 요청할 수 있는데, 엔벨로프는 단순히 JSON 문서의 추가 정보 계층이며 일반적으로 응답 헤더에 있는 모든 관련 세부 정보를 포함합니다. 기본적으로 Atlas 관리 API는 엔벨로프에 응답을 포함하지 않습니다 . 요청하려면 쿼리 매개변수 envelope=true 를 추가하기만 하면 됩니다.

단일 엔터티가 포함된 응답의 경우 엔벨로프에는 다음과 같은 두 개의 필드가 포함됩니다.

엔터티 목록이 포함된 응답의 경우 결과를 래핑하는 엔벨로프가 이미 있으므로 envelope=true 를 지정하면 기존 엔벨로프에 status 필드만 추가됩니다.

Pretty Printing

기본적으로 서버가 반환하는 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 응답 코드를 사용합니다.

오류

요청이 오류를 반환하면 응답 본문에 JSON 문서가 표시됩니다. 이 문서에는 Atlas 관리 API 요청이 실패한 이유에 대한 자세한 내용이 포함되어 있으며, 다음과 같은 5개의 매개변수 또한 포함되어 있습니다.

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 관리 API 는API 키 또는 서비스 계정이라는 두 가지 방법 중 하나를 사용하여 요청을 인증합니다. 이렇게 하면 사용자 이름과 비밀번호 제공 을 하는 키와 액세스 토큰이 네트워크를 통해 전송되지 않습니다. 학습보려면 Atlas 관리 API 인증을 참조하세요.

사용법에 대한 자세한 내용은 API 요청하기를 참조하세요.

속도 제한

특정 리소스는 분당 처리할 수 있는 요청 수를 제한합니다.

이러한 리소스의 경우 Atlas 는 100 프로젝트 당 분당 최대 개의 요청을 허용합니다. Atlas 관리 API 인증 방법은 조직 에 속하지만 여러 프로젝트에 대한 액세스 을 부여할 수 있습니다.

속도 제한을 초과하는 경우 Atlas 관리 API는 를 반환합니다.429 (너무 많은 요청) HTTP 상태 코드입니다.

다음 단계

시작하려면 Atlas 관리 API 시작하기를 참조하세요.

Atlas 관리 API에 대한 프로그래밍 방식의 액세스를 관리하려면 다음 절차 중 하나를 참조하세요.

• 조직에 대한 프로그래밍 방식의 접근을 관리합니다.

• 여러 조직에 대한 프로그래밍 방식의 액세스를 관리합니다.

• 프로젝트에 대한 프로그래밍 방식의 접근을 관리합니다.