تكوين مدة البقاء في Azure Cosmos DB

مقالة
01/10/2024

ينطبق على: NoSQL

في Azure Cosmos DB، يمكنك اختيار تكوين مدة البقاء (TTL) على مستوى الحاوية، أو يمكنك تجاوزها على مستوى العنصر بعد تعيين الحاوية. يمكنك تكوين مدة البقاء لحاوية باستخدام مدخل Azure أو حزم SDK الخاصة باللغة. يمكن تكوين تجاوزات مدة البقاء على مستوى العنصر باستخدام حزم SDK.

يرتبط محتوى هذه المقالة بمخزن معاملات مدة البقاء لـ Azure Cosmos DB. إذا كنت تبحث عن TTL لمتجر Analitycal، الذي يمكن سيناريوهات NoETL HTAP من خلال Azure Synapse Link، يرجى النقر هنا.

تمكين مدة البقاء في حاوية باستخدام مدخل Azure

استخدم الخطوات التالية لتمكين مدة البقاء في حاوية دون انتهاء الصلاحية. تمكين TTL على مستوى الحاوية للسماح بتجاوز نفس القيمة على مستوى عنصر فردي. يمكنك أيضاً تعيين مدة البقاء عن طريق إدخال قيمة غير صفرية للثواني.

قم بتسجيل الدخول إلى بوابة Azure.
إنشاء حساب Azure Cosmos DB جديد أو تحديد حساب موجود.
افتح جزء مستكشف البيانات.
حدد حاوية موجودة، وقم بتوسيع علامة تبويب الإعدادات وقم بتعديل القيم التالية:
- ضمن "Setting find"، "Time to Live".
- بناءً على متطلباتك، يمكنك:
  - أوقف تشغيل هذا الإعداد
  - اضبطه على تشغيل (ليس افتراضيًا) أو
  - تشغيل باستخدام قيمة TTL محددة بالثواني.
- حدد حفظ لحفظ التغييرات.

عندما تكون قيمة مدة البقاء الافتراضية فارغة، فسيتم إيقاف تشغيل قيمة مدة البقاء
عندما تكون قيمة مدة البقاء الافتراضية هي -1، فإن إعداد قيمة مدة البقاء الخاصة بك قيد التشغيل (ليس افتراضياً)
عندما يكون لقيمة مدة البقاء الافتراضية أي قيمة Int أخرى (باستثناء 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
)

اضبط مدة البقاء في حاوية باستخدام 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
)

تعيين مدة البقاء على عنصر باستخدام المدخل

بالإضافة إلى تعيين مدة بقاء افتراضية في حاوية، يمكنك تعيين مدة بقاء لعنصر ما. سيؤدي تعيين مدة البقاء على مستوى العنصر إلى تجاوز مدة البقاء الافتراضية للعنصر في تلك الحاوية.

لتعيين TTL على عنصر، تحتاج إلى توفير رقم موجب غير صفري، والذي يشير إلى الفترة، بالثوان، لتنتهي صلاحية العنصر بعد آخر طابع زمني معدل للعنصر _ts. يمكنك توفير -1 أيضا عندما لا تنتهي صلاحية العنصر.
إذا لم يكن العنصر يحتوي على حقل مدة البقاء، فسيتم تطبيق مدة البقاء المعينة على الحاوية بشكل افتراضي على العنصر.
إذا تم تعطيل مدة البقاء على مستوى الحاوية، فسيتم تجاهل حقل مدة البقاء على العنصر حتى تتم إعادة تمكين مدة البقاء في الحاوية.

استخدم الخطوات التالية لتمكين مدة البقاء على عنصر:

قم بتسجيل الدخول إلى بوابة Azure.
إنشاء حساب Azure Cosmos DB جديد أو تحديد حساب موجود.
افتح جزء مستكشف البيانات.
حدد حاوية موجودة، وقم بتوسيعها وتعديل القيم التالية:
- افتح إطار المقياس والإعدادات.
- ضمن "Setting find"، "Time to Live".
- حدد تشغيل (دون افتراضي) أو حدد تشغيل ثم قم بتعيين قيمة TTL.
- حدد حفظ لحفظ التغييرات.

بعد ذلك، انتقل إلى العنصر الذي تريد تعيين وقت البقاء له، وأضف الخاصية 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)

إعادة تعيين الوقت للبقاء باستخدام 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
)

تعطيل الوقت للبقاء باستخدام 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
)

الخطوات التالية

تعرف على المزيد حول مدة البقاء في المقالة التالية:

مدة البقاء

مشاركة عبر