Replace an Offer
To replace an entire offer resource, perform a PUT operation on the specific offer resource. To learn more about the maximum and minimum provisioned throughput that can be set on a container or a database, see the Provision throughput on containers and databases article.
Request
Method | Request URI | Description |
---|---|---|
PUT | https://{databaseaccount}.documents.azure.com/offers/{_rid-offer} |
{databaseaccount} is the name of the Azure Cosmos DB account you created under your subscription. The {_rid-offer} value is the system-generated resource ID of the offer. |
Tip
To find the _rid of the offer associated with a database or collection, first GET the database or GET the collection and note the _rid property of the resource. Then, query the offers to find the _rid-offer that corresponds to the database or collection's _rid. Typically, a database _rid is length 8, a collection _rid is length 12, and an offer _rid is length 4.
Headers
See Common Azure Cosmos DB REST request headers for headers that are used by all Cosmos DB requests
Body
Property | Required | Description |
---|---|---|
offerVersion | Required | It can be V1 for the legacy S1, S2, and S3 levels and V2 for user-defined throughput levels (recommended). |
offerType | Optional | This property is only applicable in the V1 offer version. Set it to S1, S2, or S3 for V1 offer types. It is invalid for user-defined performance levels or provisioned throughput based model. |
content | Required | Contains information about the offer – for V2 offers, this value contains the throughput of the collection. |
resource | Required | When creating a new collection, this property is set to the self-link of the collection for example, dbs/pLJdAA==/colls/pLJdAOlEdgA=/. |
offerResourceId | Required | During creation of a collection, this property is automatically associated to the resource ID, that is, _rid of the collection. In the example above, the _rid for the collection is pLJdAOlEdgA=. |
id | Required | It is a system-generated property. The ID for the offer resource is automatically generated when it is created. It has the same value as the _rid for the offer. |
_rid | Required | It is a system-generated property. The resource ID (_rid) is a unique identifier that is also hierarchical per the resource stack on the resource model. It is used internally for placement and navigation of the offer. |
{
"offerVersion": "V2",
"offerType": "Invalid",
"content": {
"offerThroughput": 4000
},
"resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",
"offerResourceId": "rgkVAMHcJww=",
"id": "uT2L",
"_rid": "uT2L",
}
Response
Returns the updated offer resource.
Headers
See Common Azure Cosmos DB REST response headers for headers that are returned by all Cosmos DB responses.
Status codes
The following table lists common status codes returned by this operation. For a full list of status codes, see HTTP Status Codes.
HTTP status code | Description |
---|---|
200 OK | The replace operation was successful. |
400 Bad Request | The JSON body is invalid. Check for missing curly brackets or quotes. |
401 Unauthorized | The Authorization or x-ms-date header is not set. 401 is also returned when the Authorization header is set to an invalid authorization token. |
404 Not Found | The offer is no longer a resource, that is, the resource was deleted. |
429 Too Many Requests | The replace offer is throttled because the offer scale down operation is attempted within the idle timeout period, that is 4 hours. Refer to the "x-ms-retry-after-ms response" header to see how long you should wait before retrying this operation. |
Body
Property | Description |
---|---|
offerVersion | This value can be V1 for pre-defined throughput levels and V2 for user-defined throughput levels. |
offerType | Pre-defined performance levels S1, S2, or S3 for V1 Offers. Its set to Invalid for user-defined performance levels. |
content | It contains information about the offer. For V2 offers, it contains the throughput of the collection. |
resource | When creating a new collection, this property is set to the self-link of the collection for example, dbs/pLJdAA==/colls/pLJdAOlEdgA=/. |
offerResourceId | During creation of a collection, this property is automatically associated to the resource ID, that is, _rid of the collection. In the example above, the _rid for the collection is pLJdAOlEdgA=. |
id | It is a system-generated property. The ID for the offer resource is automatically generated when it is created. It has the same value as the _rid for the offer. |
_rid | It is a system-generated property. The resource ID (_rid) is a unique identifier that is also hierarchical per the resource stack on the resource model. It is used internally for placement and navigation of the offer. |
_ts | It is a system-generated property. It specifies the last updated timestamp of the resource. The value is a timestamp. |
_self | It is a system-generated property. It is the unique addressable URI for the resource. |
_etag | It is a system-generated property that specifies the resource etag required for optimistic concurrency control. |
{
"offerVersion": "V2",
"_rid": "uT2L",
"content": {
"offerThroughput": 4000
},
"resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",
"offerResourceId": "rgkVAMHcJww=",
"id": "uT2L",
"_self": "offers/uT2L/"
}
Example 1
This example shows how to change the manual throughput (RU/s) of a collection to 1000 RU/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="
}
Below is a sample response.
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
}
Example 2
This example shows how to change the max throughput (RU/s) of an offer with autoscale throughput to 8000 RU/s (scales between 800 - 8000 RU/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"
}
Example 3
This example shows how to migrate an offer with manual throughput to autoscale throughput. The header x-ms-cosmos-migrate-offer-to-autopilot
with value true
is required.
When migrating, Azure Cosmos DB automatically determines the new autoscale max RU/s based on the current resource settings. The maxThroughput
property in the response object represents the default autoscale max RU/s set by the system.
In the body, the content
property with a defined offerThroughput
is required, but the value will be ignored by the service. The following example uses -1.
After the change is complete, you can follow Example 2 to change the autoscale max RU/s to a custom value.
Learn more about migrating to autoscale.
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"
}
Below is a sample response body.
The property maxThroughput
represents the autoscale max RU/s set by the system. The property offerThroughput
represents the RU/s the system is currently scaled to.
{
"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
}
Example 4
This example shows how to migrate an offer with autoscale throughput to manual throughput. The header x-ms-cosmos-migrate-offer-to-manual-throughput
with value true
is required.
When migrating, Azure Cosmos DB automatically determines the new manual throughput (RU/s) based on the current resource settings. After the change is complete, you can follow Example 1 to change the manual RU/s to a custom value.
In the body, the content
property with a defined offerAutopilotSettings
and maxThroughput
is required, but the value will be ignored by the service. Below we pass in -1.
Learn more about migrating to manual throughput.
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"
}
Below is a sample response body. The property offerThroughput
represents the manual throughput (RU/s) set on the resource.
{
"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
}
Remarks
When you are changing the manual or autoscale throughput on a database or container, the system enforces constraints on the RU/s that can be set on the resource. To learn more about the minimum and maximum provisioned throughput (RU/s) that can be set with manual throughput, see the Provision throughput on containers and databases article. To learn about the minimum autoscale max RU/s you can set, see the autoscale FAQ.
To retrieve the minimum throughput that can be set on database or container, perform GET on the offer resource. The response header x-ms-cosmos-min-throughput
denotes the system determined minimum throughput. This represents the minimum value you can set for the RU/s on a resource with manual throughput, or the minimum value you can set for the autoscale max RU/s on a resource with autoscale throughput.