REST API를 사용하여 Azure Cosmos DB 리소스 쿼리

Azure Cosmos DB는 여러 API를 지원하는 전역으로 분산된 다중 모델 데이터베이스입니다. 이 문서에서는 REST를 사용하여 SQL API를 사용하여 리소스를 쿼리하는 방법을 설명합니다.

REST를 사용하여 리소스를 쿼리하는 방법

리소스에 대한 SQL 쿼리를 수행하려면 다음 단계를 진행합니다.

• 속성이 POST SQL 쿼리 문자열로 설정된 JSON과 query 선택적 매개 변수 값의 배열로 설정된 "parameters" 속성을 사용하여 리소스 경로에 대해 메서드를 실행합니다.
• x-ms-documentdb-isquery 헤더를 True으로 설정합니다.
• Content-Type 헤더를 application/query+json으로 설정합니다.

.NET을 사용하여 리소스에서 SQL 쿼리를 수행하는 방법을 보여 주는 샘플은 .NET 샘플의 REST를 참조하세요.

예제

아래에는 문서 리소스에 대한 예제 REST 쿼리 작업이 나와 있습니다. 이 예제에서는 작성자가 "Don"인 모든 문서를 찾습니다.

POST https://contosomarketing.documents.azure.com/dbs/XP0mAA==/colls/XP0mAJ3H-AA=/docs HTTP/1.1  
x-ms-documentdb-isquery: True  
x-ms-date: Mon, 18 Apr 2015 13:05:49 GMT  
authorization: type%3dmaster%26ver%3d1.0%26sig%3dkOU%2bBn2vkvIlHypfE8AA5fulpn8zKjLwdrxBqyg0YGQ%3d  
x-ms-version: 2015-12-16  
x-ms-query-enable-crosspartition: True  
Accept: application/json  
Content-Type: application/query+json  
Host: contosomarketing.documents.azure.com  
Content-Length: 50  

{  
    "query": "SELECT * FROM root WHERE (root.Author.id = 'Don')",  
    "parameters": []  
}  
  

요청 세부 정보

방법	요청 URI
POST	필수. 인증 유형과 서명 토큰입니다. 이 작업에는 마스터 키 토큰만 사용할 수 있습니다. 자세한 내용은 Cosmos DB 리소스에 대한 Access Control 참조하세요.

요청 헤더

아래 표에는 쿼리 작업을 수행하는 데 사용되는 일반 헤더가 나와 있습니다.

표준 헤더	설명
권한 부여	필수. 인증 유형과 서명 토큰입니다. 이 작업에는 마스터 키 토큰만 사용할 수 있습니다. 자세한 내용은 Cosmos DB 리소스에 대한 Access Control 참조하세요.
Content-Type	필수. application/query+json으로 설정해야 합니다.
수락	선택 사항입니다. 현재 Cosmos DB는 항상 표준 JSON 형식으로 응답 페이로드를 반환합니다. 클라이언트에서 표준 JSON 형식의 응답 본문을 수락할 수 있어야 합니다.
User-Agent	선택 사항입니다. 요청을 수행하는 사용자 에이전트입니다. 권장되는 형식은 {사용자 에이전트 이름}/{버전}입니다. 예를 들어 SQL API .NET SDK는 User-Agent 문자열을 Microsoft.Document.Client/1.0.0.0으로 설정합니다.

사용자 지정 헤더	설명
x-ms-date	필수. RFC 1123에 지정된 요청 날짜입니다. 예를 들어 날짜 형식은 UTC(협정 세계시)로 표현됩니다. 2015/4/08(금) 03:52:31 GMT와 같이 UTC(협정 표준시)로 표시됩니다.
x-ms-documentdb-isquery	필수. 이 속성은 true로 설정해야 합니다.
x-ms-max-item-count	선택 사항입니다. 결과 집합에서 페이지를 설정하려면 이 헤더를 단일 페이지에서 반환할 항목의 최대 수로 설정합니다.
x-ms-continuation	선택 사항입니다. 다음 항목 페이지로 이동하려면 이 헤더를 다음 페이지의 연속 토큰으로 설정합니다.
x-ms-version	선택 사항입니다. Cosmos DB REST 서비스의 버전입니다. 이 헤더가 제공되지 않으면 최신 버전이 사용됩니다. 자세한 내용은 Azure Cosmos DB REST API 참조를 참조하세요.
x-ms-documentdb-query-enable-scan	선택 사항입니다. 형식의 올바른 인덱스 경로를 사용할 수 없는 경우 인덱스 검색을 사용하여 쿼리를 처리합니다.
x-ms-session-token	선택 사항입니다. 요청의 세션 토큰입니다. 세션 일관성을 유지하는 데 사용됩니다.
x-ms-partition-key	선택 사항입니다. 지정된 경우 쿼리는 헤더의 파티션 키 값과 일치하는 문서에서만 실행됩니다.
x-ms-documentdb-query-enablecrosspartition	선택 사항입니다. 단일 파티션 키에 대해 필터링하지 않는 쿼리의 경우 true로 설정해야 합니다. 단일 파티션 키 값에 대해 필터링하는 쿼리는 true로 설정된 경우에도 단일 파티션에 대해서만 실행됩니다.
x-ms-documentdb-populatequerymetrics	선택 사항입니다. 쿼리 메트릭을 True 반환하려면 를 로 설정해야 합니다.

요청 본문

요청 본문은 SQL 쿼리와 매개 변수를 포함하는 올바른 JSON 문서여야 합니다. 입력이 잘못된 형식이거나 올바르지 않은 SQL 구문이면 작업이 실패하며 400 잘못된 요청 오류가 발생합니다.

게이트웨이에서 쿼리를 처리할 수 없는 경우에도 400 잘못된 요청이 표시됩니다.

속성	설명
Query	필수. 쿼리의 SQL 쿼리 문자열입니다. 자세한 내용은 Azure Cosmos DB SQL 구문 참조를 참조하세요.
매개 변수	필수. 이름/값 쌍으로 지정되는 매개 변수의 JSON 배열입니다. 매개 변수 배열은 0에서 많은 매개 변수까지 포함할 수 있습니다. 각 매개 변수에는 다음 값이 있어야 합니다. name: 매개 변수의 이름입니다. 매개 변수 이름은 유효한 문자열 리터럴이어야 하며 '@'로 시작해야 합니다. value: 매개 변수의 값입니다. 유효한 모든 JSON 값(문자열, 숫자, 개체, 배열, 부울, Null)일 수 있습니다.

요청 예제

다음 예제에서는 에 대한 문자열 매개 변수를 사용하여 매개 변수가 있는 SQL 요청을 만듭니다 @author.

POST https://contosomarketing.documents.azure.com/dbs/XP0mAA==/colls/XP0mAJ3H-AA=/docs HTTP/1.1  
x-ms-documentdb-isquery: True  
x-ms-date: Mon, 18 Apr 2015 13:05:49 GMT  
authorization: type%3dmaster%26ver%3d1.0%26sig%3dkOU%2bBn2vkvIlHypfE8AA5fulpn8zKjLwdrxBqyg0YGQ%3d  
x-ms-version: 2015-04-08  
Accept: application/json  
Content-Type: application/query+json  
Host: contosomarketing.documents.azure.com  
Content-Length: 50  
  
{  
    "query": "SELECT * FROM root WHERE (root.Author.id = @author)",  
    "parameters":   
    [  
        { "name": "@author", "value": "Leo Tolstoy"}  
    ]  
}  

SQL 쿼리에 대한 자세한 내용은 Azure Cosmos DB에 대한 SQL 쿼리를 참조하세요.

응답 세부 정보

아래에는 이 작업에서 반환하는 일반 상태 코드가 나와 있습니다. 오류 상태 코드에 대한 자세한 내용은 Azure Cosmos DB에 대한 HTTP 상태 코드를 참조하세요.

‘코드’	설명
200 Ok	작업에 성공했습니다.
400 잘못된 요청	SQL 문의 구문이 잘못되었습니다.
401 권한 없음	Authorization 또는 x-ms-date 헤더가 설정되어 있지 않습니다. 401은 권한 부여 헤더가 잘못된 권한 부여 토큰으로 설정된 경우에도 반환됩니다.
403 사용할 수 없음	권한 부여 토큰이 만료되었습니다.
404 찾을 수 없음	컬렉션이 더 이상 리소스가 아닙니다. 리소스가 삭제된 경우 등을 예로 들 수 있습니다.

응답 헤더

이 작업은 다음과 같은 일반 헤더를 반환합니다. 그 외 추가적인 표준 및 일반 헤더가 반환될 수 있습니다.

표준 헤더	설명
Content-Type	콘텐츠-유형은 application/json입니다. Cosmos DB는 항상 표준 JSON 형식으로 응답 본문을 반환합니다.
날짜	응답 작업의 날짜-시간입니다. 이 날짜/시간 형식은 UTC로 표시되는 [RFC1123] 날짜/시간 형식을 따릅니다.

사용자 지정 헤더	설명
x-ms-item-count	작업에서 반환하는 항목의 수입니다.
x-ms-continuation	쿼리에 검색할 항목이 더 있을 때 반환되는 불투명 문자열입니다. x-ms-continuation은 쿼리 실행을 다시 시작하는 요청 헤더로 후속 요청에 포함할 수 있습니다.
x-ms-request-charge	작업에 사용되는 RU(요청 단위)의 수입니다. 요청 단위에 대한 자세한 내용은 Azure Cosmos DB의 요청 단위를 참조하세요.
x-ms-activity-id	작업에 대한 고유 식별자입니다. Cosmos DB 요청의 실행을 추적하는 데 사용할 수 있습니다.
x-ms-session-token	후속 요청에 사용할 세션 토큰입니다. 세션 일관성을 유지하는 데 사용됩니다.

응답 본문

쿼리 작업의 응답 본문은 쿼리 중인 리소스의 부모 리소스 _rid와 프로젝션 및 선택용 리소스 속성이 포함된 리소스 배열로 구성됩니다. 예를 들어 _rid가 XP0mAJ3H-AA=인 컬렉션의 docs 경로에 대해 쿼리를 수행한 경우의 응답은 다음과 같습니다.

{"_rid":" XP0mAJ3H-AA=","Documents":   [  ….  ….   ],"_count":10}  

속성	설명
_rid	쿼리 내에서 사용되는 컬렉션의 리소스 ID입니다.
_횟수	반환되는 항목의 수입니다.
리소스 배열	쿼리 결과를 포함하는 배열입니다.

쿼리 요청 본문 작성

쿼리 요청은 올바른 SQL 쿼리 문자열이 들어 있는 query 속성과 선택적 매개 변수 배열이 들어 있는 parameters 속성을 포함하는 유효한 JSON 문서여야 합니다. 각 매개 변수는 쿼리 내에서 지정되는 매개 변수의 name 및 value 속성을 포함해야 합니다. 매개 변수 이름은 "@" 문자로 시작해야 합니다. 값은 문자열, 정수, 부울, Null 등 유효한 모든 JSON 값일 수 있습니다.

쿼리 텍스트에 지정된 매개 변수의 하위 집합만 지정하는 것이 유효합니다. 이처럼 지정되지 않은 매개 변수를 참조하는 식은 undefined로 계산됩니다. query 텍스트 내에서 사용되지 않는 추가 매개 변수를 지정할 수도 있습니다.

아래에 유효한 쿼리 요청의 몇 가지 예제가 나와 있습니다. 예를 들어 다음 쿼리에는 단일 매개 변수 @id가 있습니다.

{  
    "query": "select * from docs d where d.id = @id",   
    "parameters": [   
        {"@id": "newdoc"}   
     ]  
}  
  

다음 예제에는 각각 문자열 값과 정수 값을 포함하는 매개 변수 두 개가 있습니다.

{  
    "query": "select * from docs d where d.id = @id and d.prop = @prop",   
    "parameters": [   
        {"@id": "newdoc"},  
        {"@prop": 5}   
     ]  
}  

다음 예제에서는 SELECT 절 내에서 매개 변수를 사용하며 매개 변수 이름을 통해 액세스하는 속성도 매개 변수로 사용합니다.

{  
    "query": "select @id, d[@propName] from docs d",   
    "parameters": [   
        {"@id": "newdoc"},  
        {"@propName": "prop"}  
     ]  
}  

게이트웨이에서 처리할 수 없는 쿼리

연속 작업에서 상태가 필요한 쿼리는 게이트웨이에서 처리할 수 없습니다. 다음 내용이 포함됩니다.

• 맨 위로 이동
• ORDER BY
• OFFSET LIMIT
• 집계
• DISTINCT
• GROUP BY

게이트웨이에서 처리할 수 있는 쿼리는 다음과 같습니다.

• 간단한 프로젝션
• 필터

게이트웨이에서 처리할 수 없는 쿼리에 대한 응답이 반환되면 상태 코드 400(BadRequest) 및 다음 메시지가 포함됩니다.

{"code":"BadRequest","message":"The provided cross partition query can not be directly served by the gateway. 
This is a first chance (internal) exception that all newer clients will know how to handle gracefully. 
This exception is traced, but unless you see it bubble up as an exception (which only happens on older SDK clients), 
then you can safely ignore this message.\r\nActivityId: db660ee4-350a-40e9-bc2c-99f92f2b445d, Microsoft.Azure.Documents.Common/2.2.0.0",
"additionalErrorInfo":"{\"partitionedQueryExecutionInfoVersion\":2,\"queryInfo\":{\"distinctType\":\"None\",\"top\":null,\"offset\":null,\"limit\":null,
\"orderBy\":[\"Ascending\"],\"orderByExpressions\":[\"c._ts\"],\"aggregates\":[],
\"rewrittenQuery\":\"SELECT c._rid, [{\\\"item\\\": c._ts}] AS orderByItems, 
c AS payload\\nFROM c\\nWHERE ({documentdb-formattableorderbyquery-filter})\\nORDER BY c._ts\"},
\"queryRanges\":[{\"min\":\"\",\"max\":\"FF\",\"isMinInclusive\":true,\"isMaxInclusive\":false}]}"}

쿼리 결과 페이지 매김

쿼리 요청에서는 x-ms-max-item-count 및 x-ms-continuation request 헤더를 통해 페이지를 매길 수 있습니다. x-ms-max-item-count 헤더는 쿼리 실행에서 반환될 수 있는 최대 값 수를 지정합니다. 이 값은 1~1000 사이일 수 있으며 기본값 100으로 구성됩니다.

쿼리는 실행 결과에서 값을 반환하지 않을 수도 있고 지정된 최대 x-ms-max-item-count개 값까지 반환할 수도 있습니다. 쿼리 결과에는 쿼리에서 반환하는 실제 문서 수를 지정하는 x-ms-item-count 헤더가 포함됩니다. 쿼리에서 검색할 수 있는 추가 결과가 있으면 응답에는 x-ms-continuation 헤더에 대해 비어 있지 않은 값이 포함됩니다.

클라이언트는 x-ms-continuation 헤더를 다른 요청으로 에코하여 후속 결과 페이지를 가져올 수 있습니다. 모든 결과를 읽으려면 클라이언트는 빈 x-ms-continuation이 반환될 때까지 이 프로세스를 반복해야 합니다.

Cosmos DB 쿼리 실행은 서버 쪽에서 상태 비저장이며 x-ms-continuation 헤더를 사용하여 언제든지 다시 시작할 수 있습니다. x-ms-continuation 값은 마지막으로 처리된 문서 리소스 ID(_rid)를 사용하여 실행 진행률을 추적합니다. 따라서 페이지 가져오기 사이에 문서를 삭제하고 다시 삽입하면 쿼리 일괄 처리에서 문서가 제외될 수 있습니다. 그러나 x-ms-continuation 헤더의 동작과 형식은 이후 서비스 업데이트에서 변경될 수 있습니다.

참고 항목

• Azure Cosmos DB
• Azure Cosmos DB SQL API
• Azure Cosmos DB SQL API SDK
• .NET 샘플의 REST