Azure Cosmos DB'de yaşam süresini yapılandırma

Makale
01/10/2024

UYGULANANLAR: NoSQL

Azure Cosmos DB'de Yaşam Süresi'ni (TTL) kapsayıcı düzeyinde yapılandırmayı seçebilir veya kapsayıcıyı ayarladıktan sonra öğe düzeyinde geçersiz kılabilirsiniz. Azure portalı veya dile özgü SDK'ları kullanarak kapsayıcı için TTL'yi yapılandırabilirsiniz. Öğe düzeyinde TTL geçersiz kılmaları SDK'lar kullanılarak yapılandırılabilir.

Bu makalenin içeriği Azure Cosmos DB işlem deposu TTL ile ilgilidir. Azure Synapse Link aracılığıyla NoETL HTAP senaryolarını etkinleştiren analitycal store TTL'yi arıyorsanız lütfen buraya tıklayın.

Azure portalını kullanarak kapsayıcıda yaşam süresini etkinleştirme

Süre sonu olmayan bir kapsayıcıda yaşama süresini etkinleştirmek için aşağıdaki adımları kullanın. Aynı değerin tek bir öğenin düzeyinde geçersiz kılınmasına izin vermek için kapsayıcı düzeyinde TTL'yi etkinleştirme. Saniyeler için sıfır olmayan bir değer girerek TTL'yi de ayarlayabilirsiniz.

Azure Portal oturum açın.
Yeni bir Azure Cosmos DB hesabı oluşturun veya mevcut bir hesabı seçin.
Veri Gezgini bölmesini açın.
Var olan bir kapsayıcıyı seçin, Ayarlar sekmesini genişletin ve aşağıdaki değerleri değiştirin:
- Bul ayarının altında Yaşam Süresi...
- Gereksinimlerinize bağlı olarak şunları yapabilirsiniz:
  - Bu ayarı kapat
  - Açık olarak ayarlayın (varsayılan ayar yok) veya
  - Saniye cinsinden belirtilen bir TTL değeriyle Aç'a tıklayın.
- Değişiklikleri kaydetmek için Kaydet'i seçin.

DefaultTimeToLive null olduğunda Yaşam Süreniz Kapalı olur
DefaultTimeToLive -1 olduğunda Yaşam Süresi ayarınız Açık olur (Varsayılan değil)
DefaultTimeToLive başka bir Int değerine sahip olduğunda (0 hariç), Yaşam Süresi ayarınız Açık olur. Sunucu, yapılandırılan değere göre öğeleri otomatik olarak siler.

Azure CLI veya Azure PowerShell kullanarak kapsayıcıda yaşam süresini etkinleştirme

Kapsayıcıda TTL oluşturmak veya etkinleştirmek için bkz.

SDK kullanarak kapsayıcıda yaşam süresini etkinleştirme

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
)

SDK kullanarak kapsayıcıda yaşam süresini ayarlama

Bir kapsayıcıda yaşam süresini ayarlamak için, saniye cinsinden süreyi gösteren sıfır olmayan pozitif bir sayı sağlamanız gerekir. Yapılandırılan TTL değerine bağlı olarak, öğenin _ts son değiştirilen zaman damgasından sonra kapsayıcıdaki tüm öğeler silinir.

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
)

Portalı kullanarak bir öğede yaşam süresini ayarlama

Bir kapsayıcıda yaşamak için varsayılan bir süre ayarlamaya ek olarak, bir öğe için yaşam süresi ayarlayabilirsiniz. Öğe düzeyinde yaşam süresi ayarlandığında, bu kapsayıcıdaki öğenin varsayılan TTL değeri geçersiz kılınır.

Bir öğede TTL'yi ayarlamak için, öğenin son değiştirilen zaman damgasından _tssonra öğenin süresinin dolmasına ilişkin süreyi saniye cinsinden gösteren sıfır olmayan pozitif bir sayı sağlamanız gerekir. Öğenin süresinin dolmaması gereken bir -1 de sağlayabilirsiniz.
Öğenin TTL alanı yoksa, varsayılan olarak kapsayıcıya ayarlanan TTL öğeye uygulanır.
TTL kapsayıcı düzeyinde devre dışı bırakılırsa, kapsayıcıda TTL yeniden etkinleştirilene kadar öğedeki TTL alanı yoksayılır.

Bir öğede yaşam süresini etkinleştirmek için aşağıdaki adımları kullanın:

Azure Portal oturum açın.
Yeni bir Azure Cosmos DB hesabı oluşturun veya mevcut bir hesabı seçin.
Veri Gezgini bölmesini açın.
Mevcut bir kapsayıcıyı seçin, genişletin ve aşağıdaki değerleri değiştirin:
- Ölçek &Ayarlar penceresini açın.
- Bul ayarının altında Yaşam Süresi...
- Açık (varsayılan değil) seçeneğini belirleyin veya Açık'ı seçip bir TTL değeri ayarlayın.
- Değişiklikleri kaydetmek için Kaydet'i seçin.

Ardından yaşam süresini ayarlamak istediğiniz öğeye gidin, özelliği ekleyin ttl ve Güncelleştir'i seçin.

{
    "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 kullanarak bir öğede yaşam süresini ayarlama

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)

SDK kullanarak yaşam süresini sıfırlama

Öğe üzerinde bir yazma veya güncelleştirme işlemi gerçekleştirerek bir öğe üzerinde yaşam süresini sıfırlayabilirsiniz. Yazma veya güncelleştirme işlemi değerini geçerli saate ayarlar _ts ve öğenin süresinin dolacağı TTL yeniden başlar. Bir öğenin TTL'sini değiştirmek isterseniz, diğer herhangi bir alanı güncelleştirdiğiniz gibi alanı da güncelleştirebilirsiniz.

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
)

SDK kullanarak yaşam süresini devre dışı bırakma

Bir kapsayıcıda yaşam süresini devre dışı bırakmak ve arka plan işleminin süresi dolan öğeleri denetlemesini durdurmak için kapsayıcıdaki DefaultTimeToLive özelliğin silinmesi gerekir. Bu özelliği silmek, -1 olarak ayarlamaktan farklıdır. -1 olarak ayarladığınızda, kapsayıcıya eklenen yeni öğeler sonsuza kadar kalır, ancak bu değeri kapsayıcıdaki belirli öğelerde geçersiz kılabilirsiniz. TTL özelliğini kapsayıcıdan kaldırdığınızda, önceki varsayılan TTL değerini açıkça geçersiz kılsalar bile öğelerin süresi asla dolmaz.

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
)

Sonraki adımlar

Yaşam süresi hakkında daha fazla bilgiyi aşağıdaki makalede bulabilirsiniz:

Yaşam süresi