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

مقالة
05/16/2022
قراءة خلال 10 دقائق

ينطبق على: واجهة برمجة تطبيقات SQL

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

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

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

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

تسجيل الدخول إلى ⁧⁩مدخل Azure⁧⁩.
أنشئ حساب Azure Cosmos جديدًا، أو حدد حسابًا موجودًا.
افتح لوحة مستكشف البيانات.
حدد حاوية موجودة، وقم بتوسيع علامة تبويب الإعدادات وقم بتعديل القيم التالية:
- ضمن الإعداد، ابحث عن مدة البقاء.
- بناءً على متطلباتك، يمكنك:
  - أوقف تشغيل هذا الإعداد
  - اضبطه على تشغيل (ليس افتراضيًا) أو
  - تشغيل باستخدام قيمة TTL محددة بالثواني.
- انقر فوق حفظ لحفظ التغييرات.

عندما تكون قيمة مدة البقاء الافتراضية فارغة، فسيتم إيقاف تشغيل قيمة مدة البقاء
عندما تكون قيمة مدة البقاء الافتراضية هي -1، فإن إعداد قيمة مدة البقاء الخاصة بك قيد التشغيل (ليس افتراضياً)
عندما يكون لقيمة مدة البقاء الافتراضية أي قيمة Int أخرى (باستثناء 0) يكون إعداد مدة البقاء قيد التشغيل. سيقوم الخادم تلقائيًا بحذف العناصر بناءً على القيمة التي تم تكوينها.

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

لإنشاء أو تمكين مدة البقاء في حاوية، انظر،

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

.NET SDK V2 (Microsoft.Azure.DocumentDB)

// Create a new container with TTL enabled and without any expiration value
DocumentCollection collectionDefinition = new DocumentCollection();
collectionDefinition.Id = "myContainer";
collectionDefinition.PartitionKey.Paths.Add("/myPartitionKey");
collectionDefinition.DefaultTimeToLive = -1; //(never expire by default)

DocumentCollection ttlEnabledCollection = await client.CreateDocumentCollectionAsync(
    UriFactory.CreateDatabaseUri("myDatabaseName"),
    collectionDefinition);

.NET SDK V3 (Microsoft.Azure.Cosmos)

// Create a new container with TTL enabled and without any expiration value
await client.GetDatabase("database").CreateContainerAsync(new ContainerProperties
{
    Id = "container",
    PartitionKeyPath = "/myPartitionKey",
    DefaultTimeToLive = -1 //(never expire by default)
});

Java SDK

⁦⁩Java SDK V4⁦⁩
⁦⁩Java SDK V3⁦⁩

Java SDK V4 (Maven com.azure::azure-cosmos)

CosmosAsyncContainer container;

// Create a new container with TTL enabled and without any expiration value
CosmosContainerProperties containerProperties = new CosmosContainerProperties("myContainer", "/myPartitionKey");
containerProperties.setDefaultTimeToLiveInSeconds(-1);
container = database.createContainerIfNotExists(containerProperties, 400).block().getContainer();

Java SDK V3 (Maven com.microsoft.azure::azure-cosmos)

CosmosContainer container;

// Create a new container with TTL enabled and without any expiration value
CosmosContainerProperties containerProperties = new CosmosContainerProperties("myContainer", "/myPartitionKey");
containerProperties.defaultTimeToLive(-1);
container = database.createContainerIfNotExists(containerProperties, 400).block().container();

اضبط مدة البقاء في حاوية باستخدام SDK

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

.NET SDK

NET SDK. الإصدار 2
⁦⁩.NET SDK V3⁦⁩

.NET SDK V2 (Microsoft.Azure.DocumentDB)

// Create a new container with TTL enabled and a 90 day expiration
DocumentCollection collectionDefinition = new DocumentCollection();
collectionDefinition.Id = "myContainer";
collectionDefinition.PartitionKey.Paths.Add("/myPartitionKey");
collectionDefinition.DefaultTimeToLive = 90 * 60 * 60 * 24 // expire all documents after 90 days

DocumentCollection ttlEnabledCollection = await client.CreateDocumentCollectionAsync(
    UriFactory.CreateDatabaseUri("myDatabaseName"),
    collectionDefinition;

.NET SDK V3 (Microsoft.Azure.Cosmos)

// Create a new container with TTL enabled and a 90 day expiration
await client.GetDatabase("database").CreateContainerAsync(new ContainerProperties
{
    Id = "container",
    PartitionKeyPath = "/myPartitionKey",
    DefaultTimeToLive = 90 * 60 * 60 * 24 // expire all documents after 90 days
});

Java SDK

⁦⁩Java SDK V4⁦⁩
⁦⁩Java SDK V3⁦⁩

Java SDK V4 (Maven com.azure::azure-cosmos)

CosmosAsyncContainer container;

// Create a new container with TTL enabled with default expiration value
CosmosContainerProperties containerProperties = new CosmosContainerProperties("myContainer", "/myPartitionKey");
containerProperties.setDefaultTimeToLiveInSeconds(90 * 60 * 60 * 24);
container = database.createContainerIfNotExists(containerProperties, 400).block().getContainer();

Java SDK V3 (Maven com.microsoft.azure::azure-cosmos)

CosmosContainer container;

// Create a new container with TTL enabled with default expiration value
CosmosContainerProperties containerProperties = new CosmosContainerProperties("myContainer", "/myPartitionKey");
containerProperties.defaultTimeToLive(90 * 60 * 60 * 24);
container = database.createContainerIfNotExists(containerProperties, 400).block().container();

⁦⁩⁦⁩NodeJS SDK

const containerDefinition = {
          id: "sample container1",
        };

async function createcontainerWithTTL(db: Database, containerDefinition: ContainerDefinition, collId: any, defaultTtl: number) {
      containerDefinition.id = collId;
      containerDefinition.defaultTtl = defaultTtl;
      await db.containers.create(containerDefinition);
}

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

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

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

مدخل Azure

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

تسجيل الدخول إلى ⁧⁩مدخل Azure⁧⁩.
أنشئ حساب Azure Cosmos جديدًا، أو حدد حسابًا موجودًا.
افتح لوحة مستكشف البيانات.
حدد حاوية موجودة، وقم بتوسيعها وتعديل القيم التالية:
- افتح نافذة إعدادات & تغيير الحجم .
- ضمن الإعداد، ابحث عن مدة البقاء.
- حدد تشغيل (ليس افتراضياً) أو حدد تشغيل وقم بتعيين قيمة مدة البقاء.
- انقر فوق حفظ لحفظ التغييرات.

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

⁦⁩⁦⁩.NET SDK (any)

// Include a property that serializes to "ttl" in JSON
public class SalesOrder
{
    [JsonProperty(PropertyName = "id")]
    public string Id { get; set; }
    [JsonProperty(PropertyName="cid")]
    public string CustomerId { get; set; }
    // used to set expiration policy
    [JsonProperty(PropertyName = "ttl", NullValueHandling = NullValueHandling.Ignore)]
    public int? ttl { get; set; }

    //...
}
// Set the value to the expiration in seconds
SalesOrder salesOrder = new SalesOrder
{
    Id = "SO05",
    CustomerId = "CO18009186470",
    ttl = 60 * 60 * 24 * 30;  // Expire sales orders in 30 days
};

NodeJS SDK

const itemDefinition = {
          id: "doc",
          name: "sample Item",
          key: "value",
          ttl: 2
        };

Java SDK

⁦⁩Java SDK V4⁦⁩
⁦⁩Java SDK V3⁦⁩

Java SDK V4 (Maven com.azure::azure-cosmos)

// Include a property that serializes to "ttl" in JSON
public class SalesOrder
{
    private String id;
    private String customerId;
    private Integer ttl;

    public SalesOrder(String id, String customerId, Integer ttl) {
        this.id = id;
        this.customerId = customerId;
        this.ttl = ttl;
    }

    public String getId() {return this.id;}
    public void setId(String new_id) {this.id = new_id;}
    public String getCustomerId() {return this.customerId;}
    public void setCustomerId(String new_cid) {this.customerId = new_cid;}
    public Integer getTtl() {return this.ttl;}
    public void setTtl(Integer new_ttl) {this.ttl = new_ttl;}

    //...
}

// Set the value to the expiration in seconds
SalesOrder salesOrder = new SalesOrder(
    "SO05",
    "CO18009186470",
    60 * 60 * 24 * 30  // Expire sales orders in 30 days
);

Java SDK V3 (Maven com.microsoft.azure::azure-cosmos)

// Include a property that serializes to "ttl" in JSON
public class SalesOrder
{
    private String id;
    private String customerId;
    private Integer ttl;

    public SalesOrder(String id, String customerId, Integer ttl) {
        this.id = id;
        this.customerId = customerId;
        this.ttl = ttl;
    }

    public String id() {return this.id;}
    public void id(String new_id) {this.id = new_id;}
    public String customerId() {return this.customerId;}
    public void customerId(String new_cid) {this.customerId = new_cid;}
    public Integer ttl() {return this.ttl;}
    public void ttl(Integer new_ttl) {this.ttl = new_ttl;}

    //...
}

// Set the value to the expiration in seconds
SalesOrder salesOrder = new SalesOrder(
    "SO05",
    "CO18009186470",
    60 * 60 * 24 * 30  // Expire sales orders in 30 days
);

إعادة تعيين مدة البقاء

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

.NET SDK

NET SDK. الإصدار 2
⁦⁩.NET SDK V3⁦⁩

.NET SDK V2 (Microsoft.Azure.DocumentDB)

// This examples leverages the Sales Order class above.
// Read a document, update its TTL, save it.
response = await client.ReadDocumentAsync(
    "/dbs/salesdb/colls/orders/docs/SO05"),
    new RequestOptions { PartitionKey = new PartitionKey("CO18009186470") });

Document readDocument = response.Resource;
readDocument.ttl = 60 * 30 * 30; // update time to live
response = await client.ReplaceDocumentAsync(readDocument);

.NET SDK V3 (Microsoft.Azure.Cosmos)

// This examples leverages the Sales Order class above.
// Read a document, update its TTL, save it.
ItemResponse<SalesOrder> itemResponse = await client.GetContainer("database", "container").ReadItemAsync<SalesOrder>("SO05", new PartitionKey("CO18009186470"));

itemResponse.Resource.ttl = 60 * 30 * 30; // update time to live
await client.GetContainer("database", "container").ReplaceItemAsync(itemResponse.Resource, "SO05");

Java SDK

⁦⁩Java SDK V4⁦⁩
⁦⁩Java SDK V3⁦⁩

Java SDK V4 (Maven com.azure::azure-cosmos)

// This examples leverages the Sales Order class above.
// Read a document, update its TTL, save it.
CosmosAsyncItemResponse<SalesOrder> itemResponse = container.readItem("SO05", new PartitionKey("CO18009186470"), SalesOrder.class)
        .flatMap(readResponse -> {
            SalesOrder salesOrder = readResponse.getItem();
            salesOrder.setTtl(60 * 30 * 30);
            return container.createItem(salesOrder);
}).block();

SDK V3 (Maven com.microsoft.azure::azure-cosmos)

// This examples leverages the Sales Order class above.
// Read a document, update its TTL, save it.
container.getItem("SO05", new PartitionKey("CO18009186470")).read()
        .flatMap(readResponse -> {
            SalesOrder salesOrder = null;
            try {
                salesOrder = readResponse.properties().getObject(SalesOrder.class);
            } catch (Exception err) {

            }
            salesOrder.ttl(60 * 30 * 30);
            return container.createItem(salesOrder);
}).block();

إيقاف مدة البقاء

إذا تم تعيين مدة البقاء على عنصر ولم تعد تريد أن تنتهي صلاحية هذا العنصر، فيمكنك حينئذٍ الحصول على العنصر وإزالة حقل مدة البقاء واستبدال العنصر الموجود على الخادم. عند إزالة حقل مدة البقاء من العنصر، يتم تطبيق قيمة مدة البقاء الافتراضية المعينة للحاوية على العنصر. عيّن قيمة مدة البقاء على -1 لمنع انتهاء صلاحية العنصر وعدم اكتساب قيمة مدة البقاء من الحاوية.

.NET SDK

NET SDK. الإصدار 2
⁦⁩.NET SDK V3⁦⁩

.NET SDK V2 (Microsoft.Azure.DocumentDB)

// This examples leverages the Sales Order class above.
// Read a document, turn off its override TTL, save it.
response = await client.ReadDocumentAsync(
    "/dbs/salesdb/colls/orders/docs/SO05"),
    new RequestOptions { PartitionKey = new PartitionKey("CO18009186470") });

Document readDocument = response.Resource;
readDocument.ttl = null; // inherit the default TTL of the container

response = await client.ReplaceDocumentAsync(readDocument);

.NET SDK V3 (Microsoft.Azure.Cosmos)

// This examples leverages the Sales Order class above.
// Read a document, turn off its override TTL, save it.
ItemResponse<SalesOrder> itemResponse = await client.GetContainer("database", "container").ReadItemAsync<SalesOrder>("SO05", new PartitionKey("CO18009186470"));

itemResponse.Resource.ttl = null; // inherit the default TTL of the container
await client.GetContainer("database", "container").ReplaceItemAsync(itemResponse.Resource, "SO05");

Java SDK

⁦⁩Java SDK V4⁦⁩
⁦⁩Java SDK V3⁦⁩

Java SDK V4 (Maven com.azure::azure-cosmos)

// This examples leverages the Sales Order class above.
// Read a document, update its TTL, save it.
CosmosAsyncItemResponse<SalesOrder> itemResponse = container.readItem("SO05", new PartitionKey("CO18009186470"), SalesOrder.class)
        .flatMap(readResponse -> {
            SalesOrder salesOrder = readResponse.getItem();
            salesOrder.setTtl(null);
            return container.createItem(salesOrder);
}).block();

Java SDK V3 (Maven com.microsoft.azure::azure-cosmos)

// This examples leverages the Sales Order class above.
// Read a document, update its TTL, save it.
container.getItem("SO05", new PartitionKey("CO18009186470")).read()
        .flatMap(readResponse -> {
            SalesOrder salesOrder = null;
            try {
                salesOrder = readResponse.properties().getObject(SalesOrder.class);
            } catch (Exception err) {

            }
            salesOrder.ttl(null);
            return container.createItem(salesOrder);
}).block();

تعطيل مدة البقاء

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

.NET SDK

NET SDK. الإصدار 2
⁦⁩.NET SDK V3⁦⁩

.NET SDK V2 (Microsoft.Azure.DocumentDB)

// Get the container, update DefaultTimeToLive to null
DocumentCollection collection = await client.ReadDocumentCollectionAsync("/dbs/salesdb/colls/orders");
// Disable TTL
collection.DefaultTimeToLive = null;
await client.ReplaceDocumentCollectionAsync(collection);

.NET SDK V3 (Microsoft.Azure.Cosmos)

// Get the container, update DefaultTimeToLive to null
ContainerResponse containerResponse = await client.GetContainer("database", "container").ReadContainerAsync();
// Disable TTL
containerResponse.Resource.DefaultTimeToLive = null;
await client.GetContainer("database", "container").ReplaceContainerAsync(containerResponse.Resource);

Java SDK

⁦⁩Java SDK V4⁦⁩
⁦⁩Java SDK V3⁦⁩

Java SDK V4 (Maven com.azure::azure-cosmos)

CosmosContainerProperties containerProperties = new CosmosContainerProperties("myContainer", "/myPartitionKey");
// Disable TTL
containerProperties.setDefaultTimeToLiveInSeconds(null);
// Update container settings
container.replace(containerProperties).block();

Java SDK V3 (Maven com.microsoft.azure::azure-cosmos)

CosmosContainer container;

// Create a new container with TTL enabled and without any expiration value
CosmosContainerProperties containerProperties = new CosmosContainerProperties("myContainer", "/myPartitionKey");
// Disable TTL
containerProperties.defaultTimeToLive(null);
// Update container settings
container = database.createContainerIfNotExists(containerProperties, 400).block().container();

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

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

حان الوقت للحياة

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

هل هذه الصفحة مفيدة؟

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

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

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

.NET SDK

Java SDK

اضبط مدة البقاء في حاوية باستخدام SDK

.NET SDK

Java SDK

⁦⁩⁦⁩NodeJS SDK

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

مدخل Azure

⁦⁩⁦⁩.NET SDK (any)

NodeJS SDK

Java SDK

إعادة تعيين مدة البقاء

.NET SDK

Java SDK

إيقاف مدة البقاء

.NET SDK

Java SDK

تعطيل مدة البقاء

.NET SDK

Java SDK

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