Azure Cosmos DB와의 RESTful 상호 작용

아티클
2023. 07. 19.

Azure Cosmos DB 는 문서, 그래프 및 키-값 데이터 모델을 지원하는 전역적으로 분산된 다중 모델 데이터베이스입니다. 이 섹션의 내용은 REST를 통해 SQL API 를 사용하여 문서 리소스를 만들고, 쿼리하고, 관리하기 위한 것입니다.

이 문서를 읽으면 다음 질문에 대답할 수 있습니다.

표준 HTTP 메서드는 Azure Cosmos DB 리소스에서 어떻게 작동합니까?
POST를 사용하여 새 리소스를 만드는 방법
POST를 사용하여 저장 프로시저를 등록하는 방법
Azure Cosmos DB는 동시성 제어를 어떻게 지원하나요?
HTTPS 및 TCP에 대한 연결 옵션

REST를 사용하여 특정 리소스에서 CRUD 작업을 수행하는 방법에 대한 자세한 내용은 Azure Cosmos DB REST API를 사용하는 일반적인 작업을 참조하세요. C# 및 REST를 사용하여 CRUD 작업을 수행하는 방법에 대한 샘플을 찾고 있는 경우 GitHub의 .NET 샘플에서 REST 를 참조하세요.

참고

Cosmos DB SDK를 사용하여 Cosmos DB 리소스에서 CRUD 작업을 수행할 수도 있습니다. 샘플은 Azure Cosmos DB 예제를 참조하세요. SDK 다운로드 및 설명서에 대한 링크는 Cosmos DB SDK를 참조하세요.

HTTP 동사 개요

Azure Cosmos DB 리소스는 표준 해석을 통해 다음 HTTP 동사를 지원합니다.

POST는 새 항목 리소스 만들기를 의미합니다.
GET은 기존 항목 또는 피드 리소스 읽기를 의미합니다.
PUT은 기존 항목 리소스 바꾸기를 의미합니다.
DELETE는 기존 항목 리소스 삭제를 의미합니다.
HEAD GET이 응답 페이로드(즉, 헤더만)를 sans한다는 것을 의미합니다.

다음 HTTP 동사 다이어그램에 표시된 대로, POST는 피드 리소스에 대해서만 실행할 수 있고 PUT 및 DELETE는 항목 리소스에 대해서만 실행할 수 있고 GET 및 HEAD는 피드 또는 항목 리소스에 대해서만 실행할 수 있습니다.

표준 HTTP 메서드를 사용하는 상호 작용 모델

표준 HTTP 메서드를 사용한 조작 모델

POST HTTP 메서드를 사용하여 새 리소스 만들기

조작 모델의 이해를 돕기 위해 새 리소스를 만드는 경우(INSERT라고도 함)를 고려해 보겠습니다. 새 리소스를 만들려면 리소스가 속한 컨테이너 피드의 URI에 대한 리소스 표현이 포함된 요청 본문으로 HTTP POST 요청을 실행해야 합니다. 요청에 필요한 유일한 속성은 리소스의 ID입니다.

예를 들어 새 데이터베이스를 만들기 위해 /dbs에 대해 ID 속성을 고유한 이름으로 설정하여 데이터베이스 리소스를 게시합니다. 마찬가지로 새 컬렉션을 만들려면 /dbs/_rid/colls/ 등에 대해 컬렉션 리소스를 게시합니다. 응답에는 다른 리소스로 이동할 수 있는 리소스의 _self 링크를 포함하여 시스템 생성 속성이 포함된 완전히 커밋된 리소스가 포함됩니다. 간단한 HTTP 기반 상호 작용 모델의 예로 클라이언트는 계정 내에서 새 데이터베이스를 만들기 위해 HTTP 요청을 실행할 수 있습니다.

POST https://fabrikam.documents.azure.com/dbs  
{  
    "id":"MyDb"
}

예를 들어 새 데이터베이스 POST 를 만들려면 에 대해 고유한 이름으로 ID 속성을 설정하여 데이터베이스 리소스를 만듭니다 /dbs. 마찬가지로, 새 컬렉션을 POST 만들기 위해 컬렉션 리소스 등을 사용합니다 /dbs/_rid/colls/ . 응답에는 다른 리소스로 이동할 수 있는 를 사용하는 리소스 링크를 포함하여 _self 시스템 생성 속성이 포함된 완전히 커밋된 리소스가 포함됩니다. 간단한 HTTP 기반 상호 작용 모델의 예로 클라이언트는 계정 내에서 새 데이터베이스를 만들기 위해 HTTP 요청을 실행할 수 있습니다.

Azure Cosmos DB 서비스는 성공적인 응답과 데이터베이스를 성공적으로 만들 수 있음을 나타내는 상태 코드로 응답합니다.

HTTP/1.1 201 Created  
Content-Type: application/json  
x-ms-request-charge: 4.95  
...  
  
{  
    "id": "MyDb",  
    "_rid": "UoEi5w==",  
    "_self": "dbs/UoEi5w==/",  
    "_ts": 1407370063,  
    "_etag": "00000100-0000-0000-0000-54b636600000",  
    "_colls": "colls/",  
    "_users": "users/"  
}

POST HTTP 메서드를 사용하여 저장 프로시저 등록

리소스를 만들고 실행하는 또 다른 예로, JavaScript로만 작성된 단순한 "HelloWorld" 저장 프로시저를 고려해 보세요.

function HelloWorld() {  
    var context = getContext();  
    var response = context.getResponse();  

    response.setBody("Hello, World");  
}

에 대해 /dbs/_rid-db/colls/_rid-coll/sprocsPOST를 발급하여 MyDb 아래의 컬렉션에 저장 프로시저를 등록할 수 있습니다.

POST https://fabrikam.documents.azure.com/dbs/UoEi5w==/colls/UoEi5w+upwA=/sprocs HTTP/1.1  
  
{  
    "id": "HelloWorld",  
    "body": "function HelloWorld() {  
                var context = getContext();  
                var response = context.getResponse();  

                response.setBody("Hello, World");  
            }"  
}

Azure Cosmos DB 서비스는 성공적인 응답과 저장 프로시저의 성공적인 등록을 나타내는 상태 코드로 응답합니다.

HTTP/1.1 201 Created  
Content-Type: application/json  
x-ms-request-charge: 4.95  
...  
  
{  
    "body": "function HelloWorld() {  
        var context = getContext();  
        var response = context.getResponse();  

        response.setBody("Hello, World");  
        }",  
    "id": "HelloWorld"  
    "_rid": "UoEi5w+upwABAAAAAAAAgA==",  
    "_ts" :  1421227641  
    "_self": "dbs/UoEi5w==/colls/UoEi5w+upwA=/sprocs/UoEi5w+upwABAAAAAAAAgA==/",  
    "_etag": "00002100-0000-0000-0000-50f71fda0000"  
}

POST HTTP 메서드를 사용하여 저장 프로시저 실행

마지막으로, 이전 예제에서 저장 프로시저를 실행하려면 아래 그림과 같이 저장 프로시저 리소스(/dbs/UoEi5w==/colls/UoEi5w+upwA=/sprocs/UoEi5w+upwABAAAAAAAAgA==/)의 URI에 대해 을 실행 POST 해야 합니다.

POST https://fabrikam.documents.azure.com/dbs/UoEi5w==/colls/UoEi5w+upwA=/sprocs/UoEi5w+upwABAAAAAAAAgA== HTTP/1.1

Azure Cosmos DB 서비스는 다음 응답으로 응답합니다.

HTTP/1.1 200 OK  
  
"Hello World"

POST HTTP 동사는 새 리소스를 만들거나 저장 프로시저를 실행하거나 SQL 쿼리를 실행하는 데 사용됩니다. SQL 쿼리 실행을 보여 주기 위해 다음을 고려하세요.

POST https://fabrikam.documents.azure.com/dbs/UoEi5w==/colls/UoEi5w+upwA=/docs HTTP/1.1  
...  
x-ms-documentdb-isquery: True  
x-ms-documentdb-query-enable-scan: True  
Content-Type: application/query+json  
...  

{"query":"SELECT f.LastName AS Name, f.Address.City AS City FROM Families f WHERE f.id='AndersenFamily' OR f.Address.City='NY'"}

서비스가 SQL 쿼리 결과로 응답합니다.

HTTP/1.1 200 Ok  
...  
x-ms-activity-id: 83f9992c-abae-4eb1-b8f0-9f2420c520d2  
x-ms-item-count: 2  
x-ms-session-token: 4  
x-ms-request-charge: 3.1  
Content-Type: application/json1  

{"_rid":"UoEi5w+upwA=","Documents":[{"Name":"Andersen","City":"Seattle"},{"Name":"Wakefield","City":"NY"}],"_count":2}

PUT, GET 및 DELETE HTTP 동사 사용

리소스를 교체하거나 읽는 것은 각각 리소스의 _self 링크에 대해 발급 PUT (유효한 요청 본문 포함) 및 GET 동사에 해당합니다. 마찬가지로 리소스를 삭제하면 리소스의 _self 링크에 대해 동사를 발급하는 DELETE 데 해당합니다. Azure Cosmos DB의 리소스 모델에서 리소스의 계층적 organization 소유자 리소스를 삭제하면 종속 리소스가 삭제되는 경우 연속 삭제에 대한 지원이 필요하다는 점을 지적할 필요가 있습니다. 종속 리소스가 소유자 리소스와 다른 노드에 분산될 수도 있으므로 삭제가 지연 발생할 수 있습니다. 가비지 수집 방식에 관계없이 리소스를 삭제하면 할당량이 즉시 해제되고 사용할 수 있게 됩니다. 참조 무결성은 시스템에서 유지합니다. 예를 들어 삭제된 데이터베이스에 컬렉션을 삽입하거나 더 이상 존재하지 않는 컬렉션의 문서를 바꾸거나 쿼리할 수 없습니다.

GET 리소스 피드에 대해 을 실행하거나 컬렉션을 쿼리하면 잠재적으로 수백만 개의 항목이 발생할 수 있으므로 서버와 클라이언트가 단일 왕복/요청 및 응답 교환의 일부로 이를 사용하는 것은 실용적이지 않습니다. 이 문제를 해결하기 위해 Azure Cosmos DB를 사용하면 클라이언트가 한 번에 큰 피드 페이지를 매길 수 있습니다. 클라이언트는 [x-ms-continuation] 응답 헤더를 커서로 사용하여 다음 페이지로 이동할 수 있습니다.

낙관적 동시성 제어

대부분의 웹 애플리케이션은 "업데이트 손실" 및 "삭제 손실" 문제를 방지하기 위해 엔터티 태그 기반 낙관적 동시성 제어를 사용합니다. 엔터티 태그는 HTTP에서 잘 작동하는 논리적 타임스탬프로, 리소스와 연결됩니다. Cosmos DB는 기본적으로 모든 HTTP 응답에 특정 리소스와 연결된 버전(지속성)이 포함되어 있는지 확인하여 낙관적 동시성 제어를 지원합니다. 다음과 같은 경우 동시성 제어 충돌이 올바르게 검색됩니다.

두 클라이언트가 최신 버전의 리소스([if-match] 요청 헤더를 통해 지정됨)가 있는 리소스에서 PUT/DELETE 동사를 통해 동시에 변경 요청을 발행하는 경우 Cosmos DB 데이터베이스 엔진은 이를 트랜잭션 동시성 제어에 적용합니다.
클라이언트가 [if-match] 요청 헤더를 통해 지정된 이전 리소스 버전을 제공할 경우 요청이 거부됩니다.

연결 옵션

Cosmos DB는 각 리소스에 _self 링크로 식별된 논리적이고 안정적인 URI가 있는 논리적 주소 지정 모델을 노출합니다. 분산 스토리지 시스템이 지역에 분산됨에 따라 Cosmos DB의 다양한 데이터베이스 계정 아래에 있는 리소스는 여러 컴퓨터에 분할되고 각 파티션은 고가용성을 위해 복제됩니다. 지정된 파티션의 리소스를 관리하는 복제본은 물리적 주소를 등록합니다. 물리적 주소는 실패로 인해 점차 변경되지만 논리적 주소는 안정적이고 일정하게 유지됩니다. 논리적-물리적 주소 변환이 유지되는 라우팅 테이블도 내부적으로 리소스로 사용할 수 있습니다. Cosmos DB는 두 가지 연결 모드를 노출합니다.

게이트웨이 모드: 클라이언트는 논리적 주소와 실제 주소 간 또는 라우팅 세부 정보 간의 변환으로부터 보호됩니다. 논리 URI를 처리하고 리소스 모델을 RESTfully 탐색하기만 하면 됩니다. 클라이언트는 논리 URI를 사용하여 요청을 실행하고 에지 머신은 논리 URI를 리소스를 관리하고 요청을 전달하는 복제본(replica) 실제 주소로 변환합니다. 에지 머신이 라우팅 테이블을 캐싱하고 주기적으로 새로 고치면 라우팅이 매우 효율적입니다.
직접 연결 모드: 클라이언트가 해당 프로세스 공간에서 직접 라우팅 테이블을 관리하고 주기적으로 새로 고칩니다. 클라이언트가 복제본에 직접 연결하고 에지 컴퓨터를 무시할 수 있습니다.

연결 모드	프로토콜	세부 정보	Azure Cosmos DB SDK
게이트웨이	HTTPS	애플리케이션이 논리적 URI를 사용하여 에지 노드에 직접 연결합니다. 이 경우 추가 네트워크 홉이 발생합니다.	REST API, .NET, Node.js, Java, Python, JavaScript
직접 연결	HTTPS 및 TCP	애플리케이션이 라우팅 테이블에 직접 액세스하고 클라이언트 쪽 라우팅을 수행하여 복제본에 직접 연결할 수 있습니다.	.NET, Java

다음을 통해 공유