# Amazon CloudFront KeyValueStore
CloudFront KeyValueStore is a secure, global, low-latency key value datastore that allows read access from within [CloudFront Functions](cloudfront-functions.md), enabling advanced customizable logic at the CloudFront edge locations.
With CloudFront KeyValueStore, you make updates to function code and updates to the data associated with a function independently of each other. This separation simplifies function code and makes it easy to update data without the need to deploy code changes.
**Note**
To use CloudFront KeyValueStore, your CloudFront function must use [JavaScript runtime 2.0](functions-javascript-runtime-20.md).
The following is the general procedure for using key-value pairs:
+ Create key value stores, and populate it with a set of key-value pairs. You can add your key value stores to an Amazon S3 bucket or enter them manually.
+ Associate the key value stores with your CloudFront function.
+ Within your function code, use the name of the key to either retrieve the value associated with the key or to evaluate if a key exists. For more information about using key-value pairs in function code, and about helper methods, see [Helper methods for key value stores](functions-custom-methods.md).
## Use cases
You can use key-value pairs for the following examples:
+ **URL rewrites or redirects **– The key-value pair can hold the rewritten URLs or the redirect URLs.
+ **A/B testing and feature flags **– You can create a function to run experiments by assigning a percentage of traffic to a specific version of your website.
+ **Access authorization** – You can implement access control to allow or deny requests based on criteria defined by you and the data stored in a key value store.
## Supported formats for values
You can store the value in a key-value pair in any of the following formats:
+ String
+ Byte-encoded string
+ JSON
## Security
The CloudFront function and all its key value stores data are handled securely, as follows:
+ CloudFront encrypts each key value stores at rest and during transit (when reading or writing to the key value stores) when you call the [CloudFront KeyValueStore](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_Operations_Amazon_CloudFront_KeyValueStore.html) API operations.
+ When the function is run, CloudFront decrypts each key-value pair in memory at the CloudFront edge locations.
To get started with CloudFront KeyValueStore, see the following topics.
**Topics**
+ [
## Use cases
](#key-value-store-use-cases)
+ [
## Supported formats for values
](#key-value-store-supported-formats)
+ [
## Security
](#key-value-store-security)
+ [
# Work with key value store
](kvs-with-functions-kvs.md)
+ [
# Work with key value data
](kvs-with-functions-kvp.md)
+ For more information about getting started with CloudFront KeyValueStore, see the [Introducing Amazon CloudFront KeyValueStore](https://aws.amazon.com/blogs/aws/introducing-amazon-cloudfront-keyvaluestore-a-low-latency-datastore-for-cloudfront-functions/) AWS blog post.
# Work with key value store
You must create a key value store to hold the key-value pairs that you want to use in CloudFront Functions.
After you create the key value stores and added key-value pairs, you can use the key values in your CloudFront function code.
To get started, see the following topics:
**Topics**
+ [
# Create a key value store
](kvs-with-functions-create.md)
+ [
# Associate a key value store with a function
](kvs-with-functions-associate.md)
+ [
# Update a key value store
](kvs-with-functions-edit.md)
+ [
# Get a reference to a key value store
](kvs-with-functions-get-reference.md)
+ [
# Delete a key value store
](kvs-with-functions-delete.md)
+ [
# File format for key-value pairs
](kvs-with-functions-create-s3-kvp.md)
**Note**
The JavaScript runtime 2.0 includes some helper methods for working with key values in the function code. For more information, see [Helper methods for key value stores](functions-custom-methods.md).
# Create a key value store
You can create a key value store and its key-value pairs at the same time. You can also create an empty key value store now and then add the key-value pairs later.
**Note**
If you specify your data source from an Amazon S3 bucket, you must have the `s3:GetObject` and `s3:GetBucketLocation` permissions to that bucket. If you don't have these permissions, CloudFront can't successfully create your key value store.
Decide if you want to add key-value pairs at the same time when you create the key value store. You can import your key-value pairs by using the CloudFront console, CloudFront API, or AWS SDKs. However, you can only import your file of key-value pairs when you *initially* create the key value store.
To create a file of key-value pairs, see [File format for key-value pairs](kvs-with-functions-create-s3-kvp.md).
------
#### [ Console ]
**To create a key value store**
1. 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](https://console.aws.amazon.com/cloudfront/v4/home#/functions).
1. Choose the **KeyValueStores** tab, and then choose **Create KeyValueStore**.
1. Enter a name and optional description for the key value store.
1. Complete **S3 URI**:
+ If you have a file of key-value pairs, enter the path to the Amazon S3 bucket where you stored the file.
+ Leave this field blank if you plan to enter the key-value pairs manually.
1. Choose **Create**. The key value store now exists.
The details page for the new key value store appears. The information on the page includes the ID and the ARN of the key value store.
+ The ID is a random string of characters that is unique in your AWS account.
+ The ARN has this syntax:
*AWS account*`:key-value-store/`*the key value stores ID*
1. Look at the **Key value pairs** section. If you imported a file, this section shows some key-value pairs. You can do the following:
+ If you imported a file, you can also add more values manually.
+ If you didn't import a file from an Amazon S3 bucket, and if you want to add key-value pairs now, you can complete the next step.
+ You can skip this step and add the key-value pairs later.
1. To add the pairs now:
1. Choose **Add key-value pairs**.
1. Choose **Add pair** and enter a name and value. Repeat this step to add more pairs.
1. When you're finished, choose **Save changes** to save all the key-value pairs in the key value store. On the dialog box that appears, choose **Done**.
1. To associate the key value store with a function now, complete the **Associated functions** section. For more information, see [Create functions](create-function.md) or [Update functions](update-function.md).
You can also associate the function later, either from this key value store details page, or from the function's details page.
------
#### [ AWS CLI ]
**To create a key value store**
+ Run the following command to create a key value store and import the key-value pairs from an Amazon S3 bucket.
```
aws cloudfront create-key-value-store \
--name=keyvaluestore1 \
--comment="This is my key value store file" \
--import-source=SourceType=S3,SourceARN=arn:aws:s3:::amzn-s3-demo-bucket1/kvs-input.json
```
**Response**
```
{
"ETag": "ETVABCEXAMPLE",
"Location": "https://cloudfront.amazonaws.com/2020-05-31/key-value-store/arn:aws:cloudfront::123456789012:key-value-store/8aa76c93-3198-462c-aaf6-example",
"KeyValueStore": {
"Name": "keyvaluestore1",
"Id": "8aa76c93-3198-462c-aaf6-example",
"Comment": "This is my key value store file",
"ARN": "arn:aws:cloudfront::123456789012:key-value-store/8aa76c93-3198-462c-aaf6-example",
"Status": "PROVISIONING",
"LastModifiedTime": "2024-08-06T22:19:10.813000+00:00"
}
}
```
------
#### [ API ]
**To create a key value store**
1. Use the [CloudFront CreateKeyValueStore](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_CreateKeyValueStore.html) operation. The operation takes several parameters:
+ A `name` of the key value store.
+ A `comment` parameter that includes a comment.
+ An `import-source` parameter that lets you import key-value pairs from a file that is stored in an Amazon S3 bucket. You can import from a file only when you first create the key value store. For information about the file structure, see [File format for key-value pairs](kvs-with-functions-create-s3-kvp.md).
The operation response includes the following information:
+ The values passed in the request, including the name that you assigned.
+ Data such as the creation time.
+ An `ETag` (for example, `ETVABCEXAMPLE`), the ARN that includes the name of the key value store (for example, `arn:aws:cloudfront::123456789012:key-value-store/keyvaluestore1`).
You will use some combination of the `ETag`, the ARN, and the name to work with the key value store programmatically.
------
## Key value store statuses
When you create a key value store, the data store can have the following status values.
****
| Value | Description |
| --- | --- |
| **Provisioning** | The key value store was created and CloudFront is processing the data source that you specified. |
| **Ready** | The key value store was created and CloudFront successfully processed the data source that you specified. |
| **Import failed** | CloudFront wasn't able to process the data source that you specified. This status can appear if your file format isn't valid or that it exceeds the size limit. For more information, see [File format for key-value pairs](kvs-with-functions-create-s3-kvp.md). |
# Associate a key value store with a function
After you create your key value store, you can update your function to associate it with your key value store. You must make this association to use the key-value pairs from that store in that function. The following rules apply:
+ A function can have only one key value store
+ You can associate the same key value store with multiple functions
------
#### [ Console ]
**To associate a key value store with a function**
1. Sign in to the CloudFront console at [https://console.aws.amazon.com/cloudfront/v4/home#/functions](https://console.aws.amazon.com/cloudfront/v4/home#/functions) and choose the **Functions** page.
1. Choose the function name.
1. Go to the **Associate KeyValueStore** section and choose **Associate existing KeyValueStore**.
1. Select the key value store that contains the key-value pairs in the function, and then choose **Associate KeyValueStore**.
CloudFront immediately associates the store with the function. You don't need to save the function.
1. To specify a different key value store, choose **Update associated KeyValueStore**, select another key value store name, and then choose **Associate KeyValueStore**.
For more information, see [Update functions](update-function.md).
------
#### [ AWS CLI ]
**To associate a key value store with a function**
+ Run the following command to update the `MaxAge` function and associate a key value store resource.
```
aws cloudfront update-function \
--name MaxAge \
--function-config '{"Comment":"Max Age 2 years","Runtime":"cloudfront-js-2.0","KeyValueStoreAssociations":{"Quantity":1,"Items":[{"KeyValueStoreARN":"arn:aws:cloudfront::123456789012:key-value-store/8aa76c93-3198-462c-aaf6-example"}]}}' \
--function-code fileb://function-max-age-v1.js \
--if-match ETVABCEXAMPLE
```
+ To associate a key value store with a function, specify the `KeyValueStoreAssociations` parameter and the key value store ARN.
+ To change the association, specify another key value store ARN.
+ To remove the association, remove the `KeyValueStoreAssociations` parameter.
For more information, see [Update functions](update-function.md).
------
#### [ API ]
**To associate a key value store with a function**
+ Use the [UpdateFunction](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_UpdateFunction.html) API operation. For more information, see [Update functions](update-function.md).
------
**Notes**
If you modify a key value store without changing the key-value pairs, or if you only modify the key-value pairs in the key value store, you don't need to associate the key value store again. You also don't need to republish the function.
However, we recommend that you test the function to verify that it works as expected. For more information, see [Test functions](test-function.md).
You can view all the functions that use specific key value stores. On the CloudFront console, choose the key value store details page.
# Update a key value store
When you update a key value store, you can change the key-value pairs, or change the association between the key value store and the function.
------
#### [ Console ]
**To update a key value store**
1. 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](https://console.aws.amazon.com/cloudfront/v4/home#/functions).
1. Choose the **KeyValueStores** tab.
1. Select the key value store that you want to update.
+ To update the key-value pairs, choose **Edit** in the **Key value pairs** section. You can add or delete any key-value pairs. You can also change the value for an existing key-value pair. When you're finished, choose **Save changes**.
+ To update the association for this key value store, choose **Go to functions**. For more information, see [Associate a key value store with a function](kvs-with-functions-associate.md).
------
#### [ AWS CLI ]
**To update a key value store**
1. **Change the key-value pairs** – You can add more key-value pairs, delete one or more key-value pairs, and change the value of an existing key-value pair. For more information, see [Work with key value data](kvs-with-functions-kvp.md).
1. **Change the function association for the key value store ** – To update the function the association for the key value store, see [Associate a key value store with a function](kvs-with-functions-associate.md).
**Tip**
You will need the ARN of the key value store. For more information, see [Get a reference to a key value store](kvs-with-functions-get-reference.md).
------
#### [ API ]
**To update a key value store**
1. **Change the key-value pairs** – You can add more key-value pairs, delete one or more key-value pairs, and change the value of an existing key-value pair. For more information, see [Work with key value data](kvs-with-functions-kvp.md).
1. **Change the function association for the key value store** – To update the function association for the key value store, use the [UpdateFunction](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_UpdateFunction.html) API operation. For more information, see [Update functions](update-function.md).
**Tip**
You will need the ARN of the key value store. For more information, see [Get a reference to a key value store](kvs-with-functions-get-reference.md).
------
# Get a reference to a key value store
To work with the key value stores programmatically, you need the `ETag` and the name of the key value store.
To get both values, you can use the AWS Command Line Interface (AWS CLI) or the CloudFront API.
------
#### [ AWS CLI ]
**To get the key value store reference**
1. To return a list of key value stores, run the following command Find the name of the key value store that you want to change.
```
aws cloudfront list-key-value-stores
```
1. From the response, find the name of the key value store that you want.
**Response**
```
{
"KeyValueStoreList": {
"Items": [
{
"Name": "keyvaluestore3",
"Id": "37435e19-c205-4271-9e5c-example3",
"ARN": "arn:aws:cloudfront::123456789012:key-value-store/37435e19-c205-4271-9e5c-example3",
"Status": "READY",
"LastModifiedTime": "2024-05-08T14:50:18.876000+00:00"
},
{
"Name": "keyvaluestore2",
"Id": "47970d59-6408-474d-b850-example2",
"ARN": "arn:aws:cloudfront::123456789012:key-value-store/47970d59-6408-474d-b850-example2",
"Status": "READY",
"LastModifiedTime": "2024-05-30T21:06:22.113000+00:00"
},
{
"Name": "keyvaluestore1",
"Id": "8aa76c93-3198-462c-aaf6-example",
"ARN": "arn:aws:cloudfront::123456789012:key-value-store/8aa76c93-3198-462c-aaf6-example",
"Status": "READY",
"LastModifiedTime": "2024-08-06T22:19:30.510000+00:00"
}
]
}
}
```
1. Run the following command to return the `ETag` for the specified key value store.
```
aws cloudfront describe-key-value-store \
--name=keyvaluestore1
```
**Response**
```
{
"ETag": "E3UN6WX5RRO2AG",
"KeyValueStore": {
"Name": "keyvaluestore1",
"Id": "8aa76c93-3198-462c-aaf6-example",
"Comment": "This is an example KVS",
"ARN": "arn:aws:cloudfront::123456789012:key-value-store/8aa76c93-3198-462c-aaf6-example",
"Status": "READY",
"LastModifiedTime": "2024-08-06T22:19:30.510000+00:00"
}
}
```
------
#### [ API ]
**To get the key value store reference**
1. Use the [https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_ListKeyValueStores.html](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_ListKeyValueStores.html) API operation to return a list of key value stores. Find the name of the key value store that you want to change.
1. Use the [https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_DescribeKeyValueStore.html](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_DescribeKeyValueStore.html) API operation and specify the name of the key value store that you returned from the previous step.
------
The response includes a UUID, the ARN of the key value store, and the `ETag` of the key value store.
+ An `ETag`, such as `E3UN6WX5RRO2AG`
+ The UUID is 128 bits, such as `8aa76c93-3198-462c-aaf6-example`
+ The ARN includes the AWS account number, the constant `key-value-store`, and the UUID, like the following example:
`arn:aws:cloudfront::123456789012:key-value-store/8aa76c93-3198-462c-aaf6-example`
For more information about the `DescribeKeyValueStore` operation, see [About the CloudFront KeyValueStore](kvs-with-functions-kvp.md#kvs-with-functions-api-describe).
# Delete a key value store
You can delete your key value store by using the Amazon CloudFront console or API.
------
#### [ Console ]
**To delete a key value store**
1. 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](https://console.aws.amazon.com/cloudfront/v4/home#/functions).
1. Choose the function name.
1. Under the **Associated KeyValueStore** section, verify if a key value store is associated with the function. If it is, remove the association by choosing **Disassociate KeyValueStore** and then choose **Remove association**.
1. In the navigation pane, choose the **Functions** page and then choose the **KeyValueStores** tab.
1. Select the key value store that you want to delete and then choose **Delete**.
------
#### [ AWS CLI ]
**To delete a key value store**
1. Get the `ETag` and the name of the key value stores. For more information, see [Get a reference to a key value store](kvs-with-functions-get-reference.md).
1. Verify if the key value stores is associated with a function. If it is, remove the association. For more information on both these steps, see [Update functions](update-function.md).
1. After you have the name and `ETag` of the key value store and it's no longer associated with a function, you can delete it.
Run the following command to delete the specified key value store.
```
aws cloudfront delete-key-value-store \
--name=keyvaluestore1 \
--if-match=E3UN6WX5RRO2AG
```
------
#### [ API ]
**To delete a key value store**
1. Get the `ETag` and the name of the key value stores. For more information, see [Get a reference to a key value store](kvs-with-functions-get-reference.md).
1. Verify if the key value stores is associated with a function. If it is, remove the association. For more information on both these steps, see [Update functions](update-function.md).
1. To delete the key value store, use the CloudFront [https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_DeleteKeyValueStore.html](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_DeleteKeyValueStore.html) API operation.
------
# File format for key-value pairs
When you create a UTF-8 encoded file, use the following JSON format:
```
{
"data":[
{
"key":"key1",
"value":"value"
},
{
"key":"key2",
"value":"value"
}
]
}
```
Your file can't include duplicate keys. If you specified an invalid file in your Amazon S3 bucket, you can update the file to remove any duplicates and then try creating your key value store again.
For more information, see [Create a key value store](kvs-with-functions-create.md).
**Note**
The file for your data source and its key-value pairs have the following limits:
File size – 5 MB
Key size – 512 characters
Value size – 1024 characters
# 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](kvs-with-functions-create.md).
**Topics**
+ [
## Work with key-value pairs (console)
](#kvs-with-functions-kvp-using-console)
+ [
## About the CloudFront KeyValueStore
](#kvs-with-functions-api-describe)
+ [
## Work with key-value pairs (AWS CLI)
](#work-with-kvs-cli-keys)
+ [
## Work with key-value pairs (API)
](#kvs-with-functions-kvp-using-api)
## 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**
1. 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](https://console.aws.amazon.com/cloudfront/v4/home#/functions).
1. Choose the **KeyValueStores** tab.
1. Select the key value store that you want to change.
1. In the **Key value pairs** section, choose **Edit**.
1. You can add a key-value pair, delete a key-value pair, or change the value for an existing key-value pair.
1. 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](cloudfront-function-restrictions.md#regional-endpoint-for-key-value-store).
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 `ETag`, the UUID, and the ARN of the key value store. | Returns an `ETag` and the ARN of the key value store. |
**Notes**
Each DescribeKeyValueStore operation returns a *different * `ETag`. The `ETags` 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](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_DeleteKey.html) operation, you specify the `ETag` that you returned from the CloudFront KeyValueStore [https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_DescribeKeyValueStore.html](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_DescribeKeyValueStore.html) operation.
When you invoke your CloudFront Functions by using CloudFront KeyValueStore, the values in the key value store aren't updated or changed during the invocation of the function. Updates are processed in between invocations of a function.
## 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
](#kvs-cli-list-keys)
+ [
### Get key-value pairs
](#kvs-cli-get-keys)
+ [
### Describe a key value store
](#kvs-cli-describe-keys)
+ [
### Create a key-value pair
](#kvs-cli-create-keys)
+ [
### Delete a key-value pair
](#kvs-cli-delete-keys)
+ [
### Update key-value pairs
](#kvs-cli-update-key)
### 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
](#kvs-with-functions-api-ref)
+ [
### Change key-value pairs in a key value store
](#kvs-with-functions-api-actions)
+ [
### Example code for CloudFront KeyValueStore
](#example-code-key-value-store)
### 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**
1. Use the [https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_ListKeyValueStores.html](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_ListKeyValueStores.html) API operation to get a list of key value stores. Find the key value store that you want to change.
1. Use the [CloudFrontKeyValueStore DescribeKeyValueStore API operation](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_DescribeKeyValueStore.html) 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](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_DeleteKey.html) – Deletes a key-value pair
+ [CloudFrontKeyValueStore GetKey](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_GetKey.html) – Returns a key-value pair
+ [CloudFrontKeyValueStore ListKeys](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_ListKeys.html) – Returns a list of key-value pairs
+ [CloudFrontKeyValueStore PutKey](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_PutKey.html) – 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](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_UpdateKeys.html) – 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
**Example**
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);
}
})();
```