Mengonfigurasi waktu hidup di Azure Cosmos DB

BERLAKU UNTUK: NoSQL

Di Azure Cosmos DB, Anda dapat memilih untuk mengonfigurasi Waktu Hidup (TTL) di tingkat kontainer, atau Anda dapat menggantinya pada tingkat item setelah pengaturan untuk kontainer. Anda dapat mengonfigurasi TTL untuk kontainer dengan menggunakan portal Microsoft Azure atau SDK khusus bahasa. Penggantian TTL tingkat item dapat dikonfigurasi dengan menggunakan SDK.

Konten artikel ini terkait dengan TTL penyimpanan transaksi Microsoft Azure Cosmos DB. Jika Anda mencari TTL penyimpanan analitik, yang memungkinkan skenario HTAP NoETL melalui Azure Synapse Link, silakan klik di sini.

Aktifkan waktu hidup di kontainer menggunakan portal Microsoft Azure

Gunakan langkah-langkah berikut untuk mengaktifkan waktu hidup di kontainer tanpa kedaluwarsa. Mengaktifkan TTL di tingkat kontainer untuk memungkinkan nilai yang sama ditimpa di tingkat item individual. Anda juga dapat mengatur TTL dengan memasukkan nilai bukan nol selama detik.

1. Masuk ke portal Azure.

2. Buat akun Azure Cosmos DB baru atau pilih akun yang sudah ada.

3. Buka panel Data Explorer.

4. Pilih kontainer yang ada, luaskan tab Aturan dan ubah nilai berikut:

   • Di bawah Pengaturan temukan, Waktu Hidup.

   • Berdasarkan kebutuhan Anda, Anda dapat:

     • Matikan nonaktifkan pengaturan ini
     • Atur ke Aktif (tanpa bawaan) atau
     • Aktifkan dengan nilai TTL yang ditentukan dalam hitungan detik.

   • Pilih Simpan untuk menyimpan perubahan.

   

• Ketika DefaultTimeToLive null, maka Waktu Hidup Anda diatur Nonaktif
• Ketika DefaultTimeToLive adalah -1, maka pengaturan Waktu Hidup Anda Aktif (Tidak default)
• Saat DefaultTimeToLive memiliki nilai Int lainnya (kecuali 0), maka pengaturan Waktu Hidup Anda aktif. Server akan secara otomatis menghapus item berdasarkan nilai yang dikonfigurasi.

Mengaktifkan waktu hidup di kontainer menggunakan Azure CLI atau Azure PowerShell

Untuk membuat atau mengaktifkan TTL pada kontainer lihat,

• Membuat kontainer dengan TTL menggunakan Azure CLI
• Membuat kontainer dengan TTL menggunakan PowerShell

Aktifkan waktu hidup di kontainer menggunakan SDK

.NET SDK v3

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);

Java SDK v4

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);

Node SDK

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);

Python SDK

database = client.get_database_client('database')

database.create_container(
    id='container',
    partition_key=PartitionKey(path='/customerId'),
    # Never expire by default
    default_ttl=-1
)

Atur waktu hidup di kontainer menggunakan SDK

Untuk mengatur waktu hidup di kontainer, Anda perlu memberikan angka positif bukan nol yang menunjukkan periode waktu dalam detik. Berdasarkan nilai TTL yang dikonfigurasi, semua item dalam kontainer setelah tanda waktu terakhir yang dimodifikasi item _ts dihapus.

.NET SDK v3

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);

Java SDK v4

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);

Node SDK

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);

Python SDK

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
)

Atur waktu hidup di item menggunakan Portal

Selain mengatur waktu hidup secara default di kontainer, Anda dapat mengatur waktu hidup untuk item. Mengatur waktu hidup di tingkat item akan menggantikan TTL default item dalam kontainer tersebut.

• Untuk mengatur TTL pada item, Anda perlu memberikan angka positif bukan nol, yang menunjukkan waktu, dalam detik, untuk kedaluwarsa item setelah tanda waktu terakhir yang dimodifikasi dari item _ts. Anda dapat memberikan -1 ketika item tidak seharusnya kedaluwarsa.

• Jika item tidak memiliki bidang TTL, maka secara default, TTL yang diatur ke kontainer akan berlaku untuk item.

• Jika TTL dinonaktifkan pada tingkat kontainer, bidang TTL pada item akan diabaikan sampai TTL diaktifkan kembali pada kontainer.

Gunakan langkah-langkah berikut untuk mengaktifkan waktu hidup pada item:

1. Masuk ke portal Azure.

2. Buat akun Azure Cosmos DB baru atau pilih akun yang sudah ada.

3. Buka panel Data Explorer.

4. Pilih kontainer yang sudah ada, perluas dan ubah nilai berikut ini:

   • Buka jendela Skala & Pengaturan.
   • Di bawah Pengaturan temukan, Waktu Hidup.
   • Pilih Aktif (tidak default) atau pilih Aktif dan atur nilai TTL.
   • Pilih Simpan untuk menyimpan perubahan.

5. Selanjutnya navigasi ke item yang ingin Anda atur waktu hidupnya, tambahkan properti ttl dan pilih Perbarui.

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

Atur waktu hidup item menggunakan SDK

.NET SDK v3

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);

Java SDK v4

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);

Node SDK

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);

Python SDK

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)

Atur ulang waktu hidup menggunakan SDK

Anda dapat mengatur ulang waktu hidup pada item dengan melakukan operasi tulis atau pembaruan pada item. Operasi tulis atau perbarui akan mengatur _ts ke waktu saat ini, dan TTL untuk item yang kedaluwarsa akan dimulai lagi. Jika ingin mengubah TTL item, Anda dapat memperbarui bidang sama seperti memperbarui bidang lainnya.

.NET SDK v3

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")    
);

Java SDK v4

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
);

Node SDK

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);

Python SDK

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
)

Nonaktifkan waktu hidup menggunakan SDK

Untuk menonaktifkan waktu hidup di kontainer dan menghentikan proses latar belakang dari memeriksa item yang kedaluwarsa, properti DefaultTimeToLive pada kontainer harus dihapus. Menghapus properti ini berbeda dengan mengaturnya menjadi -1. Ketika Anda mengaturnya menjadi -1, item baru yang ditambahkan ke kontainer akan hidup selamanya, namun Anda dapat mengganti nilai ini pada item tertentu dalam kontainer. Ketika Anda menghapus properti TTL dari kontainer, item tidak akan pernah kedaluwarsa, bahkan jika mereka telah secara eksplisit menimpa nilai TTL default sebelumnya.

.NET SDK v3

ContainerProperties properties = await container.ReadContainerAsync();

// Disable ttl at container-level
properties.DefaultTimeToLive = null;

await container.ReplaceContainerAsync(properties);

Java SDK v4

CosmosContainerResponse response = container.read();
CosmosContainerProperties properties = response.getProperties();

// Disable ttl at container-level
properties.setDefaultTimeToLiveInSeconds(null);

container.replace(properties);

Node SDK

const { resource: definition } = await container.read();

// Disable ttl at container-level
definition.defaultTtl = null;

await container.replace(definition);

Python SDK

database.replace_container(
    container,
    partition_key=PartitionKey(path='/id'),
    # Disable ttl at container-level
    default_ttl=None
)

Langkah berikutnya

Pelajari selengkapnya tentang waktu hidup di artikel berikut ini:

• Waktu untuk aktif