Configurare la durata (TTL) in Azure Cosmos DB

SI APPLICA A: NoSQL

In Azure Cosmos DB è possibile scegliere di configurare la durata (TTL) a livello di contenitore oppure è possibile eseguirne l'override a livello di elemento dopo l'impostazione per il contenitore. È possibile configurare la durata (TTL) per un contenitore usando il portale di Azure o gli SDK specifici del linguaggio. Gli override della durata (TTL) a livello di elemento possono essere configurati usando gli SDK.

Il contenuto del presente articolo è correlato al TTL dell'archivio transazionale di Azure Cosmos DB. Se si sta cercando la durata (TTL) dell'archivio analitico che abilita gli scenari NoETL HTAP tramite Azure Collegamento a Synapse, fare clic qui.

Abilitare la durata (TTL) in un contenitore usando il portale di Azure

Usare la procedura seguente per abilitare la durata (TTL) in un contenitore senza scadenza. Abilitazione della durata (TTL) a livello di contenitore per consentire l'override dello stesso valore a livello di singolo elemento. È anche possibile impostare la durata (TTL) immettendo un valore diverso da zero per i secondi.

1. Accedere al portale di Azure.

2. Creare un nuovo account Azure Cosmos DB o selezionarne uno esistente.

3. Aprire il riquadro Esplora dati.

4. Selezionare un contenitore esistente, espandere la scheda Impostazioni e modificare i valori seguenti:

   • In Impostazione trovare Durata (TTL).

   • In base alle esigenze, è possibile:

     • Disattivare questa impostazione
     • Impostare l'opzione su Sì (nessun valore predefinito) oppure
     • Attivare l'opzione con un valore TTL specificato in secondi.

   • Seleziona Salva per salvare le modifiche.

   

• Quando DefaultTimeToLive è Null, la durata TTL è disattivata
• Quando DefaultTimeToLive è -1, l'impostazione della durata TTL è attivata (nessun valore predefinito)
• Quando DefaultTimeToLive include qualsiasi altro valore Int, ad eccezione di 0, l'impostazione della durata TTL è attivata. Il server eliminerà automaticamente gli elementi sulla base del valore configurato.

Abilitare la durata (TTL) in un contenitore usando l'interfaccia della riga di comando di Azure o Azure PowerShell

Per creare o abilitare la durata (TTL) in un contenitore, consultare:

• Creare un contenitore con durata (TTL) tramite l'interfaccia della riga di comando di Azure
• Creare un contenitore con durata (TTL) tramite PowerShell

Abilitare la durata (TTL) in un contenitore usando un SDK

.NET SDK v3

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);

Java SDK v4

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);

Node SDK

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);

Python SDK

database = client.get_database_client('database')

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

Impostare la durata (TTL) in un contenitore usando un SDK

Per impostare la durata (TTL) in un contenitore, è necessario specificare un numero positivo diverso da zero che indica il periodo di tempo in secondi. In base al valore TTL configurato, tutti gli elementi nel contenitore dopo l'ultima modifica del timestamp dell'elemento _ts vengono eliminati.

.NET SDK v3

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);

Java SDK v4

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);

Node SDK

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);

Python SDK

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
)

Impostare la durata (TTL) per un elemento usando il portale

Oltre a impostare una durata (TTL) predefinita per un contenitore, è possibile impostare una durata (TTL) per un elemento. L'impostazione della durata (TTL) a livello di elemento eseguirà l'override della durata (TTL) predefinita dell'elemento in tale contenitore.

• Per impostare la durata (TTL) in un elemento, è necessario specificare un numero positivo diverso da zero che indica il periodo di tempo, espresso in secondi, per la scadenza dell'elemento dopo l'ultima modifica del timestamp dell'elemento _ts. È possibile fornire anche un -1 quando l'elemento non deve scadere.

• Se l'elemento non ha un campo TTL, per impostazione predefinita all'elemento verrà applicata la durata (TTL) impostata per il contenitore.

• Se la durata (TTL) è disabilitata a livello di contenitore, il campo TTL dell'elemento viene ignorato finché la durata (TTL) non viene abilitata nuovamente per il contenitore.

Usare la procedura seguente per abilitare la durata (TTL) in un elemento:

1. Accedere al portale di Azure.

2. Creare un nuovo account Azure Cosmos DB o selezionarne uno esistente.

3. Aprire il riquadro Esplora dati.

4. Selezionare un contenitore esistente, espanderlo e modificare i valori seguenti:

   • Aprire la finestra Scalabilità e impostazioni.
   • In Impostazione trovare Durata (TTL).
   • Selezionare Sì (nessun valore predefinito) oppure selezionare Sì e impostare un valore TTL.
   • Seleziona Salva per salvare le modifiche.

5. Passare quindi all'elemento per cui si desidera impostare la durata, aggiungere la proprietà ttl e selezionare Aggiorna.

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

Impostare la durata (TTL) di un elemento usando un SDK

.NET SDK v3

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);

Java SDK v4

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);

Node SDK

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);

Python SDK

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)

Reimpostare la durata (TTL) usando un SDK

È possibile reimpostare la durata (TTL) per un elemento eseguendo un'operazione di scrittura o aggiornamento per l'elemento. L'operazione di scrittura o aggiornamento imposterà _ts sull'ora corrente e la durata (TTL) per la scadenza dell'elemento inizierà nuovamente. Se si vuole modificare la durata (TTL) di un elemento, è possibile aggiornare il campo nello stesso modo in cui si aggiornano tutti gli altri campi.

.NET SDK v3

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")    
);

Java SDK v4

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
);

Node SDK

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);

Python SDK

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
)

Disabilitare la durata (TTL) usando un SDK

Per disabilitare la durata (TTL) in un contenitore e impedire al processo in background di controllare gli elementi scaduti, è necessario eliminare la proprietà DefaultTimeToLive per il contenitore. Eliminare questa proprietà non equivale a impostarla su -1. Quando si imposta il valore su -1, i nuovi elementi aggiunti al contenitore non hanno scadenza, tuttavia è possibile eseguire l'override di questo valore per elementi specifici nel contenitore. Quando si rimuove la proprietà TTL dal contenitore, gli elementi non avranno mai scadenza anche se sono presenti elementi con override esplicito di un valore TTL predefinito precedente.

.NET SDK v3

ContainerProperties properties = await container.ReadContainerAsync();

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

await container.ReplaceContainerAsync(properties);

Java SDK v4

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

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

container.replace(properties);

Node SDK

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

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

await container.replace(definition);

Python SDK

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

Passaggi successivi

Altre informazioni sulla durata (TTL) nell'articolo seguente:

• Durata (TTL)