Configurer la durée de vie dans Azure Cosmos DB

Article
04/03/2023

S’APPLIQUE À : NoSQL

Dans Azure Cosmos DB, vous pouvez choisir de configurer la durée de vie (TTL) au niveau du conteneur, mais vous pouvez aussi la définir au niveau de l’élément après avoir configuré le conteneur. Vous pouvez configurer la TTL d’un conteneur en utilisant le portail Azure ou les kits SDK propres à chaque langage. Les remplacements de la TTL au niveau de l’élément peuvent être configurés avec les kits SDK.

Le contenu de cet article concerne la TTL des magasins transactionnels d’Azure Cosmos DB. Si vous recherchez la TTL des magasins analytiques, qui permet des scénarios de HTAP NoETL via Azure Synapse Link, cliquez ici.

Activer la durée de vie sur un conteneur avec le portail Azure

Utilisez les étapes suivantes pour activer la durée de vie sur un conteneur sans date d’expiration. Activation de la TTL au niveau du conteneur pour permettre la substitution de la même valeur au niveau d’un élément individuel. Vous pouvez également définir la TTL en entrant une valeur différente de zéro pour les secondes.

Connectez-vous au portail Azure.
Créez un compte Azure Cosmos DB ou sélectionnez un compte existant.
Ouvrez le volet Explorateur de données.
Sélectionnez un conteneur existant, développez l’onglet Paramètres et modifiez les valeurs suivantes :
- Sous Paramètres, recherchez Durée de vie.
- En fonction de vos besoins, vous pouvez :
  - Désactiver ce paramètre.
  - Lui affecter la valeur Activée (pas par défaut), ou
  - L’activer avec une valeur TTL exprimée en secondes.
- Sélectionnez Enregistrer pour enregistrer les modifications.

Quand DefaultTimeToLive est null, votre Durée de vie est Désactivée
Lorsque DefaultTimeToLive est -1, votre Durée de vie est Activée (pas par défaut)
Quand DefaultTimeToLive a une autre valeur Int (à l’exception de 0), alors votre Durée de vie est Activée. Le serveur supprime automatiquement les éléments en fonction de la valeur configurée.

Activer la durée de vie sur un conteneur avec l’interface Azure CLI ou Azure PowerShell

Pour créer ou activer la TTL sur un conteneur, consultez :

Activer la durée de vie sur un conteneur à l’aide d’un kit 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
)

Définir la durée de vie sur un conteneur à l’aide d’un kit SDK

Pour définir la durée de vie sur un conteneur, vous devez fournir un nombre positif non nul qui indique la durée en secondes. Selon la valeur de la TTL configurée, tous les éléments présents dans le conteneur sont supprimés après l’horodatage de la dernière modification de l’élément _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
)

Définir la durée de vie d'un élément à l'aide du portail

Non seulement vous pouvez définir une durée de vie par défaut sur un conteneur, mais vous pouvez aussi définir une durée de vie pour un élément. La définition de la durée de vie au niveau d’un élément remplace la valeur TTL par défaut de l’élément dans le conteneur donné.

Pour définir la TTL sur un élément, vous devez fournir un nombre positif non nul qui indique, en secondes, le délai d’expiration de l’élément après l’horodatage de la dernière modification de l’élément _ts. Vous pouvez également fournir un -1 lorsque l’élément ne doit pas expirer.
Si l’élément ne présente aucun champ TTL, la durée de vie définie par défaut dans le conteneur s’applique à l’élément.
Si la TTL est désactivée au niveau du conteneur, le champ TTL de l’élément est ignoré jusqu’à ce que la TTL soit de nouveau activée sur le conteneur.

Utilisez les étapes suivantes pour activer la durée de vie sur un élément :

Connectez-vous au portail Azure.
Créez un compte Azure Cosmos DB ou sélectionnez un compte existant.
Ouvrez le volet Explorateur de données.
Sélectionnez un conteneur existant, développez-le et modifiez les valeurs suivantes :
- Ouvrez la fenêtre Mise à l’échelle et paramètres.
- Sous Paramètres, recherchez Durée de vie.
- Sélectionnez Activée (pas par défaut) ou sélectionnez Activée et définissez une valeur de TTL.
- Sélectionnez Enregistrer pour enregistrer les modifications.

Accédez ensuite à l’élément pour lequel vous souhaitez définir une durée de vie, ajoutez la propriété ttl, puis sélectionnez Mettre à jour.

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

Définir la durée de vie d'un élément à l'aide d’un kit 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)

Réinitialisation de la durée de vie à l’aide d’un kit SDK

Vous pouvez réinitialiser la durée de vie sur un élément en effectuant une opération d’écriture ou de mise à jour sur celui-ci. L’opération d’écriture ou de mise à jour définit l’élément _ts sur l’heure actuelle, et la durée de vie déclenchant l’expiration de l’élément recommence son décompte. Si vous souhaitez modifier la durée de vie d’un élément, vous pouvez mettre à jour ce champ de la même manière que vous mettriez à jour n’importe quel autre champ.

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
)

Désactivation de la durée de vie à l’aide d’un kit SDK

Pour désactiver la durée de vie sur un conteneur et arrêter le processus en arrière-plan qui recherche les éléments ayant expiré, la propriété DefaultTimeToLive sur le conteneur doit être supprimée. Supprimer cette propriété ne revient pas à la définir sur -1. Lorsque vous la définissez sur -1, les nouveaux éléments ajoutés au conteneur continuent de vivre indéfiniment, mais vous pouvez remplacer cette valeur sur des éléments spécifiques du conteneur. Lorsque vous supprimez du conteneur la propriété de durée de vie, les éléments n’expirent jamais, même si la précédente valeur de durée de vie par défaut a été explicitement remplacée.

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
)

Étapes suivantes

Apprenez-en davantage sur la durée de vie dans l’article suivant :

Durée de vie