Konfigurowanie czasu wygaśnięcia w usłudze Azure Cosmos DB

2025-07-08

DOTYCZY: NoSQL

W usłudze Azure Cosmos DB możesz skonfigurować czas wygaśnięcia (Time to Live, TTL) na poziomie kontenera lub zastąpić go na poziomie elementu po ustawieniu TTL dla kontenera. TTL można skonfigurować dla kontenera przy użyciu witryny Azure Portal lub zestawu SDK właściwego dla używanego języka. Zastępowanie TTL na poziomie elementu można skonfigurować za pomocą pakietów SDK.

Zawartość tego artykułu jest powiązana z czasem życia danych w sklepie transakcyjnym usługi Azure Cosmos DB. Jeśli szukasz magazynu analitycznego TTL, który umożliwia scenariusze NoETL HTAP za pośrednictwem Azure Synapse Link, kliknij tutaj.

Włącz czas działania (TTL) kontenera za pomocą portalu Microsoft Azure

Wykonaj następujące czynności, aby włączyć czas życia dla kontenera bez ustalonego terminu wygaśnięcia. Włączenie czasu życia (TTL) na poziomie kontenera w celu umożliwienia zastąpienia tej wartości na poziomie pojedynczego elementu. Możesz także ustawić TTL, wprowadzając niezerową liczbę sekund.

Zaloguj się w witrynie Azure Portal.
Utwórz nowe konto usługi Azure Cosmos DB lub wybierz istniejące konto.
Otwórz okienko Eksplorator danych.
Wybierz istniejący kontener, rozwiń kartę Ustawienia i zmodyfikuj następujące wartości:
- W obszarze Ustawienia znajdź pozycję Czas wygaśnięcia.
- W zależności od wymagań możesz wykonywać następujące czynności:
  - Wyłącz to ustawienie
  - Ustaw wartość Włączone (bez wartości domyślnej) lub
  - Włącz z określoną wartością TTL w sekundach.
- Wybierz Zapisz, aby zapisać zmiany.

Jeśli DefaultTimeToLive jest ustawione na null, to Czas Życia jest wyłączony.
Gdy wartość DefaultTimeToLive wynosi -1, ustawienie Czas wygaśnięcia ma wartość Włączone (wartość domyślna)
Jeśli DefaultTimeToLive ma dowolną inną wartość całkowitą (z wyjątkiem 0), wtedy ustawienie Czas wygaśnięcia jest włączone. Serwer automatycznie usunie elementy na podstawie skonfigurowanej wartości.

Włączanie czasu wygaśnięcia w kontenerze przy użyciu interfejsu wiersza polecenia platformy Azure lub programu Azure PowerShell

Aby utworzyć lub włączyć TTL w kontenerze, zobacz:

Włączanie czasu wygaśnięcia w kontenerze przy użyciu zestawu 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)

Ustawianie czasu wygaśnięcia w kontenerze przy użyciu zestawu SDK

Aby ustawić czas wygaśnięcia dla kontenera, należy podać niezerową liczbę dodatnią, określającą czas w sekundach. Na podstawie skonfigurowanej wartości TTL wszystkie elementy w kontenerze zostaną usunięte po upływie wskazanego czasu od wartości znacznika czasu ostatniej modyfikacji _ts.

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)

Ustawianie czasu wygaśnięcia elementu przy użyciu portalu

Oprócz skonfigurowania domyślnego czasu wygaśnięcia dla kontenera możesz ustawić czas wygaśnięcia konkretnego elementu. Ustawienie czasu wygaśnięcia na poziomie elementu spowoduje zastąpienie domyślnego czasu wygaśnięcia elementu w kontenerze.

Aby ustawić czas wygaśnięcia elementu, podaj niezerową liczbę dodatnią oznaczającą czas w sekundach — element zostanie usunięty po upływie tego czasu od wartości znacznika czasu ostatniej modyfikacji _ts. Możesz również podać element -1 , gdy element nie powinien wygasać.
Jeśli element nie ma pola TTL, będzie obowiązywał domyślny czas wygaśnięcia ustawiony dla kontenera.
Jeśli TTL zostanie wyłączony na poziomie kontenera, pole TTL elementu będzie ignorowane do momentu włączenia TTL ponownie dla kontenera.

Aby włączyć czas wygaśnięcia elementu, wykonaj następujące kroki:

Zaloguj się w witrynie Azure Portal.
Utwórz nowe konto usługi Azure Cosmos DB lub wybierz istniejące konto.
Otwórz okienko Eksplorator danych.
Wybierz istniejący kontener, rozwiń go, a następnie zmodyfikuj następujące wartości:
- Otwórz okno Skalowanie i ustawienia.
- W obszarze Ustawienia znajdź pozycję Czas wygaśnięcia.
- Wybierz Włączone (bez wartości domyślnej) lub Włączone i ustaw wartość TTL.
- Wybierz Zapisz, aby zapisać zmiany.

Następnie przejdź do elementu, dla którego chcesz ustawić czas wygaśnięcia, dodaj ttl właściwość i wybierz pozycję Aktualizuj.

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

Ustaw czas życia elementu przy użyciu 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)

Resetowanie czasu życia przy użyciu zestawu SDK

Możesz zresetować czas życia elementu, wykonując operację zapisu lub aktualizacji na nim. Operacja zapisu lub aktualizacji spowoduje ustawienie znacznika czasu _ts na bieżący czas, a czas życia (TTL) dla wygaśnięcia elementu rozpocznie się od nowa. Jeśli chcesz zmienić czas wygaśnięcia elementu, możesz zaktualizować pole TTL tak samo jak każde inne pole.

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)

Wyłącz czas życia przy użyciu SDK

Aby wyłączyć czas wygaśnięcia dla kontenera i zatrzymać proces w tle sprawdzający, czy elementy wygasły, należy usunąć właściwość DefaultTimeToLive z kontenera. Usunięcie tej właściwości ma inne skutki niż ustawienie jej na –1. Jeśli ustawisz to na –1, nowe elementy dodawane do kontenera będą trwały wiecznie, jednak możesz nadpisać tę wartość dla konkretnych elementów w kontenerze. Usunięcie właściwości TTL z kontenera spowoduje, że elementy nigdy nie wygasną, nawet jeśli jawnie zastąpią poprzednią domyślną wartość czasu wygaśnięcia.

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)

Następne kroki

Aby dowiedzieć się więcej na temat czasu do życia, przeczytaj poniższy artykuł:

Czas wygaśnięcia