本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用鍵值資料
本節說明如何將鍵值對新增至現有的鍵值存放區。若要在最初建立鍵值存放區時包含鍵值對，請參閱 [建立鍵值存放區](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 是使用 Signature 第 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
```
**輸出**
```
{
"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);
}
})();
```