Настройка срока жизни в Azure Cosmos DB

2025-04-04

ОБЛАСТЬ ПРИМЕНЕНИЯ: NoSQL

В Azure Cosmos DB вы можете настроить срок жизни (TTL) на уровне контейнера или переопределить его на уровне элемента после настройки для контейнера. Срок жизни для контейнера можно настроить с помощью портала Azure или пакетов SDK для конкретных языков. Переопределение срока жизни на уровне элемента можно настроить с использованием пакетов SDK.

Содержимое этой статьи имеет отношение к сроку жизни записи в транзакционном хранилище Azure Cosmos DB. Если вы ищете функцию TTL для аналитического хранилища, позволяющую сценарии NoETL HTAP с использованием Azure Synapse Link, нажмите здесь.

Включение срока жизни для контейнера с помощью портала Azure

Следуйте нижеуказанным шагам, чтобы включить для контейнера время жизни без истечения срока. Включение TTL на уровне контейнера, чтобы можно было переопределить то же значение на уровне отдельного элемента. Вы также можете установить TTL, введя ненулевое значение в секундах.

Войдите на портал Azure.
Создайте новую учетную запись Azure Cosmos DB или выберите существующую учетную запись.
Откройте область Data Explorer.
Выберите существующий контейнер, на вкладке Настройки разверните его и измените следующие значения:
- В разделе Параметры найдите Срок жизни.
- В зависимости от своих требований можно:
  - отключить этот параметр;
  - установите для него значение Включен (без значения по умолчанию) или
  - Включить с указанным значением TTL в секундах.
- Выберите Сохранить, чтобы сохранить изменения.

Если параметр DefaultTimeToLive имеет значение null, значит, параметр срока жизни отключен.
Если параметр DefaultTimeToLive имеет значение –1, значит, параметр срока жизни включен (без значения по умолчанию).
Если параметр DefaultTimeToLive имеет любое другое целочисленное значение (кроме 0), значит, параметр срока жизни включен. Сервер будет автоматически удалять элементы на основе настроенного значения.

Включение срока жизни для контейнера с помощью Azure CLI или Azure PowerShell

Сведения о создании или включении срока жизни для контейнера см. в следующих статьях:

Включение срока жизни для контейнера с помощью пакета 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)

Настройка срока жизни для контейнера с помощью пакета SDK

Чтобы задать срок жизни в контейнере, необходимо ввести ненулевое положительное число, указывающее период времени в секундах. Исходя из настроенного значения срока жизни, все элементы в контейнере после последнего изменения метки времени элемента _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)

Настройка срока жизни элемента с помощью портала

Помимо установки времени жизни по умолчанию для контейнера, вы можете установить время жизни для элемента. Настройка срока жизни на уровне элемента переопределит значение срока жизни по умолчанию для элемента в этом контейнере.

Чтобы задать срок жизни для элемента, необходимо ввести ненулевое положительное число, которое будет означать время в секундах, по истечении которого с момента последнего изменения элемента (метка времени _ts) этот элемент будет считаться устаревшим. Вы также можете предоставить -1, если элемент не должен истекать.
Если у элемента нет поля срока жизни, то по умолчанию к элементу будет применяться срок жизни, заданный для контейнера.
Если TTL отключено на уровне контейнера, поле TTL в элементе будет игнорироваться до тех пор, пока TTL не будет повторно включено на контейнере.

Чтобы включить время жизни на элементе, выполните следующие действия:

Войдите на портал Azure.
Создайте новую учетную запись Azure Cosmos DB или выберите существующую учетную запись.
Откройте область Data Explorer.
Выберите существующий контейнер, разверните его и измените следующие значения:
- Откройте окно Scale & Settings (Параметры масштабирования).
- В разделе Параметры найдите Срок жизни.
- Выберите Включен (не по умолчанию) или Включен и задайте значение срока жизни.
- Выберите Сохранить, чтобы сохранить изменения.

Затем перейдите к элементу, для которого нужно установить срок жизни, добавьте свойство ttl и выберите Обновить.

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

Настройка срока жизни элемента с помощью пакета 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)

Сброс срока жизни с помощью пакета SDK

Вы можете сбросить срок жизни элемента, выполнив операцию записи или обновления для этого элемента. Операция записи или обновления установит для _ts текущий момент времени, и отсчет времени до истечения срока жизнеспособности элемента начнется заново. Если вы хотите изменить срок жизни элемента, это поле можно обновить так же, как любое другое.

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)

Отключение времени жизни с помощью SDK

Чтобы отключить срок жизни в контейнере и остановить фоновый процесс проверки на наличие просроченных элементов, нужно удалить свойство DefaultTimeToLive контейнера. Удаление этого свойства и выбор значения -1 имеют разный эффект. Если задано значение -1, срок действия новых элементов, добавляемых в контейнер, не будет истекать, однако это значение можно переопределить для определенных элементов в контейнере. При удалении свойства TTL из контейнера элементы никогда не истекают, даже если они явно переопределяют предыдущее значение TTL по умолчанию.

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)

Следующие шаги

Дополнительные сведения о сроке жизни см. в следующей статье:

Срок жизни