キーと値のデータを操作する

このトピックでは、既存のキーバリューストアにキーと値のペアを追加する方法について説明します。キーバリューストアを最初に作成するときに、キーと値のペアを含めるには、「キーバリューストアの作成」を参照してください。

key-value ペアを使用する (コンソール)

CloudFront コンソールを使用してキーと値のペアを操作できます。

キーと値のペアを使用するには

1. AWS Management Consoleにサインインし、https://console.aws.amazon.com/cloudfront/v4/home#/functions で CloudFront コンソールの [関数] ページを開きます。

2. [KeyValueStores] タブを選択します。

3. 変更するキーバリューストアを選択します。

4. [キーと値のペア] セクションで、[編集] を選択します。

5. キーと値のペアを追加または削除したり、既存のキーと値のペアの値を変更したりできます。

6. 完了したら、[変更の保存] を選択します。

CloudFront KeyValueStore について

ヒント

CloudFront KeyValueStore API は、認証に Signature Version 4A (SigV4A) を使用するグローバルサービスです。SigV4A で一時的な認証情報を使用するには、Version 2 のセッショントークンが必要です。詳細については、「CloudFront KeyValueStore API での一時的な認証情報の使用」を参照してください。

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 オペレーションでは、CloudFront KeyValueStore DescribeKeyValueStore オペレーションから返された ETag を指定します。

key-value ペアを使用する (AWS CLI)

CloudFront KeyValueStore に関しては、以下の AWS Command Line Interface コマンドを実行できます。

目次

• key-value ペアの一覧表示
• key-value ペアの取得
• キーバリューストアの説明
• key-value ペアの作成
• key-value ペアの削除
• key-value ペアの更新

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)

キーと値のペアをプログラムで操作するには、このセクションに従います。

目次

• キーバリューストアへの参照の取得
• キーバリューストア内のキーと値のペアを変更する
• CloudFront KeyValueStore のコード例

キーバリューストアへの参照の取得

CloudFront KeyValueStore API を使用して書き込みオペレーションを呼び出す際は、キーバリューストアの ARN と ETag を指定する必要があります。このデータを取得するには、以下を実行します。

キーバリューストアへの参照を取得するには

1. CloudFront ListKeyValueStores API オペレーションを使用して、キーバリューストアのリストを取得します。変更するキーバリューストアを見つけます。

2. CloudFrontKeyValueStore DescribeKeyValueStore API オペレーションを使用して、前のステップからのキーバリューストアを指定します。

   この応答には、キーバリューストアの 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 – キーと値のペアを削除します。

• CloudFrontKeyValueStore GetKey – キーと値のペアを返します。

• CloudFrontKeyValueStore ListKeys – キーと値のペアのリストを返します。

• CloudFrontKeyValueStore PutKey – 以下のタスクを実行できます。

  • 1 つのキーバリューストアに 1 つのキーと値のペアを作成する: この場合は、新しいキー名と値を指定します。

  • 1 つの既存のキーと値のペアに別の値を設定する: この場合は、既存のキー名と新しいキー値を指定します。

• CloudFrontKeyValueStore UpdateKeys – 1 つの all-or-nothing オペレーションで、以下の 1 つ以上のアクションを実行できます。

  • 1 つ以上のキーと値のペアを削除する

  • 1 つ以上のキーと値のペアを新規作成する

  • 1 つ以上の既存のキーと値のペアに別の値を設定する

CloudFront KeyValueStore のコード例

次のコードは、キーバリューストアの 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);
  }
})();