本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

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

您可採用下列任何一種格式儲存鍵值對中的值：
+ String
+ 位元組編碼字串
+ JSON 

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

CloudFront 函數及其所有鍵值存放區資料均可安全地處理，如下所示：
+ 您呼叫 [CloudFront KeyValueStore](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_Operations_Amazon_CloudFront_KeyValueStore.html) API 操作時，CloudFront 會在靜態和傳輸期間 (讀取或寫入鍵值存放區時) 將每個鍵值存放區加密。
+ 執行函數時，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 SDKs匯入金鑰/值對。不過您只能在*最初*建立鍵值存放區時匯入鍵值對檔案。

若要建立鍵值對檔案，請參閱 [鍵值對的檔案格式](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` 參數。
   + 可讓您從存放在 Amazon S3 儲存貯體的檔案匯入鍵值對的 `import-source` 參數。您只能在第一次建立鍵值存放區時從檔案匯入。如需檔案結構的相關資訊，請參閱 [鍵值對的檔案格式](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>

您建立鍵值存放區時，資料存放區可能有下列狀態值。


****  

| Value | Description | 
| --- | --- | 
|  **佈建**  |  鍵值存放區已建立，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 是使用 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)
<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
```

**輸出**

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