Configurar a vida útil no Azure Cosmos DB

Aplica-se a: ✅ NoSQL

No Azure Cosmos DB, você pode optar por configurar o TTL (tempo de vida útil) no nível do contêiner ou substituí-lo em um nível de item depois de definir TTL para o contêiner. Você pode configurar o TTL para um contêiner usando o portal do Azure ou os SDKs específicos do idioma. As substituições de TTL no nível do item podem ser configuradas usando os SDKs.

Habilitar o TTL em um contêiner usando o portal do Azure

Use as etapas a seguir para habilitar o TTL em um contêiner sem expiração. Habilitar o TTL no nível do contêiner permite que o mesmo valor seja substituído no nível de um item individual. Você também pode definir o TTL inserindo um valor diferente de zero por segundos.

Entre no portal do Azure.
Crie uma conta do Azure Cosmos DB ou selecione uma conta existente.
Abra o painel Data Explorer.
Selecione um contêiner existente, expanda a guia Configurações e modifique os seguintes valores:
1. Em Configurações, localize Tempo de Vida.
2. Com base no requisito, você pode:
- Desative essa configuração.
- Defina-o como Ativado (sem padrão).
- Ligue com um valor TTL especificado em segundos.
1. Selecione Salvar para salvar as alterações.

Quando DefaultTimeToLive for nulo, o TTL estará Desativado.
Quando DefaultTimeToLive é -1, sua configuração de TTL estará Ativada (não padrão).
Quando DefaultTimeToLive tiver qualquer outro valor inteiro (exceto 0), a configuração de TTL será Ativada. O servidor exclui automaticamente itens com base no valor configurado.

Habilitar TTL em um contêiner usando a CLI do Azure ou o Azure PowerShell

Para criar ou habilitar o TTL em um contêiner, consulte:

Habilitar o TTL em um contêiner usando um 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
)

db, _ := c.NewDatabase("demo_db")

pkDefinition := azcosmos.PartitionKeyDefinition{
	Paths: []string{"/state"},
	Kind:  azcosmos.PartitionKeyKindHash,
}

// Never expire by default
ttl := int32(-1)

db.CreateContainer(context.Background(), azcosmos.ContainerProperties{
	ID:                     "demo_container",
	PartitionKeyDefinition: pkDefinition,
	DefaultTimeToLive:      &ttl,
}, nil)

Definir TTL em um contêiner usando um SDK

Para definir o TTL em um contêiner, você precisa fornecer um número positivo diferente de zero que indique o período de tempo em segundos. Com base no valor de TTL configurado, todos os itens no contêiner após a última modificação do carimbo de hora do item _ts serão excluídos.

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
)

db, _ := c.NewDatabase("demo_db")

// Expire all documents after 90 days
ttl := int32(90 * 24 * 60 * 60)

db.CreateContainer(context.Background(), azcosmos.ContainerProperties{
	ID:                     containerName,
	PartitionKeyDefinition: pkDefinition,
	DefaultTimeToLive:      &ttl,
}, nil)

Definir TTL em um item usando o portal do Azure

Além de definir um TTL padrão em um contêiner, você pode definir um TTL para um item. A configuração de TTL no nível do item substitui o TTL padrão do item nesse contêiner.

Para definir o TTL em um item, você precisa fornecer um número positivo diferente de zero, que indica o período, em segundos, para expirar o item após o último carimbo de data/hora modificado do item _ts. Você também pode fornecer um -1 quando o item não deve expirar.
Se o item não tiver um campo TTL, por padrão, o TTL definido para o contêiner se aplicará ao item.
Se o TTL estiver desabilitado no nível do contêiner, o campo TTL no item será ignorado até que o TTL seja habilitado novamente no contêiner.

Use as seguintes etapas para habilitar o TTL em um item:

Entre no portal do Azure.
Crie uma conta do Azure Cosmos DB ou selecione uma conta existente.
Abra o painel Data Explorer.
Selecione um contêiner existente, expanda-o e modifique os seguintes valores:
- Abra a janela Escala e Configurações.
- Em Configuração, localize Time to Live (TTL).
- Selecione Ativado (não há padrão) ou selecione Ativado e defina um valor de vida útil.
- Selecione Salvar para salvar as alterações.

Navegue até o item para o qual você deseja definir o tempo de vida útil, adicione a ttl propriedade e selecione Atualizar.

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

Definir TTL em um item usando um 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)

custInfo := map[string]any{
	"id":    "SO05",
	"customerId": "CO18009186470",
	// Expire sales order in 30 days using "ttl" property
	"ttl": int32(60 * 60 * 24 * 30),
}

container, _ := db.NewContainer(containerName)

item, err := json.Marshal(custInfo)
container.CreateItem(context.Background(), azcosmos.NewPartitionKeyString("CO18009186470"), item, nil)

Redefinir TTL usando um SDK

Você pode redefinir o TTL em um item executando uma operação de gravação ou atualização no item. A operação de gravação ou atualização define o _ts como a hora atual, e a TTL até que o item expire ser iniciada novamente. Se você quiser alterar a TTL de um item, poderá atualizar o campo exatamente como atualizaria qualquer outro campo.

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
)

// Read the item
resp, _ := container.ReadItem(context.Background(), azcosmos.NewPartitionKeyString("CO18009186470"), "SO05", nil)

var order map[string]any
json.Unmarshal(resp.Value, &order)

// Update ttl to 2 hours
order["ttl"] = int32(120 * 60)
updatedOrder, err = json.Marshal(order)

container.ReplaceItem(context.Background(), azcosmos.NewPartitionKeyString("CO18009186470"), "SO05", updatedOrder, nil)

Desabilitar o TTL usando um SDK

Para desabilitar a TTL em um contêiner e impedir que o processo em segundo plano verifique se há itens expirados, a DefaultTimeToLive propriedade no contêiner deve ser excluída. Excluir essa propriedade é diferente de defini-la como -1. Quando você o define como -1, novos itens adicionados ao contêiner vivem para sempre, no entanto, você pode substituir esse valor em itens específicos no contêiner. Quando você remove a propriedade TTL do contêiner, os itens nunca expiram, mesmo que eles substituam explicitamente o valor TTL padrão anterior.

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
)

containerInfo, _ := container.Read(context.Background(), nil)
props := containerInfo.ContainerProperties

// Disable ttl at container-level
props.DefaultTimeToLive = nil
container.Replace(context.Background(), *props, nil)

Vida útil no Azure Cosmos DB

Comentários

Esta página foi útil?

Last updated on 2025-12-19