依分割區索引鍵值刪除項目 - API for NoSQL (預覽)

發行項
08/15/2024

適用於：NoSQL

本文說明如何使用 Azure Cosmos DB SDK，依邏輯分割區索引鍵值刪除所有項目。

重要

依分割區索引鍵值刪除項目處於公開預覽狀態。此功能已推出但不提供服務等級協定。如需詳細資訊，請參閱 Microsoft Azure 預覽版增補使用條款。

功能概觀

「依分割區索引鍵刪除」功能為非同步背景作業，可讓您使用 Cosmos SDK 刪除具有相同邏輯分割區索引鍵值的所有文件。

因為要刪除的文件數目可能很大，所以作業會在背景執行。雖然實體刪除作業會在背景執行，但因為要刪除的文件不會出現在查詢或讀取作業的結果中，所以會立即提供效果。

分割區索引鍵作業的刪除目標是盡最大努力每秒在容器上耗用 10% 的總可用 RU/秒。這有助於限制此背景工作所使用的資源。

開始使用

更新您的 Azure Cosmos DB 帳戶，以使用 Azure CLI 來啟用「依分割區索引鍵刪除」功能。

步驟 1：設定殼層變數

    $resourceGroupName = <azure_resource_group>
    $accountName = <azure_cosmos_db_account_name>
    $DeleteByPk = "DeleteAllItemsByPartitionKey"

步驟 2：列出您帳戶的現有功能。

   $cosmosdb = az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName
   $capabilities = ($cosmosdb | ConvertFrom-Json).capabilities

步驟 3：在功能清單中新增 [依分割區索引鍵刪除項目] 功能 (若尚未存在)。

注意

功能清單必須一律指定您想要啟用的所有功能。這包括已針對您想要保留的帳戶所啟用的功能。
```
   $capabilities = $DeleteByPk
```

步驟 4：更新 Cosmos DB 帳戶，以啟用「依分割區索引鍵刪除項目」功能

    az cosmosdb update --capabilities $capabilities \
     -n $accountName -g $resourceGroupName

範例指令碼

使用 Azure Cosmos DB .NET SDK 的 3.25.0-preview 版 (或更新的預覽版本) 依分割區索引鍵刪除項目。

// Suppose our container is partitioned by tenantId, and we want to delete all the data for a particular tenant Contoso

// Get reference to the container
var container = cosmosClient.GetContainer("DatabaseName", "ContainerName");

// Delete by logical partition key
ResponseMessage deleteResponse = await container.DeleteAllItemsByPartitionKeyStreamAsync(new PartitionKey("Contoso"));

 if (deleteResponse.IsSuccessStatusCode) {
    Console.WriteLine($"Delete all documents with partition key operation has successfully started");
}

使用 Azure Cosmos DB Java SDK 的 4.19.0 版 (或更新版本) 依分割區索引鍵刪除項目。依分割區索引鍵 API 的刪除將會標示為搶鮮版 (Beta)。

// Suppose our container is partitioned by tenantId, and we want to delete all the data for a particular tenant Contoso

// Delete by logical partition key
CosmosItemResponse<?> deleteResponse = container.deleteAllItemsByPartitionKey(
            new PartitionKey("Contoso"), new CosmosItemRequestOptions()).block();

使用 Azure Cosmos DB Python SDK 的搶鮮版 (Beta) (>= 4.4.0b1)，以依分割區索引鍵來刪除項目。依分割區索引鍵 API 的刪除將會標示為搶鮮版 (Beta)。

# Suppose our container is partitioned by tenantId, and we want to delete all the data for a particular tenant Contoso

# Delete by logical partition key
container.delete_all_items_by_partition_key("Contoso")

常見問題集 (FAQ)

依分割區索引鍵作業刪除的結果是否立即反映？

是，「依分割區索引鍵刪除」作業開始之後，要刪除的文件將不會出現在查詢或讀取作業的結果中。這也表示，您可以使用與要刪除的文件相同的識別碼和分割區索引鍵寫入新文件，而不會造成衝突。

如有例外狀況，請參閱已知問題。

如果我發出依分割區索引鍵作業刪除，然後立即使用相同的分割區索引鍵寫入新文件，會發生什麼事？

發出「依分割區索引鍵刪除」作業時，只會刪除存在於容器中且具有分割區索引鍵值的文件。任何傳入的新文件都不在刪除範圍內。

在針對容器的其他作業中，依分割區索引鍵刪除作業的優先順序如何？

根據預設，依分割區索引鍵值刪除作業最多可以消耗資源上總 RU/s 的保留分數 - 0.1 或 10%。此貯體中未使用的任何要求單位 (RU) 將可用於其他非背景作業，如讀取、寫入和查詢。

例如，假設您已在容器上佈建 1000 RU/秒。「依分割區索引鍵刪除」作業會持續進行，而且每秒使用 100 個 RU，並持續 5 秒。在這 5 秒的每一秒中，都有 900 個 RU 可用於非背景資料庫作業。刪除作業完成後，所有 1000 RU/s 現在都再次可供使用。

已知問題

在某些情況下，「依分割區索引鍵刪除」作業可能不會立即保證其效果，而且可能會在作業期間發生局部可見度。

使用索引的彙總查詢 (例如，COUNT 查詢) 在持續進行的「依分割區索引鍵刪除」作業期間發出，可能包含所要刪除文件的結果。這可能會在刪除作業完全完成之前發生。
在執行依分割區索引鍵作業刪除期間針對分析存放區發出的查詢可能包含要刪除文件的結果。這可能會在刪除作業完全完成之前發生。
持續備份 (時間點還原) - 在持續依分割區索引鍵作業刪除期間觸發的還原可能包含要在還原集合中刪除文件的結果。如果您有需要連續備份的情節，則不建議使用此預覽功能。

限制

不支援階層式分割區索引鍵刪除。此功能只允許根據最後一個分割區索引鍵層級來刪除項目。例如，假設分割區索引鍵包含三個階層式層級：國家/地區、州和城市。在此內容中，可以指定完整的分割區索引鍵 (包括所有層級，即國家/地區/州/城市)，以有效地運用「依分割區索引鍵刪除」功能。嘗試使用中繼分割區索引鍵 (例如國家/地區/州或僅國家/地區) 進行刪除將會導致錯誤。

如何提供意見反應或回報問題/錯誤

向 cosmosPkDeleteFeedbk@microsoft.com 傳送問題或意見反應。

SDK 需求

尋找支援此功能的最新版本 SDK。

SDK	支援的版本	套件管理員連結
.NET SDK v3	>= 3.25.0-preview (必須是預覽版本)	https://www.nuget.org/packages/Microsoft.Azure.Cosmos/
Java SDK v4	>= 4.19.0 (API 標示為搶鮮版 (Beta))	https://mvnrepository.com/artifact/com.azure/azure-cosmos
Python SDK v4	>= 4..4.0b1 (必須是搶鮮版 (Beta) 版本)	https://pypi.org/project/azure-cosmos/4.4.0b1/

規劃未來將支援其他 SDK。

下一步

請參閱下列文章，以了解 Azure Cosmos DB 中的更多 SDK 作業。

共用方式為