# Amazon CloudFront KeyValueStore
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)」を参照してください。
## ユースケース
キーと値のペアは、以下の例に示すように使用できます。
+ **URL の書き換えまたはリダイレクト** — キーと値のペアは、書き換えられた URL またはリダイレクト URL を保持できます。
+ **A/B テストと機能フラグ** – ウェブサイトの特定のバージョンにトラフィックの割合を割り当てることで、テストを実行する関数を作成できます。
+ **アクセスの認可** – 独自に定義した条件とキーバリューストアに保存したデータに基づいて、リクエストを許可または拒否するアクセスコントロールを実装できます。
## サポートされている値の形式
キーと値のペアの値は、以下のいずれかの形式で保存できます。
+ String
+ バイトでエンコードされた文字列
+ JSON
## セキュリティ
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 の使用を開始する方法の詳細については、AWS ブログ記事「[Amazon CloudFront KeyValueStore の紹介](https://aws.amazon.com/blogs/aws/introducing-amazon-cloudfront-keyvaluestore-a-low-latency-datastore-for-cloudfront-functions/)」を参照してください。
# キーバリューストアの操作
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)」を参照してください。
# キーバリューストアの作成
キーバリューストアおよびキーと値のペアを同時に作成できます。最初に空のキーバリューストアを作成し、後でキーと値のペアを追加することもできます。
**注記**
Amazon S3 バケット内のデータソースを指定する場合は、そのバケットに対する `s3:GetObject` と `s3:GetBucketLocation` のアクセス許可が必要です。これらのアクセス許可がない場合、CloudFront はキーバリューストアを正常に作成できません。
キーバリューストアを作成すると同時にキーと値のペアを追加するかどうかを決定します。key-value ペアは、CloudFront コンソール、CloudFront API、AWS SDK を使用してインポートできます。ただし、key-value ペアのファイルをインポートできるのは、最初にキーバリューストアを作成する際にのみです。**
key-value ペアのファイルを作成するには、「[キーと値のペアのファイル形式](kvs-with-functions-create-s3-kvp.md)」を参照してください。
------
#### [ Console ]
**キーバリューストアを作成するには**
1. AWS マネジメントコンソールにサインインし、[https://console.aws.amazon.com/cloudfront/v4/home#/functions](https://console.aws.amazon.com/cloudfront/v4/home#/functions) で CloudFront コンソールの **[関数]** ページを開きます。
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 バケットから key-value ペアをインポートします。
```
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、名前の組み合わせを使用します。
------
## キーバリューストアのステータス
キーバリューストアを作成する場合、データストアのステータス値は次のようになります。
****
| 値 | 説明 |
| --- | --- |
| **プロビジョニング** | キーバリューストアが作成済みであり、指定したデータソースを CloudFront が処理中です。 |
| **Ready** | キーバリューストアが作成済みであり、指定したデータソースを CloudFront が正常に処理しました。 |
| **インポート失敗** | CloudFront は、指定したデータソースを処理できませんでした。このステータスは、ファイルの形式が有効でないか、ファイルのサイズが制限を超えている場合に表示されることがあります。詳細については、「[キーと値のペアのファイル形式](kvs-with-functions-create-s3-kvp.md)」を参照してください。 |
# キーバリューストアを関数に関連付ける
キーバリューストアを作成したら、関数を更新してキーバリューストアに関連付けることができます。この関連付けは、キーバリューストア内のキーと値のペアを、関数で使用するために必要です。以下のルールが適用されます。
+ 1 つの関数には 1 つのキーバリューストアのみを関連付けることができます。
+ 同じキーバリューストアを複数の関数に関連付けることができます。
------
#### [ Console ]
**キーバリューストアを関数に関連付けるには**
1. CloudFront コンソール ([https://console.aws.amazon.com/cloudfront/v4/home#/functions](https://console.aws.amazon.com/cloudfront/v4/home#/functions)) にサインインし、**[関数]** ページを選択します。
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 コンソールで、キーバリューストアの詳細ページを選択します。
# キーバリューストアを更新する
キーバリューストアを更新するときに、キーと値のペアを変更したり、キーバリューストアと関数の関連付けを変更したりできます。
------
#### [ Console ]
**キーバリューストアを更新するには**
1. AWS マネジメントコンソールにサインインし、[https://console.aws.amazon.com/cloudfront/v4/home#/functions](https://console.aws.amazon.com/cloudfront/v4/home#/functions) で CloudFront コンソールの **[関数]** ページを開きます。
1. **[KeyValueStores]** タブを選択します。
1. 更新するキーバリューストアを選択します。
+ キーと値のペアを更新するには、**[キーと値のペア]** セクションで **[編集]** を選択します。任意の数のキーと値のペアを追加または削除できます。また、既存のキーと値のペアの値を変更することもできます。完了したら、[**変更の保存**] を選択します。
+ このキーバリューストアの関連付けを更新するには、**[関数へ移動]** を選択します。詳細については、「[キーバリューストアを関数に関連付ける](kvs-with-functions-associate.md)」を参照してください。
------
#### [ AWS CLI ]
**キーバリューストアを更新するには**
1. **key-value ペアの変更** – key-value ペアを追加したり、単一または複数の key-value ペアを削除したり、既存の key-value ペアの値を変更したりできます。詳細については、「[キーと値のデータを操作する](kvs-with-functions-kvp.md)」を参照してください。
1. **キーバリューストアの関数の関連付けの変更** – キーバリューストアの関連付けを更新するには、「[キーバリューストアを関数に関連付ける](kvs-with-functions-associate.md)」を参照してください。
**ヒント**
キーバリューストアの ARN が必要になります。詳細については、「[キー値ストアへの参照の取得](kvs-with-functions-get-reference.md)」を参照してください。
------
#### [ API ]
**キーバリューストアを更新するには**
1. **key-value ペアの変更** – key-value ペアを追加したり、単一または複数の key-value ペアを削除したり、既存の key-value ペアの値を変更したりできます。詳細については、「[キーと値のデータを操作する](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)」を参照してください。
------
# キー値ストアへの参照の取得
キーバリューストアをプログラムで操作するには、キーバリューストアの `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` が含まれます。
+ `E3UN6WX5RRO2AG` などの `ETag`
+ UUID は `8aa76c93-3198-462c-aaf6-example` などの 128 ビットです。
+ 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)」を参照してください。
# キーバリューストアの削除
キーバリューストアを削除するには、Amazon CloudFront コンソールまたは API を使用できます。
------
#### [ Console ]
**キーバリューストアを削除するには**
1. AWS マネジメントコンソールにサインインし、[https://console.aws.amazon.com/cloudfront/v4/home#/functions](https://console.aws.amazon.com/cloudfront/v4/home#/functions) で CloudFront コンソールの **[関数]** ページを開きます。
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 オペレーションを使用します。
------
# キーと値のペアのファイル形式
UTF-8 でエンコードしたファイルを作成するときは、次の JSON 形式を使用します。
```
{
"data":[
{
"key":"key1",
"value":"value"
},
{
"key":"key2",
"value":"value"
}
]
}
```
ファイルに重複キーを含めることはできません。Amazon S3 バケットに無効なファイルを指定した場合は、ファイルを更新して重複を削除してから、キーバリューストアを作成し直してみてください。
詳細については、「[キーバリューストアの作成](kvs-with-functions-create.md)」を参照してください。
**注記**
データソースのファイルとそのキーと値のペアには、以下の制限があります。
ファイルサイズ — 5 MB
キーサイズ — 512 文字
値のサイズ — 1024 文字
# キーと値のデータを操作する
このトピックでは、既存のキーバリューストアにキーと値のペアを追加する方法について説明します。キーバリューストアを最初に作成するときに、キーと値のペアを含めるには、「[キーバリューストアの作成](kvs-with-functions-create.md)」を参照してください。
**Topics**
+ [key-value ペアを使用する (コンソール)](#kvs-with-functions-kvp-using-console)
+ [CloudFront KeyValueStore について](#kvs-with-functions-api-describe)
+ [key-value ペアを使用する (AWS CLI)](#work-with-kvs-cli-keys)
+ [key-value ペアを使用する (API)](#kvs-with-functions-kvp-using-api)
## key-value ペアを使用する (コンソール)
CloudFront コンソールを使用してキーと値のペアを操作できます。
**キーと値のペアを使用するには**
1. AWS マネジメントコンソールにサインインし、[https://console.aws.amazon.com/cloudfront/v4/home#/functions](https://console.aws.amazon.com/cloudfront/v4/home#/functions) で CloudFront コンソールの **[関数]** ページを開きます。
1. **[KeyValueStores]** タブを選択します。
1. 変更するキーバリューストアを選択します。
1. **[キーと値のペア]** セクションで、**[編集]** を選択します。
1. キーと値のペアを追加または削除したり、既存のキーと値のペアの値を変更したりできます。
1. 完了したら、[**変更の保存**] を選択します。
## CloudFront KeyValueStore について
**ヒント**
CloudFront KeyValueStore API は、認証に Signature Version 4A (SigV4A) を使用するグローバルサービスです。SigV4A で一時的な認証情報を使用するには、Version 2 のセッショントークンが必要です。詳細については、「[CloudFront KeyValueStore API での一時的な認証情報の使用](cloudfront-function-restrictions.md#regional-endpoint-for-key-value-store)」を参照してください。
AWS Command Line Interface (AWS CLI) または独自のコードを使用して CloudFront KeyValueStore API を呼び出す場合は、以降のセクションを参照してください。
キーバリューストアとそのキーと値のペアを操作する場合、呼び出すサービスはユースケースによって異なります。
+ 既存のキーバリューストア内の key-value ペアをプログラムで操作するには、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 を呼び出す場合、キーバリューストアの値は関数の呼び出し中に更新または変更されません。更新は、関数の呼び出しの合間に処理されます。
## key-value ペアを使用する (AWS CLI)
CloudFront KeyValueStore に関しては、以下の AWS Command Line Interface コマンドを実行できます。
**Contents**
+ [key-value ペアの一覧表示](#kvs-cli-list-keys)
+ [key-value ペアの取得](#kvs-cli-get-keys)
+ [キーバリューストアの説明](#kvs-cli-describe-keys)
+ [key-value ペアの作成](#kvs-cli-create-keys)
+ [key-value ペアの削除](#kvs-cli-delete-keys)
+ [key-value ペアの更新](#kvs-cli-update-key)
### key-value ペアの一覧表示
キーバリューストアの key-value ペアを一覧表示するには、次のコマンドを実行します。
```
aws cloudfront-keyvaluestore list-keys \
--kvs-arn=arn:aws:cloudfront::123456789012:key-value-store/37435e19-c205-4271-9e5c-example
```
**応答**
```
{
"Items": [
{
"Key": "key1",
"Value": "value1"
}
]
}
```
### key-value ペアの取得
キーバリューストアの key-value ペアを取得するには、次のコマンドを実行します。
```
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"
}
```
### key-value ペアの作成
キーバリューストアで key-value ペアを作成するには、次のコマンドを実行します。
```
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
}
```
### key-value ペアの削除
key-value ペアのを削除するには、次のコマンドを実行します。
```
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
}
```
### key-value ペアの更新
単数または複数の key-value ペアを更新するには、`update-keys` コマンドを使用します。例えば、既存の key-value ペアを削除して別の key-value ペアを作成するには、次のコマンドを実行します。
```
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
}
```
## key-value ペアを使用する (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) – 以下のタスクを実行できます。
+ 1 つのキーバリューストアに 1 つのキーと値のペアを作成する: この場合は、新しいキー名と値を指定します。
+ 1 つの既存のキーと値のペアに別の値を設定する: この場合は、既存のキー名と新しいキー値を指定します。
+ [CloudFrontKeyValueStore UpdateKeys](https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_kvs_UpdateKeys.html) – 1 つの all-or-nothing オペレーションで、以下の 1 つ以上のアクションを実行できます。
+ 1 つ以上のキーと値のペアを削除する
+ 1 つ以上のキーと値のペアを新規作成する
+ 1 つ以上の既存のキーと値のペアに別の値を設定する
### 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);
}
})();
```