Work with key value data
This topic describes how to add key-value pairs to an existing key value store. To include key-value pairs when you initially create the key value stores, see Create a key value store.
Topics
Work with key-value pairs (console)
You can use the CloudFront console to work with your key-value pairs.
To work with key-value pairs
-
Sign in to the AWS Management Console and open the Functions page in the CloudFront console at https://console.aws.amazon.com/cloudfront/v4/home#/functions
. -
Choose the KeyValueStores tab.
-
Select the key value store that you want to change.
-
In the Key value pairs section, choose Edit.
-
You can add a key-value pair, delete a key-value pair, or change the value for an existing key-value pair.
-
When you're finished, choose Save changes.
About the CloudFront KeyValueStore
Tip
The CloudFront KeyValueStore API is a global service that uses Signature Version 4A (SigV4A) for authentication. Using temporary credentials with SigV4A requires version 2 session tokens. For more information, see Using temporary credentials with the CloudFront KeyValueStore API.
If you're using the AWS Command Line Interface (AWS CLI) or your own code to call the CloudFront KeyValueStore API, see the following sections.
When you work with a key value store and its key-value pairs, the service that you call depends on your use case:
-
To work with key-value pairs in an existing key value store, use the CloudFront KeyValueStore service.
-
To include key-value pairs in the key value store when you initially create the key value store, use the CloudFront service.
Both the CloudFront API and the CloudFront KeyValueStore API have a DescribeKeyValueStore
operation. You call them for different reasons. To understand the differences, see
the following table.
CloudFront DescribeKeyValueStore API | CloudFront KeyValueStore DescribeKeyValueStore API | |
---|---|---|
Data about the key value store |
Returns data, such as the status and the date that the key value store itself was last modified. |
Returns data about the contents of the storage resource – the key-value pairs in the store, and the size of the contents. |
Data that identifies the key value store |
Returns an |
Returns an |
Notes
-
Each DescribeKeyValueStore operation returns a different
ETag
. TheETags
aren't interchangeable. -
When you call an API operation to complete an action, you must specify the
ETag
from the appropriate API. For example, in the CloudFront KeyValueStore DeleteKey operation, you specify theETag
that you returned from the CloudFront KeyValueStore DescribeKeyValueStore operation.
Work with key-value pairs (AWS CLI)
You can run the following AWS Command Line Interface commands for CloudFront KeyValueStore.
Contents
List key-value pairs
To list key-value pairs in your key value store, run the following command.
aws cloudfront-keyvaluestore list-keys \ --kvs-arn=arn:aws:cloudfront::123456789012:key-value-store/37435e19-c205-4271-9e5c-example
Response
{ "Items": [ { "Key": "key1", "Value": "value1" } ] }
Get key-value pairs
To get a key-value pair in your key value store, run the following command.
aws cloudfront-keyvaluestore get-key \ --key=key1 \ --kvs-arn=arn:aws:cloudfront::123456789012:key-value-store/37435e19-c205-4271-9e5c-example
Response
{ "Key": "key1", "Value": "value1", "ItemCount": 1, "TotalSizeInBytes": 11 }
Describe a key value store
To describe a key value store, run the following command.
aws cloudfront-keyvaluestore describe-key-value-store \ --kvs-arn=arn:aws:cloudfront::123456789012:key-value-store/37435e19-c205-4271-9e5c-example
Response
{ "ETag": "KV1F83G8C2ARO7P", "ItemCount": 1, "TotalSizeInBytes": 11, "KvsARN": "arn:aws:cloudfront::123456789012:key-value-store/37435e19-c205-4271-9e5c-example", "Created": "2024-05-08T07:48:45.381000-07:00", "LastModified": "2024-08-05T13:50:58.843000-07:00", "Status": "READY" }
Create a key-value pair
To create a key-value pair in your key value store, run the following command.
aws cloudfront-keyvaluestore put-key \ --if-match=KV1PA6795UKMFR9 \ --key=key2 \ --value=value2 \ --kvs-arn=arn:aws:cloudfront::123456789012:key-value-store/37435e19-c205-4271-9e5c-example
Response
{ "ETag": "KV13V1IB3VIYZZH", "ItemCount": 3, "TotalSizeInBytes": 31 }
Delete a key-value pair
To delete a key-value pair, run the following command.
aws cloudfront-keyvaluestore delete-key \ --if-match=KV13V1IB3VIYZZH \ --key=key1 \ --kvs-arn=arn:aws:cloudfront::123456789012:key-value-store/37435e19-c205-4271-9e5c-example
Output
{ "ETag": "KV1VC38T7YXB528", "ItemCount": 2, "TotalSizeInBytes": 22 }
Update key-value pairs
You can use the update-keys
command to update more than one
key-value pair. For example, to delete an existing key-value pair and create
another one, run the following command.
aws cloudfront-keyvaluestore update-keys \ --if-match=KV2EUQ1WTGCTBG2 \ --kvs-arn=arn:aws:cloudfront::123456789012:key-value-store/37435e19-c205-4271-9e5c-example \ --deletes '[{"Key":"key2"}]' \ --puts '[{"Key":"key3","Value":"value3"}]'
Response
{ "ETag": "KV3AEGXETSR30VB", "ItemCount": 3, "TotalSizeInBytes": 28 }
Work with key-value pairs (API)
Follow this section to work with your key-value pairs programatically.
Contents
Get a reference to a key value store
When you use the CloudFront KeyValueStore API to call a write operation, you need to specify
the ARN and the ETag
of the key value store. To get this data, do
the following:
To get a reference to a key value store
-
Use the CloudFront ListKeyValueStores API operation to get a list of key value stores. Find the key value store that you want to change.
-
Use the CloudFrontKeyValueStore DescribeKeyValueStore API operation and specify the key value store from the previous step.
The response includes the ARN and the
ETag
of the key value store.-
The ARN includes the AWS account number, the constant
key-value-store
, and the UUID, such as the following example:arn:aws:cloudfront::123456789012:key-value-store/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111
-
An
ETag
that looks like the following example:ETVABCEXAMPLE2
-
Change key-value pairs in a key value store
You can specify the key value store that contains the key-value pair that you want to update.
See the following CloudFront KeyValueStore API operations:
-
CloudFrontKeyValueStore DeleteKey – Deletes a key-value pair
-
CloudFrontKeyValueStore GetKey – Returns a key-value pair
-
CloudFrontKeyValueStore ListKeys – Returns a list of key-value pairs
-
CloudFrontKeyValueStore PutKey – You can perform the following tasks:
-
Create a key-value pair in one key value store by specifying a new key name and value.
-
Set a different value in an existing key-value pair by specifying an existing key name, and a new key value.
-
-
CloudFrontKeyValueStore UpdateKeys – You can perform one or more of the following actions in one all-or-nothing operation:
-
Delete one or more key-value pairs
-
Create one or more new key-value pairs
-
Set a different value in one or more existing key-value pairs
-
Example code for CloudFront KeyValueStore
The following code shows you how to call the
DescribeKeyValueStore
API operation for a
key value store.
const { CloudFrontKeyValueStoreClient, DescribeKeyValueStoreCommand, } = require("@aws-sdk/client-cloudfront-keyvaluestore"); require("@aws-sdk/signature-v4-crt"); (async () => { try { const client = new CloudFrontKeyValueStoreClient({ region: "us-east-1" }); const input = { KvsARN: "arn:aws:cloudfront::123456789012:key-value-store/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", }; const command = new DescribeKeyValueStoreCommand(input); const response = await client.send(command); } catch (e) { console.log(e); } })();