Condividi tramite


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.

    Configurare la durata (TTL) nel portale di Azure

  • 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:

Abilitare la durata (TTL) in un contenitore usando un 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);

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.

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

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

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

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.

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

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.

ContainerProperties properties = await container.ReadContainerAsync();

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

await container.ReplaceContainerAsync(properties);

Passaggi successivi

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