你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

替换服务

项目
08/05/2023

若要替换整个产品/服务资源，请对特定的产品/服务资源执行 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 相同。
_摆脱	必需	它是系统生成的属性。资源 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 未授权	未设置 Authorization 或 x-ms-date 标头。将 Authorization 标头设置为无效的授权令牌时，也返回 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 相同。
_摆脱	它是系统生成的属性。资源 ID (_rid) 是一个唯一标识符，也是根据资源模型上的资源堆栈分层的。它可供内部用于放置和导航服务。
_ts	它是系统生成的属性。它指定资源的上次更新时间戳。高值是一个时间戳。
_自我	它是系统生成的属性。它是资源的唯一可寻址 URI。
_Etag	它是一个系统生成的属性，用于指定乐观并发控制所需的资源 etag。

{  
  "offerVersion": "V2",  
  "_rid": "uT2L",
   "content": {  
    "offerThroughput": 4000
  }, 
  "resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",  
  "offerResourceId": "rgkVAMHcJww=",  
  "id": "uT2L",  
  "_self": "offers/uT2L/"
}

示例 1

此示例演示如何将集合的手动吞吐量 (RU/秒) 更改为 1000 RU/秒。

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/秒) 更改为 8000 RU/秒， (缩放在 800 - 8000 RU/秒之间)

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/秒。 maxThroughput响应对象中的属性表示系统设置的默认自动缩放最大 RU/秒。

在正文中 content ，需要具有定义的 offerThroughput 属性，但服务将忽略该值。以下示例使用 -1。

更改完成后，可以按照示例 2 将自动缩放最大 RU/秒更改为自定义值。

详细了解如何迁移到自动缩放。

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/秒。属性 offerThroughput 表示系统当前缩放到的 RU/秒。

{
    "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/秒) 。更改完成后，可以按照示例 1 将手动 RU/秒更改为自定义值。

在正文中 content ，需要具有已定义 offerAutopilotSettings 和 maxThroughput 的属性，但服务将忽略该值。下面我们传入 -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/秒) 。

{
    "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/秒强制实施约束。若要详细了解可以使用手动吞吐量设置的最小和最大预配吞吐量 (RU/秒) ，请参阅针对容器和数据库预配吞吐量一文。若要了解可设置的最小自动缩放最大 RU/秒，请参阅自动缩放常见问题解答。

若要检索可在数据库或容器上设置的最小吞吐量，请对产品/服务资源执行 GET。响应标头 x-ms-cosmos-min-throughput 表示系统确定的最小吞吐量。这表示可为具有手动吞吐量的资源上的 RU/秒设置的最小值，或可为具有自动缩放吞吐量的资源上的自动缩放最大 RU/秒设置的最小值。