Konfigurowanie czasu wygaśnięcia w usłudze Azure Cosmos DB

Artykuł
01/10/2024

DOTYCZY: NoSQL

W usłudze Azure Cosmos DB możesz skonfigurować czas wygaśnięcia (Time to Live, TTL) na poziomie kontenera lub zastąpić go na poziomie elementu po ustawieniu TTL dla kontenera. TTL można skonfigurować dla kontenera przy użyciu witryny Azure Portal lub zestawu SDK właściwego dla używanego języka. Zastępowanie TTL na poziome elementu można skonfigurować za pomocą zestawów SDK.

Zawartość tego artykułu jest powiązana z czas wygaśnięcia magazynu transakcyjnego usługi Azure Cosmos DB. Jeśli szukasz czasu wygaśnięcia magazynu analitycalnego, który umożliwia scenariusze NoETL HTAP za pośrednictwem usługi Azure Synapse Link, kliknij tutaj.

Włączanie czasu wygaśnięcia w kontenerze przy użyciu witryny Azure Portal

Wykonaj następujące czynności, aby włączyć czas wygaśnięcia dla kontenera bez terminu wygaśnięcia. Włączenie czasu wygaśnięcia na poziomie kontenera w celu umożliwienia zastąpienia tej samej wartości na poziomie pojedynczego elementu. Możesz także ustawić TTL, wprowadzając niezerową liczbę sekund.

Zaloguj się w witrynie Azure Portal.
Utwórz nowe konto usługi Azure Cosmos DB lub wybierz istniejące konto.
Otwórz okienko Eksplorator danych.
Wybierz istniejący kontener, rozwiń kartę Ustawienia i zmodyfikuj następujące wartości:
- W obszarze Ustawienia znajdź pozycję Czas wygaśnięcia.
- W zależności od wymagań możesz wykonywać następujące czynności:
  - Wyłącz to ustawienie
  - Ustaw wartość Włączone (bez wartości domyślnej) lub
  - Włącz przy użyciu wartości czasu wygaśnięcia określonej w sekundach.
- Wybierz Zapisz, aby zapisać zmiany.

Jeśli wartość DefaultTimeToLive ma wartość null, czas wygaśnięcia jest wyłączony
Gdy wartość DefaultTimeToLive wynosi -1, ustawienie Czas wygaśnięcia ma wartość Włączone (wartość domyślna)
Jeśli wartość DefaultTimeToLive ma inną wartość int (z wyjątkiem 0), ustawienie Czas wygaśnięcia jest włączone. Serwer automatycznie usunie elementy na podstawie skonfigurowanej wartości.

Włączanie czasu wygaśnięcia w kontenerze przy użyciu interfejsu wiersza polecenia platformy Azure lub programu Azure PowerShell

Aby utworzyć lub włączyć czas wygaśnięcia w kontenerze, zobacz:

Włączanie czasu wygaśnięcia w kontenerze przy użyciu zestawu 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
)

Ustawianie czasu wygaśnięcia w kontenerze przy użyciu zestawu SDK

Aby ustawić czas wygaśnięcia dla kontenera, należy podać niezerową liczbę dodatnią, określającą czas w sekundach. Na podstawie skonfigurowanej wartości TTL wszystkie elementy w kontenerze zostaną usunięte po upływie wskazanego czasu od wartości znacznika czasu ostatniej modyfikacji _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
)

Ustawianie czasu wygaśnięcia elementu przy użyciu portalu

Oprócz skonfigurowania domyślnego czasu wygaśnięcia dla kontenera możesz ustawić czas wygaśnięcia konkretnego elementu. Ustawienie czasu wygaśnięcia na poziomie elementu spowoduje zastąpienie domyślnego czasu wygaśnięcia elementu w kontenerze.

Aby ustawić czas wygaśnięcia elementu, podaj niezerową liczbę dodatnią oznaczającą czas w sekundach — element zostanie usunięty po upływie tego czasu od wartości znacznika czasu ostatniej modyfikacji _ts. Możesz również podać element -1 , gdy element nie powinien wygasać.
Jeśli element nie ma pola TTL, będzie obowiązywał domyślny czas wygaśnięcia ustawiony dla kontenera.
Jeśli czas wygaśnięcia zostanie wyłączony na poziomie kontenera, pole TTL elementu będzie ignorowane do momentu ponownego włączenia czasu wygaśnięcia dla kontenera.

Aby włączyć czas wygaśnięcia elementu, wykonaj następujące kroki:

Zaloguj się w witrynie Azure Portal.
Utwórz nowe konto usługi Azure Cosmos DB lub wybierz istniejące konto.
Otwórz okienko Eksplorator danych.
Wybierz istniejący kontener, rozwiń go, a następnie zmodyfikuj następujące wartości:
- Otwórz okno Skalowanie i ustawienia.
- W obszarze Ustawienia znajdź pozycję Czas wygaśnięcia.
- Wybierz pozycję Włączone (bez wartości domyślnej) lub wybierz pozycję Włączone i ustaw wartość czasu wygaśnięcia.
- Wybierz Zapisz, aby zapisać zmiany.

Następnie przejdź do elementu, dla którego chcesz ustawić czas wygaśnięcia, dodaj ttl właściwość i wybierz pozycję Aktualizuj.

{
    "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
}

Ustawianie czasu wygaśnięcia elementu przy użyciu zestawu 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)

Resetowanie czasu wygaśnięcia przy użyciu zestawu SDK

Możesz zresetować czas wygaśnięcia elementu, wykonując operację zapisu lub aktualizacji na elemencie. Operacja zapisu lub aktualizacji spowoduje ustawienie znacznika czasu _ts na bieżący czas, od którego ponownie rozpocznie się odliczanie czasu wygaśnięcia elementu. Jeśli chcesz zmienić czas wygaśnięcia elementu, możesz zaktualizować pole TTL tak samo jak każde inne pole.

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
)

Wyłączanie czasu wygaśnięcia przy użyciu zestawu SDK

Aby wyłączyć czas wygaśnięcia dla kontenera i zatrzymać proces w tle sprawdzający, czy elementy wygasły, należy usunąć właściwość DefaultTimeToLive z kontenera. Usunięcie tej właściwości ma inne skutki niż ustawienie jej na –1. Jeśli wartość właściwości zostanie ustawiona na –1, nowe elementy dodawane do kontenera nie będą wygasały, ale można będzie zastąpić tę wartość w przypadku wybranych elementów w kontenerze. Usunięcie właściwości TTL z kontenera spowoduje, że elementy nigdy nie wygasną, nawet jeśli jawnie zastąpią poprzednią domyślną wartość czasu wygaśnięcia.

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
)

Następne kroki

Aby dowiedzieć się więcej na temat czasu wygaśnięcia, zobacz artykuł:

Time to live (Czas wygaśnięcia)