Configuración del período de vida en Azure Cosmos DB

SE APLICA A: NoSQL

En Azure Cosmos DB, puede elegir configurar el período de vida (TTL) en el nivel de contenedor, o puede invalidarlo en un nivel de elemento después de configurarlo para el contenedor. Puede configurar el período de vida de un contenedor mediante Azure Portal o los SDK específicos del lenguaje. Las invalidaciones del período de vida en el nivel de elemento se pueden configurar mediante los SDK.

El contenido de este artículo está relacionado con el TTL del almacén transaccional de Azure Cosmos DB. Si está buscando el TTL del almacén de análisis, que habilita escenarios de NoETL HTAP mediante Azure Synapse Link, haga clic aquí.

Habilitación del período de vida en un contenedor mediante Azure Portal

Siga estos pasos para habilitar el período de vida de un contenedor para que no expire. Habilite el TTL en el nivel de contenedor para permitir que se reemplace el mismo valor en el nivel de un elemento individual. También puede establecer el período de vida especificando un valor distinto a cero segundos.

1. Inicie sesión en Azure Portal.

2. Cree una nueva cuenta de Azure Cosmos DB o seleccione una existente.

3. Abra el panel Explorador de datos.

4. Seleccione un contenedor existente, expanda la pestaña de Configuración y modifique los valores siguientes:

   • En Configuración busque, Período de vida.

   • En función de sus requisitos, puede:

     • Desactivar este valor
     • Establecerlo en On (sin valor predeterminado) o
     • Activar con un valor TTL especificado en segundos.

   • Seleccione Guardar para guardar los cambios.

   

• Si DefaultTimeToLive es NULL, el Período de vida está Desactivado
• Si DefaultTimeToLive es -1, el valor del Período de vida es Activado (no de manera predeterminada)
• Si DefaultTimeToLive tiene cualquier otro valor Int (excepto 0) el de Período de vida es Activado. El servidor eliminará automáticamente los elementos en función del valor configurado.

Habilitación del período de vida en un contenedor mediante la CLI de Azure o Azure PowerShell

Para crear o habilitar TTL en un contenedor, consulte

• Creación de un contenedor con TTL mediante la CLI de Azure
• Creación de un contenedor con TTL mediante PowerShell

Habilitación del período de vida en un contenedor mediante 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);

SDK de Java 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);

SDK de Node

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

SDK de Python

database = client.get_database_client('database')

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

Establecimiento del período de vida en un contenedor mediante un SDK

Para establecer el período de vida en un contenedor, deberá proporcionar un número positivo distinto de cero que indique el período de tiempo en segundos. En función del valor del período de vida configurado, se eliminarán todos los elementos del contenedor posteriores a la última marca de tiempo modificada del elemento _ts.

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

SDK de Java 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);

SDK de Node

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

SDK de Python

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
)

Establecimiento del período de vida en un elemento mediante el portal

Además de establecer un período de vida predeterminado en un contenedor, también puede establecerlo para un elemento. Si establece el período de vida en el nivel de elemento, se reemplazará el período de vida predeterminado del elemento en ese contenedor.

• Para establecer el período de vida en un elemento, debe proporcionar un número positivo distinto de cero que indica el período, en segundos, para hacer que expire el elemento después de la marca de tiempo de última modificación del elemento (_ts). También puede proporcionar -1 cuando el elemento no deba expirar.

• Si el elemento no tiene un campo para el período de vida, se aplicará de forma predeterminada al elemento el valor del período de vida establecido en el contenedor.

• Si el TTL se deshabilita en el nivel de contenedor, se omitirá el campo TTL en el elemento hasta que se vuelva a habilitar el TTL en el contenedor.

Use estos pasos para habilitar el período de vida en un elemento:

1. Inicie sesión en Azure Portal.

2. Cree una nueva cuenta de Azure Cosmos DB o seleccione una existente.

3. Abra el panel Explorador de datos.

4. Seleccione un contenedor existente, expándalo y modifique los valores siguientes:

   • Abra la ventana Escala y configuración.
   • En Configuración busque, Período de vida.
   • Seleccione Activado (valor no predeterminado) o seleccione Activado y establezca un valor para el período de vida.
   • Seleccione Guardar para guardar los cambios.

5. A continuación, vaya al elemento para el que quiere establecer el período de vida, agregue la propiedad ttl y seleccione Actualizar.

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

Establecimiento del período de vida en un elemento mediante 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);

SDK de Java 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);

SDK de Node

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

SDK de Python

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)

Restablecimiento del período de vida mediante un SDK

Puede restablecer el período de vida en un elemento mediante la realización de una operación de escritura o actualización en él. La operación de escritura o actualización establecerá _ts en la hora actual, y el período de vida para el elemento que va a expirar comenzará de nuevo. Si desea cambiar el período de vida de un elemento, puede actualizar el campo al igual que actualizaría cualquier otro campo.

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

SDK de Java 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
);

SDK de Node

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

SDK de Python

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
)

Deshabilitación del período de vida mediante un SDK

Para deshabilitar el período de vida en un contenedor e impedir que el proceso en segundo plano compruebe los elementos expirados, se debe eliminar la propiedad DefaultTimeToLive del contenedor. Eliminar esta propiedad es diferente de establecerla en -1. Si la establece en -1, los nuevos elementos que se agreguen al contenedor no expirarán nunca. No obstante, puede invalidar este valor en elementos específicos del contenedor. Si elimina la propiedad TTL del contenedor los elementos no expirarán nunca, incluso si se ha reemplazado explícitamente el valor predeterminado anterior del TTL.

.NET SDK v3

ContainerProperties properties = await container.ReadContainerAsync();

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

await container.ReplaceContainerAsync(properties);

SDK de Java v4

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

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

container.replace(properties);

SDK de Node

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

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

await container.replace(definition);

SDK de Python

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

Pasos siguientes

Obtenga más información sobre el período de vida en el siguiente artículo:

• Período de vida