共用方式為

取代供應項目

  • 發行項

若要取代整個供應專案資源，請在特定供應專案資源上執行 PUT 作業。 若要深入瞭解可以在容器或資料庫上設定的最大和最小布建輸送量，請參閱 在容器和資料庫上布建輸送量 一文。

要求

方法 要求 URI Description
PUT https://{databaseaccount}.documents.azure.com/offers/{_rid-offer} {databaseaccount} 是您在訂用帳戶下建立的 Azure Cosmos DB 帳戶名稱。 {_rid-offer} 值是供應專案的系統產生的資源識別碼。

提示

若要尋找與資料庫或集合相關聯的供應專案_rid，請先 取得資料庫 或 GET 集合 ，並記下資源的_rid屬性。 然後， 查詢供應專案 以尋找對應至資料庫或集合_rid的_rid供應專案。 一般而言，資料庫_rid長度為 8、集合_rid長度為 12，而供應專案_rid長度為 4。

標題

如需所有 Cosmos DB 要求所使用的標頭，請參閱一般 Azure Cosmos DB REST 要求標頭

主體

屬性 必要 Description
offerVersion 必要 適用于舊版 S1、S2 和 S3 層級的 V1，以及使用者定義輸送量層級的 V2， (建議) 。
offerType 選擇性 此屬性僅適用于 V1 供應專案版本。 針對 V1 供應專案類型，將其設定為 S1、S2 或 S3。 使用者定義效能層級或布建的輸送量模型無效。
content 必要 包含供應專案的相關資訊 – 針對 V2 供應專案，此值包含集合的輸送量。
資源 必要 建立新的集合時，這個屬性會設定為集合的自我連結，例如 dbs/pLJdAA==/colls/pLJdAOlEdgA=/。
offerResourceId 必要 在建立集合期間，此屬性會自動與資源識別碼相關聯，也就是 集合_rid 。 在上述範例中，集合 的_rid 是 pLJdAOlEdgA=。
id 必要 它是系統產生的屬性。 供應 專案資源的 識別碼會在建立時自動產生。 其值與供應專案的 _rid 相同。
_擺脫 必要 它是系統產生的屬性。 資源識別碼 (_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 狀態碼 Description
200 確定 取代作業成功。
400 不正確的要求 JSON 內文無效。 檢查是否缺少大括號或引號。
401 未經授權 未設定 Authorization 或 x-ms-date 標頭。 當 Authorization 標頭設為無效的授權權杖時，也會傳回 401。
404 找不到 供應專案不再是資源，也就是資源已刪除。
429 要求太多 取代供應專案會受到節流，因為供應專案相應減少作業會在閒置逾時期間內嘗試，也就是 4 小時。 請參閱「x-ms-retry-after-ms response」 標頭，以查看重試此作業之前應該等候的時間長度。

主體

屬性 Description
offerVersion 此值可以是預先定義的輸送量層級的 V1，而使用者定義輸送量層級則為 V2。
offerType V1 供應專案的預先定義效能等級 S1、S2 或 S3。 其設定為 [使用者定義效能等級無效]。
content 其中包含供應專案的相關資訊。 對於 V2 供應專案，它包含集合的輸送量。
資源 建立新的集合時，這個屬性會設定為集合的自我連結，例如 dbs/pLJdAA==/colls/pLJdAOlEdgA=/。
offerResourceId 在建立集合期間，此屬性會自動與資源識別碼相關聯，也就是 集合_rid 。 在上述範例中，集合 的_rid 是 pLJdAOlEdgA=。
id 它是系統產生的屬性。 供應 專案資源的 識別碼會在建立時自動產生。 其值與供應專案的 _rid 相同。
_擺脫 它是系統產生的屬性。 資源識別碼 (_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/秒所設定的最小值。

另請參閱