Konfigurieren der Gültigkeitsdauer in Azure Cosmos DB

Artikel
04/03/2023

GILT FÜR: NoSQL

In Azure Cosmos DB können Sie die Gültigkeitsdauer (Time to Live, TTL) auf der Containerebene konfigurieren oder auf der Elementebene außer Kraft setzen, nachdem Sie sie für den Container festgelegt haben. Die Gültigkeitsdauer für einen Container kann über das Azure-Portal oder mithilfe der sprachspezifischen SDKs konfiguriert werden. Die Außerkraftsetzung der Gültigkeitsdauer auf der Elementebene kann mithilfe der SDKs konfiguriert werden.

Dieser Inhalt des Artikels bezieht sich auf die Gültigkeitsdauer des Azure Cosmos DB-Transaktionsspeichers. Wenn Sie nach der Gültigkeitsdauer des Analysespeichers suchen, die NoETL-HTAP-Szenarien über Azure Synapse Link ermöglicht, klicken Sie hier.

Aktivieren der Gültigkeitsdauer für einen Container über das Azure-Portal

Gehen Sie wie folgt vor, um die Gültigkeitsdauer für einen Container ohne Ablauf zu aktivieren. Aktivieren von TTL auf Containerebene, damit derselbe Wert auf Ebene eines einzelnen Elements außer Kraft gesetzt werden kann. Sie können auch eine Gültigkeitsdauer festlegen, indem Sie einen Sekundenwert festlegen, der nicht Null ist.

Melden Sie sich beim Azure-Portal an.
Erstellen Sie ein neues Azure Cosmos DB-Konto, oder wählen Sie ein bereits vorhandenes Konto aus.
Öffnen Sie den Bereich Daten-Explorer.
Wählen Sie einen vorhandenen Container aus, erweitern Sie die Registerkarte-Einstellungen, und ändern Sie die folgenden Werte:
- Suchen Sie unter Einstellung nach Gültigkeitsdauer.
- Basierend auf Ihren Anforderungen können Sie:
  - Deaktivieren dieser Einstellung
  - Legen Sie ihn auf Ein (kein Standard) oder
  - Aktivieren Sie dies mit einem in Sekunden angegebenen TTL-Wert.
- Klicken Sie zum Speichern der Änderungen auf Speichern.

Wenn „DefaultTimeToLive“ auf „0“ festgelegt ist, ist die Gültigkeitsdauer deaktiviert
Wenn „DefaultTimeToLive“ auf „-1“ festgelegt ist, ist die Gültigkeitsdauer aktiviert (ohne Standardwert)
Wenn „DefaultTimeToLive“ auf einen beliebigen anderen Wert festgelegt ist (mit Ausnahme von „0“), ist die Gültigkeitsdauer aktiviert Der Server löscht Elemente automatisch basierend auf dem konfigurierten Wert.

Aktivieren der Gültigkeitsdauer für einen Container mithilfe der Azure CLI oder von Azure PowerShell

Informationen zum Erstellen oder Aktivieren der Gültigkeitsdauer für einen Container finden Sie in den Themen zum

Aktivieren der Gültigkeitsdauer für einen Container per 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
)

Festlegen der Gültigkeitsdauer für einen Container per SDK

Wenn Sie die Gültigkeitsdauer für einen Container festlegen möchten, müssen Sie eine positive Zahl ungleich Null angeben, die den Zeitraum in Sekunden angibt. Auf der Grundlage des konfigurierten Werts für die Gültigkeitsdauer werden alle Elemente im Container nach dem Zeitstempel (_ts) der letzten Änderung des Elements gelöscht.

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
)

Lebenszeit für einen Artikel über das Portal festlegen

Zusätzlich zu einer Standardgültigkeitsdauer für einen Container können Sie auch eine Gültigkeitsdauer für ein Element festlegen. Wenn Sie eine Gültigkeitsdauer auf der Elementebene festlegen, setzt diese die Standardgültigkeitsdauer des Elements in diesem Container außer Kraft.

Wenn Sie die Gültigkeitsdauer für ein Element festlegen möchten, müssen Sie mit einer positiven Zahl ungleich Null den Zeitraum angeben, nach dem das Element ablaufen soll, und zwar in Sekunden ab dem Zeitstempel (_ts) der letzten Änderung des Elements. Sie können auch -1 angeben, wenn das Element nicht ablaufen sollte.
Wenn das Element über kein Feld für die Gültigkeitsdauer verfügt, gilt automatisch die für den Container festgelegte Gültigkeitsdauer.
Wird die Gültigkeitsdauer auf der Containerebene deaktiviert, wird das elementspezifische Feld für die Gültigkeitsdauer ignoriert, bis die Gültigkeitsdauer für den Container wieder aktiviert wird.

Gehen Sie wie folgt vor, um die Gültigkeitsdauer für ein Element zu aktivieren:

Melden Sie sich beim Azure-Portal an.
Erstellen Sie ein neues Azure Cosmos DB-Konto, oder wählen Sie ein bereits vorhandenes Konto aus.
Öffnen Sie den Bereich Daten-Explorer.
Wählen Sie einen vorhandenen Container aus, erweitern Sie ihn, und ändern Sie die folgenden Werte:
- Öffnen Sie das Fenster Scale & Settings (Skalierung und Einstellungen).
- Suchen Sie unter Einstellung nach Gültigkeitsdauer.
- Wählen Sie Ein (Standard) oder Ein aus, und legen Sie einen Wert für die Gültigkeitsdauer fest.
- Klicken Sie zum Speichern der Änderungen auf Speichern.

Navigieren Sie anschließend zu dem Element, für das Sie die Gültigkeitsdauer festlegen möchten, fügen Sie die Eigenschaft ttl hinzu, und wählen Sie Aktualisieren aus.

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

Lebenszeit für einen Artikel über ein SDK festlegen

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)

Zurücksetzen der Lebensdauer mithilfe eines SDK

Sie können die Gültigkeitsdauer für ein Element zurücksetzen, indem Sie einen Schreib- oder Aktualisierungsvorgang für das Element ausführen. Der Schreib- oder Aktualisierungsvorgang legt den Zeitstempel (_ts) auf die aktuelle Zeit fest, und die Gültigkeitsdauer für den Ablauf des Elements beginnt von vorn. Wenn Sie die Gültigkeitsdauer eines Elements ändern möchten, können Sie das Feld genau wie jedes andere Feld aktualisieren.

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
)

Deaktivieren der Lebensdauer mithilfe eines SDK

Wenn Sie die Gültigkeitsdauer für einen Container deaktivieren und verhindern möchten, dass der Hintergrundprozess nach abgelaufenen Elementen sucht, muss die Eigenschaft DefaultTimeToLive für den Container gelöscht werden. Das Löschen dieser Eigenschaft ist nicht das Gleiche wie das Festlegen der Eigenschaft auf „-1“. Wenn Sie die Eigenschaft auf „-1“ festlegen, laufen neue Elemente, die dem Container hinzugefügt werden, nicht ab, und der Wert kann für bestimmte Elemente im Container außer Kraft gesetzt werden. Wenn Sie die Eigenschaft für die Gültigkeitsdauer aus dem Container entfernen, laufen die Elemente auch dann nicht ab, wenn Sie den vorherigen Standardwert für die Gültigkeitsdauer explizit außer Kraft gesetzt haben.

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
)

Nächste Schritte

Weitere Informationen zur Gültigkeitsdauer finden Sie im folgenden Artikel:

Gültigkeitsdauer