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

Применяется к: ✅ NoSQL

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

Включение TTL в контейнере с помощью портала Azure

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

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

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

Включение TTL в контейнере с помощью Azure CLI или Azure PowerShell

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

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

Настройка TTL в контейнере с помощью пакета SDK

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

Настройка TTL для элемента с помощью портала Azure

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

Чтобы задать TTL для элемента, необходимо указать ненулевое положительное число, которое определяет период в секундах, по истечении которого срок действия элемента заканчивается после времени последнего изменения _ts. Вы также можете предоставить -1, если элемент не должен истекать.
Если у элемента нет поля TTL, то по умолчанию значение TTL, заданное контейнером, применяется к элементу.
Если TTL отключен на уровне контейнера, поле 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
}

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

Сброс TTL с помощью SDK

Вы можете сбросить параметр TTL для элемента, выполнив операцию записи или обновления этого элемента. Операция записи или обновления задает _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)

Отключение TTL с помощью пакета SDK

Чтобы отключить TTL в контейнере и остановить фоновый процесс проверки просроченных элементов, 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)

Срок жизни в Azure Cosmos DB

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-04-27