本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 操作過期項目與存留時間 (TTL)
可從讀取與寫入操作中篩選出待刪除的過期項目。當過期資料已失效且不應再使用時，這項設計特別實用。若未進行篩選，這些項目將持續出現在讀取與寫入操作中，直到由背景程序刪除。
**注意**
在刪除前，這些項目仍計入儲存與讀取成本。
TTL 刪除可在 DynamoDB 串流中識別，但僅限於刪除發生的區域。被複寫至全域資料表其他區域的 TTL 刪除，無法在那些區域的 DynamoDB 串流中識別。
## 從讀取操作中篩選過期項目
針對[掃描](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Scan.html)與[查詢](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html)等讀取操作，可使用篩選條件表達式排除待刪除的過期項目。如下列程式碼片段所示，篩選條件表達式可排除 TTL 時間小於或等於目前時間的項目。例如，Python SDK 程式碼中包含指派語句，將目前時間作為變數 (`now`) 取得，並將其轉換為 `int` 以符合 epoch 時間格式。
下列程式碼範例示範如何查詢 TTL 項目。
------
#### [ Java ]
**適用於 Java 2.x 的 SDK**
查詢篩選表達式，以使用 在 DynamoDB 資料表中收集 TTL 項目 AWS SDK for Java 2.x。
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
import software.amazon.awssdk.services.dynamodb.model.DynamoDbException;
import software.amazon.awssdk.services.dynamodb.model.QueryRequest;
import software.amazon.awssdk.services.dynamodb.model.QueryResponse;
import software.amazon.awssdk.services.dynamodb.model.ResourceNotFoundException;
import java.util.Map;
import java.util.Optional;
final QueryRequest request = QueryRequest.builder()
.tableName(tableName)
.keyConditionExpression(KEY_CONDITION_EXPRESSION)
.filterExpression(FILTER_EXPRESSION)
.expressionAttributeNames(expressionAttributeNames)
.expressionAttributeValues(expressionAttributeValues)
.build();
try (DynamoDbClient ddb = dynamoDbClient != null
? dynamoDbClient
: DynamoDbClient.builder().region(region).build()) {
final QueryResponse response = ddb.query(request);
System.out.println("Query successful. Found " + response.count() + " items that have not expired yet.");
// Print each item
response.items().forEach(item -> {
System.out.println("Item: " + item);
});
return 0;
} catch (ResourceNotFoundException e) {
System.err.format(TABLE_NOT_FOUND_ERROR, tableName);
throw e;
} catch (DynamoDbException e) {
System.err.println(e.getMessage());
throw e;
}
```
+ 如需 API 的詳細資訊，請參閱《*AWS SDK for Java 2.x API 參考*》中的 [Query](https://docs.aws.amazon.com/goto/SdkForJavaV2/dynamodb-2012-08-10/Query)。
------
#### [ JavaScript ]
**適用於 JavaScript (v3) 的 SDK**
查詢篩選表達式，以使用 在 DynamoDB 資料表中收集 TTL 項目 適用於 JavaScript 的 AWS SDK。
```
import { DynamoDBClient, QueryCommand } from "@aws-sdk/client-dynamodb";
import { marshall, unmarshall } from "@aws-sdk/util-dynamodb";
export const queryFiltered = async (tableName, primaryKey, region = 'us-east-1') => {
const client = new DynamoDBClient({
region: region,
endpoint: `https://dynamodb.${region}.amazonaws.com`
});
const currentTime = Math.floor(Date.now() / 1000);
const params = {
TableName: tableName,
KeyConditionExpression: "#pk = :pk",
FilterExpression: "#ea > :ea",
ExpressionAttributeNames: {
"#pk": "primaryKey",
"#ea": "expireAt"
},
ExpressionAttributeValues: marshall({
":pk": primaryKey,
":ea": currentTime
})
};
try {
const { Items } = await client.send(new QueryCommand(params));
Items.forEach(item => {
console.log(unmarshall(item))
});
return Items;
} catch (err) {
console.error(`Error querying items: ${err}`);
throw err;
}
}
// Example usage (commented out for testing)
// queryFiltered('your-table-name', 'your-partition-key-value');
```
+ 如需 API 的詳細資訊，請參閱《*適用於 JavaScript 的 AWS SDK API 參考*》中的 [Query](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/dynamodb/command/QueryCommand)。
------
#### [ Python ]
**適用於 Python 的 SDK (Boto3)**
查詢篩選表達式，以使用 在 DynamoDB 資料表中收集 TTL 項目 適用於 Python (Boto3) 的 AWS SDK。
```
from datetime import datetime
import boto3
def query_dynamodb_items(table_name, partition_key):
"""
:param table_name: Name of the DynamoDB table
:param partition_key:
:return:
"""
try:
# Initialize a DynamoDB resource
dynamodb = boto3.resource("dynamodb", region_name="us-east-1")
# Specify your table
table = dynamodb.Table(table_name)
# Get the current time in epoch format
current_time = int(datetime.now().timestamp())
# Perform the query operation with a filter expression to exclude expired items
# response = table.query(
# KeyConditionExpression=boto3.dynamodb.conditions.Key('partitionKey').eq(partition_key),
# FilterExpression=boto3.dynamodb.conditions.Attr('expireAt').gt(current_time)
# )
response = table.query(
KeyConditionExpression=dynamodb.conditions.Key("partitionKey").eq(partition_key),
FilterExpression=dynamodb.conditions.Attr("expireAt").gt(current_time),
)
# Print the items that are not expired
for item in response["Items"]:
print(item)
except Exception as e:
print(f"Error querying items: {e}")
# Call the function with your values
query_dynamodb_items("Music", "your-partition-key-value")
```
+ 如需 API 的詳細資訊，請參閱《*適用於 Python (Boto3) 的AWS SDK API 參考*》中的 [Query](https://docs.aws.amazon.com/goto/boto3/dynamodb-2012-08-10/Query)。
------
## 有條件地寫入過期項目
可使用條件表達式以避免對過期項目執行寫入。以下程式碼片段為條件式更新，用以檢查過期時間是否晚於目前時間。若條件為 true，則繼續執行寫入操作。
下列程式碼範例示範如何有條件地更新項目的 TTL。
------
#### [ Java ]
**適用於 Java 2.x 的 SDK**
使用條件更新資料表中現有的 DynamoDB 項目之 TTL。
```
package com.amazon.samplelib.ttl;
import com.amazon.samplelib.CodeSampleUtils;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
import software.amazon.awssdk.services.dynamodb.model.ConditionalCheckFailedException;
import software.amazon.awssdk.services.dynamodb.model.DynamoDbException;
import software.amazon.awssdk.services.dynamodb.model.ResourceNotFoundException;
import software.amazon.awssdk.services.dynamodb.model.UpdateItemRequest;
import software.amazon.awssdk.services.dynamodb.model.UpdateItemResponse;
import java.util.Map;
import java.util.Optional;
/**
* Updates an item in a DynamoDB table with TTL attributes using a conditional expression.
* This class demonstrates how to conditionally update TTL expiration timestamps.
*/
public class UpdateTTLConditional {
private static final String USAGE =
"""
Usage:
Where:
tableName - The Amazon DynamoDB table being queried.
primaryKey - The name of the primary key. Also known as the hash or partition key.
sortKey - The name of the sort key. Also known as the range attribute.
region (optional) - The AWS region that the Amazon DynamoDB table is located in. (Default: us-east-1)
""";
private static final int DAYS_TO_EXPIRE = 90;
private static final int SECONDS_PER_DAY = 24 * 60 * 60;
private static final String PRIMARY_KEY_ATTR = "primaryKey";
private static final String SORT_KEY_ATTR = "sortKey";
private static final String UPDATED_AT_ATTR = "updatedAt";
private static final String EXPIRE_AT_ATTR = "expireAt";
private static final String UPDATE_EXPRESSION = "SET " + UPDATED_AT_ATTR + "=:c, " + EXPIRE_AT_ATTR + "=:e";
private static final String CONDITION_EXPRESSION = "attribute_exists(" + PRIMARY_KEY_ATTR + ")";
private static final String SUCCESS_MESSAGE = "%s UpdateItem operation with TTL successful.";
private static final String CONDITION_FAILED_MESSAGE = "Condition check failed. Item does not exist.";
private static final String TABLE_NOT_FOUND_ERROR = "Error: The Amazon DynamoDB table \"%s\" can't be found.";
private final DynamoDbClient dynamoDbClient;
/**
* Constructs an UpdateTTLConditional with a default DynamoDB client.
*/
public UpdateTTLConditional() {
this.dynamoDbClient = null;
}
/**
* Constructs an UpdateTTLConditional with the specified DynamoDB client.
*
* @param dynamoDbClient The DynamoDB client to use
*/
public UpdateTTLConditional(final DynamoDbClient dynamoDbClient) {
this.dynamoDbClient = dynamoDbClient;
}
/**
* Main method to demonstrate conditionally updating an item with TTL.
*
* @param args Command line arguments
*/
public static void main(final String[] args) {
try {
int result = new UpdateTTLConditional().processArgs(args);
System.exit(result);
} catch (Exception e) {
System.err.println(e.getMessage());
System.exit(1);
}
}
/**
* Process command line arguments and conditionally update an item with TTL.
*
* @param args Command line arguments
* @return 0 if successful, non-zero otherwise
* @throws ResourceNotFoundException If the table doesn't exist
* @throws DynamoDbException If an error occurs during the operation
* @throws IllegalArgumentException If arguments are invalid
*/
public int processArgs(final String[] args) {
// Argument validation (remove or replace this line when reusing this code)
CodeSampleUtils.validateArgs(args, new int[] {3, 4}, USAGE);
final String tableName = args[0];
final String primaryKey = args[1];
final String sortKey = args[2];
final Region region = Optional.ofNullable(args.length > 3 ? args[3] : null)
.map(Region::of)
.orElse(Region.US_EAST_1);
// Get current time in epoch second format
final long currentTime = System.currentTimeMillis() / 1000;
// Calculate expiration time 90 days from now in epoch second format
final long expireDate = currentTime + (DAYS_TO_EXPIRE * SECONDS_PER_DAY);
// Create the key map for the item to update
final Map keyMap = Map.of(
PRIMARY_KEY_ATTR, AttributeValue.builder().s(primaryKey).build(),
SORT_KEY_ATTR, AttributeValue.builder().s(sortKey).build());
// Create the expression attribute values
final Map expressionAttributeValues = Map.of(
":c", AttributeValue.builder().n(String.valueOf(currentTime)).build(),
":e", AttributeValue.builder().n(String.valueOf(expireDate)).build());
final UpdateItemRequest request = UpdateItemRequest.builder()
.tableName(tableName)
.key(keyMap)
.updateExpression(UPDATE_EXPRESSION)
.conditionExpression(CONDITION_EXPRESSION)
.expressionAttributeValues(expressionAttributeValues)
.build();
try (DynamoDbClient ddb = dynamoDbClient != null
? dynamoDbClient
: DynamoDbClient.builder().region(region).build()) {
final UpdateItemResponse response = ddb.updateItem(request);
System.out.println(String.format(SUCCESS_MESSAGE, tableName));
return 0;
} catch (ConditionalCheckFailedException e) {
System.err.println(CONDITION_FAILED_MESSAGE);
throw e;
} catch (ResourceNotFoundException e) {
System.err.format(TABLE_NOT_FOUND_ERROR, tableName);
throw e;
} catch (DynamoDbException e) {
System.err.println(e.getMessage());
throw e;
}
}
}
```
+ 如需 API 的詳細資訊，請參閱《[AWS SDK for Java 2.x API 參考](https://docs.aws.amazon.com/goto/SdkForJavaV2/dynamodb-2012-08-10/UpdateItem)》中的 *UpdateItem*。
------
#### [ JavaScript ]
**適用於 JavaScript (v3) 的 SDK**
使用條件更新資料表中現有的 DynamoDB 項目之 TTL。
```
import { DynamoDBClient, UpdateItemCommand } from "@aws-sdk/client-dynamodb";
import { marshall, unmarshall } from "@aws-sdk/util-dynamodb";
export const updateItemConditional = async (tableName, partitionKey, sortKey, region = 'us-east-1', newAttribute = 'default-value') => {
const client = new DynamoDBClient({
region: region,
endpoint: `https://dynamodb.${region}.amazonaws.com`
});
const currentTime = Math.floor(Date.now() / 1000);
const params = {
TableName: tableName,
Key: marshall({
artist: partitionKey,
album: sortKey
}),
UpdateExpression: "SET newAttribute = :newAttribute",
ConditionExpression: "expireAt > :expiration",
ExpressionAttributeValues: marshall({
':newAttribute': newAttribute,
':expiration': currentTime
}),
ReturnValues: "ALL_NEW"
};
try {
const response = await client.send(new UpdateItemCommand(params));
const responseData = unmarshall(response.Attributes);
console.log("Item updated successfully: ", responseData);
return responseData;
} catch (error) {
if (error.name === "ConditionalCheckFailedException") {
console.log("Condition check failed: Item's 'expireAt' is expired.");
} else {
console.error("Error updating item: ", error);
}
throw error;
}
};
// Example usage (commented out for testing)
// updateItemConditional('your-table-name', 'your-partition-key-value', 'your-sort-key-value');
```
+ 如需 API 的詳細資訊，請參閱《[適用於 JavaScript 的 AWS SDK API 參考](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/dynamodb/command/UpdateItemCommand)》中的 *UpdateItem*。
------
#### [ Python ]
**適用於 Python (Boto3) 的 SDK**
使用條件更新資料表中現有的 DynamoDB 項目之 TTL。
```
from datetime import datetime, timedelta
import boto3
from botocore.exceptions import ClientError
def update_dynamodb_item_ttl(table_name, region, primary_key, sort_key, ttl_attribute):
"""
Updates an existing record in a DynamoDB table with a new or updated TTL attribute.
:param table_name: Name of the DynamoDB table
:param region: AWS Region of the table - example `us-east-1`
:param primary_key: one attribute known as the partition key.
:param sort_key: Also known as a range attribute.
:param ttl_attribute: name of the TTL attribute in the target DynamoDB table
:return:
"""
try:
dynamodb = boto3.resource("dynamodb", region_name=region)
table = dynamodb.Table(table_name)
# Generate updated TTL in epoch second format
updated_expiration_time = int((datetime.now() + timedelta(days=90)).timestamp())
# Define the update expression for adding/updating a new attribute
update_expression = "SET newAttribute = :val1"
# Define the condition expression for checking if 'expireAt' is not expired
condition_expression = "expireAt > :val2"
# Define the expression attribute values
expression_attribute_values = {":val1": ttl_attribute, ":val2": updated_expiration_time}
response = table.update_item(
Key={"primaryKey": primary_key, "sortKey": sort_key},
UpdateExpression=update_expression,
ConditionExpression=condition_expression,
ExpressionAttributeValues=expression_attribute_values,
)
print("Item updated successfully.")
return response["ResponseMetadata"]["HTTPStatusCode"] # Ideally a 200 OK
except ClientError as e:
if e.response["Error"]["Code"] == "ConditionalCheckFailedException":
print("Condition check failed: Item's 'expireAt' is expired.")
else:
print(f"Error updating item: {e}")
except Exception as e:
print(f"Error updating item: {e}")
# replace with your values
update_dynamodb_item_ttl(
"your-table-name",
"us-east-1",
"your-partition-key-value",
"your-sort-key-value",
"your-ttl-attribute-value",
)
```
+ 如需 API 的詳細資訊，請參閱《*適用於 Python (Boto3) 的AWS SDK API 參考*》中的 [UpdateItem](https://docs.aws.amazon.com/goto/boto3/dynamodb-2012-08-10/UpdateItem)。
------
## 在 DynamoDB 串流中識別已刪除的項目
串流紀錄包含使用者身分欄位 `Records[].userIdentity`。由 TTL 程序刪除的項目包含下列欄位：
```
Records[].userIdentity.type
"Service"
Records[].userIdentity.principalId
"dynamodb.amazonaws.com"
```
下列 JSON 顯示單一串流紀錄的相關部分：
```
"Records": [
{
...
"userIdentity": {
"type": "Service",
"principalId": "dynamodb.amazonaws.com"
}
...
}
]
```