# Amazon CloudFront KeyValueStore
<a name="kvs-with-functions"></a>

CloudFront KeyValueStore 是一个安全、全局、低延迟的键值数据存储，允许从 [CloudFront Functions](cloudfront-functions.md) 内部进行读取访问，从而在 CloudFront 边缘站点实现高级可自定义逻辑。

使用 CloudFront KeyValueStore，您可以对函数代码进行更新，并对与该函数关联的数据进行相互独立的更新。这种分离简化了函数代码，并且无需部署代码更改即可轻松更新数据。

**注意**  
要使用 CloudFront keyValueStore，您的 CloudFront 函数必须使用 [JavaScript 运行时 2.0](functions-javascript-runtime-20.md)。

下面是使用键值对的一般过程：
+ 创建键值存储，并在其中填充一组键值对。您可以将键值存储添加到 Amazon S3 存储桶中，也可以手动输入。
+ 将键值存储与您的 CloudFront 函数相关联。
+ 在函数代码中，使用键的名称来检索与键关联的值或评估该键是否存在。有关在函数代码中使用键值对以及有关助手方法的更多信息，请参阅[键值存储的帮助程序方法](functions-custom-methods.md)。

## 使用案例
<a name="key-value-store-use-cases"></a>

您可以对以下示例使用键值对：
+ **URL 重写或重定向** – 键值对可以保存重写的 URL 或重定向 URL。
+ **A/B 测试和功能标志** – 您可以通过为网站的特定版本分配一定比例的流量来创建运行实验的函数。
+ **访问授权** – 您可以实施访问控制，根据您定义的标准和存储在键值存储中的数据来允许或拒绝请求。

## 支持的值格式
<a name="key-value-store-supported-formats"></a>

您可以采用以下任一格式存储键值对中的值：
+ 字符串
+ 字节编码的字符串
+ JSON 

## 安全性
<a name="key-value-store-security"></a>

CloudFront 函数及其所有键值存储数据均能得到安全处理，如下所示：
+ CloudFront 会在您调用 [CloudFront KeyValueStore](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_Operations_Amazon_CloudFront_KeyValueStore.html) API 操作时，在处于静态或在传输过程中（读取或写入键值存储时），对每个键值存储进行加密。
+ 在函数运行时，CloudFront 会在 CloudFront 边缘站点对内存中的每个键值对进行解密。

要开始使用 CloudFront KeyValueStore，请参阅以下主题。

**Topics**
+ [使用案例](#key-value-store-use-cases)
+ [支持的值格式](#key-value-store-supported-formats)
+ [安全性](#key-value-store-security)
+ [使用键值存储](kvs-with-functions-kvs.md)
+ [处理键值数据](kvs-with-functions-kvp.md)
+ 有关 CloudFront KeyValueStore 入门的更多信息，请参阅 [Amazon CloudFront KeyValueStore](https://aws.amazon.com/blogs/aws/introducing-amazon-cloudfront-keyvaluestore-a-low-latency-datastore-for-cloudfront-functions/) AWS 博客文章。

# 使用键值存储
<a name="kvs-with-functions-kvs"></a>

您必须创建一个键值存储来保存要在 CloudFront Functions 中使用的键值对。

创建键值存储并添加键值对后，即可在 CloudFront 函数代码中使用键值。

要开始使用，请参阅以下主题：

**Topics**
+ [创建键值存储](kvs-with-functions-create.md)
+ [将键值存储与函数相关联](kvs-with-functions-associate.md)
+ [更新键值存储](kvs-with-functions-edit.md)
+ [获取对键值存储的引用](kvs-with-functions-get-reference.md)
+ [删除键值存储](kvs-with-functions-delete.md)
+ [键值对的文件格式](kvs-with-functions-create-s3-kvp.md)

**注意**  
JavaScript 运行时 2.0 包含一些用于在函数代码中处理键值的帮助程序方法。有关更多信息，请参阅 [键值存储的帮助程序方法](functions-custom-methods.md)。

# 创建键值存储
<a name="kvs-with-functions-create"></a>



您可以同时创建键值存储及其键值对。您还可以立即创建一个空的键值存储，稍后再添加键值对。

**注意**  
如果您指定来自 Amazon S3 存储桶的数据来源，则必须对该存储桶具有 `s3:GetObject` 和 `s3:GetBucketLocation` 权限。如果您没有这些权限，CloudFront 将无法成功创建键值存储。

决定是否要在创建键值存储的同时添加键值对。可以使用 CloudFront 控制台、CloudFront API 或 AWS SDK 导入键值对。但是，您只能在*最初* 创建键值存储时导入键值对的文件。

要创建键值对的文件，请参阅[键值对的文件格式](kvs-with-functions-create-s3-kvp.md)。

------
#### [ Console ]

**创建键值存储**

1. 登录到 AWS 管理控制台 并通过以下网址打开 CloudFront 控制台中的**函数**页面：[https://console.aws.amazon.com/cloudfront/v4/home#/functions](https://console.aws.amazon.com/cloudfront/v4/home#/functions)。

1. 选择 **KeyValueStores** 选项卡，然后选择**创建 KeyValueStore**。

1. 输入键值存储的名称和可选描述。

1. 填写 **S3 URI**：
   + 如果您有一个键值对文件，请输入存储该文件的 Amazon S3 存储桶的路径。
   + 如果您打算手动输入键值对，请将此字段留空。

1. 选择**创建**。键值存储现已存在。

   此时将显示新键值存储的详细信息页面。页面上的信息包括键值存储的 ID 和 ARN。
   + ID 是一个随机字符串，在您的 AWS 账户中是唯一的。
   + ARN 的语法如下：

     *AWS 账户*`:key-value-store/`*键值存储 ID*

1. 查看**键值对**部分。如果您导入了文件，则此部分会显示一些键值对。您可执行以下操作：
   + 如果您导入了文件，还可以手动添加更多值。
   + 如果您没有从 Amazon S3 存储桶导入文件，但却想要立即添加键值对，则可以完成下一步。
   + 您可以跳过此步骤，稍后再添加键值对。

1. 立即添加键值对：

   1. 选择**添加键值对**。

   1. 选择**添加对**并输入名称和值。重复此步骤以添加更多键值对。

   1. 完成后，选择**保存更改**，将所有键值对保存在键值存储中。在随后显示的对话框中，选择**完成**。

1. 要将键值存储立即与函数关联，请完成**关联的函数**部分。有关更多信息，请参阅[创建函数](create-function.md)或[更新函数](update-function.md)。

   您也可以稍后通过此键值存储详细信息页面或通过函数的详细信息页面关联函数。

------
#### [ AWS CLI ]

**创建键值存储**
+ 运行以下命令来创建键值存储并从 Amazon S3 存储桶导入键值对。

  ```
  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
  ```

  **响应**

  ```
  {
      "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 ]

**创建键值存储**

1. 使用 [CloudFront CreateKeyValueStore](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_CreateKeyValueStore.html) 操作。该操作需要几个参数：
   + 键值存储的 `name`。
   + 包含注释的 `comment` 参数。
   + 一个 `import-source` 参数，允许您从存储在 Amazon S3 存储桶中的文件中导入键值对。只有在您首次创建键值存储时，才能从文件导入。有关文件结构的信息，请参阅[键值对的文件格式](kvs-with-functions-create-s3-kvp.md)。

操作响应包含以下信息：
+ 请求中传递的值，包括您分配的名称。
+ 诸如创建时间之类的数据。
+ `ETag`（例如 `ETVABCEXAMPLE`），即包含键值存储名称的 ARN（例如 `arn:aws:cloudfront::123456789012:key-value-store/keyvaluestore1`）。

  您将使用 `ETag`、ARN 和名称的某种组合以编程方式使用键值存储。

------

## 键值存储状态
<a name="key-value-store-status"></a>

创建键值存储时，数据存储可以具有以下状态值。


****  

| 值 | 说明 | 
| --- | --- | 
|  **预置**  |  键值存储已创建，CloudFront 正在处理您指定的数据来源。  | 
|  **就绪**  |  键值存储已创建，CloudFront 成功处理了您指定的数据来源。  | 
|  **导入失败**  |  CloudFront 无法处理您指定的数据来源。如果您的文件格式无效或超过大小限制，则会显示此状态。有关更多信息，请参阅 [键值对的文件格式](kvs-with-functions-create-s3-kvp.md)。  | 

# 将键值存储与函数相关联
<a name="kvs-with-functions-associate"></a>

创建密钥值存储后，您可以更新您的函数以将其与键值存储关联。必须进行此关联，才能在该函数中使用该存储中的键值对。以下规则适用：
+ 一个函数只能有一个键值存储。
+ 您可以将同一键值存储与多个函数关联

------
#### [ Console ]

**将键值存储与函数相关联**

1. 通过 [https://console.aws.amazon.com/cloudfront/v4/home#/functions](https://console.aws.amazon.com/cloudfront/v4/home#/functions) 登录到 CloudFront 控制台，然后选择**函数**页面。

1. 选择函数名称。

1. 转至**关联 KeyValueStore** 部分，选择**关联现有 KeyValueStore**。

1. 选择包含函数中键值对的键值存储，然后选择**关联 KeyValueStore**。

   CloudFront 会立即将存储与该函数关联。您无需保存此函数。

1. 要指定不同的键值存储，请选择**更新关联的 KeyValueStore**，选择另一个键值存储名称，然后选择**关联 KeyValueStore**。

有关更多信息，请参阅 [更新函数](update-function.md)。

------
#### [ AWS CLI ]

**将键值存储与函数相关联**
+ 运行以下命令来更新 `MaxAge` 函数并关联键值存储资源。

  ```
  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
  ```
+ 要将键值存储与函数相关联，请指定 `KeyValueStoreAssociations` 参数和键值存储 ARN。
+ 要更改关联，请指定其它键值存储 ARN。
+ 要取消关联，请移除 `KeyValueStoreAssociations` 参数。

有关更多信息，请参阅 [更新函数](update-function.md)。

------
#### [ API ]

**将键值存储与函数相关联**
+ 使用 [UpdateFunction](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_UpdateFunction.html) API 操作。有关更多信息，请参阅 [更新函数](update-function.md)。

------

**备注**  
如果修改键值存储而不更改键值对，或者只修改键值存储中的键值对，则无需再次关联键值存储。您也不需要重新发布该函数。  
不过，我们建议您对函数进行测试，验证它是否能正常工作。有关更多信息，请参阅 [测试函数](test-function.md)。
您可以查看使用特定键值存储的所有函数。在 CloudFront 控制台上，选择键值存储详细信息页面。

# 更新键值存储
<a name="kvs-with-functions-edit"></a>

更新键值存储时，您可以更改键值对，也可以更改键值存储和函数之间的关联。

------
#### [ Console ]

**更新键值存储**

1. 登录到 AWS 管理控制台 并通过以下网址打开 CloudFront 控制台中的**函数**页面：[https://console.aws.amazon.com/cloudfront/v4/home#/functions](https://console.aws.amazon.com/cloudfront/v4/home#/functions)。

1. 选择 **KeyValueStores** 选项卡。

1.  选择要更新的键值存储。
   + 要更新键值对，请在**键值对**部分中选择**编辑**。您可以添加或删除任何键值对。您也可以更改现有键值对的值。完成后，选择**保存更改**。
   + 要更新此键值存储的关联，请选择**转至函数**。有关更多信息，请参阅 [将键值存储与函数相关联](kvs-with-functions-associate.md)。

------
#### [ AWS CLI ]

**更新键值存储**

1. **更改键值对** – 您可以添加更多键值对，删除一个或多个键值对，以及更改现有键值对的值。有关更多信息，请参阅 [处理键值数据](kvs-with-functions-kvp.md)。

1. **更改键值存储的函数关联** - 要更新键值存储的函数关联，请参阅[将键值存储与函数相关联](kvs-with-functions-associate.md)。
**提示**  
您将需要键值存储的 ARN。有关更多信息，请参阅 [获取对键值存储的引用](kvs-with-functions-get-reference.md)。

------
#### [ API ]

**更新键值存储**

1. **更改键值对** – 您可以添加更多键值对，删除一个或多个键值对，以及更改现有键值对的值。有关更多信息，请参阅 [处理键值数据](kvs-with-functions-kvp.md)。

1. **更改键值存储的函数关联** - 要更新键值存储的函数关联，请使用 [UpdateFunction](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_UpdateFunction.html) API 操作。有关更多信息，请参阅 [更新函数](update-function.md)。
**提示**  
您将需要键值存储的 ARN。有关更多信息，请参阅 [获取对键值存储的引用](kvs-with-functions-get-reference.md)。

------

# 获取对键值存储的引用
<a name="kvs-with-functions-get-reference"></a>

为了以编程方式使用键值存储，您需要键值存储的 `ETag` 和名称。

要获得这两个值，可以使用 AWS Command Line Interface（AWS CLI）或 CloudFront API。

------
#### [ AWS CLI ]

**获取键值存储引用**

1. 要返回键值存储的列表，请运行以下命令，来查找要更改的键值存储的名称。

   ```
   aws cloudfront list-key-value-stores
   ```

1. 从响应中，找到您所需的键值存储的名称。

   **响应**

   ```
   {
       "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. 运行以下命令来返回指定键值存储的 `ETag`。

   ```
   aws cloudfront describe-key-value-store \
       --name=keyvaluestore1
   ```

   **响应**

   ```
   {
       "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 ]

**获取键值存储引用**

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. 使用 [https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_DescribeKeyValueStore.html](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_DescribeKeyValueStore.html) API 操作并指定您在上一步中返回的键值存储的名称。

------

响应包括 UUID、键值存储的 ARN 和键值存储的 `ETag`。
+ `ETag`，例如 `E3UN6WX5RRO2AG`
+ UUID 为 128 位，例如 `8aa76c93-3198-462c-aaf6-example`
+ ARN 包含 AWS 账户编号、常量 `key-value-store` 和 UUID，类似于以下示例：

  `arn:aws:cloudfront::123456789012:key-value-store/8aa76c93-3198-462c-aaf6-example`

有关 `DescribeKeyValueStore` 操作的更多信息，请参阅[关于 CloudFront KeyValueStore](kvs-with-functions-kvp.md#kvs-with-functions-api-describe)。

# 删除键值存储
<a name="kvs-with-functions-delete"></a>

您可以使用 Amazon CloudFront 控制台或 API 来删除键值存储。

------
#### [ Console ]

**删除键值存储**

1. 登录到 AWS 管理控制台 并通过以下网址打开 CloudFront 控制台中的**函数**页面：[https://console.aws.amazon.com/cloudfront/v4/home#/functions](https://console.aws.amazon.com/cloudfront/v4/home#/functions)。

1. 选择函数名称。

1. 在**关联 KeyValueStore** 部分下，验证某个键值存储是否与该函数关联。如果是，请依次选择**取消关联 KeyValueStore**和**删除关联**来删除关联。

1. 在导航窗格中，选择**函数**页面，然后选择 **KeyValueStores** 选项卡。

1. 选择要删除的键值存储，然后选择**删除**。

------
#### [ AWS CLI ]

**删除键值存储**

1. 获取键值存储的 `ETag` 和名称。有关更多信息，请参阅 [获取对键值存储的引用](kvs-with-functions-get-reference.md)。

1. 验证键值存储是否与函数相关联。如果关联，则取消关联。有关这两个步骤的更多信息，请参阅[更新函数](update-function.md)。

1. 在您有了键值存储的名称和 `ETag` 并且它不再与函数关联之后，可以将其删除。

   运行以下命令来删除指定的键值存储。

   ```
   aws cloudfront delete-key-value-store \
       --name=keyvaluestore1 \
       --if-match=E3UN6WX5RRO2AG
   ```

------
#### [ API ]

**删除键值存储**

1. 获取键值存储的 `ETag` 和名称。有关更多信息，请参阅 [获取对键值存储的引用](kvs-with-functions-get-reference.md)。

1. 验证键值存储是否与函数相关联。如果关联，则取消关联。有关这两个步骤的更多信息，请参阅[更新函数](update-function.md)。

1. 要删除键值存储，请使用 CloudFront [https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_DeleteKeyValueStore.html](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_DeleteKeyValueStore.html) API 操作。

------

# 键值对的文件格式
<a name="kvs-with-functions-create-s3-kvp"></a>

创建 UTF-8 编码文件时，请使用以下 JSON 格式：

```
{
  "data":[
    {
      "key":"key1",
      "value":"value"
    },
    {
      "key":"key2",
      "value":"value"
    }
  ]
}
```

您的文件不能包含重复键。如果您在 Amazon S3 存储桶中指定了无效文件，则可以更新该文件以删除所有重复项，然后再次尝试创建键值存储。

有关更多信息，请参阅 [创建键值存储](kvs-with-functions-create.md)。

**注意**  
您的数据来源文件及其键值对具有以下限制：  
文件大小 – 5 MB
键大小 – 512 个字符
值大小 – 1024 个字符

# 处理键值数据
<a name="kvs-with-functions-kvp"></a>

本主题介绍如何将键值对添加到现有的键值存储。要在最初创建键值存储时包含键值对，请参阅[创建键值存储](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)

## 使用键值对（控制台）
<a name="kvs-with-functions-kvp-using-console"></a>

您可以使用 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
<a name="kvs-with-functions-api-describe"></a>

**提示**  
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）
<a name="work-with-kvs-cli-keys"></a>

您可以为 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)

### 列出键值对
<a name="kvs-cli-list-keys"></a>

要列出键值存储中的键值对，请运行以下命令。

```
aws cloudfront-keyvaluestore list-keys \
    --kvs-arn=arn:aws:cloudfront::123456789012:key-value-store/37435e19-c205-4271-9e5c-example
```

**响应**

```
{
    "Items": [
        {
            "Key": "key1",
            "Value": "value1"
        }
    ]
}
```

### 获取键值对
<a name="kvs-cli-get-keys"></a>

要获取键值存储中的键值对，请运行以下命令。

```
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
}
```

### 描述键值存储
<a name="kvs-cli-describe-keys"></a>

要描述键值存储，请运行以下命令。

```
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"
}
```

### 创建键值对
<a name="kvs-cli-create-keys"></a>

要在键值存储中创建键值对，请运行以下命令。

```
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
}
```

### 删除键值对
<a name="kvs-cli-delete-keys"></a>

要删除键值对，请运行以下命令：

```
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
}
```

### 更新键值对
<a name="kvs-cli-update-key"></a>

可以使用 `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）
<a name="kvs-with-functions-kvp-using-api"></a>

请按照本节内容以编程方式处理键值对。

**Contents**
+ [获取对键值存储的引用](#kvs-with-functions-api-ref)
+ [更改键值存储中的键值对](#kvs-with-functions-api-actions)
+ [CloudFront KeyValueStore 代码示例](#example-code-key-value-store)

### 获取对键值存储的引用
<a name="kvs-with-functions-api-ref"></a>

使用 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`

### 更改键值存储中的键值对
<a name="kvs-with-functions-api-actions"></a>

您可以指定包含要更新的键值对的键值存储。

请参阅以下 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 代码示例
<a name="example-code-key-value-store"></a>

**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);
  }
})();
```