# Amazon CloudFront KeyValueStore
CloudFront KeyValueStore는 [CloudFront 함수](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 테스트 및 기능 플래그** - 웹사이트의 특정 버전에 트래픽 비율을 할당하여 실험을 실행하는 함수를 만들 수 있습니다.
+ **액세스 권한 부여** - 사용자가 정의한 기준과 KeyValueStore에 저장된 데이터에 따라 요청을 허용하거나 거부하는 액세스 제어를 구현할 수 있습니다.
## 지원되는 값 형식
키 값 페어의 값은 다음 형식 중 하나로 저장할 수 있습니다.
+ 문자열
+ 바이트로 인코딩된 문자열
+ JSON
## 보안
CloudFront Functions 및 모든 키 값 저장소 데이터는 다음과 같이 안전하게 처리됩니다.
+ 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 키 값 저장소 시작 방법에 대한 자세한 내용은 [Introducing Amazon CloudFront KeyValueStore](https://aws.amazon.com/blogs/aws/introducing-amazon-cloudfront-keyvaluestore-a-low-latency-datastore-for-cloudfront-functions/) AWS 블로그 게시물을 참조하세요.
# 키 값 저장소 사용
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는 키 값 저장소를 성공적으로 생성할 수 없습니다.
키 값 저장소를 생성하면서 키 값 페어를 동시에 추가할지 여부를 결정하세요. CloudFront 콘솔, CloudFront API 또는 AWS SDK를 사용하여 키 값 페어를 가져올 수 있습니다. 그러나 키 값 저장소를 **처음 만들 때만 키 값 페어 파일을 가져올 수 있습니다.
키 값 페어로 구성된 파일을 생성하려면 [키 값 페어의 파일 형식](kvs-with-functions-create-s3-kvp.md) 섹션을 참조하세요.
------
#### [ Console ]
**키 값 저장소를 생성하려면**
1. AWS Management Console에 로그인하고 [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. **생성(Create)**을 선택합니다. 키 값 저장소가 생겼습니다.
새로운 키 값 저장소의 세부 정보 페이지가 나타납니다. 페이지의 정보에는 키 값 저장소의 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 및 이름을 조합하여 키 값 저장소를 프로그래밍 방식으로 사용할 수 있습니다.
------
## 키 값 저장소 상태
키 값 저장소를 생성할 때 데이터 저장소는 다음과 같은 상태 값을 가질 수 있습니다.
****
| 값 | 설명 |
| --- | --- |
| **프로비저닝** | 키 값 저장소가 생성되었으며 CloudFront는 지정된 데이터 소스를 처리하고 있습니다. |
| **준비됨** | 키 값 저장소가 생성되고 CloudFront가 지정한 데이터 소스를 성공적으로 처리했습니다. |
| **가져오기에 실패했습니다** | CloudFront는 지정한 데이터 소스를 처리하지 못했습니다. 파일 형식이 유효하지 않거나 크기 제한을 초과하는 경우 이 상태가 나타날 수 있습니다. 자세한 내용은 [키 값 페어의 파일 형식](kvs-with-functions-create-s3-kvp.md) 섹션을 참조하세요. |
# 키 값 저장소를 함수와 연결
키 값 저장소를 생성한 후 함수를 업데이트하여 키 값 저장소와 연결할 수 있습니다. 해당 함수에서 해당 저장소의 키 값 페어를 사용하려면 이 연결을 만들어야 합니다. 다음 규칙이 적용됩니다.
+ 함수 하나에는 키 값 저장소가 하나만 있을 수 있습니다.
+ 동일한 키 값 저장소를 여러 함수와 연결할 수 있습니다.
------
#### [ 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을 지정합니다.
+ 연결을 변경하려면 다른 키 값 저장소의 이름을 지정합니다.
+ 연결을 제거하려면 `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 Management Console에 로그인하고 [https://console.aws.amazon.com/cloudfront/v4/home#/functions](https://console.aws.amazon.com/cloudfront/v4/home#/functions)에 있는 CloudFront 콘솔에서 **함수** 페이지를 엽니다.
1. **KeyValueStore** 탭을 선택합니다.
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) 섹션을 참조하세요.
------
# 키 값 저장소에 대한 참조 가져오기
프로그래밍 방식으로 키 값 저장소를 사용하려면 `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) 섹션을 참조하세요.
# 키 값 저장소 삭제
Amazon CloudFront 콘솔 또는 API를 사용하여 키 값 저장소를 삭제할 수 있습니다.
------
#### [ Console ]
**키 값 저장소를 삭제하려면**
1. AWS Management Console에 로그인하고 [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) 섹션을 참조하세요.
**참고**
데이터 소스 및 해당 키-값 페어의 파일에는 다음과 같은 한도가 있습니다.
파일 크기 - 5MB
키 크기 - 512자
키 크기 - 1,024자
# 키 값 데이터로 작업
이 주제에서는 기존 키 값 저장소에 키 값 페어를 추가하는 방법을 설명합니다. 키 값 저장소를 처음 생성할 때 키 값 페어를 포함하려면 [키 값 저장소 생성](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 Management Console에 로그인하고 [https://console.aws.amazon.com/cloudfront/v4/home#/functions](https://console.aws.amazon.com/cloudfront/v4/home#/functions)에 있는 CloudFront 콘솔에서 **함수** 페이지를 엽니다.
1. **KeyValueStore** 탭을 선택합니다.
1. 변경할 키 값 저장소를 선택합니다.
1. **키 값 페어** 섹션에서 **편집** 버튼을 선택합니다.
1. 키 값 페어를 추가하거나, 키 값 페어를 삭제하거나, 기존 키 값 페어의 값을 변경할 수 있습니다.
1. 작업을 마쳤으면 **변경 내용 저장**을 선택합니다.
## CloudFront KeyValueStore 소개
**작은 정보**
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)
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 키 값 저장소 예제 코드](#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 키 값 저장소 예제 코드
**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);
}
})();
```