# 处理键值数据
本主题介绍如何将键值对添加到现有的键值存储。要在最初创建键值存储时包含键值对，请参阅[创建键值存储](kvs-with-functions-create.md)。
**Topics**
+ [使用键值对（控制台）](#kvs-with-functions-kvp-using-console)
+ [关于 CloudFront KeyValueStore](#kvs-with-functions-api-describe)
+ [使用键值对（AWS CLI）](#work-with-kvs-cli-keys)
+ [使用键值对（API）](#kvs-with-functions-kvp-using-api)
## 使用键值对（控制台）
您可以使用 CloudFront 控制台处理键值对。
**使用键值对**
1. 登录到 AWS 管理控制台 并通过以下网址打开 CloudFront 控制台中的**函数**页面：[https://console.aws.amazon.com/cloudfront/v4/home#/functions](https://console.aws.amazon.com/cloudfront/v4/home#/functions)。
1. 选择 **KeyValueStores** 选项卡。
1. 选择要更改的键值存储。
1. 在**键值对**部分，选择**编辑**。
1. 您可以添加键值对、删除键值对或更改现有键值对的值。
1. 完成后，选择**保存更改**。
## 关于 CloudFront KeyValueStore
**提示**
CloudFront KeyValueStore API 是一项使用签名版本 4A（SigV4A）进行身份验证的全局服务。在 SigV4A 中使用临时凭证需要版本 2 会话令牌。有关更多信息，请参阅 [将临时凭证与 CloudFront KeyValueStore API 结合使用](cloudfront-function-restrictions.md#regional-endpoint-for-key-value-store)。
如果您使用 AWS Command Line Interface（AWS CLI）或自己的代码调用 CloudFront KeyValueStore API，请参阅以下各节。
在使用键值存储及其键值对时，您调用的服务取决于您的使用案例：
+ 要在*现有* 键值存储中使用键值对，可以使用 CloudFront KeyValueStore 服务。
+ 要在*最初*创建键值存储时在键值存储中包含键值对，可以使用 CloudFront 服务。
CloudFront API 和 CloudFront KeyValueStore API 都有一项 `DescribeKeyValueStore` 操作。您出于不同的原因来调用它们。要了解差异，请参阅下表。
| | CloudFront DescribeKeyValueStore API | CloudFront KeyValueStore DescribeKeyValueStore API |
| --- | --- | --- |
| 有关键值存储的数据 | 返回数据，例如状态以及键值存储本身上次被修改的日期。 | 返回有关存储资源的*内容*的数据，即存储中的键值对以及内容的大小。 |
| 标识键值存储的数据 | 返回键值存储的 `ETag`、UUID 和 ARN。 | 返回键值存储的 `ETag` 和 ARN。 |
**备注**
每个 DescribeKeyValueStore 操作都会返回一个*不同的* `ETag`。`ETags` 不可互换。
当您调用 API 操作以完成某项操作时，您必须从相应的 API 指定 `ETag`。例如，在 CloudFront KeyValueStore [ DeleteKey](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_DeleteKey.html) 操作中，您可以指定从 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) 操作返回的 `ETag`。
当您使用 CloudFront KeyValueStore 调用 CloudFront Functions 时，在调用函数期间，不会更新或更改键值存储中的值。更新是在函数的两次调用之间进行处理的。
## 使用键值对（AWS CLI）
您可以为 CloudFront KeyValueStore 运行以下 AWS Command Line Interface 命令。
**Contents**
+ [列出键值对](#kvs-cli-list-keys)
+ [获取键值对](#kvs-cli-get-keys)
+ [描述键值存储](#kvs-cli-describe-keys)
+ [创建键值对](#kvs-cli-create-keys)
+ [删除键值对](#kvs-cli-delete-keys)
+ [更新键值对](#kvs-cli-update-key)
### 列出键值对
要列出键值存储中的键值对，请运行以下命令。
```
aws cloudfront-keyvaluestore list-keys \
--kvs-arn=arn:aws:cloudfront::123456789012:key-value-store/37435e19-c205-4271-9e5c-example
```
**响应**
```
{
"Items": [
{
"Key": "key1",
"Value": "value1"
}
]
}
```
### 获取键值对
要获取键值存储中的键值对，请运行以下命令。
```
aws cloudfront-keyvaluestore get-key \
--key=key1 \
--kvs-arn=arn:aws:cloudfront::123456789012:key-value-store/37435e19-c205-4271-9e5c-example
```
**响应**
```
{
"Key": "key1",
"Value": "value1",
"ItemCount": 1,
"TotalSizeInBytes": 11
}
```
### 描述键值存储
要描述键值存储，请运行以下命令。
```
aws cloudfront-keyvaluestore describe-key-value-store \
--kvs-arn=arn:aws:cloudfront::123456789012:key-value-store/37435e19-c205-4271-9e5c-example
```
**响应**
```
{
"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"
}
```
### 创建键值对
要在键值存储中创建键值对，请运行以下命令。
```
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
```
**响应**
```
{
"ETag": "KV13V1IB3VIYZZH",
"ItemCount": 3,
"TotalSizeInBytes": 31
}
```
### 删除键值对
要删除键值对，请运行以下命令：
```
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-keys` 命令来更新多个键值对。例如，要删除现有键值对并创建另一个键值对，请运行以下命令。
```
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"}]'
```
**响应**
```
{
"ETag": "KV3AEGXETSR30VB",
"ItemCount": 3,
"TotalSizeInBytes": 28
}
```
## 使用键值对（API）
请按照本节内容以编程方式处理键值对。
**Contents**
+ [获取对键值存储的引用](#kvs-with-functions-api-ref)
+ [更改键值存储中的键值对](#kvs-with-functions-api-actions)
+ [CloudFront KeyValueStore 代码示例](#example-code-key-value-store)
### 获取对键值存储的引用
使用 CloudFront KeyValueStore API 调用写入操作时，需要指定键值存储的 ARN 和 `ETag`。要获取此数据，请执行以下操作：
**获取对键值存储的引用**
1. 使用 [https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_ListKeyValueStores.html](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_ListKeyValueStores.html) API 操作获取键值存储列表。找到要更改的键值存储。
1. 使用 [CloudFrontKeyValueStore DescribeKeyValueStore API 操作](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_DescribeKeyValueStore.html)并指定上一步中返回的键值存储。
响应包括键值存储的 ARN 和 `ETag`。
+ ARN 包含 AWS 账户编号、常量 `key-value-store` 和 UUID，类似于以下示例：
`arn:aws:cloudfront::123456789012:key-value-store/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111`
+ 一个 `ETag`，类似于以下示例：
`ETVABCEXAMPLE2`
### 更改键值存储中的键值对
您可以指定包含要更新的键值对的键值存储。
请参阅以下 CloudFront keyValueStore API 操作：
+ [CloudFrontKeyValueStore DeleteKey](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_DeleteKey.html) – 删除键值对
+ [CloudFrontKeyValueStore GetKey](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_GetKey.html) – 返回键值对
+ [CloudFrontKeyValueStore ListKeys](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_ListKeys.html) – 返回键值对列表
+ [CloudFrontKeyValueStore PutKey](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_PutKey.html) – 您可以执行以下任务：
+ 通过指定新的键名和键值，在一个键值存储中创建键值对。
+ 通过指定现有键名和新键值，在现有键值对中设置不同的值。
+ [CloudFrontKeyValueStore UpdateKeys](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_UpdateKeys.html) –您可以通过一项“要么全有，要么全无”操作执行以下一项或多项操作：
+ 删除一个或多个键值对
+ 创建一个或多个新的键值对
+ 在一个或多个现有键值对中设置不同的值
### CloudFront KeyValueStore 代码示例
**Example**
以下代码演示了如何为键值存储调用 `DescribeKeyValueStore` API 操作。
```
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);
}
})();
```