Konfigurace hodnoty TTL ve službě Azure Cosmos DB

Článek
01/10/2024

PLATÍ PRO: NoSQL

Ve službě Azure Cosmos DB můžete nakonfigurovat hodnotu TTL (Time to Live) na úrovni kontejneru nebo ji můžete po nastavení kontejneru přepsat na úrovni položky. Hodnotu TTL pro kontejner můžete nakonfigurovat pomocí webu Azure Portal nebo sad SDK pro konkrétní jazyk. Přepsání hodnoty TTL na úrovni položky je možné nakonfigurovat pomocí sad SDK.

Obsah tohoto článku se vztahuje k hodnotě TTL transakčního úložiště služby Azure Cosmos DB. Pokud hledáte hodnotu TTL analitycal storu, která umožňuje scénáře NoETL HTAP prostřednictvím Azure Synapse Linku, klikněte sem.

Povolení doby provozu v kontejneru pomocí webu Azure Portal

Pomocí následujících kroků povolíte, aby se čas v kontejneru bez vypršení platnosti vysílil. Povolení hodnoty TTL na úrovni kontejneru, aby bylo možné přepsat stejnou hodnotu na úrovni jednotlivé položky. Hodnotu TTL můžete nastavit také zadáním nenulové hodnoty pro sekundy.

Přihlaste se k portálu Azure.
Vytvořte nový účet služby Azure Cosmos DB nebo vyberte existující účet.
Otevřete podokno Průzkumník dat.
Vyberte existující kontejner, rozbalte kartu Nastavení a upravte následující hodnoty:
- V části Nastavení najít, Time to Live.
- Na základě vašeho požadavku můžete:
  - Vypnout toto nastavení
  - Nastavte ho na Zapnuto (bez výchozího nastavení) nebo
  - Zapněte hodnotu TTL zadanou v sekundách.
- Změny uložíte tlačítkem Uložit.

Pokud je defaultTimeToLive null, bude funkce Time to Live vypnutá.
Pokud je defaultTimeToLive -1, je vaše nastavení Time to Live zapnuté (bez výchozího nastavení)
Pokud má DefaultTimeToLive jinou hodnotu Int (s výjimkou 0), je nastavení Time to Live zapnuto. Server automaticky odstraní položky na základě nakonfigurované hodnoty.

Povolení doby života v kontejneru pomocí Azure CLI nebo Azure PowerShellu

Pokud chcete vytvořit nebo povolit hodnotu TTL v kontejneru, podívejte se na

Povolení doby života v kontejneru pomocí sady 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
)

Nastavení doby provozu v kontejneru pomocí sady SDK

Pokud chcete nastavit dobu, po kterou se má v kontejneru žít, musíte zadat nenulové kladné číslo, které označuje časové období v sekundách. Na základě nakonfigurované hodnoty TTL se odstraní všechny položky v kontejneru po posledním časovém razítku změny položky _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
)

Nastavení času na živé položky pomocí portálu

Kromě nastavení výchozího času, který má být v kontejneru aktivní, můžete pro položku nastavit dobu, kterou chcete použít. Nastavení času na úrovni položky přepíše výchozí hodnotu TTL položky v daném kontejneru.

Pokud chcete nastavit hodnotu TTL u položky, musíte zadat nenulové kladné číslo, které označuje období v sekundách, aby platnost položky vypršela po posledním časovém razítku změny položky _ts. Můžete také zadat -1 , kdy by neměla vypršet platnost položky.
Pokud položka neobsahuje pole TTL, použije se ve výchozím nastavení hodnota TTL nastavená na kontejner pro danou položku.
Pokud je hodnota TTL na úrovni kontejneru zakázaná, pole TTL u položky se bude ignorovat, dokud se hodnota TTL znovu nepovolí v kontejneru.

Pomocí následujících kroků můžete povolit, aby se na položce vyživil čas:

Přihlaste se k portálu Azure.
Vytvořte nový účet služby Azure Cosmos DB nebo vyberte existující účet.
Otevřete podokno Průzkumník dat.
Vyberte existující kontejner, rozbalte ho a upravte následující hodnoty:
- Otevřete okno Škálovat a Nastavení.
- V části Nastavení najít, Time to Live.
- Vyberte Zapnuto (bez výchozího nastavení) nebo vyberte Zapnuto a nastavte hodnotu TTL.
- Změny uložíte tlačítkem Uložit.

Dále přejděte k položce, pro kterou chcete nastavit čas naživo, přidejte ttl vlastnost a vyberte Aktualizovat.

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

Nastavení doby živého přenosu u položky pomocí sady 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)

Resetování času naživo pomocí sady SDK

Čas, který se má na položce žít, můžete obnovit provedením operace zápisu nebo aktualizace položky. Operace zápisu _ts nebo aktualizace nastaví aktuální čas a hodnota TTL položky, která vyprší, začne znovu. Pokud chcete změnit hodnotu TTL položky, můžete pole aktualizovat stejně jako jakékoli jiné 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
)

Zakázání doby života pomocí sady SDK

Pokud chcete zakázat dobu, kdy se má v kontejneru žít, a zastavit proces na pozadí, aby kontroloval položky s vypršenou platností, DefaultTimeToLive měla by být vlastnost kontejneru odstraněna. Odstranění této vlastnosti se liší od nastavení na -1. Když nastavíte hodnotu -1, nové položky přidané do kontejneru budou navždy aktivní, ale tuto hodnotu můžete přepsat u konkrétních položek v kontejneru. Když odeberete vlastnost TTL z kontejneru, položky nikdy nevyprší, i když explicitně přepíše předchozí výchozí hodnotu 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
)

Další kroky

Další informace o čase k životu najdete v následujícím článku:

Čas k živému provozu