Time to Live configureren in Azure Cosmos DB

Artikel
01/10/2024

VAN TOEPASSING OP: NoSQL

In Azure Cosmos DB kunt u Time to Live (TTL) configureren op containerniveau, maar u kunt het ook overschrijven op een itemniveau nadat u het voor de container hebt ingesteld. U kunt TTL voor een container configureren via de Azure-portal of de taalspecifieke SDK's. Overschrijvingen van TTL op itemniveau kunnen worden geconfigureerd met behulp van de SDK's.

De inhoud van dit artikel is gerelateerd aan TTL voor transactionele opslag van Azure Cosmos DB. Als u op zoek bent naar analitycal store TTL, waarmee NoETL HTAP-scenario's via Azure Synapse Link worden ingeschakeld, klikt u hier.

Time to Live inschakelen voor een container met behulp van Azure Portal

Gebruik de volgende stappen om Time to Live in te schakelen op een container zonder vervaldatum. Als u TTL inschakelt op containerniveau, kan dezelfde waarde worden overschreven op het niveau van een afzonderlijk item. U kunt de TTL ook instellen door een waarde (in seconden) ongelijk aan nul in te voeren.

Meld u aan bij de Azure-portal.
Maak een nieuw Azure Cosmos DB-account of selecteer een bestaand account.
Open het deelvenster Data Explorer.
Selecteer een bestaande container, vouw het tabblad Instellingen uit en wijzig de volgende waarden:
- Onder Instelling zoekt u Time to Live.
- Op basis van uw behoeften kunt u het volgende doen:
  - Deze instelling uitschakelen
  - Stel deze in op Aan (geen standaardinstelling) of
  - Schakel in met een TTL-waarde die in seconden is opgegeven.
- Als u de wijzigingen wilt opslaan, selecteert u Opslaan.

Wanneer DefaultTimeToLive null is, is uw Time to Live uitgeschakeld
Wanneer DefaultTimeToLive -1 is, is uw Time to Live-instelling ingeschakeld (geen standaardinstelling)
Wanneer DefaultTimeToLive een andere int-waarde (behalve 0) heeft, is de instelling Time to Live ingeschakeld. De server verwijdert automatisch items op basis van de geconfigureerde waarde.

Time to Live inschakelen voor een container met behulp van Azure CLI of Azure PowerShell

Als u TTL wilt maken of inschakelen voor een container, raadpleegt u

Time to Live inschakelen voor een container met behulp van een 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
)

Time to Live instellen op een container met behulp van een SDK

Als u de Time to Live voor een container wilt instellen, dient u een positief getal (geen nul) op te geven die de tijd in seconden aangeeft. Op basis van de geconfigureerde TTL-waarde worden alle items in de container verwijderd na het laatste gewijzigde tijdstempel _ts van het item.

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
)

Time to Live instellen op een item met behulp van de portal

U kunt niet alleen de standaardwaarde voor Time to Live voor een container instellen, maar ook voor een item. Als u Time to Live op itemniveau instelt, wordt de standaard-TL van het item in die container overschreven.

Als u de TTL voor een item instelt, dient u een dient u een positief getal (geen nul) op te geven die de tijd in seconden aangeeft. Hiermee wordt aangegeven dat het item vervalt na het laatste gewijzigde tijdstempel _ts van het item. U kunt ook -1 opgeven wanneer het item niet mag verlopen.
Als het item geen TTL-veld heeft, wordt standaard de TTL-waarde die voor de container is ingesteld, op het item toegepast.
Als TTL wordt uitgeschakeld op containerniveau, wordt het TTL-veld van het item genegeerd totdat TTL opnieuw voor de container wordt ingeschakeld.

Gebruik de volgende stappen om time to live op een item in te schakelen:

Meld u aan bij de Azure-portal.
Maak een nieuw Azure Cosmos DB-account of selecteer een bestaand account.
Open het deelvenster Data Explorer.
Selecteer een bestaande container, vouw deze uit en wijzig de volgende waarden:
- Open het venster Schaal en instellingen.
- Onder Instelling zoekt u Time to Live.
- Selecteer Aan (geen standaardinstelling) of selecteer Aan en stel een TTL-waarde in.
- Als u de wijzigingen wilt opslaan, selecteert u Opslaan.

Ga vervolgens naar het item waarvoor u time to live wilt instellen, voeg de ttl eigenschap toe en selecteer Bijwerken.

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

Time to Live instellen op een item met behulp van een 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)

Time to Live opnieuw instellen met behulp van een SDK

U kunt Time to Live opnieuw voor een item instellen door een schrijf- of bijwerkbewerking voor het item uit te voeren. Met de schrijf- of bijwerkbewerking wordt _ts ingesteld op de huidige tijd en de TTL voor dat item begint van voren af aan. Als u de TTL van een item wilt wijzigen, kunt u het veld op dezelfde manier bijwerken als elk ander veld.

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
)

Time to Live uitschakelen met behulp van een SDK

Als u Time to Live voor een container wilt uitschakelen en het achtergrondproces dat op verlopen items controleert, wilt stoppen, moet eigenschap DefaultTimeToLive op de container worden verwijderd. Het verwijderen van deze eigenschap is iets anders dan het instellen ervan op -1. Als u de eigenschap op -1 instelt, zullen nieuwe items die aan de container worden toegevoegd, nooit verlopen. U kunt deze waarde echter voor bepaalde items in de container overschrijven. Wanneer u de TTL-eigenschap uit de container verwijdert, verlopen de items nooit, zelfs als ze de vorige standaard-TTL-waarde expliciet hebben overschreven.

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
)

Volgende stappen

Meer informatie over Time to Live vindt u in het volgende artikel:

Time to live