제안 바꾸기

  • 아티클

전체 제품 리소스를 바꾸려면 특정 제품 리소스에서 PUT 작업을 수행합니다. 컨테이너 또는 데이터베이스에서 설정할 수 있는 최대 및 최소 프로비전 처리량에 대한 자세한 내용은 컨테이너 및 데이터베이스에 대한 처리량 프로비전 문서를 참조하세요.

요청

메서드 요청 URI 설명
PUT https://{databaseaccount}.documents.azure.com/offers/{_rid-offer} {databaseaccount}는 구독에서 만든 Azure Cosmos DB 계정의 이름입니다. {_rid-offer} 값은 제품의 시스템 생성 리소스 ID입니다.

팁

데이터베이스 또는 컬렉션과 연결된 제품의 _rid 찾으려면 먼저 데이터베이스를 얻 거나 컬렉션을 가져와 서 리소스의 _rid 속성을 확인합니다. 그런 다음 , 제품을 쿼리 하여 데이터베이스 또는 컬렉션의 _rid 해당하는 _rid 제품을 찾습니다. 일반적으로 데이터베이스 _rid 길이가 8이고 컬렉션 _rid 길이가 12이고 제품 _rid 길이가 4입니다.

헤더

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

본문

속성 필수 설명
offerVersion 필수 레거시 S1, S2 및 S3 수준의 경우 V1이고사용자 정의 처리량 수준(권장)의 경우 V2일 수 있습니다.
offerType 선택 사항 이 속성은 V1 제품 버전에서만 적용할 수 있습니다. V1 제품 유형에 대해 S1, S2 또는 S3으로 설정합니다. 사용자 정의 성능 수준 또는 프로비전된 처리량 기반 모델에는 유효하지 않습니다.
content 필수 제품에 대한 정보를 포함합니다. V2 제품의 경우 이 값에는 컬렉션의 처리량이 포함됩니다.
resource 필수 새 컬렉션을 만들 때 이 속성은 컬렉션의 자체 링크(예: dbs/pLJdAA==/colls/pLJdAOlEdgA=/)로 설정됩니다.
offerResourceId 필수 컬렉션을 만드는 동안 이 속성은 리소스 ID, 즉 컬렉션의 _rid 자동으로 연결됩니다. 위의 예제에서 컬렉션에 대한 _rid pLJdAOlEdgA=입니다.
id 필수 시스템 생성 속성입니다. 제품 리소스의 ID 는 생성될 때 자동으로 생성됩니다. 제품의 _rid 값과 같습니다.
_rid 필수 시스템 생성 속성입니다. 리소스 ID(_rid)는 리소스 모델의 리소스 스택에 따라 계층적인 고유 식별자입니다. 제안의 배치와 탐색용으로 내부에서 사용됩니다. 
{   
  "offerVersion": "V2",   
  "offerType": "Invalid",   
  "content": {   
    "offerThroughput": 4000   
  },   
  "resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",   
  "offerResourceId": "rgkVAMHcJww=",   
  "id": "uT2L",   
  "_rid": "uT2L",   
}

응답

업데이트된 제품 리소스를 반환합니다.

헤더

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

상태 코드

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

HTTP 상태 코드 설명
200 정상 바꾸기 작업이 성공했습니다.
400 잘못된 요청 JSON 본문이 잘못되었습니다. 누락된 중괄호나 따옴표를 확인하세요.
401 권한 없음 권한 부여 또는 x-ms-date 헤더가 설정되지 않았습니다. 401은 권한 부여 헤더가 잘못된 권한 부여 토큰으로 설정된 경우에도 반환됩니다.
404 찾을 수 없음 제품은 더 이상 리소스가 아닙니다. 즉, 리소스가 삭제되었습니다.
429 요청이 너무 많음 제품 스케일 다운 작업이 유휴 시간 제한 기간(4시간) 내에 시도되기 때문에 바꾸기 제품이 제한됩니다. 이 작업을 다시 시도하기 전에 기다려야 하는 시간을 보려면 "x-ms-retry-after-ms 응답" 헤더를 참조하세요.

본문

속성 설명
offerVersion 이 값은 미리 정의된 처리량 수준의 경우 V1이고 사용자 정의 처리량 수준의 경우 V2일 수 있습니다.
offerType V1 제품에 대해 미리 정의된 성능 수준 S1, S2 또는 S3입니다. 사용자 정의 성능 수준에 대해 해당 집합이 Invalid로 설정되었습니다.
content 제품에 대한 정보가 포함되어 있습니다. V2 제품의 경우 컬렉션의 처리량을 포함합니다.
resource 새 컬렉션을 만들 때 이 속성은 컬렉션의 자체 링크(예: dbs/pLJdAA==/colls/pLJdAOlEdgA=/)로 설정됩니다.
offerResourceId 컬렉션을 만드는 동안 이 속성은 리소스 ID, 즉 컬렉션의 _rid 자동으로 연결됩니다. 위의 예제에서 컬렉션에 대한 _rid pLJdAOlEdgA=입니다.
id 시스템 생성 속성입니다. 제품 리소스의 ID 는 생성될 때 자동으로 생성됩니다. 제품의 _rid 값과 같습니다.
_rid 시스템 생성 속성입니다. 리소스 ID(_rid)는 리소스 모델의 리소스 스택에 따라 계층적인 고유 식별자입니다. 제안의 배치와 탐색용으로 내부에서 사용됩니다.
_ts 시스템 생성 속성입니다. 리소스가 마지막으로 업데이트된 시간의 타임스탬프를 지정합니다. 값은 타임스탬프입니다.
_self 시스템 생성 속성입니다. 고유한 주소를 지정할 수 있는 리소스의 URI입니다.
_etag 낙관적 동시성 제어에 필요한 리소스 etag를 지정하는 시스템 생성 속성입니다. 
{  
  "offerVersion": "V2",  
  "_rid": "uT2L",
   "content": {  
    "offerThroughput": 4000
  }, 
  "resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",  
  "offerResourceId": "rgkVAMHcJww=",  
  "id": "uT2L",  
  "_self": "offers/uT2L/"
}

예 1

이 예제에서는 컬렉션의 수동 처리량(RU/s)을 1000RU/s로 변경하는 방법을 보여 줍니다.

PUT https://querydemo.documents.azure.com/offers/uT2L HTTP/1.1 

x-ms-date: Tue, 29 Mar 2016 17:50:18 GMT  
authorization: type%3dmaster%26ver%3d1.0%26sig%3dRdNwi9H3molMOsEoHXCUHa56N8U5eFDlfuewcSoiHgc%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: 234  
Expect: 100-continue  
  
{  
  "id": "uT2L",  
  "_rid": "uT2L",  
  "_self": "offers/uT2L/",  
  "offerVersion": "V2",  
  "resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",  
  "content": {  
    "offerThroughput": 1000 
   }, 
  "offerResourceId": "rgkVAMHcJww="  
}

다음은 샘플 응답입니다.

HTTP/1.1 200 Ok  
Cache-Control: no-store, no-cache  
Pragma: no-cache  
Transfer-Encoding: chunked  
Content-Type: application/json  
Content-Location: https://querydemo.documents.azure.com/offers/uT2L  
Server: Microsoft-HTTPAPI/2.0  
Strict-Transport-Security: max-age=31536000  
x-ms-last-state-change-utc: Fri, 25 Mar 2016 22:54:09.213 GMT  
etag: "0000a900-0000-0000-0000-56fac05a0000"  
x-ms-schemaversion: 1.1  
x-ms-quorum-acked-lsn: 8110  
x-ms-current-write-quorum: 3  
x-ms-current-replica-set-size: 4  
x-ms-request-charge: 9.9  
x-ms-serviceversion: version=1.6.52.5  
x-ms-activity-id: fa543c39-a64e-44bd-ba9a-c4f313a9d7d4  
x-ms-session-token: M:8111  
x-ms-gatewayversion: version=1.6.52.5  
Date: Tue, 29 Mar 2016 17:50:20 GMT  
  
{  
  "offerVersion": "V2",
  "_rid": "uT2L",  
  "content": {  
    "offerThroughput": 1000
  },
  "resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",  
  "offerResourceId": "rgkVAMHcJww=",  
  "id": "uT2L",  
  "_self": "offers/uT2L/",  
  "_etag": "\"0000a900-0000-0000-0000-56fac05a0000\"",  
  "_ts": 1459273818  
}

예제 2

이 예제에서는 자동 크기 조정 처리량이 있는 제품의 최대 처리량(RU/s)을 8000RU/s(800~8000RU/s 사이의 크기 조정)로 변경하는 방법을 보여 줍니다.

PUT https://querydemo.documents.azure.com/offers/uT2L HTTP/1.1

x-ms-version: 2018-12-31
x-ms-date: Thu, 23 Jul 2020 00:04:41 GMT
authorization: type%3dmaster%26ver%3d1.0%26sig%3dRdNwi9H3molMOsEoHXCUHa56N8U5eFDlfuewcSoiHgc%3d  
Accept: application/json
Content-Type: application/json
User-Agent: contoso/1.0
Host: querydemo.documents.azure.com:443
Connection: keep-alive
Content-Length: 278

{   
  "offerVersion": "V2",   
  "offerType": "Invalid",   
  "content": {   
    "offerAutopilotSettings": {"maxThroughput": 8000}
  },
  "resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",  
  "offerResourceId": "rgkVAMHcJww="  
  "id": "uT2L",  
  "_rid": "uT2L"
}

예제 3

이 예제에서는 수동 처리량이 있는 제품을 자동 크기 조정 처리량으로 마이그레이션하는 방법을 보여줍니다. 값 true 이 있는 헤더 x-ms-cosmos-migrate-offer-to-autopilot 가 필요합니다.

마이그레이션할 때 Azure Cosmos DB는 현재 리소스 설정에 따라 새 자동 크기 조정 최대 RU/s를 자동으로 결정합니다. 응답 개체의 속성은 maxThroughput 시스템에서 설정한 기본 자동 크기 조정 최대 RU/s를 나타냅니다.

본문 content 에서 정의된 offerThroughput 속성이 필요하지만 서비스에서 값을 무시합니다. 다음 예제에서는 -1을 사용합니다.

변경이 완료되면 예제 2 에 따라 자동 크기 조정 최대 RU/s를 사용자 지정 값으로 변경할 수 있습니다.

자동 크기 조정으로 마이그레이션하는 방법에 대해 자세히 알아봅니다.

PUT https://querydemo.documents.azure.com/offers/uT2L HTTP/1.1

x-ms-version: 2018-12-31
x-ms-date: Wed, 22 Jul 2020 23:33:41 GMT
authorization: type%3dmaster%26ver%3d1.0%26sig%3dRdNwi9H3molMOsEoHXCUHa56N8U5eFDlfuewcSoiHgc%3d  
Accept: application/json
x-ms-cosmos-migrate-offer-to-autopilot: true
Content-Type: application/json
User-Agent: contoso/1.0  
Host: querydemo.documents.azure.com  
Connection: keep-alive
Content-Length: 254

{   
  "offerVersion": "V2",   
  "offerType": "Invalid",   
  "content": {   
    "offerThroughput": -1  
  },
  "resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",  
  "offerResourceId": "rgkVAMHcJww=",  
  "id": "uT2L",   
  "_rid": "uT2L"
}

다음은 샘플 응답 본문입니다.

속성 maxThroughput 은 시스템에서 설정한 자동 크기 조정 최대 RU/s를 나타냅니다. 속성 offerThroughput 은 시스템이 현재 크기가 조정된 RU/s를 나타냅니다.

{
    "resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",  
    "offerType": "Invalid",
    "offerResourceId": "rgkVAMHcJww=",
    "offerVersion": "V2",
    "content": {
        "offerThroughput": 400,
        "offerIsRUPerMinuteThroughputEnabled": false,
        "offerMinimumThroughputParameters": {
            "maxThroughputEverProvisioned": 4000,
            "maxConsumedStorageEverInKB": 0
        },
        "offerLastReplaceTimestamp": 1595460122,
        "offerAutopilotSettings": {
            "maxThroughput": 4000
        }
    },
    "id": "uT2L",
    "_rid": "uT2L",
    "_self": "offers/uT2L/",
    "_etag": "\"2d002059-0000-0800-0000-5f18cbf80000\"",
    "_ts": 1595460600
}

예제 4

이 예제에서는 자동 크기 조정 처리량을 사용하여 제품을 수동 처리량으로 마이그레이션하는 방법을 보여줍니다. 값 true 이 있는 헤더 x-ms-cosmos-migrate-offer-to-manual-throughput 가 필요합니다.

마이그레이션할 때 Azure Cosmos DB는 현재 리소스 설정에 따라 새 RU/s(수동 처리량)를 자동으로 결정합니다. 변경이 완료되면 예제 1 에 따라 수동 RU/s를 사용자 지정 값으로 변경할 수 있습니다.

본문 content 에서 및 가 정의된 offerAutopilotSettingsmaxThroughput 속성은 필수이지만 서비스에서 값을 무시합니다. 아래에서 -1을 전달합니다.

수동 처리량으로 마이그레이션하는 방법에 대해 자세히 알아봅니다.

PUT https://querydemo.documents.azure.com/offers/uT2L HTTP/1.1  
x-ms-version: 2018-12-31
x-ms-date: Wed, 22 Jul 2020 23:43:03 GMT
authorization: type%3dmaster%26ver%3d1.0%26sig%3dRdNwi9H3molMOsEoHXCUHa56N8U5eFDlfuewcSoiHgc%3d  
Accept: application/json
x-ms-cosmos-migrate-offer-to-manual-throughput: true
Content-Type: application/json
User-Agent: contoso/1.0  
Host: querydemo.documents.azure.com
Connection: keep-alive
Content-Length: 280

{
  "offerVersion": "V2",
  "offerType": "Invalid",
  "content": {
    "offerAutopilotSettings": {"maxThroughput": -1}
  },
  "resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",  
  "offerResourceId": "rgkVAMHcJww=",  
  "id": "uT2L",
  "_rid": "uT2L"
}

다음은 샘플 응답 본문입니다. 속성 offerThroughput 은 리소스에 설정된 수동 처리량(RU/s)을 나타냅니다.

{
    "resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",  
    "offerType": "Invalid",
    "offerResourceId": "rgkVAMHcJww=",
    "offerVersion": "V2",
    "content": {
        "offerThroughput": 4000,
        "offerIsRUPerMinuteThroughputEnabled": false,
        "offerMinimumThroughputParameters": {
            "maxThroughputEverProvisioned": 4000,
            "maxConsumedStorageEverInKB": 0
        },
        "offerLastReplaceTimestamp": 1595461384
    },
    "id": "uT2L",
    "_rid": "uT2L",
    "_self": "offers/uT2L/",
    "_etag": "\"2d002359-0000-0800-0000-5f18cf080000\"",
    "_ts": 1595461384
}

설명

데이터베이스 또는 컨테이너에서 수동 또는 자동 크기 조정 처리량을 변경하는 경우 시스템은 리소스에 설정할 수 있는 RU/s에 제약 조건을 적용합니다. 수동 처리량으로 설정할 수 있는 최소 및 최대 프로비전된 처리량(RU/s)에 대한 자세한 내용은 컨테이너 및 데이터베이스에 처리량 프로비전 문서를 참조하세요. 설정할 수 있는 최소 자동 크기 조정 최대 RU/s에 대해 알아보려면 자동 크기 조정 FAQ를 참조하세요.

데이터베이스 또는 컨테이너에서 설정할 수 있는 최소 처리량을 검색하려면 제품 리소스에서 GET을 수행합니다. 응답 헤더 x-ms-cosmos-min-throughput 는 시스템에서 결정된 최소 처리량을 표시합니다. 수동 처리량이 있는 리소스의 RU/s에 대해 설정할 수 있는 최소값 또는 자동 크기 조정 처리량이 있는 리소스의 자동 크기 조정 최대 RU/s에 대해 설정할 수 있는 최소값을 나타냅니다.

참고 항목