取代集合

發行項
08/28/2024

Replace Collection 支援在建立之後變更集合的索引編制原則。不支援變更集合的其他屬性，例如識別碼或分割區索引鍵。

注意

這些 API 參考文章示範如何使用 Azure Cosmos DB 資料平面 API 建立資源。透過資料平面 API，您可以設定基本選項，例如編制索引原則，資料分割索引鍵就像使用 Cosmos DB SDK 一樣。如果您需要所有 Azure Cosmos DB 資源的完整功能支援，建議您使用 Cosmos DB 資源提供者。

要求

方法	要求 URI	Description
PUT	HTTPs://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls/{coll-id}	{databaseaccount} 是您訂用帳戶下建立的 Azure Cosmos DB 帳戶名稱。 {db-id} 值是使用者產生的資料庫名稱/識別碼，而不是系統產生的識別碼 (rid) 。 {coll-id} 值是要取代的集合名稱。

標題

如需所有 Cosmos DB 要求所使用的標頭，請參閱常見的 Azure Cosmos DB REST 要求標頭。

主體

屬性	必要	類型	描述
id	必要	String	使用者為該集合產生的唯一名稱。不能有任兩個集合有相同的識別碼。它是不能超過 255 個字元的字串。
indexingPolicy	選擇性	Object	這個值是用來設定集合專案上的索引。根據預設，索引編制原則會針對集合內的所有檔路徑設定為自動。
partitionKey	必要	Object	這個值會設定用於資料分割的資料分割索引鍵。若要使用大型分割區索引鍵，請在 partitionKey 屬性中將版本指定為 2。如果 REST API 版本是 2018-12-31 或更高版本，集合必須包含 partitionKey 定義。在 2018-12-31 之前的版本中，您可以省略 partitionKey 定義，並確保輸送量介於 400 - 10，000 RU/秒之間，來建立具有手動輸送量的舊版非分割集合。為了獲得最佳效能和延展性，建議您一律設定分割區索引鍵。瞭解如何選擇良好的分割區索引鍵。

注意

設定自訂的索引路徑時，您必須為由特殊路徑 "/*" 所表示的整份文件樹狀目錄指定預設的編制索引規則。

{  
  "id": "testcoll",  
  "indexingPolicy": {  
    "indexingMode": "consistent",  
    "automatic": true,  
    "includedPaths": [  
      {  
        "path": "/*",  
        "indexes": [  
          {  
            "dataType": "Number",  
            "precision": -1,  
            "kind": "Range"  
          },  
          {  
            "dataType": "String",  
            "precision": 3,  
            "kind": "Hash"  
          }  
        ]  
      }  
    ],  
    "excludedPaths": []  
  },  
  "_rid": "XrdaAKx3Hgw=",  
  "_ts": 1459203135,  
  "_self": "dbs/XrdaAA==/colls/XrdaAKx3Hgw=/",  
  "_etag": "\"00006c00-0000-0000-0000-56f9ac3f0000\"",  
  "_docs": "docs/",  
  "_sprocs": "sprocs/",  
  "_triggers": "triggers/",  
  "_udfs": "udfs/",  
  "_conflicts": "conflicts/"  
}

回應

Replace Collection 會將更新的集合傳回為回應本文。

標題

如需所有 Cosmos DB 回應所傳回的標頭，請參閱常見的 Azure Cosmos DB REST 回應標頭。

狀態碼

下表列出此作業所傳回的常見狀態碼。如需狀態碼的完整清單，請參閱 HTTP 狀態碼。

程式碼	描述
201 確定	PUT 作業成功。
400 不正確的要求	JSON 內文無效。檢查是否缺少大括號或引號。

主體

屬性	Description
id	這是識別新集合的唯一名稱。
_rid	它是系統產生的屬性。資源識別碼 (_rid) 是唯一的識別碼，同時也是資源模型上資源堆疊的階層式。供內部進行放置和導覽文件資源時使用。
_ts	它是系統產生的屬性。代表資源的上次更新時間戳記。值為時間戳記。
_self	它是系統產生的屬性。代表資源的唯一可定址 URI。
_etag	這是系統產生的屬性，代表開放式並行控制所需的資源 etag。
_doc	它是系統產生的屬性，指定檔資源的可定址路徑。
_sprocs	它是系統產生的屬性，指定預存程式 (sprocs) 資源的可定址路徑。
_triggers	它是系統產生的屬性，指定觸發程式資源的可定址路徑。
_udfs	它是系統產生的屬性，指定使用者定義函式 (udfs) 資源的可定址路徑。
_conflicts	它是系統產生的屬性，指定衝突資源的可定址路徑。在操作集合內的資源期間，如果發生衝突，使用者可以在衝突 URI 路徑上執行 GET 來檢查衝突的資源。
indexingPolicy	這是集合的索引編制原則設定。
partitionKey	這是集合的資料分割組態設定。

包含路徑底下的屬性

屬性	Description
path	索引行為套用至的路徑。索引路徑的開頭為根 (/)，且通常結尾為 ? 萬用字元運算子，代表有多個可能的首碼值。例如，若要為 SELECT * FROM Families F WHERE F.familyName = "Andersen" 提供服務，您必須在集合的索引原則中包含 /familyName/? 的索引路徑。索引路徑也可以使用 * 萬用字元運算子來指定路徑首碼底下的遞迴行為。例如，使用 /payload/* 可將 payload 屬性下的所有項目自編製索引作業中排除。
dataType	這是套用索引行為的資料類型。可以是 String、 Number、 Point、 Polygon或 LineString*。布林值和 Null 會自動編制索引
kind	索引的類型。雜湊索引適用于相等比較，而範圍索引適用于相等、範圍比較和排序。空間索引對於空間查詢很有用。
精確度	索引的有效位數。可以設定為 -1 表示最大有效位數，或數位介於 1-8 之間，而 String可以設定為 1-100。不適用於 Point、 Polygon和 LineString 資料類型。

[排除路徑] 底下的屬性

屬性	Description
path	從索引編制中排除的路徑。索引路徑開頭為根 (/) ，且通常會以 * 萬用字元運算子結尾。例如，使用 /payload/* 可將 payload 屬性下的所有項目自編製索引作業中排除。

{  
  "id": "testcoll",  
  "indexingPolicy": {  
    "indexingMode": "consistent",  
    "automatic": true,  
    "includedPaths": [  
      {  
        "path": "/*",  
        "indexes": [  
          {  
            "kind": "Range",  
            "dataType": "Number",  
            "precision": -1  
          },  
          {  
            "kind": "Hash",  
            "dataType": "String",  
            "precision": 3  
          }  
        ]  
      }  
    ],  
    "excludedPaths": []  
  },  
  "_rid": "XrdaAKx3Hgw=",  
  "_ts": 1459203136,  
  "_self": "dbs/XrdaAA==/colls/XrdaAKx3Hgw=/",  
  "_etag": "\"00006e00-0000-0000-0000-56f9ac400000\"",  
  "_docs": "docs/",  
  "_sprocs": "sprocs/",  
  "_triggers": "triggers/",  
  "_udfs": "udfs/",  
  "_conflicts": "conflicts/"  
}

範例

PUT https://querydemo.documents.azure.com/dbs/XrdaAA==/colls/XrdaAKx3Hgw= HTTP/1.1  
x-ms.date: 04/20/2021
authorization: type%3dmaster%26ver%3d1.0%26sig%3dZY2s2H1TuPFKk1H2od5qVLbn57vjI9rKz0CMXKOk3GA%3d  
Cache-Control: no-cache  
User-Agent: Microsoft.Azure.Documents.Client/1.6.0.0  
x-ms-version: 2015-12-16  
Accept: application/json  
Host: querydemo.documents.azure.com  
Content-Length: 475  
Expect: 100-continue  
  
{  
  "id": "testcoll",  
  "indexingPolicy": {  
    "indexingMode": "consistent",  
    "automatic": true,  
    "includedPaths": [  
      {  
        "path": "/*",  
        "indexes": [  
          {  
            "dataType": "Number",  
            "precision": -1,  
            "kind": "Range"  
          },  
          {  
            "dataType": "String",  
            "precision": 3,  
            "kind": "Hash"  
          }  
        ]  
      }  
    ],  
    "excludedPaths": []  
  },  
  "_rid": "XrdaAKx3Hgw=",  
  "_ts": 1459203135,  
  "_self": "dbs/XrdaAA==/colls/XrdaAKx3Hgw=/",  
  "_etag": "\"00006c00-0000-0000-0000-56f9ac3f0000\"",  
  "_docs": "docs/",  
  "_sprocs": "sprocs/",  
  "_triggers": "triggers/",  
  "_udfs": "udfs/",  
  "_conflicts": "conflicts/"  
}

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/dbs/XrdaAA==/colls/XrdaAKx3Hgw=  
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: "00006e00-0000-0000-0000-56f9ac400000"  
x-ms-resource-quota: collections=5000;  
x-ms-resource-usage: collections=28;  
collection-partition-index: 0  
collection-service-index: 0  
x-ms-schemaversion: 1.1  
x-ms-alt-content-path: dbs/testdb  
x-ms-quorum-acked-lsn: 7902  
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: 6050a48c-828d-4016-b73b-5e0ce2ad6271  
x-ms-session-token: M:7903  
Set-Cookie: x-ms-session-token#M=7903; Domain=querydemo.documents.azure.com; Path=/dbs/XrdaAA==/colls/XrdaAKx3Hgw=  
Set-Cookie: x-ms-session-token=7903; Domain=querydemo.documents.azure.com; Path=/dbs/XrdaAA==/colls/XrdaAKx3Hgw=  
x-ms-gatewayversion: version=1.6.52.5  
Date: Mon, 28 Mar 2016 22:12:15 GMT  
  
{  
  "id": "testcoll",  
  "indexingPolicy": {  
    "indexingMode": "consistent",  
    "automatic": true,  
    "includedPaths": [  
      {  
        "path": "/*",  
        "indexes": [  
          {  
            "kind": "Range",  
            "dataType": "Number",  
            "precision": -1  
          },  
          {  
            "kind": "Hash",  
            "dataType": "String",  
            "precision": 3  
          }  
        ]  
      }  
    ],  
    "excludedPaths": []  
  },  
  "_rid": "XrdaAKx3Hgw=",  
  "_ts": 1459203136,  
  "_self": "dbs/XrdaAA==/colls/XrdaAKx3Hgw=/",  
  "_etag": "\"00006e00-0000-0000-0000-56f9ac400000\"",  
  "_docs": "docs/",  
  "_sprocs": "sprocs/",  
  "_triggers": "triggers/",  
  "_udfs": "udfs/",  
  "_conflicts": "conflicts/"  
}

共用方式為

取代集合

要求

標題

主體

回應

標題

狀態碼

主體

範例

另請參閱

其他資源