Konfigurera Time to Live i Azure Cosmos DB

GÄLLER FÖR: NoSQL

Du kan välja att konfigurera Time to Live (TTL) på containernivån i Azure Cosmos DB, eller så kan du åsidosätta det på en objektnivå när du har ställt in containern. Du kan konfigurera TTL för en container med hjälp av Azure-portalen eller språkspecifika SDK:er. Åsidosättningar av TTL på objektnivå kan konfigureras med hjälp av SDK:erna.

Den här artikelns innehåll är relaterat till TTL för Azure Cosmos DB-transaktionslager. Om du letar efter analitycal store TTL, som aktiverar NoETL HTAP-scenarier via Azure Synapse Link, klickar du här.

Aktivera time to live på en container med hjälp av Azure-portalen

Använd följande steg för att aktivera TTL för en container utan upphörande. Aktivera TTL på containernivå för att tillåta att samma värde åsidosättas på en enskild objektnivå. Du kan också ange TTL genom att ange ett annat värde än noll för sekunder.

1. Logga in på Azure-portalen.

2. Skapa ett nytt Azure Cosmos DB-konto eller välj ett befintligt konto.

3. Öppna fönstret Datautforskaren.

4. Välj en befintlig container, expandera fliken Inställningar och ändra följande värden:

   • Under Inställning letar du upp Time to Live.

   • Baserat på dina behov kan du:

     • Inaktivera den här inställningen
     • Ställ in den på På (inget standardvärde) eller
     • Aktivera med ett TTL-värde som anges i sekunder.

   • Välj Spara för att spara ändringarna.

   

• När DefaultTimeToLive är null är time to live av
• När DefaultTimeToLive är -1 är inställningen Time to Live på (inget standardvärde)
• När DefaultTimeToLive har något annat Int-värde (förutom 0) är time to live-inställningen På. Servern tar automatiskt bort objekt baserat på det konfigurerade värdet.

Aktivera time to live på en container med Hjälp av Azure CLI eller Azure PowerShell

Information om hur du skapar eller aktiverar TTL på en container finns i

• Skapa en container med TTL med Azure CLI
• Skapa en container med TTL med Hjälp av PowerShell

Aktivera time to live på en container med hjälp av ett 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
)

Ange tid för att leva på en container med hjälp av ett SDK

Om du vill ställa in Time to Live för en container måste du ange ett positivt tal som inte är noll som anger tidsperioden i sekunder. Baserat på det konfigurerade TTL-värde tas alla objekt i containern efter den senast ändrade tidsstämpeln för objektet _ts bort.

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

Ange tid för att leva på ett objekt med hjälp av portalen

Förutom att ställa in ett standard-TTL-värde i en container kan du ange du en tid för ett objekt. När du ställer in Time to Live på objektnivå åsidosätts standard-TTL för det objektet i containern.

• Om du vill ställa in TTL-värdet för ett objekt måste du ange ett positivt tal som inte är noll, vilket anger inom vilken period i sekunder som objektet ska upphöra att gälla efter den senast ändrade tidsstämpeln för objektet _ts. Du kan även ange ett -1 när objektet inte ska upphöra att gälla.

• Om objektet inte har något TTL-fält tillämpas som standard TTL-värdet som angetts för containern på objektet.

• Om TTL är inaktiverat på containernivå ignoreras TTL-fältet på objektet tills TTL återaktiverats för containern.

Använd följande steg för att aktivera tid för att leva på ett objekt:

1. Logga in på Azure-portalen.

2. Skapa ett nytt Azure Cosmos DB-konto eller välj ett befintligt konto.

3. Öppna fönstret Datautforskaren.

4. Välj en befintlig container, expandera den och ändra följande värden:

   • Öppna fönstret Scale & Settings (Skalning och inställningar).
   • Under Inställning letar du upp Time to Live.
   • Välj På (inget standardvärde) eller välj På och ange ett TTL-värde.
   • Välj Spara för att spara ändringarna.

5. Gå sedan till det objekt som du vill ange tid för att leva för, lägg till ttl egenskapen och välj Uppdatera.

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

Ange tid för att leva på ett objekt med hjälp av ett 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)

Återställ tid till live med hjälp av en SDK

Du kan återställa time to live på ett objekt genom att utföra en skriv- eller uppdateringsåtgärd för objektet. Skriv- eller uppdateringsåtgärden ställer in _ts på den aktuella tiden och TTL-värdet för objektet som ska upphöra att gälla påbörjas igen. Om du vill ändra TTL-värdet för ett objekt kan du uppdatera fältet precis som du uppdaterar andra fält.

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

Inaktivera time to live med hjälp av en SDK

Om du vill inaktivera Time to Live för en container och förhindra att bakgrundsprocessen söker efter objekt som har upphört att gälla ska du ta bort egenskapen DefaultTimeToLive för containern. Att ta bort den här egenskapen skiljer sig från att ställa in den på -1. När du ställer in den på -1 finns nya objekt som läggs till i containern kvar för evigt, men du kan åsidosätta det här värdet för specifika objekt i containern. När du tar bort TTL-egenskapen från containern upphör objekten aldrig att gälla, även om de uttryckligen har åsidosatt det tidigare standard-TTL-värdet.

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

Nästa steg

Läs mer om Time to Live i följande artikel:

• Time to live