在 Azure Cosmos DB 中設定存留時間

發行項
03/12/2024

適用於：NoSQL

在 Azure Cosmos DB 中，您可以選擇在容器層級設定存留時間 (TTL)，也可以在為容器設定後於項目層級加以覆寫。您可以使用 Azure 入口網站或語言專屬 SDK，來為容器設定 TTL。項目層級的 TTL 覆寫可使用 SDK 來加以設定。

本文的內容與 Azure Cosmos DB 交易式存放區 TTL 相關。如果您要尋找可透過 Azure Synapse Link 啟用 NoETL HTAP 案例的分析存放區 TTL，請按一下這裡。

使用 Azure 入口網站在容器上啟用存留時間

您可以使用下列步驟，在容器上啟用存留時間 (無到期時間)。在容器層級啟用 TTL，以允許在個別項目的層級覆寫相同的值。您也可以輸入非零值的秒數，以設定 TTL。

登入 Azure 入口網站。
建立新的 Azure Cosmos DB 帳戶或選取現有的帳戶。
開啟 [資料總管] 窗格。
選取現有容器，展開 [設定] 索引標籤，並修改下列值：
- 在 [設定] 底下，尋找 [存留時間]。
- 根據您的需求，您可以：
  - 關閉此設定
  - 將它設定為開啟 (無預設值) 或
  - 開啟並指定 TTL 值 (以秒為單位)。
- 選取儲存以儲存變更。

當 DefaultTimeToLive 為 null 時，存留時間會關閉
當 DefaultTimeToLive 為 -1 時，存留時間會開啟 (無預設值)
當 DefaultTimeToLive 具有任何其他整數值 (0 除外)，存留時間設定會開啟。伺服器將根據設定的值自動刪除項目。

使用 Azure CLI 或 Azure PowerShell 在容器上啟用存留時間

若要在容器上建立或啟用 TTL，請參閱，

使用 SDK 在容器上啟用存留時間

Database database = client.GetDatabase("database");

ContainerProperties properties = new ()
{
    Id = "container",
    PartitionKeyPath = "/customerId",
    // Never expire by default
    DefaultTimeToLive = -1
};

// Create a new container with TTL enabled and without any expiration value
Container container = await database
    .CreateContainerAsync(properties);

CosmosDatabase database = client.getDatabase("database");

CosmosContainerProperties properties = new CosmosContainerProperties(
    "container",
    "/customerId"
);
// Never expire by default
properties.setDefaultTimeToLiveInSeconds(-1);

// Create a new container with TTL enabled and without any expiration value
CosmosContainerResponse response = database
    .createContainerIfNotExists(properties);

const database = await client.database("database");

const properties = {
    id: "container",
    partitionKey: "/customerId",
    // Never expire by default
    defaultTtl: -1
};

const { container } = await database.containers
    .createIfNotExists(properties);

database = client.get_database_client('database')

database.create_container(
    id='container',
    partition_key=PartitionKey(path='/customerId'),
    # Never expire by default
    default_ttl=-1
)

使用 SDK 在容器上設定存留時間

若要在容器上設定存留時間，您必須提供零以外的正數，來指出以秒為單位的時間週期。根據所設定的 TTL 值，容器中時間在 _ts 項目上次修改時間戳記之後的所有項目都會遭到刪除。

Database database = client.GetDatabase("database");

ContainerProperties properties = new ()
{
    Id = "container",
    PartitionKeyPath = "/customerId",
    // Expire all documents after 90 days
    DefaultTimeToLive = 90 * 60 * 60 * 24
};

// Create a new container with TTL enabled and without any expiration value
Container container = await database
    .CreateContainerAsync(properties);

CosmosDatabase database = client.getDatabase("database");

CosmosContainerProperties properties = new CosmosContainerProperties(
    "container",
    "/customerId"
);
// Expire all documents after 90 days
properties.setDefaultTimeToLiveInSeconds(90 * 60 * 60 * 24);

CosmosContainerResponse response = database
    .createContainerIfNotExists(properties);

const database = await client.database("database");

const properties = {
    id: "container",
    partitionKey: "/customerId",
    // Expire all documents after 90 days
    defaultTtl: 90 * 60 * 60 * 24
};

const { container } = await database.containers
    .createIfNotExists(properties);

database = client.get_database_client('database')

database.create_container(
    id='container',
    partition_key=PartitionKey(path='/customerId'),
    # Expire all documents after 90 days
    default_ttl=90 * 60 * 60 * 24
)

使用入口網站設定項目的存留時間

除了在容器上設定預設存留時間外，您還可以為項目設定存留時間。在項目層級設定存留時間，將會覆寫該容器中項目的預設 TTL。

若要在項目上設定 TTL，您必須提供一個非零的正數，指出在 _ts 項目上次修改時間戳記之後要將項目到期的期間 (以秒為單位)。您也可以在項目不應過期時提供 -1。
如果該項目沒有 TTL 欄位，則根據預設，為容器設定的 TTL 便會套用至該項目。
如果已在容器層級停用 TTL，則會忽略項目上的 TTL 欄位，直到在容器上重新啟用 TTL 為止。

使用下列步驟，在項目上啟用存留時間：

登入 Azure 入口網站。
建立新的 Azure Cosmos DB 帳戶或選取現有的帳戶。
開啟 [資料總管] 窗格。
選取現有容器，加以展開並修改下列值：
- 開啟 [規模與設定] 視窗。
- 在 [設定] 底下，尋找 [存留時間]。
- 選取 [開啟 (無預設)]，或選取 [開啟] 並設定 TTL 值。
- 選取儲存以儲存變更。

接著瀏覽至您要設定存留時間的項目、新增 ttl 屬性，然後選取 [更新]。

{
    "id": "1",
    "_rid": "Jic9ANWdO-EFAAAAAAAAAA==",
    "_self": "dbs/Jic9AA==/colls/Jic9ANWdO-E=/docs/Jic9ANWdO-EFAAAAAAAAAA==/",
    "_etag": "\"0d00b23f-0000-0000-0000-5c7712e80000\"",
    "_attachments": "attachments/",
    "ttl": 10,
    "_ts": 1551307496
}

使用 SDK 設定項目的存留時間

public record SalesOrder(string id, string customerId, int ttl);

Container container = database.GetContainer("container");

SalesOrder item = new (
    "SO05", 
    "CO18009186470"
    // Expire sales order in 30 days using "ttl" property
    ttl:  60 * 60 * 24 * 30
);

await container.CreateItemAsync<SalesOrder>(item);

public class SalesOrder {

    public String id;

    public String customerId;

    // Include a property that serializes to "ttl" in JSON
    public Integer ttl;

}

CosmosContainer container = database.getContainer("container");

SalesOrder item = new SalesOrder();
item.id = "SO05";
item.customerId = "CO18009186470";
// Expire sales order in 30 days using "ttl" property
item.ttl = 60 * 60 * 24 * 30;

container.createItem(item);

const container = await database.container("container");

const item = {
    id: 'SO05',
    customerId: 'CO18009186470',
    // Expire sales order in 30 days using "ttl" property
    ttl: 60 * 60 * 24 * 30
};

await container.items.create(item);

container = database.get_container_client('container')

item = {
    'id': 'SO05',
    'customerId': 'CO18009186470',
    # Expire sales order in 30 days using "ttl" property
    'ttl': 60 * 60 * 24 * 30
}

container.create_item(body=item)

使用 SDK 重設存留時間

您可以在項目上執行寫入或更新作業，以重設項目上的存留時間。寫入或更新作業會將 _ts 設定為目前的時間，並重新開始項目的到期 TTL。如果您想要變更項目的 TTL，則可以如同更新任何其他欄位一樣地更新此欄位。

SalesOrder item = await container.ReadItemAsync<SalesOrder>(
    "SO05", 
    new PartitionKey("CO18009186470")
);

// Update ttl to 2 hours
SalesOrder modifiedItem = item with { 
    ttl = 60 * 60 * 2 
};

await container.ReplaceItemAsync<SalesOrder>(
    modifiedItem,
    "SO05", 
    new PartitionKey("CO18009186470")    
);

CosmosItemResponse<SalesOrder> response = container.readItem(
    "SO05", 
    new PartitionKey("CO18009186470"),
    SalesOrder.class
);

SalesOrder item = response.getItem();

// Update ttl to 2 hours
item.ttl = 60 * 60 * 2;

CosmosItemRequestOptions options = new CosmosItemRequestOptions();
container.replaceItem(
    item,
    "SO05", 
    new PartitionKey("CO18009186470"),
    options
);

const { resource: item } = await container.item(
    'SO05',
    'CO18009186470'
).read();

// Update ttl to 2 hours
item.ttl = 60 * 60 * 2;

await container.item(
    'SO05',
    'CO18009186470'
).replace(item);

item = container.read_item(
    item='SO05',
    partition_key='CO18009186470'
)

# Update ttl to 2 hours
item['ttl'] = 60 * 60 * 2 

container.replace_item(
    item='SO05',
    body=item
)

使用 SDK 停用存留時間

若要在容器上停用存留時間，並阻止背景處理程序檢查到期的項目，則應刪除容器上的 DefaultTimeToLive 屬性。刪除此屬性與將它設定為 -1 不同。當您將它設定為 -1 時，新增至容器的新項目將會永遠存在，不過，您可以在容器中的特定項目上覆寫此值。當您從容器中移除 TTL 屬性時，項目將永遠不會過期，即使這些項目已明確覆寫先前預設的 TTL 值也是一樣。

ContainerProperties properties = await container.ReadContainerAsync();

// Disable ttl at container-level
properties.DefaultTimeToLive = null;

await container.ReplaceContainerAsync(properties);

CosmosContainerResponse response = container.read();
CosmosContainerProperties properties = response.getProperties();

// Disable ttl at container-level
properties.setDefaultTimeToLiveInSeconds(null);

container.replace(properties);

const { resource: definition } = await container.read();

// Disable ttl at container-level
definition.defaultTtl = null;

await container.replace(definition);

database.replace_container(
    container,
    partition_key=PartitionKey(path='/id'),
    # Disable ttl at container-level
    default_ttl=None
)

下一步

請於下列文章深入了解存留時間：

存留時間

共用方式為