컬렉션 만들기

아티클
08/05/2023

작업은 Create Collection 데이터베이스에 새 컬렉션을 만듭니다.

참고

이러한 API 참조 문서에서는 Azure Cosmos DB 데이터 평면 API를 사용하여 리소스를 만드는 방법을 보여 줍니다. 데이터 평면 API를 사용하면 Cosmos DB SDK와 마찬가지로 인덱싱 정책, 파티션 키와 같은 기본 옵션을 구성할 수 있습니다. 모든 Azure Cosmos DB 리소스에 대한 완전한 기능 지원이 필요한 경우 Cosmos DB 리소스 공급자를 사용하는 것이 좋습니다.

요청

메서드	요청 URI	설명
POST	https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls	{databaseaccount}는 구독에서 만든 Azure Cosmos DB 계정의 이름입니다. {db-id}는 데이터베이스의 ID 또는 _rid 값일 수 있습니다.

헤더

모든 Azure Cosmos DB 요청에 사용되는 헤더는 일반적인 Azure Cosmos DB REST 요청 헤더를 참조하세요.

master 키 토큰에 대한 해시된 서명을 생성할 때 ResourceType은 "colls"여야 합니다. ResourceId는 이어야 dbs/{db-id}합니다. 여기서 {db-id}는 데이터베이스의 ID 또는 _rid 값일 수 있습니다.

속성	필수	형식	설명
x-ms-offer-throughput	선택 사항	숫자	사용자가 초당 100개 요청 단위 단위로 표현된 컬렉션에 대해 RU/s(수동 처리량)를 지정했습니다. 최소값은 최대 400개에서 1,000,000개 이상입니다(한도 증가를 요청하여 이상). 또는 `x-ms-cosmos-offer-autopilot-settings` 중 `x-ms-offer-throughput` 하나만 지정해야 합니다. 이러한 헤더는 함께 지정할 수 없습니다.
x-ms-cosmos-offer-autopilot-settings	선택 사항	JSON	사용자가 자동 크기 조정 최대 RU/s를 지정했습니다. 값은 속성 `maxThroughput`이 인 JSON입니다. 예: `{"maxThroughput": 4000}` 또는 `x-ms-cosmos-offer-autopilot-settings` 중 `x-ms-offer-throughput` 하나만 지정해야 합니다. 이러한 헤더는 함께 지정할 수 없습니다. 자동 크기 조정을 사용하는 경우 partitionKey 정의가 필요합니다.
x-ms-offer-type	선택 사항	문자열	사용 중지된 미리 정의된 성능 수준 S1, S2 및 S3에 대한 레거시 헤더 입니다. 위에서 설명한 대로 수동 또는 자동 크기 조정 처리량을 사용하는 것이 좋습니다.

본문

속성	필수	형식	Description
id	필수	문자열	사용자가 생성한 컬렉션의 고유 이름입니다. 두 컬렉션에 동일한 ID가 있을 수 없습니다. 255자를 초과하면 안 되는 문자열입니다.
indexingPolicy	선택 사항	Object	이 값을 사용하여 인덱싱 정책을 구성합니다. 기본적으로 인덱싱은 컬렉션에 있는 모든 문서 경로에 대해 자동으로 수행됩니다.
partitionKey	필수	Object	이 값은 데이터를 여러 파티션으로 분할하는 데 사용할 파티션 키를 구성하는 데 사용됩니다. 큰 파티션 키를 사용하려면 partitionKey 속성 내에서 버전을 2로 지정합니다. REST API 버전이 2018-12-31 이상인 경우 컬렉션에 partitionKey 정의가 포함되어야 합니다. 2018-12-31 이전 버전에서는 partitionKey 정의를 생략하고 처리량이 400~10,000RU/s 사이인지 확인하여 수동 처리량이 있는 레거시 비분할 컬렉션을 만들 수 있습니다. 최상의 성능과 확장성을 위해 항상 파티션 키를 설정하는 것이 좋습니다. 적절한 파티션 키를 선택하는 방법에 대해 알아봅니다.

본문 페이로드 예제

{  
  "id": "testcoll",  
  "indexingPolicy": {  
    "automatic": true,  
    "indexingMode": "Consistent",  
    "includedPaths": [  
      {  
        "path": "/*",  
        "indexes": [  
          {  
            "dataType": "String",  
            "precision": -1,  
            "kind": "Range"  
          }  
        ]  
      }  
    ]  
  },  
  "partitionKey": {  
    "paths": [  
      "/AccountNumber"  
    ],  
    "kind": "Hash",
     "Version": 2

  }  
}

응답

Create Collection은 생성된 컬렉션을 응답 본문으로 반환합니다.

헤더

모든 Azure Cosmos DB 응답 에서 반환되는 헤더는 일반적인 Azure Cosmos DB REST 응답 헤더를 참조하세요.

상태 코드

다음 표에는 이 작업에서 반환하는 일반적인 상태 코드가 나열되어 있습니다. 상태 코드의 전체 목록은 HTTP 상태 코드를 참조하세요.

HTTP 상태 코드	설명
201 생성됨	작업이 완료되었습니다.
400 잘못된 요청	JSON 본문이 잘못되었습니다. 누락된 중괄호나 따옴표를 확인하세요.
409 충돌	새 컬렉션에 제공된 ID는 기존 컬렉션에서 가져온 것입니다.
하위 상태 코드가 1013인 404	컬렉션 만들기 작업은 아직 진행 중입니다.

컬렉션을 만들 때 시간 제한 예외가 발생하는 경우 읽기 작업을 실행하여 컬렉션이 성공적으로 만들어졌는지 확인합니다. 읽기 작업은 컬렉션 만들기 작업이 성공할 때까지 예외를 발생시킵니다. 읽기 작업에서 상태 코드가 404이고 하위 상태 코드가 1013인 예외가 throw되는 경우 컬렉션 만들기 작업이 여전히 진행 중임을 의미합니다. 200 또는 201 상태 코드를 가져올 때까지 읽기 작업을 다시 시도하면 이러한 코드를 통해 컬렉션이 성공적으로 만들어졌는지 알 수 있습니다.

본문

속성	Description
id	새 컬렉션을 식별하는 고유한 이름입니다.
_rid	시스템 생성 속성입니다. 리소스 ID(_rid)는 고유 식별자로, 역시 리소스 모델에서 리소스 스택에 따라 계층적입니다. 사용 권한 리소스의 배치와 탐색용으로 내부적으로 사용됩니다.
_ts	시스템 생성 속성입니다. 리소스가 마지막으로 업데이트된 시간의 타임스탬프를 지정합니다. 값은 타임스탬프입니다.
_self	시스템 생성 속성입니다. 고유한 주소를 지정할 수 있는 리소스의 URI입니다.
_etag	낙관적 동시성 제어에 필요한 리소스 etag 를 나타내는 시스템 생성 속성입니다.
_문서	문서 리소스의 주소 지정 가능 경로를 지정하는 시스템 생성 속성입니다.
_sprocs	저장 프로시저(sprocs) 리소스의 주소 지정 가능 경로를 지정하는 시스템 생성 속성입니다.
_트리거	트리거 리소스의 주소 지정 가능 경로를 지정하는 시스템 생성 속성입니다.
_Udf	udfs(사용자 정의 함수) 리소스의 주소 지정 가능 경로를 지정하는 시스템 생성 속성입니다.
_충돌	충돌 리소스의 주소 지정 가능 경로를 지정하는 시스템 생성 속성입니다. 컬렉션 내의 리소스에 대한 작업 중에 충돌이 발생하면 사용자는 충돌 URI 경로에 대해 GET을 수행하여 충돌하는 리소스를 검사할 수 있습니다.
indexingPolicy	컬렉션에 대한 인덱싱 정책 설정입니다.
partitionKey	컬렉션에 대한 분할 구성 설정입니다.

포함된 경로 아래의 속성

속성	설명
path	인덱싱 동작이 적용되는 경로입니다. 인덱스 경로는 루트(/)로 시작하고 일반적으로 접두사에 여러 개의 가능한 값이 있음을 나타내는 물음표(?) 와일드카드 연산자로 끝납니다. 예를 들어 SELECT * FROM Families F WHERE F.familyName = "Andersen"을 처리하려면 컬렉션의 인덱스 정책에 /familyName/?의 인덱스 경로를 컬렉션의 인덱스 정책에서 또한 인덱스 경로에 * 와일드카드 연산자를 사용하여 접두사 아래에 재귀적으로 경로에 대한 동작을 지정할 수 있습니다. 예를 들어 /payload/*를 사용하여 페이로드 속성의 모든 항목을 인덱싱에서 제외할 수 있습니다.
dataType	인덱싱 동작이 적용되는 데이터 형식입니다. String, Number, Point, Polygon 또는 LineString일 수 있습니다. 부울 및 null이 자동으로 인덱싱됩니다.
kind	인덱스의 유형입니다. 해시 인덱스는 같음 비교에 유용하지만 범위 인덱스는 같음, 범위 비교 및 정렬에 유용합니다. 공간 인덱스는 공간 쿼리에 유용합니다.
전체 자릿수	인덱스의 전체 자릿수입니다. 최대 정밀도의 경우 -1로 설정하거나 Number의 경우 1-8, String의 경우 1-100으로 설정할 수 있습니다. Point, Polygon 및 LineString 데이터 형식에는 적용되지 않습니다.

제외된 경로 아래의 속성

속성	설명
path	인덱싱에서 제외되는 경로입니다. 인덱스 경로는 루트(/)로 시작하고 일반적으로 * 와일드카드 연산자로 끝납니다. 예를 들어 /payload/*를 사용하여 페이로드 속성의 모든 항목을 인덱싱에서 제외할 수 있습니다.

파티션 키 아래의 속성

속성	설명
경로	컬렉션 내에서 분할할 수 있는 데이터를 사용하는 경로 배열입니다. 경로에는 와일드카드 또는 후행 슬래시가 포함되어서는 안 됩니다. 예를 들어 JSON 속성 "AccountNumber"는 "/AccountNumber"로 지정됩니다. 배열에는 단일 값만 포함되어야 합니다.
kind	분할에 사용되는 알고리즘입니다. 해시만 지원됩니다.
version	선택적 필드(지정하지 않은 경우 기본값은 1)입니다. 큰 파티션 키를 사용하려면 버전을 2로 설정합니다. 큰 파티션 키에 대해 알아보려면 큰 파티션 키를 사용하여 컬렉션을 만드는 방법 문서를 참조하세요.

응답 본문 예제

{  
  "id": "testcoll",  
  "indexingPolicy": {  
    "indexingMode": "consistent",  
    "automatic": true,  
    "includedPaths": [  
      {  
        "path": "/*",  
        "indexes": [  
          {  
            "kind": "Range",  
            "dataType": "String",  
            "precision": -1  
          },  
          {  
            "kind": "Range",  
            "dataType": "Number",  
            "precision": -1  
          }  
        ]  
      }  
    ],  
    "excludedPaths": []  
  },  
  "partitionKey": {  
    "paths": [  
      "/AccountNumber"  
    ],  
    "kind": "Hash",
    "Version": 2
  },  
  "_rid": "PD5DALigDgw=",  
  "_ts": 1459200611,  
  "_self": "dbs/PD5DAA==/colls/PD5DALigDgw=/",  
  "_etag": "\"00005900-0000-0000-0000-56f9a2630000\"",  
  "_docs": "docs/",  
  "_sprocs": "sprocs/",  
  "_triggers": "triggers/",  
  "_udfs": "udfs/",  
  "_conflicts": "conflicts/"  
}

예 1

다음 예제에서는 수동 처리량이 400RU/s인 컬렉션을 만듭니다. x-ms-offer-throughput 헤더는 처리량(RU/s) 값을 설정하는 데 사용됩니다. 최소값이 400인 숫자를 100 단위씩 증분합니다.

POST https://querydemo.documents.azure.com/dbs/testdb/colls HTTP/1.1  
x-ms-offer-throughput: 400  
x-ms.date: 04/20/2021
authorization: type%3dmaster%26ver%3d1.0%26sig%3dpDOKhfllik0BJijp5apzqHL%2bjtoFhsvdhAGE5F8%2bOiE%3d  
Cache-Control: no-cache  
User-Agent: contoso/1.0  
x-ms-version: 2015-12-16  
Accept: application/json  
Host: querydemo.documents.azure.com  
Content-Length: 235  
Expect: 100-continue  
  
{  
  "id": "testcoll",  
  "indexingPolicy": {  
    "automatic": true,  
    "indexingMode": "Consistent",  
    "includedPaths": [  
      {  
        "path": "/*",  
        "indexes": [  
          {  
            "dataType": "String",  
            "precision": -1,  
            "kind": "Range"  
          }  
        ]  
      }  
    ]  
  },  
  "partitionKey": {  
    "paths": [  
      "/AccountNumber"  
    ],  
    "kind": "Hash",
    "Version": 2
  }  
}

HTTP/1.1 201 Created  
Cache-Control: no-store, no-cache  
Pragma: no-cache  
Transfer-Encoding: chunked  
Content-Type: application/json  
Server: Microsoft-HTTPAPI/2.0  
Strict-Transport-Security: max-age=31536000  
x-ms-last-state-change-utc: Mon, 28 Mar 2016 20:00:12.142 GMT  
etag: "00005900-0000-0000-0000-56f9a2630000"  
collection-partition-index: 0  
collection-service-index: 24  
x-ms-schemaversion: 1.1  
x-ms-alt-content-path: dbs/testdb  
x-ms-quorum-acked-lsn: 9  
x-ms-current-write-quorum: 3  
x-ms-current-replica-set-size: 4  
x-ms-request-charge: 4.95  
x-ms-serviceversion: version=1.6.52.5  
x-ms-activity-id: 05d0a3b5-4504-446a-96f4-bef3a3408595  
x-ms-session-token: 0:10  
Set-Cookie: x-ms-session-token#0=10; Domain=querydemo.documents.azure.com; Path=/dbs/PD5DAA==/colls/PD5DALigDgw=  
Set-Cookie: x-ms-session-token=10; Domain=querydemo.documents.azure.com; Path=/dbs/PD5DAA==/colls/PD5DALigDgw=  
x-ms-gatewayversion: version=1.6.52.5  
Date: Mon, 28 Mar 2016 21:30:12 GMT  
  
{  
  "id": "testcoll",  
  "indexingPolicy": {  
    "indexingMode": "consistent",  
    "automatic": true,  
    "includedPaths": [  
      {  
        "path": "/*",  
        "indexes": [  
          {  
            "kind": "Range",  
            "dataType": "String",  
            "precision": -1  
          },  
          {  
            "kind": "Range",  
            "dataType": "Number",  
            "precision": -1  
          }  
        ]  
      }  
    ],  
    "excludedPaths": []  
  },  
  "partitionKey": {  
    "paths": [  
      "/AccountNumber"  
    ],  
    "kind": "Hash"  
  },  
  "_rid": "PD5DALigDgw=",  
  "_ts": 1459200611,  
  "_self": "dbs/PD5DAA==/colls/PD5DALigDgw=/",  
  "_etag": "\"00005900-0000-0000-0000-56f9a2630000\"",  
  "_docs": "docs/",  
  "_sprocs": "sprocs/",  
  "_triggers": "triggers/",  
  "_udfs": "udfs/",  
  "_conflicts": "conflicts/"  
}

예제 2

다음 예제에서는 자동 크기 조정 최대 처리량이 4000RU/s인 컬렉션을 만듭니다(400~4000RU/s 사이 크기 조정). x-ms-cosmos-offer-autopilot-settings 헤더는 자동 크기 조정 최대 RU/s 값인 값을 설정하는 maxThroughput 데 사용됩니다. 1000 단위씩 증가하는 최소 4000의 숫자를 허용합니다. 자동 크기 조정을 사용하는 경우 다음 예제와 같이 파티션 키 정의가 필요합니다.

참고

기존 데이터베이스 또는 컬렉션에서 자동 크기 조정을 사용하도록 설정하거나 자동 크기 조정에서 수동 처리량으로 전환하려면 제품 바꾸기 문서를 참조하세요.

POST https://querydemo.documents.azure.com/dbs/testdb/colls HTTP/1.1
x-ms-cosmos-offer-autopilot-settings: {"maxThroughput": 4000}
x-ms-date: Wed, 22 Jul 2020 22:17:39 GMT
authorization: type%3dmaster%26ver%3d1.0%26sig%3dpDOKhfllik0BJijp5apzqHL%2bjtoFhsvdhAGE5F8%2bOiE%3d
Cache-Control: no-cache  
User-Agent: contoso/1.0
x-ms-version: 2018-12-31
Accept: application/json  
Host: querydemo.documents.azure.com  
Content-Length: 235  
Expect: 100-continue  
  
{  
  "id": "testcoll",  
  "indexingPolicy": {  
    "automatic": true,  
    "indexingMode": "Consistent",  
    "includedPaths": [  
      {  
        "path": "/*",  
        "indexes": [  
          {  
            "dataType": "String",  
            "precision": -1,  
            "kind": "Range"  
          }  
        ]  
      }  
    ]  
  },  
  "partitionKey": {  
    "paths": [  
      "/AccountNumber"  
    ],  
    "kind": "Hash",
    "Version": 2
  }  
}

다음을 통해 공유

컬렉션 만들기

요청

헤더

본문

본문 페이로드 예제

응답

헤더

상태 코드

본문

응답 본문 예제

예 1

예제 2

참고 항목

추가 리소스