기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# DynamoDB용 AWS AppSync 해석기 매핑 템플릿 참조
**참고**
이제 우리는 주로 APPSYNC\$1JS 런타임과 해당 문서를 지원합니다. [여기](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)에서 APPSYNC\$1JS 런타임과 해당 안내서를 사용해 보세요.
AWS AppSync DynamoDB 함수를 사용하면 수신 [GraphQL](https://graphql.org) 요청을 DynamoDB 호출에 매핑한 다음 DynamoDB 응답을 GraphQL에 다시 매핑하여 GraphQL을 사용하여 계정의 기존 Amazon DynamoDB 테이블에 데이터를 저장하고 검색할 수 있습니다. 이 섹션에서는 지원되는 DynamoDB 작업에 대한 요청 및 응답 핸들러를 설명합니다.
+ [GetItem](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-getitem.html) - GetItem 요청을 통해 DynamoDB 함수에 지시하여 DynamoDB에 GetItem 요청을 할 수 있으며, DynamoDB의 항목 키 및 일관된 읽기를 사용할지 여부를 지정할 수 있습니다.
+ [ PutItem ](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-putitem.html) - PutItem 요청 매핑 문서를 사용하면 DynamoDB 함수에 지시하여 DynamoDB에 PutItem 요청을 할 수 있으며, DynamoDB의 항목 키, 항목의 전체 내용(키 및 attributeValues로 구성), 작업 성공 조건을 지정할 수 있습니다.
+ [ UpdateItem ](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-updateitem.html) - UpdateItem 요청을 사용하면 DynamoDB 함수에 지시하여 DynamoDB에 UpdateItem 요청을 할 수 있으며, DynamoDB의 항목 키, DynamoDB에서 항목을 업데이트하는 방법을 설명하는 업데이트 표현식 및 작업 성공 조건을 지정할 수 있습니다.
+ [ DeleteItem ](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-deleteitem.html) - DeleteItem 요청을 사용하면 DynamoDB 함수에 지시하여 DynamoDB에 DeleteItem 요청을 할 수 있으며, DynamoDB의 항목 키 및 작업 성공 조건을 지정할 수 있습니다.
+ [ 쿼리 ](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-query.html) - 쿼리 요청 객체를 사용하면 DynamoDB 해석기에 지시하여 DynamoDB에 쿼리 요청을 할 수 있으며, 키 표현식, 사용할 인덱스, 추가 필터, 반환할 항목 수, 일관된 읽기 사용 여부, 쿼리 방향(앞 또는 뒤로) 및 페이지 매김 토큰을 지정할 수 있습니다.
+ [ 스캔 ](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-scan.html) - 스캔 요청을 통해 DynamoDB 함수에 지시하여 DynamoDB에 스캔 요청을 할 수 있으며, 결과를 제외하는 필터, 사용할 인덱스, 반환할 항목 수, 일관된 읽기 사용 여부, 페이지 매김 토큰 및 병렬 스캔을 지정할 수 있습니다.
+ [ 동기화 ](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-sync.html) - 동기화 요청 객체를 사용하면 DynamoDB 테이블에서 모든 결과를 가져온 다음, 마지막 쿼리(델타 업데이트) 이후에 변경된 데이터만 수신할 수 있습니다. 버전이 지정된 DynamoDB 데이터 소스에만 동기화 요청할 수 있습니다. 결과를 제외하는 필터, 반환할 항목 수, 페이지 매김 토큰 및 마지막 동기화 작업 시작 시간을 지정할 수 있습니다.
+ [ BatchGetItem ](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-batch-get-item.html) - BatchGetItem 요청 객체를 사용하면 DynamoDB 함수에 지시하여 DynamoDB에 BatchGetItem 요청을 전달하고 잠재적으로 여러 테이블에 걸쳐 여러 항목을 검색할 수 있습니다. 이 요청 객체의 경우 항목을 검색할 테이블 이름과 각 테이블에서 검색할 항목의 키를 지정해야 합니다.
+ [ BatchDeleteItem ](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-batch-delete-item.html) - BatchDeleteItem 요청 객체를 사용하면 DynamoDB 함수에 지시하여 DynamoDB에 BatchWriteItem 요청을 전달하고 잠재적으로 여러 테이블에 걸쳐 여러 항목을 삭제할 수 있습니다. 이 요청 객체의 경우 항목을 삭제할 테이블 이름과 각 테이블에서 삭제할 항목의 키를 지정해야 합니다.
+ [ BatchPutItem ](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-batch-put-item.html) - BatchPutItem 요청 객체를 사용하면 DynamoDB 함수에 지시하여 DynamoDB에 BatchWriteItem 요청을 전달하고 잠재적으로 여러 테이블에 걸쳐 여러 항목을 배치할 수 있습니다. 이 요청 객체의 경우 항목을 배치할 테이블 이름과 각 테이블에 배치할 전체 항목을 지정해야 합니다.
+ [ TransactGetItems ](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-transact-get-items.html) - TransactGetItems 요청 객체를 사용하면 DynamoDB 함수에 지시하여 DynamoDB에 TransactGetItems 요청을 전달하고 잠재적으로 여러 테이블에 걸쳐 여러 항목을 검색할 수 있습니다. 이 요청 객체의 경우 항목을 검색할 각 요청 항목의 테이블 이름과 각 테이블에서 검색할 각 요청 항목의 키를 지정해야 합니다.
+ [ TransactWriteItems ](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-transact-write-items.html) - TransactWriteItems 요청 객체를 사용하면 DynamoDB 함수에 지시하여 DynamoDB에 TransactWriteItems 요청을 전달하고 잠재적으로 여러 테이블에 걸쳐 여러 항목을 작성할 수 있습니다. 이 요청 객체의 경우 각 요청 항목의 대상 테이블 이름, 수행할 각 요청 항목의 작업, 작성할 각 요청 항목의 키를 지정해야 합니다.
+ [ 유형 시스템(요청 매핑) ](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.html) - DynamoDB 입력이 AWS AppSync 요청에 통합되는 방법에 대해 자세히 알아봅니다.
+ [ 유형 시스템(응답 매핑) ](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-responses.html) - DynamoDB 유형이 응답 페이로드에서 자동으로 GraphQL 또는 JSON으로 변환되는 방식을 자세히 알아봅니다.
+ [필터](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-filter.html) - 쿼리 및 스캔 작업의 필터에 대해 자세히 알아봅니다.
+ [ 조건 표현식 ](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-condition-expressions.html) - PutItem, UpdateItem 및 DeleteItem 작업의 조건 표현식을 자세히 알아봅니다.
+ [ 트랜잭션 조건 표현식 ](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-transaction-condition-expressions.html) - TransactWriteItems 작업의 조건 표현식을 자세히 알아봅니다.
+ [ 프로젝션 ](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-projections.html) - 읽기 작업에서 특성을 지정하는 방법을 자세히 알아봅니다.
# GetItem
`GetItem` 요청 매핑 문서를 사용하면 AWS AppSync DynamoDB 해석기에 DynamoDB에 `GetItem` 요청하도록 지시하고 다음을 지정할 수 있습니다.
+ DynamoDB의 항목 키
+ 일관된 읽기를 사용할지 여부
`GetItem` 매핑 문서의 구조는 다음과 같습니다.
```
{
"version" : "2017-02-28",
"operation" : "GetItem",
"key" : {
"foo" : ... typed value,
"bar" : ... typed value
},
"consistentRead" : true,
"projection" : {
...
}
}
```
필드는 다음과 같이 정의됩니다.
## GetItem 필드
### GetItem 필드 목록
**`version`**
템플릿 정의 버전. `2017-02-28` 및 `2018-05-29`만 현재 지원됩니다. 이 값은 필수입니다.
**`operation`**
수행할 DynamoDB 작업입니다. `GetItem` DynamoDB 작업을 수행하려면 이 값을 `GetItem`으로 설정해야 합니다. 이 값은 필수입니다.
**`key`**
DynamoDB의 항목 키입니다. DynamoDB 항목은 테이블 구조에 따라 단일 해시 키 또는 해시 키와 정렬 키를 가질 수 있습니다. '입력된 값'을 지정하는 방법에 대한 자세한 내용은 [유형 시스템(요청 매핑)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)을 참조하세요. 이 값은 필수입니다.
**`consistentRead`**
DynamoDB에서 강력히 일관된 읽기를 수행할지 여부. 선택 사항으로, 기본값은 `false`입니다.
**`projection`**
DynamoDB 작업에서 반환할 속성을 지정하는 데 사용되는 프로젝션입니다. 프로젝션에 대한 자세한 내용은 [프로젝션](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-mapping-template-reference-dynamodb.html#aws-appsync-resolver-mapping-template-reference-dynamodb-projections)을 참조하세요. 이 필드는 선택 사항입니다.
DynamoDB에서 반환된 항목은 자동으로 GraphQL 및 JSON 기본 유형으로 변환되며 매핑 컨텍스트(`$context.result`)에서 사용할 수 있습니다.
DynamoDB 형식 변환에 대한 자세한 내용은 [형식 시스템(응답 매핑)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-responses.md)을 참조하세요.
응답 매핑 템플릿에 대한 자세한 내용은 [해석기 매핑 템플릿 개요](resolver-mapping-template-reference-overview.md#aws-appsync-resolver-mapping-template-reference-overview)를 참조하세요.
## 예제
다음 예제는 GraphQL 쿼리 `getThing(foo: String!, bar: String!)`의 매핑 템플릿입니다.
```
{
"version" : "2017-02-28",
"operation" : "GetItem",
"key" : {
"foo" : $util.dynamodb.toDynamoDBJson($ctx.args.foo),
"bar" : $util.dynamodb.toDynamoDBJson($ctx.args.bar)
},
"consistentRead" : true
}
```
DynamoDB `GetItem` API에 대한 자세한 내용은 [DynamoDB API 문서](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_GetItem.html)를 참조하십시오.
# PutItem
`PutItem` 요청 매핑 문서를 사용하면 AWS AppSync DynamoDB 해석기에 DynamoDB에 `PutItem` 요청하도록 지시하고 다음을 지정할 수 있습니다.
+ DynamoDB의 항목 키
+ 항목의 전체 내용(`key` 및 `attributeValues`로 구성됨)
+ 성공할 작업의 조건
`PutItem` 매핑 문서의 구조는 다음과 같습니다.
```
{
"version" : "2018-05-29",
"operation" : "PutItem",
"customPartitionKey" : "foo",
"populateIndexFields" : boolean value,
"key": {
"foo" : ... typed value,
"bar" : ... typed value
},
"attributeValues" : {
"baz" : ... typed value
},
"condition" : {
...
},
"_version" : 1
}
```
필드는 다음과 같이 정의됩니다.
## PutItem 필드
### PutItem 필드 목록
**`version`**
템플릿 정의 버전. `2017-02-28` 및 `2018-05-29`만 현재 지원됩니다. 이 값은 필수입니다.
**`operation`**
수행할 DynamoDB 작업입니다. `PutItem` DynamoDB 작업을 수행하려면 이 값을 `PutItem`으로 설정해야 합니다. 이 값은 필수입니다.
**`key`**
DynamoDB의 항목 키입니다. DynamoDB 항목은 테이블 구조에 따라 단일 해시 키 또는 해시 키와 정렬 키를 가질 수 있습니다. '입력된 값'을 지정하는 방법에 대한 자세한 내용은 [유형 시스템(요청 매핑)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)을 참조하세요. 이 값은 필수입니다.
**`attributeValues`**
DynamoDB에 저장할 항목의 나머지 속성. '입력된 값'을 지정하는 방법에 대한 자세한 내용은 [유형 시스템(요청 매핑)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)을 참조하세요. 이 필드는 선택 사항입니다.
**`condition`**
DynamoDB에 이미 있는 객체의 상태를 기반으로 요청의 성공 여부를 결정하는 조건. 조건을 지정하지 않으면 `PutItem` 요청이 해당 항목에 대한 기존 입력을 덮어씁니다. 조건에 대한 자세한 내용은 [조건 표현식](aws-appsync-resolver-mapping-template-reference-dynamodb-condition-expressions.md)을 참조하세요. 이 값은 선택 사항입니다.
**`_version`**
항목의 알려진 최신 버전을 나타내는 숫자 값입니다. 이 값은 선택 사항입니다. 이 필드는 *충돌 감지*에 사용되며 버전이 지정된 데이터 원본에만 지원됩니다.
**`customPartitionKey`**
활성화되면 이 문자열 값은 버전 관리가 활성화되었을 때 델타 동기화 테이블에서 사용되는 `ds_sk` 및 `ds_pk` 레코드의 형식을 수정합니다(자세한 내용은 **AWS AppSync 개발자 안내서의 [충돌 감지 및 동기화](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html) 참조). 활성화되면 `populateIndexFields` 항목 처리도 활성화됩니다. 이 필드는 선택 사항입니다.
**`populateIndexFields`**
**`customPartitionKey`와 함께** 활성화되면 델타 동기화 테이블, 특히 `gsi_ds_pk` 및 `gsi_ds_sk` 열의 각 레코드에 대해 새 항목을 생성하는 부울 값입니다. 자세한 내용은 **AWS AppSync 개발자 안내서의 [충돌 감지 및 동기화](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html)를 참조하세요. 이 필드는 선택 사항입니다.
DynamoDB에 기록된 항목은 자동으로 GraphQL 및 JSON 기본 형식으로 변환되며 매핑 컨텍스트(`$context.result`)에서 사용할 수 있습니다.
DynamoDB 형식 변환에 대한 자세한 내용은 [형식 시스템(응답 매핑)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-responses.md)을 참조하세요.
응답 매핑 템플릿에 대한 자세한 내용은 [해석기 매핑 템플릿 개요](resolver-mapping-template-reference-overview.md#aws-appsync-resolver-mapping-template-reference-overview)를 참조하세요.
## 예제 1.
다음 예제는 GraphQL 변형 `updateThing(foo: String!, bar: String!, name: String!, version: Int!)`의 매핑 템플릿입니다.
지정된 키가 있는 항목이 없으면 생성됩니다. 지정된 키가 있는 항목이 있으면 덮어씁니다.
```
{
"version" : "2017-02-28",
"operation" : "PutItem",
"key": {
"foo" : $util.dynamodb.toDynamoDBJson($ctx.args.foo),
"bar" : $util.dynamodb.toDynamoDBJson($ctx.args.bar)
},
"attributeValues" : {
"name" : $util.dynamodb.toDynamoDBJson($ctx.args.name),
"version" : $util.dynamodb.toDynamoDBJson($ctx.args.version)
}
}
```
## 예제 2.
다음 예제는 GraphQL 변형 `updateThing(foo: String!, bar: String!, name: String!, expectedVersion: Int!)`의 매핑 템플릿입니다.
이 예에서는 현재 DynamoDB에 있는 항목의 `version` 필드가 `expectedVersion`으로 설정되어 있는지 확인합니다.
```
{
"version" : "2017-02-28",
"operation" : "PutItem",
"key": {
"foo" : $util.dynamodb.toDynamoDBJson($ctx.args.foo),
"bar" : $util.dynamodb.toDynamoDBJson($ctx.args.bar)
},
"attributeValues" : {
"name" : $util.dynamodb.toDynamoDBJson($ctx.args.name),
#set( $newVersion = $context.arguments.expectedVersion + 1 )
"version" : $util.dynamodb.toDynamoDBJson($newVersion)
},
"condition" : {
"expression" : "version = :expectedVersion",
"expressionValues" : {
":expectedVersion" : $util.dynamodb.toDynamoDBJson($expectedVersion)
}
}
}
```
DynamoDB `PutItem` API에 대한 자세한 내용은 [DynamoDB API 문서](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html)를 참조하십시오.
# UpdateItem
`UpdateItem` 요청 매핑 문서를 사용하면 AWS AppSync DynamoDB 해석기에 DynamoDB에 `UpdateItem` 요청을 하도록 지시하고 다음을 지정할 수 있습니다.
+ DynamoDB의 항목 키
+ DynamoDB에서 항목 업데이트 방법을 설명하는 업데이트 표현식
+ 성공할 작업의 조건
`UpdateItem` 매핑 문서의 구조는 다음과 같습니다.
```
{
"version" : "2018-05-29",
"operation" : "UpdateItem",
"customPartitionKey" : "foo",
"populateIndexFields" : boolean value,
"key": {
"foo" : ... typed value,
"bar" : ... typed value
},
"update" : {
"expression" : "someExpression",
"expressionNames" : {
"#foo" : "foo"
},
"expressionValues" : {
":bar" : ... typed value
}
},
"condition" : {
...
},
"_version" : 1
}
```
필드는 다음과 같이 정의됩니다.
## UpdateItem 필드
### UpdateItem 필드 목록
**`version`**
템플릿 정의 버전. `2017-02-28` 및 `2018-05-29`만 현재 지원됩니다. 이 값은 필수입니다.
**`operation`**
수행할 DynamoDB 작업입니다. `UpdateItem` DynamoDB 작업을 수행하려면 이 값을 `UpdateItem`으로 설정해야 합니다. 이 값은 필수입니다.
**`key`**
DynamoDB의 항목 키입니다. DynamoDB 항목은 테이블 구조에 따라 단일 해시 키 또는 해시 키와 정렬 키를 가질 수 있습니다. '입력된 값' 지정에 대한 자세한 내용은 [유형 시스템(요청 매핑)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)을 참조하세요. 이 값은 필수입니다.
**`update`**
`update` 섹션에서는 DynamoDB의 항목 업데이트 방법을 설명하는 업데이트 표현식을 지정합니다. 업데이트 표현식을 작성하는 방법에 대한 자세한 내용은 [DynamoDB UpdateExpressions 문서](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.UpdateExpressions.html)를 참조하십시오. 이 섹션은 필수입니다.
`update` 섹션에는 다음 세 가지 구성 요소가 있습니다.
** `expression` **
업데이트 표현식. 이 값은 필수입니다.
** `expressionNames` **
표현식 속성 *name* 자리 표시자의 대체 항목으로, 키-값 페어의 형식으로 표시됩니다. 키는 `expression`에 사용된 name 자리 표시자에 해당하고 값은 DynamoDB에 있는 항목의 속성 이름에 해당하는 문자열이어야 합니다. 이 필드는 선택 사항으로, `expression`에 사용된 표현식 속성인 name 자리 표시자의 대체 항목으로만 채워져야 합니다.
** `expressionValues` **
표현식 속성 *value* 자리 표시자의 대체 항목으로, 키-값 페어의 형식으로 표시됩니다. 키는 `expression`에 사용되는 value 자리 표시자에 해당하고 값은 입력된 값이어야 합니다. '입력된 값'을 지정하는 방법에 대한 자세한 내용은 [유형 시스템(요청 매핑)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)을 참조하세요. 입력된 값은 지정되어 있어야 합니다. 이 필드는 선택 사항으로, `expression`에 사용된 표현식 속성인 value 자리 표시자의 대체 항목으로만 채워져야 합니다.
**`condition`**
DynamoDB에 이미 있는 객체의 상태를 기반으로 요청의 성공 여부를 결정하는 조건. 조건을 지정하지 않으면 `UpdateItem` 요청이 현재 상태와 상관 없이 기존 항목을 업데이트합니다. 조건에 대한 자세한 내용은 [조건 표현식](aws-appsync-resolver-mapping-template-reference-dynamodb-condition-expressions.md)을 참조하세요. 이 값은 선택 사항입니다.
**`_version`**
항목의 알려진 최신 버전을 나타내는 숫자 값입니다. 이 값은 선택 사항입니다. 이 필드는 *충돌 감지*에 사용되며 버전이 지정된 데이터 원본에만 지원됩니다.
**`customPartitionKey`**
활성화되면 이 문자열 값은 버전 관리가 활성화되었을 때 델타 동기화 테이블에서 사용되는 `ds_sk` 및 `ds_pk` 레코드의 형식을 수정합니다(자세한 내용은 **AWS AppSync 개발자 안내서의 [충돌 감지 및 동기화](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html) 참조). 활성화되면 `populateIndexFields` 항목 처리도 활성화됩니다. 이 필드는 선택 사항입니다.
**`populateIndexFields`**
**`customPartitionKey`와 함께** 활성화되면 델타 동기화 테이블, 특히 `gsi_ds_pk` 및 `gsi_ds_sk` 열의 각 레코드에 대해 새 항목을 생성하는 부울 값입니다. 자세한 내용은 **AWS AppSync 개발자 안내서의 [충돌 감지 및 동기화](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html)를 참조하세요. 이 필드는 선택 사항입니다.
DynamoDB에서 업데이트된 항목은 자동으로 GraphQL 및 JSON 기본 형식으로 변환되며 매핑 컨텍스트(`$context.result`)에서 사용할 수 있습니다.
DynamoDB 형식 변환에 대한 자세한 내용은 [형식 시스템(응답 매핑)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-responses.md)을 참조하세요.
응답 매핑 템플릿에 대한 자세한 내용은 [해석기 매핑 템플릿 개요](resolver-mapping-template-reference-overview.md#aws-appsync-resolver-mapping-template-reference-overview)를 참조하세요.
## 예제 1.
다음 예제는 GraphQL 변형 `upvote(id: ID!)`의 매핑 템플릿입니다.
이 예에서 DynamoDB의 항목에는 1씩 증가하는 `upvotes` 및 `version` 필드가 있습니다.
```
{
"version" : "2017-02-28",
"operation" : "UpdateItem",
"key" : {
"id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
},
"update" : {
"expression" : "ADD #votefield :plusOne, version :plusOne",
"expressionNames" : {
"#votefield" : "upvotes"
},
"expressionValues" : {
":plusOne" : { "N" : 1 }
}
}
}
```
## 예제 2.
다음 예제는 GraphQL 변형 `updateItem(id: ID!, title: String, author: String, expectedVersion: Int!)`의 매핑 템플릿입니다.
다음은 인수를 조사해 클라이언트에서 제공한 인수만 포함하는 업데이트 표현식을 동적으로 생성하는 복잡한 예입니다. 예를 들어, `title` 및 `author`는 생략되면 업데이트되지 않습니다. 인수가 지정되어 있으나 그 값이 `null`이면 DynamoDB의 객체에서 해당 필드가 삭제됩니다. 마지막으로, 이 작업에는 DynamoDB에 현재 있는 항목에 `expectedVersion`으로 설정된 `version` 필드가 있는지 확인하는 조건이 있습니다.
```
{
"version" : "2017-02-28",
"operation" : "UpdateItem",
"key" : {
"id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
},
## Set up some space to keep track of things we're updating **
#set( $expNames = {} )
#set( $expValues = {} )
#set( $expSet = {} )
#set( $expAdd = {} )
#set( $expRemove = [] )
## Increment "version" by 1 **
$!{expAdd.put("version", ":newVersion")}
$!{expValues.put(":newVersion", { "N" : 1 })}
## Iterate through each argument, skipping "id" and "expectedVersion" **
#foreach( $entry in $context.arguments.entrySet() )
#if( $entry.key != "id" && $entry.key != "expectedVersion" )
#if( (!$entry.value) && ("$!{entry.value}" == "") )
## If the argument is set to "null", then remove that attribute from the item in DynamoDB **
#set( $discard = ${expRemove.add("#${entry.key}")} )
$!{expNames.put("#${entry.key}", "$entry.key")}
#else
## Otherwise set (or update) the attribute on the item in DynamoDB **
$!{expSet.put("#${entry.key}", ":${entry.key}")}
$!{expNames.put("#${entry.key}", "$entry.key")}
#if( $entry.key == "ups" || $entry.key == "downs" )
$!{expValues.put(":${entry.key}", { "N" : $entry.value })}
#else
$!{expValues.put(":${entry.key}", { "S" : "${entry.value}" })}
#end
#end
#end
#end
## Start building the update expression, starting with attributes we're going to SET **
#set( $expression = "" )
#if( !${expSet.isEmpty()} )
#set( $expression = "SET" )
#foreach( $entry in $expSet.entrySet() )
#set( $expression = "${expression} ${entry.key} = ${entry.value}" )
#if ( $foreach.hasNext )
#set( $expression = "${expression}," )
#end
#end
#end
## Continue building the update expression, adding attributes we're going to ADD **
#if( !${expAdd.isEmpty()} )
#set( $expression = "${expression} ADD" )
#foreach( $entry in $expAdd.entrySet() )
#set( $expression = "${expression} ${entry.key} ${entry.value}" )
#if ( $foreach.hasNext )
#set( $expression = "${expression}," )
#end
#end
#end
## Continue building the update expression, adding attributes we're going to REMOVE **
#if( !${expRemove.isEmpty()} )
#set( $expression = "${expression} REMOVE" )
#foreach( $entry in $expRemove )
#set( $expression = "${expression} ${entry}" )
#if ( $foreach.hasNext )
#set( $expression = "${expression}," )
#end
#end
#end
## Finally, write the update expression into the document, along with any expressionNames and expressionValues **
"update" : {
"expression" : "${expression}"
#if( !${expNames.isEmpty()} )
,"expressionNames" : $utils.toJson($expNames)
#end
#if( !${expValues.isEmpty()} )
,"expressionValues" : $utils.toJson($expValues)
#end
},
"condition" : {
"expression" : "version = :expectedVersion",
"expressionValues" : {
":expectedVersion" : $util.dynamodb.toDynamoDBJson($ctx.args.expectedVersion)
}
}
}
```
DynamoDB `UpdateItem` API에 대한 자세한 내용은 [DynamoDB API 문서](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_UpdateItem.html)를 참조하십시오.
# DeleteItem
`DeleteItem` 요청 매핑 문서를 사용하면 AWS AppSync DynamoDB 해석기에 DynamoDB에 `DeleteItem` 요청하도록 지시하고 다음을 지정할 수 있습니다.
+ DynamoDB의 항목 키
+ 성공할 작업의 조건
`DeleteItem` 매핑 문서의 구조는 다음과 같습니다.
```
{
"version" : "2018-05-29",
"operation" : "DeleteItem",
"customPartitionKey" : "foo",
"populateIndexFields" : boolean value,
"key": {
"foo" : ... typed value,
"bar" : ... typed value
},
"condition" : {
...
},
"_version" : 1
}
```
필드는 다음과 같이 정의됩니다.
## DeleteItem 필드
### DeleteItem 필드 목록
** `version` **
템플릿 정의 버전. `2017-02-28` 및 `2018-05-29`만 현재 지원됩니다. 이 값은 필수입니다.
** `operation` **
수행할 DynamoDB 작업입니다. `DeleteItem` DynamoDB 작업을 수행하려면 이 값을 `DeleteItem`으로 설정해야 합니다. 이 값은 필수입니다.
** `key` **
DynamoDB의 항목 키입니다. DynamoDB 항목은 테이블 구조에 따라 단일 해시 키 또는 해시 키와 정렬 키를 가질 수 있습니다. '입력된 값' 지정에 대한 자세한 내용은 [유형 시스템(요청 매핑)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)을 참조하세요. 이 값은 필수입니다.
** `condition` **
DynamoDB에 이미 있는 객체의 상태를 기반으로 요청의 성공 여부를 결정하는 조건. 조건을 지정하지 않으면 `DeleteItem` 요청이 현재 상태와 상관 없이 항목을 삭제합니다. 조건에 대한 자세한 내용은 [조건 표현식](aws-appsync-resolver-mapping-template-reference-dynamodb-condition-expressions.md)을 참조하세요. 이 값은 선택 사항입니다.
** `_version` **
항목의 알려진 최신 버전을 나타내는 숫자 값입니다. 이 값은 선택 사항입니다. 이 필드는 *충돌 감지*에 사용되며 버전이 지정된 데이터 원본에만 지원됩니다.
**`customPartitionKey`**
활성화되면 이 문자열 값은 버전 관리가 활성화되었을 때 델타 동기화 테이블에서 사용되는 `ds_sk` 및 `ds_pk` 레코드의 형식을 수정합니다(자세한 내용은 **AWS AppSync 개발자 안내서의 [충돌 감지 및 동기화](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html) 참조). 활성화되면 `populateIndexFields` 항목 처리도 활성화됩니다. 이 필드는 선택 사항입니다.
**`populateIndexFields`**
**`customPartitionKey`와 함께** 활성화되면 델타 동기화 테이블, 특히 `gsi_ds_pk` 및 `gsi_ds_sk` 열의 각 레코드에 대해 새 항목을 생성하는 부울 값입니다. 자세한 내용은 **AWS AppSync 개발자 안내서의 [충돌 감지 및 동기화](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html)를 참조하세요. 이 필드는 선택 사항입니다.
DynamoDB에서 삭제된 항목은 자동으로 GraphQL 및 JSON 기본 형식으로 변환되며 매핑 컨텍스트(`$context.result`)에서 사용할 수 있습니다.
DynamoDB 형식 변환에 대한 자세한 내용은 [형식 시스템(응답 매핑)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-responses.md)을 참조하세요.
응답 매핑 템플릿에 대한 자세한 내용은 [해석기 매핑 템플릿 개요](resolver-mapping-template-reference-overview.md#aws-appsync-resolver-mapping-template-reference-overview)를 참조하세요.
## 예제 1.
다음 예제는 GraphQL 변형 `deleteItem(id: ID!)`의 매핑 템플릿입니다. 이 ID를 가진 항목이 있으면 해당 항목은 삭제됩니다.
```
{
"version" : "2017-02-28",
"operation" : "DeleteItem",
"key" : {
"id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
}
}
```
## 예제 2.
다음 예제는 GraphQL 변형 `deleteItem(id: ID!, expectedVersion: Int!)`의 매핑 템플릿입니다. 이 ID를 가진 항목이 있으면 해당 항목은 `version` 필드가 `expectedVersion`으로 설정된 경우에만 삭제됩니다.
```
{
"version" : "2017-02-28",
"operation" : "DeleteItem",
"key" : {
"id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
},
"condition" : {
"expression" : "attribute_not_exists(id) OR version = :expectedVersion",
"expressionValues" : {
":expectedVersion" : $util.dynamodb.toDynamoDBJson($expectedVersion)
}
}
}
```
DynamoDB `DeleteItem` API에 대한 자세한 내용은 [DynamoDB API 문서](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DeleteItem.html)를 참조하십시오.
# Query
`Query` 요청 매핑 문서를 사용하면 AWS AppSync DynamoDB 해석기에 DynamoDB에 `Query` 요청하도록 지시하고 다음을 지정할 수 있습니다.
+ 키 표현식
+ 사용할 인덱스
+ 모든 추가 필터
+ 반환할 항목 수
+ 일관된 읽기를 사용할지 여부
+ 쿼리 방향(앞으로 또는 뒤로)
+ 페이지 매김 토큰입니다
`Query` 매핑 문서의 구조는 다음과 같습니다.
```
{
"version" : "2017-02-28",
"operation" : "Query",
"query" : {
"expression" : "some expression",
"expressionNames" : {
"#foo" : "foo"
},
"expressionValues" : {
":bar" : ... typed value
}
},
"index" : "fooIndex",
"nextToken" : "a pagination token",
"limit" : 10,
"scanIndexForward" : true,
"consistentRead" : false,
"select" : "ALL_ATTRIBUTES" | "ALL_PROJECTED_ATTRIBUTES" | "SPECIFIC_ATTRIBUTES",
"filter" : {
...
},
"projection" : {
...
}
}
```
필드는 다음과 같이 정의됩니다.
## 쿼리 필드
### 쿼리 필드 목록
** `version` **
템플릿 정의 버전. `2017-02-28` 및 `2018-05-29`만 현재 지원됩니다. 이 값은 필수입니다.
** `operation` **
수행할 DynamoDB 작업입니다. `Query` DynamoDB 작업을 수행하려면 이 값을 `Query`으로 설정해야 합니다. 이 값은 필수입니다.
** `query` **
`query` 섹션에서는 DynamoDB에서 가져올 항목을 설명하는 키 조건 표현식을 지정할 수 있습니다. 키 조건 표현식을 작성하는 방법에 대한 자세한 내용은 [DynamoDB KeyConditions 문서](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LegacyConditionalParameters.KeyConditions.html)를 참조하십시오. 이 섹션은 지정되어 있어야 합니다.
** `expression` **
쿼리 표현식. 이 필드는 지정되어 있어야 합니다.
** `expressionNames` **
표현식 속성 *name* 자리 표시자의 대체 항목으로, 키-값 페어의 형식으로 표시됩니다. 키는 `expression`에 사용된 name 자리 표시자에 해당하고 값은 DynamoDB에 있는 항목의 속성 이름에 해당하는 문자열이어야 합니다. 이 필드는 선택 사항으로, `expression`에 사용된 표현식 속성인 name 자리 표시자의 대체 항목으로만 채워져야 합니다.
** `expressionValues` **
표현식 속성 *value* 자리 표시자의 대체 항목으로, 키-값 페어의 형식으로 표시됩니다. 키는 `expression`에 사용되는 value 자리 표시자에 해당하고 값은 입력된 값이어야 합니다. '입력된 값'을 지정하는 방법에 대한 자세한 내용은 [유형 시스템(요청 매핑)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)을 참조하세요. 이 값은 필수입니다. 이 필드는 선택 사항으로, `expression`에 사용된 표현식 속성인 value 자리 표시자의 대체 항목으로만 채워져야 합니다.
** `filter` **
반환되기 전 DynamoDB의 결과를 필터링하는 데 사용할 수 있는 추가 필터입니다. 필터에 대한 자세한 내용은 [필터](aws-appsync-resolver-mapping-template-reference-dynamodb-filter.md)를 참조하십시오. 이 필드는 선택 사항입니다.
** `index` **
쿼리할 인덱스의 이름. DynamoDB 쿼리 작업을 사용하면 해시 키의 프라이머리 키 인덱스 이외에 로컬 보조 인덱스 및 글로벌 보조 인덱스를 검사할 수 있습니다. 지정하면 이 값은 DynamoDB에 지정한 인덱스를 쿼리하라고 지시합니다. 이 값을 생략하면 기본 키 인덱스가 쿼리됩니다.
** `nextToken` **
이전 쿼리를 지속하는 페이지 매김 토큰. 이 토큰은 이전 쿼리에서 얻습니다. 이 필드는 선택 사항입니다.
** `limit` **
평가할 최대 항목 수입니다(반드시 일치하는 항목 수는 아님). 이 필드는 선택 사항입니다.
** `scanIndexForward` **
앞으로 또는 뒤로 쿼리할지 여부를 나타내는 부울. 이 필드는 선택 사항으로, 기본값은 `true`입니다.
** `consistentRead` **
DynamoDB 쿼리 시 일관된 읽기를 사용할지 여부를 나타내는 부울. 이 필드는 선택 사항으로, 기본값은 `false`입니다.
** `select` **
기본적으로 AWS AppSync DynamoDB 해석기는 인덱스로 프로젝션된 속성만 반환합니다. 추가 속성이 필요한 경우 이 필드를 설정할 수 있습니다. 이 필드는 선택 사항입니다. 지원되는 값은 다음과 같습니다.
** `ALL_ATTRIBUTES` **
지정한 테이블 또는 인덱스에서 항목 속성을 모두 반환합니다. 로컬 보조 인덱스를 쿼리하는 경우 DynamoDB는 인덱스의 일치하는 각 항목에 대해 상위 테이블의 전체 항목을 가져옵니다. 인덱스가 모든 항목 속성을 프로젝션하도록 구성된 경우, 모든 데이터를 로컬의 보조 인덱스에서 얻을 수 있기 때문에 가져올 필요가 없습니다.
** `ALL_PROJECTED_ATTRIBUTES` **
인덱스를 쿼리하는 경우에만 허용됩니다. 인덱스로 프로젝션된 모든 속성을 가져옵니다. 모든 속성을 프로젝션하도록 인덱스가 구성된 경우 이 반환 값은 `ALL_ATTRIBUTES`를 지정하는 것과 동일합니다.
**`SPECIFIC_ATTRIBUTES`**
`projection`의 `expression`에 나열된 속성만 반환합니다. 이 반환 값은 `Select`에 대한 값을 지정하지 않고 `projection`의 `expression`을 지정하는 것과 같습니다.
**`projection`**
DynamoDB 작업에서 반환할 속성을 지정하는 데 사용되는 프로젝션입니다. 프로젝션에 대한 자세한 내용은 [프로젝션](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-mapping-template-reference-dynamodb.html#aws-appsync-resolver-mapping-template-reference-dynamodb-projections)을 참조하세요. 이 필드는 선택 사항입니다.
DynamoDB의 결과는 자동으로 GraphQL 및 JSON 기본 형식으로 변환되며 매핑 컨텍스트(`$context.result`)에서 사용할 수 있습니다.
DynamoDB 형식 변환에 대한 자세한 내용은 [형식 시스템(응답 매핑)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-responses.md)을 참조하세요.
응답 매핑 템플릿에 대한 자세한 내용은 [해석기 매핑 템플릿 개요](resolver-mapping-template-reference-overview.md#aws-appsync-resolver-mapping-template-reference-overview)를 참조하세요.
결과의 구조는 다음과 같습니다.
```
{
items = [ ... ],
nextToken = "a pagination token",
scannedCount = 10
}
```
필드는 다음과 같이 정의됩니다.
** `items` **
DynamoDB 쿼리에서 반환하는 항목이 포함된 목록.
** `nextToken` **
더 많은 결과가 있을 수 있는 경우 `nextToken`에는 다른 요청에 사용할 수 있는 페이지 매김 토큰이 포함됩니다. 참고로 AWS AppSync는 DynamoDB에서 반환된 페이지 매김 토큰을 암호화하고 난독화합니다. 따라서 테이블 데이터가 호출자에게 실수로 유출되는 일이 없습니다. 페이지 매김 토큰은 여러 해석기 간에 사용할 수 없습니다.
** `scannedCount` **
필터 표현식(있는 경우)을 적용하기 전에 쿼리 조건 표현식과 일치했던 항목 수
## 예제
다음 예제는 GraphQL 쿼리 `getPosts(owner: ID!)`의 매핑 템플릿입니다.
이 예에서는 테이블의 글로벌 보조 인덱스를 쿼리해 지정한 ID가 소유한 게시물을 모두 반환합니다.
```
{
"version" : "2017-02-28",
"operation" : "Query",
"query" : {
"expression" : "ownerId = :ownerId",
"expressionValues" : {
":ownerId" : $util.dynamodb.toDynamoDBJson($context.arguments.owner)
}
},
"index" : "owner-index"
}
```
DynamoDB `Query` API에 대한 자세한 내용은 [DynamoDB API 문서](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html)를 참조하십시오.
# 스캔
`Scan` 요청 매핑 문서를 사용하면 AWS AppSync DynamoDB 해석기에 DynamoDB에 `Scan` 요청하도록 지시하고 다음을 지정할 수 있습니다.
+ 결과를 제외하는 필터
+ 사용할 인덱스
+ 반환할 항목 수
+ 일관된 읽기를 사용할지 여부
+ 페이지 매김 토큰입니다
+ 병렬 스캔
`Scan` 매핑 문서의 구조는 다음과 같습니다.
```
{
"version" : "2017-02-28",
"operation" : "Scan",
"index" : "fooIndex",
"limit" : 10,
"consistentRead" : false,
"nextToken" : "aPaginationToken",
"totalSegments" : 10,
"segment" : 1,
"filter" : {
...
},
"projection" : {
...
}
}
```
필드는 다음과 같이 정의됩니다.
## Scan 필드
### Scan 필드 목록
** `version` **
템플릿 정의 버전. `2017-02-28` 및 `2018-05-29`만 현재 지원됩니다. 이 값은 필수입니다.
** `operation` **
수행할 DynamoDB 작업입니다. `Scan` DynamoDB 작업을 수행하려면 이 값을 `Scan`으로 설정해야 합니다. 이 값은 필수입니다.
** `filter` **
반환되기 전 DynamoDB의 결과를 필터링하는 데 사용할 수 있는 필터. 필터에 대한 자세한 내용은 [필터](aws-appsync-resolver-mapping-template-reference-dynamodb-filter.md)를 참조하십시오. 이 필드는 선택 사항입니다.
** `index` **
쿼리할 인덱스의 이름. DynamoDB 쿼리 작업을 사용하면 해시 키의 프라이머리 키 인덱스 이외에 로컬 보조 인덱스 및 글로벌 보조 인덱스를 검사할 수 있습니다. 지정하면 이 값은 DynamoDB에 지정한 인덱스를 쿼리하라고 지시합니다. 이 값을 생략하면 기본 키 인덱스가 쿼리됩니다.
** `limit` **
한 번에 평가올 수 있는 최대 항목 수입니다. 이 필드는 선택 사항입니다.
** `consistentRead` **
DynamoDB 쿼리 시 일관된 읽기를 사용할지 여부를 나타내는 부울. 이 필드는 선택 사항으로, 기본값은 `false`입니다.
** `nextToken` **
이전 쿼리를 지속하는 페이지 매김 토큰. 이 토큰은 이전 쿼리에서 얻습니다. 이 필드는 선택 사항입니다.
** `select` **
기본적으로 AWS AppSync DynamoDB 해석기는 인덱스로 프로젝션되는 속성만 반환합니다. 추가 속성이 필요한 경우 이 필드를 설정할 수 있습니다. 이 필드는 선택 사항입니다. 지원되는 값은 다음과 같습니다.
** `ALL_ATTRIBUTES` **
지정한 테이블 또는 인덱스에서 항목 속성을 모두 반환합니다. 로컬 보조 인덱스를 쿼리하는 경우 DynamoDB는 인덱스의 일치하는 각 항목에 대해 상위 테이블의 전체 항목을 가져옵니다. 인덱스가 모든 항목 속성을 프로젝션하도록 구성된 경우, 모든 데이터를 로컬의 보조 인덱스에서 얻을 수 있기 때문에 가져올 필요가 없습니다.
** `ALL_PROJECTED_ATTRIBUTES` **
인덱스를 쿼리하는 경우에만 허용됩니다. 인덱스로 프로젝션된 모든 속성을 가져옵니다. 모든 속성을 프로젝션하도록 인덱스가 구성된 경우 이 반환 값은 `ALL_ATTRIBUTES`를 지정하는 것과 동일합니다.
**`SPECIFIC_ATTRIBUTES`**
`projection`의 `expression`에 나열된 속성만 반환합니다. 이 반환 값은 `Select`에 대한 값을 지정하지 않고 `projection`의 `expression`을 지정하는 것과 같습니다.
** `totalSegments` **
병렬 스캔을 수행할 때 테이블을 분할할 기준이 될 세그먼트 수. 이 필드는 선택 사항이지만 `segment`가 지정된 경우에는 반드시 지정해야 합니다.
** `segment` **
병렬 스캔을 수행할 때 작업의 테이블 세그먼트. 이 필드는 선택 사항이지만 `totalSegments`가 지정된 경우에는 반드시 지정해야 합니다.
**`projection`**
DynamoDB 작업에서 반환할 속성을 지정하는 데 사용되는 프로젝션입니다. 프로젝션에 대한 자세한 내용은 [프로젝션](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-mapping-template-reference-dynamodb.html#aws-appsync-resolver-mapping-template-reference-dynamodb-projections)을 참조하세요. 이 필드는 선택 사항입니다.
DynamoDB 스캔에서 반환하는 결과는 자동으로 GraphQL 및 JSON 기본 형식으로 변환되며 매핑 컨텍스트(`$context.result`)에서 사용할 수 있습니다.
DynamoDB 형식 변환에 대한 자세한 내용은 [형식 시스템(응답 매핑)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-responses.md)을 참조하세요.
응답 매핑 템플릿에 대한 자세한 내용은 [해석기 매핑 템플릿 개요](resolver-mapping-template-reference-overview.md#aws-appsync-resolver-mapping-template-reference-overview)를 참조하세요.
결과의 구조는 다음과 같습니다.
```
{
items = [ ... ],
nextToken = "a pagination token",
scannedCount = 10
}
```
필드는 다음과 같이 정의됩니다.
** `items` **
DynamoDB 스캔에서 반환하는 항목이 포함된 목록
** `nextToken` **
결과가 더 있을 수 있는 경우 에는 다른 요청에 사용할 수 있는 페이지 매김 토큰이 `nextToken` 포함되어 있습니다. AWS AppSync는 DynamoDB에서 반환된 페이지 매김 토큰을 암호화하고 난독화합니다. 따라서 테이블 데이터가 호출자에게 실수로 유출되는 일이 없습니다. 또한 페이지 매김 토큰은 여러 해석기 간에 사용할 수 없습니다.
** `scannedCount` **
필터 표현식(있는 경우)을 적용하기 전에 DynamoDB에서 검색한 항목 수.
## 예제 1.
다음 예제는 GraphQL 쿼리 `allPosts`의 매핑 템플릿입니다.
이 예에서는 테이블의 항목을 모두 반환합니다.
```
{
"version" : "2017-02-28",
"operation" : "Scan"
}
```
## 예제 2.
다음 예제는 GraphQL 쿼리 `postsMatching(title: String!)`의 매핑 템플릿입니다.
이 예에서는 제목이 `title` 인수로 시작하는 경우 테이블의 모든 항목이 반환됩니다.
```
{
"version" : "2017-02-28",
"operation" : "Scan",
"filter" : {
"expression" : "begins_with(title, :title)",
"expressionValues" : {
":title" : $util.dynamodb.toDynamoDBJson($context.arguments.title)
},
}
}
```
DynamoDB `Scan` API에 대한 자세한 내용은 [DynamoDB API 문서](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Scan.html)를 참조하십시오.
# 동기화
`Sync` 요청 매핑 문서를 사용하면 DynamoDB 테이블에서 모든 결과를 가져온 다음, 마지막 쿼리(델타 업데이트) 이후에 변경된 데이터만 수신할 수 있습니다. `Sync` 요청은 버전이 지정된 DynamoDB 데이터 소스에만 수행할 수 있습니다. 다음을 지정할 수 있습니다.
+ 결과를 제외하는 필터
+ 반환할 항목 수
+ 페이지 매김 토큰
+ 마지막 `Sync` 작업이 시작된 경우
`Sync` 매핑 문서의 구조는 다음과 같습니다.
```
{
"version" : "2018-05-29",
"operation" : "Sync",
"basePartitionKey": "Base Tables PartitionKey",
"deltaIndexName": "delta-index-name",
"limit" : 10,
"nextToken" : "aPaginationToken",
"lastSync" : 1550000000000,
"filter" : {
...
}
}
```
필드는 다음과 같이 정의됩니다.
## Sync 필드
### Sync 필드 목록
** `version` **
템플릿 정의 버전. 현재 `2018-05-29`만 지원됩니다. 이 값은 필수입니다.
** `operation` **
수행할 DynamoDB 작업입니다. `Sync` 작업을 수행하려면 이 값을 `Sync`으로 설정해야 합니다. 이 값은 필수입니다.
** `filter` **
반환되기 전 DynamoDB의 결과를 필터링하는 데 사용할 수 있는 필터. 필터에 대한 자세한 내용은 [필터](aws-appsync-resolver-mapping-template-reference-dynamodb-filter.md)를 참조하십시오. 이 필드는 선택 사항입니다.
** `limit` **
한 번에 평가올 수 있는 최대 항목 수입니다. 이 필드는 선택 사항입니다. 생략된 경우, 기본 제한이 `100`개 항목으로 설정됩니다. 이 필드의 최대값은 `1000`개 항목입니다.
** `nextToken` **
이전 쿼리를 지속하는 페이지 매김 토큰. 이 토큰은 이전 쿼리에서 얻습니다. 이 필드는 선택 사항입니다.
** `lastSync` **
마지막으로 성공한 `Sync` 작업이 시작되었던 시간(epoch 밀리초)입니다. 지정된 경우, `lastSync` 이후에 변경된 항목만 반환됩니다. 이 필드는 선택 사항이며 초기 `Sync` 작업에서 모든 페이지를 가져온 이후에만 채워져야 합니다. 생략된 경우, *기본* 테이블의 결과가 반환되고, 그렇지 않으면 *델타* 테이블의 결과가 반환됩니다.
**`basePartitionKey`**
`Sync` 작업을 수행할 때 사용되는 *기본* 테이블의 파티션 키입니다. 이 필드를 사용하면 테이블에서 사용자 지정 파티션 키를 활용할 때 `Sync` 작업을 수행할 수 있습니다. 이 필드는 선택 사항입니다.
**`deltaIndexName`**
`Sync` 작업에 사용되는 인덱스. 이 인덱스는 테이블에서 사용자 지정 파티션 키를 사용할 때 전체 델타 저장소 테이블에서 `Sync` 작업을 활성화하는 데 필요합니다. `Sync` 작업은 GSI(`gsi_ds_pk` 및 `gsi_ds_sk`에서 생성)에서 수행됩니다. 이 필드는 선택 사항입니다.
DynamoDB 동기화에서 반환하는 결과는 자동으로 GraphQL 및 JSON 기본 형식으로 변환되며 매핑 컨텍스트(`$context.result`)에서 사용할 수 있습니다.
DynamoDB 형식 변환에 대한 자세한 내용은 [형식 시스템(응답 매핑)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-responses.md)을 참조하세요.
응답 매핑 템플릿에 대한 자세한 내용은 [해석기 매핑 템플릿 개요](resolver-mapping-template-reference-overview.md#aws-appsync-resolver-mapping-template-reference-overview)를 참조하세요.
결과의 구조는 다음과 같습니다.
```
{
items = [ ... ],
nextToken = "a pagination token",
scannedCount = 10,
startedAt = 1550000000000
}
```
필드는 다음과 같이 정의됩니다.
** `items` **
동기화에서 반환하는 항목이 포함된 목록.
** `nextToken` **
결과가 더 있을 수 있는 경우 에는 다른 요청에 사용할 수 있는 페이지 매김 토큰이 `nextToken` 포함되어 있습니다. AWS AppSync는 DynamoDB에서 반환된 페이지 매김 토큰을 암호화하고 난독화합니다. 따라서 테이블 데이터가 호출자에게 실수로 유출되는 일이 없습니다. 또한 페이지 매김 토큰은 여러 해석기 간에 사용할 수 없습니다.
** `scannedCount` **
필터 표현식(있는 경우)을 적용하기 전에 DynamoDB에서 검색한 항목 수.
** `startedAt` **
로컬로 저장하고 다른 요청에 `lastSync` 인수로 사용할 수 있는 동기화 작업이 시작된 시간(Epoch 밀리초)입니다. 페이지 매김 토큰이 요청에 포함된 경우, 이 값은 결과의 첫 페이지에 대한 요청에 의해 반환된 값과 동일합니다.
## 예제
다음 예제는 GraphQL 쿼리 `syncPosts(nextToken: String, lastSync: AWSTimestamp)`의 매핑 템플릿입니다.
이 예에서 `lastSync`가 생략된 경우, 기본 테이블의 모든 항목이 반환됩니다. `lastSync`가 제공된 경우 `lastSync` 이후 변경된 델타 동기화 테이블의 항목만 반환됩니다.
```
{
"version" : "2018-05-29",
"operation" : "Sync",
"limit": 100,
"nextToken": $util.toJson($util.defaultIfNull($ctx.args.nextToken, null)),
"lastSync": $util.toJson($util.defaultIfNull($ctx.args.lastSync, null))
}
```
# BatchGetItem
`BatchGetItem` 요청 매핑 문서를 사용하면 AWS AppSync DynamoDB 해석기에 DynamoDB에 `BatchGetItem` 요청하여 잠재적으로 여러 테이블에서 여러 항목을 검색하도록 지시할 수 있습니다. 이 요청 템플릿에 대해 다음을 지정해야 합니다.
+ 항목을 가져올 테이블 이름
+ 각 테이블에서 가져올 항목의 키
DynamoDB `BatchGetItem` 한도가 적용되고 **표현식 없음**이 제공될 수 있습니다.
`BatchGetItem` 매핑 문서의 구조는 다음과 같습니다.
```
{
"version" : "2018-05-29",
"operation" : "BatchGetItem",
"tables" : {
"table1": {
"keys": [
## Item to retrieve Key
{
"foo" : ... typed value,
"bar" : ... typed value
},
## Item2 to retrieve Key
{
"foo" : ... typed value,
"bar" : ... typed value
}
],
"consistentRead": true|false,
"projection" : {
...
}
},
"table2": {
"keys": [
## Item3 to retrieve Key
{
"foo" : ... typed value,
"bar" : ... typed value
},
## Item4 to retrieve Key
{
"foo" : ... typed value,
"bar" : ... typed value
}
],
"consistentRead": true|false,
"projection" : {
...
}
}
}
}
```
필드는 다음과 같이 정의됩니다.
## BatchGetItem 필드
### BatchGetItem 필드 목록
** `version` **
템플릿 정의 버전. `2018-05-29`만 지원됩니다. 이 값은 필수입니다.
** `operation` **
수행할 DynamoDB 작업입니다. `BatchGetItem` DynamoDB 작업을 수행하려면 이 값을 `BatchGetItem`으로 설정해야 합니다. 이 값은 필수입니다.
** `tables` **
항목을 가져올 DynamoDB 테이블입니다. 이 값은 테이블 이름이 맵의 키로 지정되는 맵입니다. 테이블이 하나 이상 제공되어야 합니다. 이 `tables` 값은 필수입니다.
** `keys` **
검색할 항목의 프라이머리 키를 나타내는 DynamoDB 키 목록입니다. DynamoDB 항목은 테이블 구조에 따라 단일 해시 키 또는 해시 키와 정렬 키를 가질 수 있습니다. '입력된 값'을 지정하는 방법에 대한 자세한 내용은 [유형 시스템(요청 매핑)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)을 참조하세요.
** `consistentRead` **
*GetItem* 작업을 실행할 때 일관된 읽기를 사용할지 여부. 이 값은 선택 사항으로, 기본값은 *false*입니다.
**`projection`**
DynamoDB 작업에서 반환할 속성을 지정하는 데 사용되는 프로젝션입니다. 프로젝션에 대한 자세한 내용은 [프로젝션](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-mapping-template-reference-dynamodb.html#aws-appsync-resolver-mapping-template-reference-dynamodb-projections)을 참조하세요. 이 필드는 선택 사항입니다.
기억해야 할 내용:
+ 테이블에서 항목을 가져오지 못하면 해당 테이블의 데이터 블록에 *null* 요소가 나타납니다.
+ 호출 결과는 요청 매핑 템플릿 내에 제공된 순서에 따라 테이블별로 정렬됩니다.
+ `BatchGetItem` 내부의 각 `Get` 명령은 원자성이지만 배치는 부분적으로 처리될 수 있습니다. 오류로 인해 배치가 부분적으로 처리된 경우 처리되지 않은 키는 *unprocessedKeys* 블록 내에 호출 결과의 일부로 반환됩니다.
+ `BatchGetItem`은 100개의 키로 제한됩니다.
다음과 같은 요청 매핑 템플릿 예제가 있습니다.
```
{
"version": "2018-05-29",
"operation": "BatchGetItem",
"tables": {
"authors": [
{
"author_id": {
"S": "a1"
}
},
],
"posts": [
{
"author_id": {
"S": "a1"
},
"post_id": {
"S": "p2"
}
}
],
}
}
```
`$ctx.result`에서 사용할 수 있는 호출 결과는 다음과 같습니다.
```
{
"data": {
"authors": [null],
"posts": [
# Was retrieved
{
"author_id": "a1",
"post_id": "p2",
"post_title": "title",
"post_description": "description",
}
]
},
"unprocessedKeys": {
"authors": [
# This item was not processed due to an error
{
"author_id": "a1"
}
],
"posts": []
}
}
```
`$ctx.error`에는 오류에 대한 세부 정보가 포함됩니다. 키 **data**, **unprocessedKeys** 및 요청 매핑 템플릿에서 제공된 각 테이블 키는 호출 결과에 표시됩니다. 삭제된 항목은 **데이터** 블록에 나타납니다. 처리되지 않은 항목은 데이터 블록 내에서 *null*로 표시되고 **unprocessedKeys** 블록 내에 배치됩니다.
보다 완벽한 예제를 찾아보려면 [자습서: DynamoDB 배치 해석기](tutorial-dynamodb-batch.md#aws-appsync-tutorial-dynamodb-batch)에서 AppSync 관련 DynamoDB 배치 자습서를 따라해 보세요.
# BatchDeleteItem
`BatchDeleteItem` 요청 매핑 문서를 사용하면 AWS AppSync DynamoDB 해석기에 DynamoDB에 `BatchWriteItem` 요청하여 잠재적으로 여러 테이블에서 여러 항목을 삭제하도록 지시할 수 있습니다. 이 요청 템플릿에 대해 다음을 지정해야 합니다.
+ 항목을 삭제할 테이블 이름
+ 각 테이블에서 삭제할 항목의 키
DynamoDB `BatchWriteItem` 한도가 적용되고 **표현식 없음**이 제공될 수 있습니다.
`BatchDeleteItem` 매핑 문서의 구조는 다음과 같습니다.
```
{
"version" : "2018-05-29",
"operation" : "BatchDeleteItem",
"tables" : {
"table1": [
## Item to delete Key
{
"foo" : ... typed value,
"bar" : ... typed value
},
## Item2 to delete Key
{
"foo" : ... typed value,
"bar" : ... typed value
}],
"table2": [
## Item3 to delete Key
{
"foo" : ... typed value,
"bar" : ... typed value
},
## Item4 to delete Key
{
"foo" : ... typed value,
"bar" : ... typed value
}],
}
}
```
필드는 다음과 같이 정의됩니다.
## BatchDeleteItem 필드
### BatchDeleteItem 필드 목록
** `version` **
템플릿 정의 버전. `2018-05-29`만 지원됩니다. 이 값은 필수입니다.
** `operation` **
수행할 DynamoDB 작업입니다. `BatchDeleteItem` DynamoDB 작업을 수행하려면 이 값을 `BatchDeleteItem`으로 설정해야 합니다. 이 값은 필수입니다.
** `tables` **
항목을 삭제할 DynamoDB 테이블입니다. 각 테이블은 삭제할 항목의 프라이머리 키를 나타내는 DynamoDB 키 목록입니다. DynamoDB 항목은 테이블 구조에 따라 단일 해시 키 또는 해시 키와 정렬 키를 가질 수 있습니다. '입력된 값'을 지정하는 방법에 대한 자세한 내용은 [유형 시스템(요청 매핑)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)을 참조하세요. 테이블이 하나 이상 제공되어야 합니다. `tables` 값이 필요합니다.
기억해야 할 내용:
+ `DeleteItem` 작업과 달리 완전히 삭제된 항목은 응답에서 반환되지 않습니다. 전달된 키만 반환됩니다.
+ 테이블에서 항목을 삭제하지 못하면 해당 테이블의 데이터 블록에 *null* 요소가 나타납니다.
+ 호출 결과는 요청 매핑 템플릿 내에 제공된 순서에 따라 테이블별로 정렬됩니다.
+ `BatchDeleteItem` 내부의 각 `Delete` 명령은 원자성입니다. 그러나 배치는 부분적으로 처리될 수 있습니다. 오류로 인해 배치가 부분적으로 처리된 경우 처리되지 않은 키는 *unprocessedKeys* 블록 내에 호출 결과의 일부로 반환됩니다.
+ `BatchDeleteItem`은 25개의 키로 제한됩니다.
+ 충돌 감지와 함께 사용할 때 이 작업은 지원되지 **않습니다**. 두 가지를 동시에 사용하면 오류가 발생할 수 있습니다.
다음과 같은 요청 매핑 템플릿 예제가 있습니다.
```
{
"version": "2018-05-29",
"operation": "BatchDeleteItem",
"tables": {
"authors": [
{
"author_id": {
"S": "a1"
}
},
],
"posts": [
{
"author_id": {
"S": "a1"
},
"post_id": {
"S": "p2"
}
}
],
}
}
```
`$ctx.result`에서 사용할 수 있는 호출 결과는 다음과 같습니다.
```
{
"data": {
"authors": [null],
"posts": [
# Was deleted
{
"author_id": "a1",
"post_id": "p2"
}
]
},
"unprocessedKeys": {
"authors": [
# This key was not processed due to an error
{
"author_id": "a1"
}
],
"posts": []
}
}
```
`$ctx.error`에는 오류에 대한 세부 정보가 포함됩니다. 키 **data**, **unprocessedKeys** 및 요청 매핑 템플릿에서 제공된 각 테이블 키는 호출 결과에 표시됩니다. 삭제된 항목은 **데이터** 블록에 나타납니다. 처리되지 않은 항목은 데이터 블록 내에서 *null*로 표시되고 **unprocessedKeys** 블록 내에 배치됩니다.
보다 완벽한 예제를 찾아보려면 [자습서: DynamoDB 배치 해석기](tutorial-dynamodb-batch.md#aws-appsync-tutorial-dynamodb-batch)에서 AppSync 관련 DynamoDB 배치 자습서를 따라해 보세요.
# BatchPutItem
`BatchPutItem` 요청 매핑 문서를 사용하면 AWS AppSync DynamoDB 해석기에 DynamoDB에 `BatchWriteItem` 요청하여 잠재적으로 여러 테이블에 여러 항목을 배치하도록 지시할 수 있습니다. 이 요청 템플릿에 대해 다음을 지정해야 합니다.
+ 항목을 저장할 테이블 이름
+ 각 테이블에 저장할 전체 항목
DynamoDB `BatchWriteItem` 한도가 적용되고 **표현식 없음**이 제공될 수 있습니다.
`BatchPutItem` 매핑 문서의 구조는 다음과 같습니다.
```
{
"version" : "2018-05-29",
"operation" : "BatchPutItem",
"tables" : {
"table1": [
## Item to put
{
"foo" : ... typed value,
"bar" : ... typed value
},
## Item2 to put
{
"foo" : ... typed value,
"bar" : ... typed value
}],
"table2": [
## Item3 to put
{
"foo" : ... typed value,
"bar" : ... typed value
},
## Item4 to put
{
"foo" : ... typed value,
"bar" : ... typed value
}],
}
}
```
필드는 다음과 같이 정의됩니다.
## BatchPutItem 필드
### BatchPutItem 필드 목록
** `version` **
템플릿 정의 버전. `2018-05-29`만 지원됩니다. 이 값은 필수입니다.
** `operation` **
수행할 DynamoDB 작업입니다. `BatchPutItem` DynamoDB 작업을 수행하려면 이 값을 `BatchPutItem`으로 설정해야 합니다. 이 값은 필수입니다.
** `tables` **
항목을 넣을 DynamoDB 테이블입니다. 각 테이블 항목은 이 특정 테이블에 삽입할 DynamoDB 항목 목록을 나타냅니다. 테이블이 하나 이상 제공되어야 합니다. 이 값은 필수입니다.
기억해야 할 내용:
+ 성공하면, 완전히 삽입된 항목이 응답에서 반환됩니다.
+ 테이블에 항목이 삽입되지 못하면 해당 테이블의 데이터 블록에 *null* 요소가 표시됩니다.
+ 삽입된 항목은 요청 매핑 템플릿 내에 제공된 순서에 따라 테이블별로 정렬됩니다.
+ `BatchPutItem` 내부의 각 `Put` 명령은 원자성이지만 배치는 부분적으로 처리될 수 있습니다. 오류로 인해 배치가 부분적으로 처리된 경우 처리되지 않은 키는 *unprocessedKeys* 블록 내에 호출 결과의 일부로 반환됩니다.
+ `BatchPutItem`은 25개의 항목으로 제한됩니다.
+ 충돌 감지와 함께 사용할 때 이 작업은 지원되지 **않습니다**. 두 가지를 동시에 사용하면 오류가 발생할 수 있습니다.
다음과 같은 요청 매핑 템플릿 예제가 있습니다.
```
{
"version": "2018-05-29",
"operation": "BatchPutItem",
"tables": {
"authors": [
{
"author_id": {
"S": "a1"
},
"author_name": {
"S": "a1_name"
}
},
],
"posts": [
{
"author_id": {
"S": "a1"
},
"post_id": {
"S": "p2"
},
"post_title": {
"S": "title"
}
}
],
}
}
```
`$ctx.result`에서 사용할 수 있는 호출 결과는 다음과 같습니다.
```
{
"data": {
"authors": [
null
],
"posts": [
# Was inserted
{
"author_id": "a1",
"post_id": "p2",
"post_title": "title"
}
]
},
"unprocessedItems": {
"authors": [
# This item was not processed due to an error
{
"author_id": "a1",
"author_name": "a1_name"
}
],
"posts": []
}
}
```
`$ctx.error`에는 오류에 대한 세부 정보가 포함됩니다. 키 **data**, **unprocessedItems** 및 요청 매핑 템플릿에서 제공된 각 테이블 키는 호출 결과에 표시됩니다. 삽입된 항목은 **데이터** 블록에 나타납니다. 처리되지 않은 항목은 데이터 블록 내에서 *null*로 표시되고 **unprocessedItems** 블록 내에 배치됩니다.
보다 완벽한 예제를 찾아보려면 [자습서: DynamoDB 배치 해석기](tutorial-dynamodb-batch.md#aws-appsync-tutorial-dynamodb-batch)에서 AppSync 관련 DynamoDB 배치 자습서를 따라해 보세요.
# TransactGetItems
`TransactGetItems` 요청 매핑 문서를 사용하면 AWS AppSync DynamoDB 해석기에 DynamoDB에 `TransactGetItems` 요청하여 잠재적으로 여러 테이블에서 여러 항목을 검색하도록 지시할 수 있습니다. 이 요청 템플릿에 대해 다음을 지정해야 합니다.
+ 항목을 가져올 각 요청 항목의 테이블 이름
+ 각 테이블에서 가져올 각 요청 항목의 키
DynamoDB `TransactGetItems` 한도가 적용되고 **표현식 없음**이 제공될 수 있습니다.
`TransactGetItems` 매핑 문서의 구조는 다음과 같습니다.
```
{
"version": "2018-05-29",
"operation": "TransactGetItems",
"transactItems": [
## First request item
{
"table": "table1",
"key": {
"foo": ... typed value,
"bar": ... typed value
},
"projection" : {
...
}
},
## Second request item
{
"table": "table2",
"key": {
"foo": ... typed value,
"bar": ... typed value
},
"projection" : {
...
}
}
]
}
```
필드는 다음과 같이 정의됩니다.
## TransactGetItems 필드
### TransactGetItems 필드 목록
** `version` **
템플릿 정의 버전. `2018-05-29`만 지원됩니다. 이 값은 필수입니다.
** `operation` **
수행할 DynamoDB 작업입니다. `TransactGetItems` DynamoDB 작업을 수행하려면 이 값을 `TransactGetItems`으로 설정해야 합니다. 이 값은 필수입니다.
** `transactItems` **
포함할 요청 항목입니다. 이 값은 요청 항목의 배열입니다. 하나 이상의 요청 항목이 제공되어야 합니다. 이 `transactItems` 값은 필수입니다.
** `table` **
항목을 가져올 DynamoDB 테이블입니다. 이 값은 테이블 이름의 문자열입니다. 이 `table` 값은 필수입니다.
** `key` **
검색할 항목의 프라이머리 키를 나타내는 DynamoDB 키입니다. DynamoDB 항목은 테이블 구조에 따라 단일 해시 키 또는 해시 키와 정렬 키를 가질 수 있습니다. '입력된 값'을 지정하는 방법에 대한 자세한 내용은 [유형 시스템(요청 매핑)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)을 참조하세요.
**`projection`**
DynamoDB 작업에서 반환할 속성을 지정하는 데 사용되는 프로젝션입니다. 프로젝션에 대한 자세한 내용은 [프로젝션](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-mapping-template-reference-dynamodb.html#aws-appsync-resolver-mapping-template-reference-dynamodb-projections)을 참조하세요. 이 필드는 선택 사항입니다.
기억해야 할 내용:
+ 트랜잭션이 성공하면 `items` 블록에서 가져오는 항목의 순서는 요청 항목의 순서와 동일합니다.
+ 트랜잭션은 전부 또는 전무 방식으로 수행됩니다. 요청 항목에 오류가 발생하면 전체 트랜잭션이 수행되지 않고 오류 세부 정보가 반환됩니다.
+ 가져올 수 없는 요청 항목은 오류가 아닙니다. 대신 해당 위치의 *항목* 블록에 *null* 요소가 나타납니다.
+ 트랜잭션의 오류가 *TransactionCanceledException*인 경우 `cancellationReasons` 블록이 채워집니다. `cancellationReasons` 블록 내의 취소 사유 순서는 요청 항목의 순서와 동일합니다.
+ `TransactGetItems`는 100개의 요청 항목으로 제한됩니다.
다음과 같은 요청 매핑 템플릿 예제가 있습니다.
```
{
"version": "2018-05-29",
"operation": "TransactGetItems",
"transactItems": [
## First request item
{
"table": "posts",
"key": {
"post_id": {
"S": "p1"
}
}
},
## Second request item
{
"table": "authors",
"key": {
"author_id": {
"S": a1
}
}
}
]
}
```
트랜잭션이 성공하고 첫 번째 요청된 항목만 검색되는 경우 `$ctx.result`에서 사용할 수 있는 호출 결과는 다음과 같습니다.
```
{
"items": [
{
// Attributes of the first requested item
"post_id": "p1",
"post_title": "title",
"post_description": "description"
},
// Could not retrieve the second requested item
null,
],
"cancellationReasons": null
}
```
첫 번째 요청 항목으로 인한 *TransactionCanceledException* 때문에 트랜잭션이 실패할 경우 `$ctx.result`에서 사용할 수 있는 호출 결과는 다음과 같습니다.
```
{
"items": null,
"cancellationReasons": [
{
"type":"Sample error type",
"message":"Sample error message"
},
{
"type":"None",
"message":"None"
}
]
}
```
`$ctx.error`에는 오류에 대한 세부 정보가 포함됩니다. 키 **항목** 과 **cancellationReasons**는 `$ctx.result`에 있습니다.
보다 완벽한 예제를 찾아보려면 [자습서: DynamoDB 트랜잭션 해석기](tutorial-dynamodb-transact.md#aws-appsync-tutorial-dynamodb-transact)에서 AppSync 관련 DynamoDB 트랜잭션 자습서를 따라해 보세요.
# TransactWriteItems
`TransactWriteItems` 요청 매핑 문서를 사용하면 AWS AppSync DynamoDB 해석기에 DynamoDB에 `TransactWriteItems` 요청하여 잠재적으로 여러 테이블에 여러 항목을 쓰도록 지시할 수 있습니다. 이 요청 템플릿에 대해 다음을 지정해야 합니다.
+ 각 요청 항목의 대상 테이블 이름
+ 수행할 각 요청 항목의 작업입니다. 지원되는 작업에는 *PutItem*, *UpdateItem*, *DeleteItem*, *ConditionCheck*의 네 가지 유형이 있습니다.
+ 작성할 각 요청 항목의 키
DynamoDB `TransactWriteItems` 제한이 적용됩니다.
`TransactWriteItems` 매핑 문서의 구조는 다음과 같습니다.
```
{
"version": "2018-05-29",
"operation": "TransactWriteItems",
"transactItems": [
{
"table": "table1",
"operation": "PutItem",
"key": {
"foo": ... typed value,
"bar": ... typed value
},
"attributeValues": {
"baz": ... typed value
},
"condition": {
"expression": "someExpression",
"expressionNames": {
"#foo": "foo"
},
"expressionValues": {
":bar": ... typed value
},
"returnValuesOnConditionCheckFailure": true|false
}
},
{
"table":"table2",
"operation": "UpdateItem",
"key": {
"foo": ... typed value,
"bar": ... typed value
},
"update": {
"expression": "someExpression",
"expressionNames": {
"#foo": "foo"
},
"expressionValues": {
":bar": ... typed value
}
},
"condition": {
"expression": "someExpression",
"expressionNames": {
"#foo":"foo"
},
"expressionValues": {
":bar": ... typed value
},
"returnValuesOnConditionCheckFailure": true|false
}
},
{
"table": "table3",
"operation": "DeleteItem",
"key":{
"foo": ... typed value,
"bar": ... typed value
},
"condition":{
"expression": "someExpression",
"expressionNames": {
"#foo": "foo"
},
"expressionValues": {
":bar": ... typed value
},
"returnValuesOnConditionCheckFailure": true|false
}
},
{
"table": "table4",
"operation": "ConditionCheck",
"key":{
"foo": ... typed value,
"bar": ... typed value
},
"condition":{
"expression": "someExpression",
"expressionNames": {
"#foo": "foo"
},
"expressionValues": {
":bar": ... typed value
},
"returnValuesOnConditionCheckFailure": true|false
}
}
]
}
```
## TransactWriteItems 필드
### TransactWriteItems 필드 목록
**필드는 다음과 같이 정의됩니다.**
** `version` **
템플릿 정의 버전. `2018-05-29`만 지원됩니다. 이 값은 필수입니다.
** `operation` **
수행할 DynamoDB 작업입니다. `TransactWriteItems` DynamoDB 작업을 수행하려면 이 값을 `TransactWriteItems`으로 설정해야 합니다. 이 값은 필수입니다.
** `transactItems` **
포함할 요청 항목입니다. 이 값은 요청 항목의 배열입니다. 하나 이상의 요청 항목이 제공되어야 합니다. 이 `transactItems` 값은 필수입니다.
`PutItem`의 필드는 다음과 같이 정의됩니다.
** `table` **
대상 DynamoDB 테이블입니다. 이 값은 테이블 이름의 문자열입니다. 이 `table` 값은 필수입니다.
** `operation` **
수행할 DynamoDB 작업입니다. `PutItem` DynamoDB 작업을 수행하려면 이 값을 `PutItem`으로 설정해야 합니다. 이 값은 필수입니다.
** `key` **
입력할 항목의 프라이머리 키를 나타내는 DynamoDB 키입니다. DynamoDB 항목은 테이블 구조에 따라 단일 해시 키 또는 해시 키와 정렬 키를 가질 수 있습니다. '입력된 값'을 지정하는 방법에 대한 자세한 내용은 [유형 시스템(요청 매핑)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)을 참조하세요. 이 값은 필수입니다.
** `attributeValues` **
DynamoDB에 저장할 항목의 나머지 속성. '입력된 값'을 지정하는 방법에 대한 자세한 내용은 [유형 시스템(요청 매핑)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)을 참조하세요. 이 필드는 선택 사항입니다.
** `condition` **
DynamoDB에 이미 있는 객체의 상태를 기반으로 요청의 성공 여부를 결정하는 조건. 조건을 지정하지 않으면 `PutItem` 요청이 해당 항목에 대한 기존 입력을 덮어씁니다. 조건 검사에 실패할 경우 기존 항목을 다시 가져올지 여부를 지정할 수 있습니다. 트랜잭션 조건에 대한 자세한 내용은 [트랜잭션 조건 표현식](aws-appsync-resolver-mapping-template-reference-dynamodb-transaction-condition-expressions.md)을 참조하세요. 이 값은 선택 사항입니다.
`UpdateItem`의 필드는 다음과 같이 정의됩니다.
** `table` **
업데이트할 DynamoDB 테이블입니다. 이 값은 테이블 이름의 문자열입니다. 이 `table` 값은 필수입니다.
** `operation` **
수행할 DynamoDB 작업입니다. `UpdateItem` DynamoDB 작업을 수행하려면 이 값을 `UpdateItem`으로 설정해야 합니다. 이 값은 필수입니다.
** `key` **
업데이트할 항목의 프라이머리 키를 나타내는 DynamoDB 키입니다. DynamoDB 항목은 테이블 구조에 따라 단일 해시 키 또는 해시 키와 정렬 키를 가질 수 있습니다. '입력된 값'을 지정하는 방법에 대한 자세한 내용은 [유형 시스템(요청 매핑)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)을 참조하세요. 이 값은 필수입니다.
** `update` **
`update` 섹션에서는 DynamoDB의 항목 업데이트 방법을 설명하는 업데이트 표현식을 지정합니다. 업데이트 표현식을 작성하는 방법에 대한 자세한 내용은 [DynamoDB UpdateExpressions 문서](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.UpdateExpressions.html)를 참조하십시오. 이 섹션은 필수입니다.
** `condition` **
DynamoDB에 이미 있는 객체의 상태를 기반으로 요청의 성공 여부를 결정하는 조건. 조건을 지정하지 않으면 `UpdateItem` 요청이 현재 상태와 상관 없이 기존 항목을 업데이트합니다. 조건 검사에 실패할 경우 기존 항목을 다시 가져올지 여부를 지정할 수 있습니다. 트랜잭션 조건에 대한 자세한 내용은 [트랜잭션 조건 표현식](aws-appsync-resolver-mapping-template-reference-dynamodb-transaction-condition-expressions.md)을 참조하세요. 이 값은 선택 사항입니다.
`DeleteItem`의 필드는 다음과 같이 정의됩니다.
** `table` **
항목을 삭제할 DynamoDB 테이블입니다. 이 값은 테이블 이름의 문자열입니다. 이 `table` 값은 필수입니다.
** `operation` **
수행할 DynamoDB 작업입니다. `DeleteItem` DynamoDB 작업을 수행하려면 이 값을 `DeleteItem`으로 설정해야 합니다. 이 값은 필수입니다.
** `key` **
삭제할 항목의 프라이머리 키를 나타내는 DynamoDB 키입니다. DynamoDB 항목은 테이블 구조에 따라 단일 해시 키 또는 해시 키와 정렬 키를 가질 수 있습니다. '입력된 값'을 지정하는 방법에 대한 자세한 내용은 [유형 시스템(요청 매핑)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)을 참조하세요. 이 값은 필수입니다.
** `condition` **
DynamoDB에 이미 있는 객체의 상태를 기반으로 요청의 성공 여부를 결정하는 조건. 조건을 지정하지 않으면 `DeleteItem` 요청이 현재 상태와 상관 없이 항목을 삭제합니다. 조건 검사에 실패할 경우 기존 항목을 다시 가져올지 여부를 지정할 수 있습니다. 트랜잭션 조건에 대한 자세한 내용은 [트랜잭션 조건 표현식](aws-appsync-resolver-mapping-template-reference-dynamodb-transaction-condition-expressions.md)을 참조하세요. 이 값은 선택 사항입니다.
`ConditionCheck`의 필드는 다음과 같이 정의됩니다.
** `table` **
조건을 검사할 DynamoDB 테이블입니다. 이 값은 테이블 이름의 문자열입니다. 이 `table` 값은 필수입니다.
** `operation` **
수행할 DynamoDB 작업입니다. `ConditionCheck` DynamoDB 작업을 수행하려면 이 값을 `ConditionCheck`으로 설정해야 합니다. 이 값은 필수입니다.
** `key` **
조건을 확인할 항목의 프라이머리 키를 나타내는 DynamoDB 키입니다. DynamoDB 항목은 테이블 구조에 따라 단일 해시 키 또는 해시 키와 정렬 키를 가질 수 있습니다. '입력된 값'을 지정하는 방법에 대한 자세한 내용은 [유형 시스템(요청 매핑)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)을 참조하세요. 이 값은 필수입니다.
** `condition` **
DynamoDB에 이미 있는 객체의 상태를 기반으로 요청의 성공 여부를 결정하는 조건. 조건 검사에 실패할 경우 기존 항목을 다시 가져올지 여부를 지정할 수 있습니다. 트랜잭션 조건에 대한 자세한 내용은 [트랜잭션 조건 표현식](aws-appsync-resolver-mapping-template-reference-dynamodb-transaction-condition-expressions.md)을 참조하세요. 이 값은 필수입니다.
기억해야 할 내용:
+ 성공할 경우 요청 항목의 키만 응답에 반환됩니다. 키 순서는 요청 항목의 순서와 동일합니다.
+ 트랜잭션은 전부 또는 전무 방식으로 수행됩니다. 요청 항목에 오류가 발생하면 전체 트랜잭션이 수행되지 않고 오류 세부 정보가 반환됩니다.
+ 두 개의 요청 항목이 동일한 항목을 대상으로 할 수 없습니다. 그렇지 않으면 *TransactionCanceledException* 오류가 발생합니다.
+ 트랜잭션의 오류가 *TransactionCanceledException*인 경우 `cancellationReasons` 블록이 채워집니다. 요청 항목의 조건 검사에 실패한 **동시에** `returnValuesOnConditionCheckFailure`를 `false`로 지정하지 않은 경우, 테이블에 있는 항목이 검색되고 `item`에서 `cancellationReasons` 블록의 해당 위치에 저장됩니다.
+ `TransactWriteItems`는 100개의 요청 항목으로 제한됩니다.
+ 충돌 감지와 함께 사용할 때 이 작업은 지원되지 **않습니다**. 두 가지를 동시에 사용하면 오류가 발생할 수 있습니다.
다음과 같은 요청 매핑 템플릿 예제가 있습니다.
```
{
"version": "2018-05-29",
"operation": "TransactWriteItems",
"transactItems": [
{
"table": "posts",
"operation": "PutItem",
"key": {
"post_id": {
"S": "p1"
}
},
"attributeValues": {
"post_title": {
"S": "New title"
},
"post_description": {
"S": "New description"
}
},
"condition": {
"expression": "post_title = :post_title",
"expressionValues": {
":post_title": {
"S": "Expected old title"
}
}
}
},
{
"table":"authors",
"operation": "UpdateItem",
"key": {
"author_id": {
"S": "a1"
},
},
"update": {
"expression": "SET author_name = :author_name",
"expressionValues": {
":author_name": {
"S": "New name"
}
}
},
}
]
}
```
트랜잭션이 성공하면 `$ctx.result`에서 사용할 수 있는 호출 결과는 다음과 같습니다.
```
{
"keys": [
// Key of the PutItem request
{
"post_id": "p1",
},
// Key of the UpdateItem request
{
"author_id": "a1"
}
],
"cancellationReasons": null
}
```
`PutItem` 요청의 조건 검사 실패로 인해 트랜잭션이 실패할 경우 `$ctx.result`에서 사용할 수 있는 간접 호출 결과는 다음과 같습니다.
```
{
"keys": null,
"cancellationReasons": [
{
"item": {
"post_id": "p1",
"post_title": "Actual old title",
"post_description": "Old description"
},
"type": "ConditionCheckFailed",
"message": "The condition check failed."
},
{
"type": "None",
"message": "None"
}
]
}
```
`$ctx.error`에는 오류에 대한 세부 정보가 포함됩니다. **키** 및 **cancellationReasons** 키는 `$ctx.result`에 있습니다.
보다 완벽한 예제를 찾아보려면 [자습서: DynamoDB 트랜잭션 해석기](tutorial-dynamodb-transact.md#aws-appsync-tutorial-dynamodb-transact)에서 AppSync 관련 DynamoDB 트랜잭션 자습서를 따라해 보세요.
# 형식 시스템(요청 매핑)
AWS AppSync DynamoDB 해석기를 사용하여 DynamoDB 테이블을 호출하는 경우 AWS AppSync는 해당 호출에 사용할 각 값의 유형을 알아야 합니다. 이는 DynamoDB가 GraphQL 또는 JSON(예: 세트 및 바이너리 데이터)보다 더 많은 유형의 프리미티브를 지원하기 때문입니다. AWS AppSync는 GraphQL과 DynamoDB 간에 변환할 때 몇 가지 힌트가 필요하며, 그렇지 않으면 테이블에서 데이터가 구조화되는 방식을 일부 가정해야 합니다.
DynamoDB 데이터 유형에 대한 자세한 내용은 DynamoDB [데이터 유형 설명자](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Programming.LowLevelAPI.html#Programming.LowLevelAPI.DataTypeDescriptors) 및 [데이터 유형](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes) 설명서를 참조하세요.
DynamoDB 값은 단일 키-값 페어가 포함된 JSON 객체로 나타납니다. 여기서 키는 DynamoDB 형식을 지정하고 값은 값 자체를 지정합니다. 다음 예에서 키 `S`는 값이 문자열임을 나타내고 값 `identifier`는 문자열 값 자체를 나타냅니다.
```
{ "S" : "identifier" }
```
JSON 객체는 키-값 페어를 두 개 이상 포함할 수 없습니다. 키-값 페어를 두 개 이상 지정하면 요청 매핑 문서가 구문 분석되지 않습니다.
요청 매핑 문서에서 값을 지정해야 하는 모든 곳에 DynamoDB 값을 사용할 수 있습니다. 이렇게 해야 하는 위치로는 `key` 및 `attributeValue` 섹션과 표현식 섹션 중 `expressionValues` 섹션이 있습니다. 다음 예에서는 DynamoDB 문자열 값 `identifier`를 `key` 섹션(`GetItem` 요청 매핑 문서)의 `id` 필드에 할당합니다.
```
"key" : {
"id" : { "S" : "identifier" }
}
```
**지원되는 유형**
AWS AppSync는 다음과 같은 DynamoDB 스칼라, 문서 및 세트 유형을 지원합니다.
**String 형식 `S` **
단일 문자열 값. DynamoDB String 값은 다음과 같이 표시됩니다.
```
{ "S" : "some string" }
```
사용 예제는 다음과 같습니다.
```
"key" : {
"id" : { "S" : "some string" }
}
```
**String set 형식 `SS` **
문자열 값 집합. DynamoDB String Set 값은 다음과 같이 표시됩니다.
```
{ "SS" : [ "first value", "second value", ... ] }
```
사용 예제는 다음과 같습니다.
```
"attributeValues" : {
"phoneNumbers" : { "SS" : [ "+1 555 123 4567", "+1 555 234 5678" ] }
}
```
**Number 형식 `N` **
단일 숫자 값. DynamoDB Number 값은 다음과 같이 표시됩니다.
```
{ "N" : 1234 }
```
사용 예제는 다음과 같습니다.
```
"expressionValues" : {
":expectedVersion" : { "N" : 1 }
}
```
**Number set 형식 `NS` **
숫자 값 집합. DynamoDB Number Set 값은 다음과 같이 표시됩니다.
```
{ "NS" : [ 1, 2.3, 4 ... ] }
```
사용 예제는 다음과 같습니다.
```
"attributeValues" : {
"sensorReadings" : { "NS" : [ 67.8, 12.2, 70 ] }
}
```
**Binary 형식 `B` **
이진 값. DynamoDB Binary 값은 다음과 같이 표시됩니다.
```
{ "B" : "SGVsbG8sIFdvcmxkIQo=" }
```
값은 실제로 문자열입니다. 여기서 문자열은 이진 데이터의 base64 인코딩 표현입니다. AWS AppSync는이 문자열을 DynamoDB로 보내기 전에 이진 값으로 다시 디코딩합니다. AWS AppSync는 RFC 2045에 정의된 base64 디코딩 체계를 사용합니다. base64 알파벳에 없는 모든 문자는 무시됩니다.
사용 예제는 다음과 같습니다.
```
"attributeValues" : {
"binaryMessage" : { "B" : "SGVsbG8sIFdvcmxkIQo=" }
}
```
**Binary set 형식 `BS` **
이진 값 집합. DynamoDB Binary Set 값은 다음과 같이 표시됩니다.
```
{ "BS" : [ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ... ] }
```
값은 실제로 문자열입니다. 여기서 문자열은 이진 데이터의 base64 인코딩 표현입니다. AWS AppSync는이 문자열을 DynamoDB로 보내기 전에 이진 값으로 다시 디코딩합니다. AWS AppSync는 RFC 2045에 정의된 base64 디코딩 체계를 사용합니다. base64 알파벳에 없는 모든 문자는 무시됩니다.
사용 예제는 다음과 같습니다.
```
"attributeValues" : {
"binaryMessages" : { "BS" : [ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ] }
}
```
**Boolean 형식 `BOOL` **
부울 값. DynamoDB Boolean 값은 다음과 같이 표시됩니다.
```
{ "BOOL" : true }
```
`true` 및 `false`만 유효한 값입니다.
사용 예제는 다음과 같습니다.
```
"attributeValues" : {
"orderComplete" : { "BOOL" : false }
}
```
**List 형식 `L` **
기타 지원되는 DynamoDB 값 목록입니다. DynamoDB List 값은 다음과 같이 표시됩니다.
```
{ "L" : [ ... ] }
```
값은 복합 값으로, 목록에는 지원되는 DynamoDB 값(다른 목록 포함)이 0개 이상 포함될 수 있습니다. 또한 목록에는 여러 형식이 혼합되어 포함될 수 있습니다.
사용 예제는 다음과 같습니다.
```
{ "L" : [
{ "S" : "A string value" },
{ "N" : 1 },
{ "SS" : [ "Another string value", "Even more string values!" ] }
]
}
```
**Map 형식 `M` **
지원되는 다른 DynamoDB 값의 키-값 페어로 구성된 순서 없는 모음을 나타냅니다. DynamoDB Map 값은 다음과 같이 표시됩니다.
```
{ "M" : { ... } }
```
맵에는 키-값 페어가 0개 이상 포함될 수 있습니다. 키는 문자열이어야 하며 값은 지원되는 모든 DynamoDB 값(다른 맵 포함)일 수 있습니다. 또한 맵에는 여러 형식이 혼합되어 포함될 수 있습니다.
사용 예제는 다음과 같습니다.
```
{ "M" : {
"someString" : { "S" : "A string value" },
"someNumber" : { "N" : 1 },
"stringSet" : { "SS" : [ "Another string value", "Even more string values!" ] }
}
}
```
**Null 형식 `NULL` **
null 값. DynamoDB Null 값은 다음과 같이 표시됩니다.
```
{ "NULL" : null }
```
사용 예제는 다음과 같습니다.
```
"attributeValues" : {
"phoneNumbers" : { "NULL" : null }
}
```
각 형식에 대한 자세한 내용은 [DynamoDB 문서](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html)를 참조하십시오.
# 형식 시스템(응답 매핑)
DynamoDB로부터 응답을 수신하면 AWS AppSync는 자동으로 응답을 GraphQL 및 JSON 기본 유형으로 변환합니다. DynamoDB의 각 속성은 디코딩되어 응답 매핑 컨텍스트에서 반환됩니다.
예를 들어 DynamoDB에서 다음을 반환한 경우:
```
{
"id" : { "S" : "1234" },
"name" : { "S" : "Nadia" },
"age" : { "N" : 25 }
}
```
그런 다음 AWS AppSync DynamoDB 해석기는 이를 GraphQL 및 JSON 유형으로 다음과 같이 변환합니다.
```
{
"id" : "1234",
"name" : "Nadia",
"age" : 25
}
```
이 섹션에서는 AWS AppSync가 다음 DynamoDB 스칼라, 문서 및 세트 유형을 변환하는 방법을 설명합니다.
**String 형식 `S` **
단일 문자열 값. DynamoDB String 값은 문자열로 반환됩니다.
예를 들어 DynamoDB에서 다음 DynamoDB String 값을 반환한 경우:
```
{ "S" : "some string" }
```
AWS AppSync는 이를 문자열로 변환합니다.
```
"some string"
```
**String set 형식 `SS` **
문자열 값 집합. DynamoDB String Set 값은 문자열 목록으로 반환됩니다.
예를 들어 DynamoDB에서 다음 DynamoDB String Set 값을 반환한 경우:
```
{ "SS" : [ "first value", "second value", ... ] }
```
AWS AppSync는 이를 문자열 목록으로 변환합니다.
```
[ "+1 555 123 4567", "+1 555 234 5678" ]
```
**Number 형식 `N` **
단일 숫자 값. DynamoDB Number 값은 숫자로 반환됩니다.
예를 들어 DynamoDB에서 다음 DynamoDB Number 값을 반환한 경우:
```
{ "N" : 1234 }
```
AWS AppSync는 이를 숫자로 변환합니다.
```
1234
```
**Number set 형식 `NS` **
숫자 값 집합. DynamoDB Number Set 값은 숫자 목록으로 반환됩니다.
예를 들어 DynamoDB에서 다음 DynamoDB Number Set 값을 반환한 경우:
```
{ "NS" : [ 67.8, 12.2, 70 ] }
```
AWS AppSync는 이를 숫자 목록으로 변환합니다.
```
[ 67.8, 12.2, 70 ]
```
**Binary 형식 `B` **
이진 값. DynamoDB Binary 값은 base64로 표시된 값이 포함된 문자열로 반환됩니다.
예를 들어 DynamoDB에서 다음 DynamoDB Binary 값을 반환한 경우:
```
{ "B" : "SGVsbG8sIFdvcmxkIQo=" }
```
AWS AppSync는 값을 base64로 표현한 문자열로 변환합니다.
```
"SGVsbG8sIFdvcmxkIQo="
```
이진 데이터는 [RFC 4648](https://tools.ietf.org/html/rfc4648) 및 [RFC 2045](https://tools.ietf.org/html/rfc2045)에 지정된 base64 인코딩 체계로 인코딩됩니다.
**Binary set 형식 `BS` **
이진 값 집합. DynamoDB Binary Set 값은 base64로 표시된 값이 포함된 문자열 목록으로 반환됩니다.
예를 들어 DynamoDB에서 다음 DynamoDB Binary Set 값을 반환한 경우:
```
{ "BS" : [ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ... ] }
```
AWS AppSync는 값을 base64로 표현한 문자열 목록으로 변환합니다.
```
[ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ... ]
```
이진 데이터는 [RFC 4648](https://tools.ietf.org/html/rfc4648) 및 [RFC 2045](https://tools.ietf.org/html/rfc2045)에 지정된 base64 인코딩 체계로 인코딩됩니다.
**Boolean 형식 `BOOL` **
부울 값. DynamoDB Boolean 값은 부울로 반환됩니다.
예를 들어 DynamoDB에서 다음 DynamoDB Boolean 값을 반환한 경우:
```
{ "BOOL" : true }
```
AWS AppSync는 이를 부울로 변환합니다.
```
true
```
**List 형식 `L` **
기타 지원되는 DynamoDB 값 목록입니다. DynamoDB List 값은 값 목록으로 반환되며, 여기서 각 내부 값 역시 변환됩니다.
예를 들어 DynamoDB에서 다음 DynamoDB List 값을 반환한 경우:
```
{ "L" : [
{ "S" : "A string value" },
{ "N" : 1 },
{ "SS" : [ "Another string value", "Even more string values!" ] }
]
}
```
AWS AppSync는 변환된 값 목록으로 변환합니다.
```
[ "A string value", 1, [ "Another string value", "Even more string values!" ] ]
```
**Map 형식 `M` **
지원되는 기타 모든 DynamoDB 값의 키/값 모음입니다. DynamoDB Map 값은 JSON 객체로 반환되며, 여기서 각 키/값 역시 변환됩니다.
예를 들어 DynamoDB에서 다음 DynamoDB Map 값을 반환한 경우:
```
{ "M" : {
"someString" : { "S" : "A string value" },
"someNumber" : { "N" : 1 },
"stringSet" : { "SS" : [ "Another string value", "Even more string values!" ] }
}
}
```
AWS AppSync는 이를 JSON 객체로 변환합니다.
```
{
"someString" : "A string value",
"someNumber" : 1,
"stringSet" : [ "Another string value", "Even more string values!" ]
}
```
**Null 형식 `NULL` **
null 값.
예를 들어 DynamoDB에서 다음 DynamoDB Null 값을 반환한 경우:
```
{ "NULL" : null }
```
AWS AppSync는 이를 null로 변환합니다.
```
null
```
# 필터
`Query` 및 `Scan` 작업을 사용하여 DynamoDB에서 객체를 쿼리하는 경우, 결과를 평가해 원하는 값만 반환하는 `filter`를 선택적으로 지정할 수 있습니다.
`Query` 또는 `Scan` 매핑 문서의 필터 매핑 섹션의 구조는 다음과 같습니다.
```
"filter" : {
"expression" : "filter expression"
"expressionNames" : {
"#name" : "name",
},
"expressionValues" : {
":value" : ... typed value
},
}
```
필드는 다음과 같이 정의됩니다.
** `expression` **
쿼리 표현식. 필터 표현식을 작성하는 방법에 대한 자세한 내용은 [DynamoDB QueryFilter](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LegacyConditionalParameters.QueryFilter.html) 및 [DynamoDB ScanFilter](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LegacyConditionalParameters.ScanFilter.html) 문서를 참조하십시오. 이 필드는 지정되어 있어야 합니다.
** `expressionNames` **
표현식 속성 *name* 자리 표시자의 대체 항목으로, 키-값 페어의 형식으로 표시됩니다. 키는 `expression`에 사용된 이름 자리 표시자에 해당합니다. 이 값은 DynamoDB에서 항목의 속성 이름에 해당하는 문자열이어야 합니다. 이 필드는 선택 사항으로, `expression`에 사용된 표현식 속성인 name 자리 표시자의 대체 항목으로만 채워져야 합니다.
** `expressionValues` **
표현식 속성 *value* 자리 표시자의 대체 항목으로, 키-값 페어의 형식으로 표시됩니다. 키는 `expression`에 사용되는 value 자리 표시자에 해당하고 값은 입력된 값이어야 합니다. ‘입력된 값’을 지정하는 방법에 대한 자세한 내용은 [형식 시스템(요청 매핑)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)을 참조하십시오. 입력된 값은 지정되어 있어야 합니다. 이 필드는 선택 사항으로, `expression`에 사용된 표현식 속성인 value 자리 표시자의 대체 항목으로만 채워져야 합니다.
## 예제
다음 예제는 매핑 템플릿의 필터 섹션으로, 여기서 DynamoDB에서 가져온 항목은 제목이 `title` 인수로 시작되는 경우에만 반환됩니다.
```
"filter" : {
"expression" : "begins_with(#title, :title)",
"expressionNames" : {
"#title" : "title"
},
"expressionValues" : {
":title" : $util.dynamodb.toDynamoDBJson($context.arguments.title)
}
}
```
# 조건 표현식
DynamoDB에서 `PutItem`, `UpdateItem` 및 `DeleteItem` DynamoDB 작업을 사용하여 객체를 변경하는 경우, 작업을 수행하기 전에 DynamoDB에 이미 있는 객체의 상태를 기준으로 요청에 성공할지 여부를 제어하는 조건 표현식을 선택적으로 지정할 수 있습니다.
AWS AppSync DynamoDB 해석기를 사용하면 `PutItem`, `UpdateItem`및 `DeleteItem` 요청 매핑 문서에 조건 표현식을 지정할 수 있으며, 조건이 실패하고 객체가 업데이트되지 않은 경우 따라야 할 전략도 지정할 수 있습니다.
## 예제 1.
다음 `PutItem` 매핑 문서에는 조건식은 포함되어 있지 않습니다. 따라서 키가 같은 항목이 이미 존재하더라도 DynamoDB에 항목을 저장하기 때문에 기존 항목을 덮어 씁니다.
```
{
"version" : "2017-02-28",
"operation" : "PutItem",
"key" : {
"id" : { "S" : "1" }
}
}
```
## 예제 2.
다음 `PutItem` 매핑 문서에는 동일한 키를 가진 항목이 DynamoDB에 *없는* 경우에만 작업을 성공시킬 수 있는 조건 표현식이 있습니다.
```
{
"version" : "2017-02-28",
"operation" : "PutItem",
"key" : {
"id" : { "S" : "1" }
},
"condition" : {
"expression" : "attribute_not_exists(id)"
}
}
```
기본적으로 조건 확인에 실패하면 AWS AppSync DynamoDB 해석기는 변형에 대한 오류를 반환합니다. 그러나 AWS AppSync DynamoDB 해석기는 개발자가 몇 가지 일반적인 엣지 사례를 처리하는 데 도움이 되는 몇 가지 추가 기능을 제공합니다.
+ AWS AppSync DynamoDB 해석기가 DynamoDB의 현재 값이 원하는 결과와 일치하는지 확인할 수 있는 경우 작업을 성공한 것처럼 취급합니다.
+ 오류를 반환하는 대신 사용자 지정 Lambda 함수를 호출하도록 해석기를 구성하여 AWS AppSync DynamoDB 해석기가 오류를 처리하는 방법을 결정할 수 있습니다.
이러한 내용은 [조건 확인 실패 처리](#aws-appsync-resolver-mapping-template-reference-dynamodb-condition-handling) 단원에 자세히 설명되어 있습니다.
DynamoDB 조건 표현식에 대한 자세한 내용은 [DynamoDB ConditionExpressions 문서](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ConditionExpressions.html)를 참조하세요.
## 조건 지정
`PutItem`, `UpdateItem` 및 `DeleteItem` 요청 매핑 문서 모두에서 선택적 `condition` 섹션을 지정할 수 있습니다. 이 섹션을 지정하지 않으면 조건 검사가 수행되지 않습니다. 지정한 경우, 해당 조건을 충족해야 작업이 성공합니다.
`condition` 섹션의 구조는 다음과 같습니다.
```
"condition" : {
"expression" : "someExpression"
"expressionNames" : {
"#foo" : "foo"
},
"expressionValues" : {
":bar" : ... typed value
},
"equalsIgnore" : [ "version" ],
"consistentRead" : true,
"conditionalCheckFailedHandler" : {
"strategy" : "Custom",
"lambdaArn" : "arn:..."
}
}
```
조건을 지정하는 필드는 다음과 같습니다.
** `expression` **
업데이트 표현식 자체. 조건 표현식을 작성하는 방법에 대한 자세한 내용은 [DynamoDB ConditionExpressions 문서](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ConditionExpressions.html)를 참조하십시오. 이 필드는 지정되어 있어야 합니다.
** `expressionNames` **
표현식 속성 name 자리 표시자의 대체 항목으로, 키-값 페어의 형식으로 표시됩니다. 키는 *expression*에 사용된 name 자리 표시자에 해당하고 값은 DynamoDB에 있는 항목의 속성 이름에 해당하는 문자열이어야 합니다. 이 필드는 선택 사항으로, *expression*에 사용된 표현식 속성인 name 자리 표시자의 대체 항목으로만 채워져야 합니다.
** `expressionValues` **
표현식 속성 value 자리 표시자의 대체 항목으로, 키-값 페어의 형식으로 표시됩니다. 키는 expression에 사용되는 value 자리 표시자에 해당하고 값은 입력된 값이어야 합니다. ‘입력된 값’을 지정하는 방법에 대한 자세한 내용은 [형식 시스템(요청 매핑)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)을 참조하십시오. 입력된 값은 지정되어 있어야 합니다. 이 필드는 선택 사항으로, expression에 사용된 표현식 속성인 value 자리 표시자의 대체 항목으로만 채워져야 합니다.
나머지 필드는 AWS AppSync DynamoDB 해석기에 조건 확인 실패를 처리하는 방법을 알려줍니다.
** `equalsIgnore` **
`PutItem` 작업을 사용할 때 조건 확인이 실패하면 AWS AppSync DynamoDB 해석기는 현재 DynamoDB에 있는 항목을 쓰려고 시도한 항목과 비교합니다. 이러한 두 항목이 동일하면 해석기에서는 해당 작업을 마치 성공한 것처럼 간주합니다. `equalsIgnore` 필드를 사용하여 해당 비교를 수행할 때 AWS AppSync가 무시해야 하는 속성 목록을 지정할 수 있습니다. 예를 들어, `version` 속성만 차이가 나는 경우에는 해당 작업을 성공한 작업으로 취급합니다. 이 필드는 선택 사항입니다.
** `consistentRead` **
조건 확인에 실패하면 AWS AppSync는 강력히 일관된 읽기를 사용하여 DynamoDB에서 항목의 현재 값을 가져옵니다. 이 필드를 사용하여 AWS AppSync DynamoDB 해석기에 최종적으로 일관된 읽기를 대신 사용하도록 지시할 수 있습니다. 이 필드는 선택 사항으로, 기본값은 `true`입니다.
** `conditionalCheckFailedHandler` **
이 섹션에서는 AWS AppSync DynamoDB 해석기가 DynamoDB의 현재 값을 예상 결과와 비교한 후 조건 확인 실패를 처리하는 방법을 지정할 수 있습니다. 이 섹션은 선택 사항입니다. 방법을 지정하지 않으면 `Reject` 전략이 기본값으로 지정됩니다.
** `strategy` **
AWS AppSync DynamoDB 해석기가 DynamoDB의 현재 값을 예상 결과와 비교한 후 수행하는 전략입니다. 이 필드는 필수 필드로, 다음과 같은 두 가지 값을 가질 수 있습니다.
** `Reject` **
변형이 실패하고 GraphQL 응답에 오류가 추가됩니다.
** `Custom` **
AWS AppSync DynamoDB 해석기는 사용자 지정 Lambda 함수를 호출하여 조건 확인 실패를 처리하는 방법을 결정합니다. `strategy`를 `Custom`으로 설정하면 `lambdaArn` 필드에 호출할 Lambda 함수의 ARN이 포함되어 있어야 합니다.
** `lambdaArn` **
AWS AppSync DynamoDB 해석기가 조건 확인 실패를 처리하는 방법을 결정하는 호출할 Lambda 함수의 ARN입니다. 이 필드는 `strategy`를 `Custom`으로 설정한 경우에만 지정해야 합니다. 이 기능을 사용하는 방법에 대한 자세한 내용은 [조건 검사 실패 처리](#aws-appsync-resolver-mapping-template-reference-dynamodb-condition-handling)를 참조하십시오.
## 조건 검사 실패 처리
기본적으로 조건 확인이 실패하면 AWS AppSync DynamoDB 해석기는 변형에 대한 오류와 DynamoDB에 있는 객체의 현재 값을 반환합니다. 그러나 AWS AppSync DynamoDB 해석기는 개발자가 몇 가지 일반적인 엣지 사례를 처리하는 데 도움이 되는 몇 가지 추가 기능을 제공합니다.
+ AWS AppSync DynamoDB 해석기가 DynamoDB의 현재 값이 원하는 결과와 일치하는지 확인할 수 있는 경우 작업을 성공한 것처럼 취급합니다.
+ 오류를 반환하는 대신 사용자 지정 Lambda 함수를 호출하도록 해석기를 구성하여 AWS AppSync DynamoDB 해석기가 오류를 처리하는 방법을 결정할 수 있습니다.
이 프로세스의 흐름 차트입니다.
![\[Flowchart showing process for transforming requests with mutation attempts and value checks.\]](http://docs.aws.amazon.com/ko_kr/appsync/latest/devguide/images/DynamoDB-condition-check-failure-handling.png)
### 원하는 결과 확인
조건 확인에 실패하면 AWS AppSync DynamoDB 해석기는 `GetItem` DynamoDB 요청을 수행하여 DynamoDB에서 항목의 현재 값을 가져옵니다. 기본적으로 이 해석기는 강력히 일관된 읽기를 사용하지만, `condition` 블록의 `consistentRead` 필드를 사용하여 예상 결과와 비교하도록 구성할 수 있습니다.
+ `PutItem` 작업의 경우 AWS AppSync DynamoDB 해석기는 비교`equalsIgnore`에서에 나열된 속성을 제외하고 현재 값을 쓰려고 시도한 값과 비교합니다. 항목이 동일한 경우 해당 작업을 성공한 작업으로 간주하고 DynamoDB에서 가져온 항목을 반환합니다. 그렇지 않으면 구성된 전략을 따릅니다.
예를 들어, `PutItem` 요청 매핑 문서가 다음과 같은 경우:
```
{
"version" : "2017-02-28",
"operation" : "PutItem",
"key" : {
"id" : { "S" : "1" }
},
"attributeValues" : {
"name" : { "S" : "Steve" },
"version" : { "N" : 2 }
},
"condition" : {
"expression" : "version = :expectedVersion",
"expressionValues" : {
":expectedVersion" : { "N" : 1 }
},
"equalsIgnore": [ "version" ]
}
}
```
그리고 DynamoDB에 현재 있는 항목이 다음과 같은 경우:
```
{
"id" : { "S" : "1" },
"name" : { "S" : "Steve" },
"version" : { "N" : 8 }
}
```
AWS AppSync DynamoDB 해석기는 쓰려고 시도한 항목을 현재 값과 비교하고 유일한 차이점은 `version` 필드였지만 필드를 무시하도록 구성되어 있으므로 작업을 성공으로 `version` 처리하고 DynamoDB에서 검색된 항목을 반환합니다.
+ `DeleteItem` 작업의 경우 AWS AppSync DynamoDB 해석기는 항목을 DynamoDB에서 반환했는지 확인합니다. 반환되는 항목이 없는 경우 해당 작업을 성공으로 간주합니다. 그렇지 않으면 구성된 전략을 따릅니다.
+ `UpdateItem` 작업의 경우 AWS AppSync DynamoDB 해석기에 현재 DynamoDB에 있는 항목이 예상 결과와 일치하는지 확인하기에 충분한 정보가 없으므로 구성된 전략을 따릅니다.
DynamoDB에서 객체의 현재 상태가 예상 결과와 다른 경우 AWS AppSync DynamoDB 해석기는 구성된 전략을 따라 변형을 거부하거나 Lambda 함수를 호출하여 다음에 수행할 작업을 결정합니다.
### 'Reject' 전략 따르기
`Reject` 전략을 따르면 AWS AppSync DynamoDB 해석기가 변형에 대한 오류를 반환합니다.
예를 들어 다음과 같은 변형 요청이 있습니다.
```
mutation {
updatePerson(id: 1, name: "Steve", expectedVersion: 1) {
Name
theVersion
}
}
```
DynamoDB에서 반환된 항목이 다음과 같은 경우:
```
{
"id" : { "S" : "1" },
"name" : { "S" : "Steve" },
"version" : { "N" : 8 }
}
```
그리고 응답 매핑 템플릿이 다음과 같은 경우:
```
{
"id" : $util.toJson($context.result.id),
"Name" : $util.toJson($context.result.name),
"theVersion" : $util.toJson($context.result.version)
}
```
GraphQL 응답은 다음과 같습니다.
```
{
"data": null,
"errors": [
{
"message": "The conditional request failed (Service: AmazonDynamoDBv2; Status Code: 400; Error Code: ConditionalCheckFailedException; Request ID: ABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZ)"
"errorType": "DynamoDB:ConditionalCheckFailedException",
...
}
]
}
```
반환된 객체의 필드를 다른 해석기가 채우고 변형에 성공했는데 이 객체가 `error` 섹션에서 반환되면 반환된 객체의 필드가 확인되지 않습니다.
### 'Custom' 전략 따르기
`Custom` 전략을 따르면 AWS AppSync DynamoDB 해석기가 Lambda 함수를 호출하여 다음에 수행할 작업을 결정합니다. Lambda 함수는 다음 옵션 중 하나를 선택합니다.
+ 변형 `reject`. 이렇게 하면 AWS AppSync DynamoDB 해석기가 구성된 전략이 인 것처럼 동작하여 이전 섹션에서 설명한 대로 DynamoDB에 있는 객체의 현재 값과 변형에 대한 오류를 `Reject`반환하도록 지시합니다.
+ 변형 `discard`. 이렇게 하면 AWS AppSync DynamoDB 해석기에 조건 확인 실패를 자동으로 무시하고 DynamoDB에서 값을 반환하도록 지시합니다.
+ 변형 `retry`. 이렇게 하면 AWS AppSync DynamoDB 해석기에 새 요청 매핑 문서로 변형을 다시 시도하도록 지시합니다.
**Lambda 호출 요청**
AWS AppSync DynamoDB 해석기는에 지정된 Lambda 함수를 호출합니다`lambdaArn`. 데이터 원본에 대해 구성된 동일한 `service-role-arn`을 사용합니다. 호출의 페이로드 구조는 다음과 같습니다.
```
{
"arguments": { ... },
"requestMapping": {... },
"currentValue": { ... },
"resolver": { ... },
"identity": { ... }
}
```
필드는 다음과 같이 정의됩니다.
** `arguments` **
GraphQL 변형의 인수. `$context.arguments`에서 요청 매핑 문서에 사용할 수 있는 인수와 동일합니다.
** `requestMapping` **
작업에 대한 요청 매핑 문서
** `currentValue` **
DynamoDB에 있는 객체의 현재 값
** `resolver` **
AWS AppSync 해석기에 대한 정보입니다.
** `identity` **
호출자에 대한 정보. `$context.identity`에서 요청 매핑 문서에 사용할 수 있는 자격 증명 정보와 동일합니다.
페이로드 전체를 보여주는 예:
```
{
"arguments": {
"id": "1",
"name": "Steve",
"expectedVersion": 1
},
"requestMapping": {
"version" : "2017-02-28",
"operation" : "PutItem",
"key" : {
"id" : { "S" : "1" }
},
"attributeValues" : {
"name" : { "S" : "Steve" },
"version" : { "N" : 2 }
},
"condition" : {
"expression" : "version = :expectedVersion",
"expressionValues" : {
":expectedVersion" : { "N" : 1 }
},
"equalsIgnore": [ "version" ]
}
},
"currentValue": {
"id" : { "S" : "1" },
"name" : { "S" : "Steve" },
"version" : { "N" : 8 }
},
"resolver": {
"tableName": "People",
"awsRegion": "us-west-2",
"parentType": "Mutation",
"field": "updatePerson",
"outputType": "Person"
},
"identity": {
"accountId": "123456789012",
"sourceIp": "x.x.x.x",
"user": "AIDAAAAAAAAAAAAAAAAAA",
"userArn": "arn:aws:iam::123456789012:user/appsync"
}
}
```
**Lambda 호출 응답**
Lambda 함수는 호출 페이로드를 검사해 AWS AppSync DynamoDB 해석기에서 실패를 처리해야 하는 방법을 결정하는 비즈니스 로직을 어떠한 것이든 적용할 수 있습니다. 조건 검사 실패를 처리하기 위한 옵션에는 다음 3가지가 있습니다.
+ 변형 `reject`. 이 옵션에 대한 응답 페이로드의 구조는 다음과 같아야 합니다.
```
{
"action": "reject"
}
```
이렇게 하면 위의 섹션에 설명된 대로 AWS AppSync DynamoDB 해석기에 구성된 전략이 인 것처럼 동작하여 DynamoDB에 있는 객체의 현재 값과 변형에 대한 오류를 `Reject`반환하도록 지시합니다.
+ 변형 `discard`. 이 옵션에 대한 응답 페이로드의 구조는 다음과 같아야 합니다.
```
{
"action": "discard"
}
```
이렇게 하면 AWS AppSync DynamoDB 해석기에 조건 확인 실패를 자동으로 무시하고 DynamoDB에서 값을 반환하도록 지시합니다.
+ 변형 `retry`. 이 옵션에 대한 응답 페이로드의 구조는 다음과 같아야 합니다.
```
{
"action": "retry",
"retryMapping": { ... }
}
```
그러면 AWS AppSync DynamoDB 해석기에 새 요청 매핑 문서로 변형을 다시 시도하도록 지시합니다. `retryMapping` 섹션의 구조는 DynamoDB 작업에 따라 달라지며 해당 작업에 대한 전체 요청 매핑 문서의 하위 집합입니다.
`PutItem`의 경우 `retryMapping` 섹션의 구조는 다음과 같습니다. `attributeValues` 필드에 대한 설명은 [PutItem](aws-appsync-resolver-mapping-template-reference-dynamodb-putitem.md)을 참조하십시오.
```
{
"attributeValues": { ... },
"condition": {
"equalsIgnore" = [ ... ],
"consistentRead" = true
}
}
```
`UpdateItem`의 경우 `retryMapping` 섹션의 구조는 다음과 같습니다. `update` 섹션에 대한 설명은 [UpdateItem](aws-appsync-resolver-mapping-template-reference-dynamodb-updateitem.md)을 참조하십시오.
```
{
"update" : {
"expression" : "someExpression"
"expressionNames" : {
"#foo" : "foo"
},
"expressionValues" : {
":bar" : ... typed value
}
},
"condition": {
"consistentRead" = true
}
}
```
`DeleteItem`의 경우 `retryMapping` 섹션의 구조는 다음과 같습니다.
```
{
"condition": {
"consistentRead" = true
}
}
```
작동할 수 있는 다른 작업 또는 키를 지정할 수 있는 방법은 없습니다. AWS AppSync DynamoDB 해석기는 동일한 객체에서 동일한 작업의 재시도만 허용합니다. `condition` 섹션에서는 `conditionalCheckFailedHandler`를 지정할 수 없습니다. 재시도가 실패하면 AWS AppSync DynamoDB 해석기는 `Reject` 전략을 따릅니다.
다음은 실패한 `PutItem` 요청을 처리하는 Lambda 함수의 예입니다. 이 비즈니스 로직은 호출한 사람이 누구인지 확인합니다. `jeffTheAdmin`이 호출한 경우 요청을 재시도해 현재 DynamoDB에 있는 항목에서 `version` 및 `expectedVersion`을 업데이트합니다. 그렇지 않으면 변형을 거부합니다.
```
exports.handler = (event, context, callback) => {
console.log("Event: "+ JSON.stringify(event));
// Business logic goes here.
var response;
if ( event.identity.user == "jeffTheAdmin" ) {
response = {
"action" : "retry",
"retryMapping" : {
"attributeValues" : event.requestMapping.attributeValues,
"condition" : {
"expression" : event.requestMapping.condition.expression,
"expressionValues" : event.requestMapping.condition.expressionValues
}
}
}
response.retryMapping.attributeValues.version = { "N" : event.currentValue.version.N + 1 }
response.retryMapping.condition.expressionValues[':expectedVersion'] = event.currentValue.version
} else {
response = { "action" : "reject" }
}
console.log("Response: "+ JSON.stringify(response))
callback(null, response)
};
```
# 트랜잭션 조건 표현식
트랜잭션 조건식은 `TransactWriteItems`에서 네 가지 작업 유형 모두(`PutItem`, `DeleteItem`, `UpdateItem`, `ConditionCheck`)의 요청 매핑 템플릿에 사용할 수 있습니다.
`PutItem`, `DeleteItem`, `UpdateItem`의 경우 트랜잭션 조건 표현식은 선택 사항입니다. `ConditionCheck`의 경우 트랜잭션 조건 표현식이 필수입니다.
## 예제 1.
다음 트랜잭션 `DeleteItem` 매핑 문서에는 조건식이 없습니다. 따라서 DynamoDB에서 항목을 삭제합니다.
```
{
"version": "2018-05-29",
"operation": "TransactWriteItems",
"transactItems": [
{
"table": "posts",
"operation": "DeleteItem",
"key": {
"id": { "S" : "1" }
}
}
]
}
```
## 예제 2.
다음 트랜잭션 `DeleteItem` 매핑 문서에는 해당 게시물의 작성자가 특정 이름과 같은 경우에만 작업이 성공할 수 있는 트랜잭션 조건식이 있습니다.
```
{
"version": "2018-05-29",
"operation": "TransactWriteItems",
"transactItems": [
{
"table": "posts",
"operation": "DeleteItem",
"key": {
"id": { "S" : "1" }
}
"condition": {
"expression": "author = :author",
"expressionValues": {
":author": { "S" : "Chunyan" }
}
}
}
]
}
```
조건 검사에 실패하면 `TransactionCanceledException`이 발생하고, `$ctx.result.cancellationReasons`에 오류 세부 정보가 반환됩니다. 기본적으로, 조건 검사가 실패하게 된 원인인 DynamoDB의 이전 항목이 `$ctx.result.cancellationReasons`에 반환됩니다.
## 조건 지정
`PutItem`, `UpdateItem` 및 `DeleteItem` 요청 매핑 문서 모두에서 선택적 `condition` 섹션을 지정할 수 있습니다. 이 섹션을 지정하지 않으면 조건 검사가 수행되지 않습니다. 지정한 경우, 해당 조건을 충족해야 작업이 성공합니다. `ConditionCheck`에는 지정할 `condition` 섹션이 있어야 합니다. 전체 트랜잭션이 성공하려면 조건이 true여야 합니다.
`condition` 섹션의 구조는 다음과 같습니다.
```
"condition": {
"expression": "someExpression",
"expressionNames": {
"#foo": "foo"
},
"expressionValues": {
":bar": ... typed value
},
"returnValuesOnConditionCheckFailure": false
}
```
조건을 지정하는 필드는 다음과 같습니다.
** `expression` **
업데이트 표현식 자체. 조건 표현식을 작성하는 방법에 대한 자세한 내용은 [DynamoDB ConditionExpressions 문서](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ConditionExpressions.html)를 참조하십시오. 이 필드는 지정되어 있어야 합니다.
** `expressionNames` **
표현식 속성 name 자리 표시자의 대체 항목으로, 키-값 페어의 형식으로 표시됩니다. 키는 *expression*에 사용된 name 자리 표시자에 해당하고 값은 DynamoDB에 있는 항목의 속성 이름에 해당하는 문자열이어야 합니다. 이 필드는 선택 사항으로, *expression*에 사용된 표현식 속성인 name 자리 표시자의 대체 항목으로만 채워져야 합니다.
** `expressionValues` **
표현식 속성 value 자리 표시자의 대체 항목으로, 키-값 페어의 형식으로 표시됩니다. 키는 expression에 사용되는 value 자리 표시자에 해당하고 값은 입력된 값이어야 합니다. ‘입력된 값’을 지정하는 방법에 대한 자세한 내용은 형식 시스템(요청 매핑)을 참조하십시오. 입력된 값은 지정되어 있어야 합니다. 이 필드는 선택 사항으로, expression에 사용된 표현식 속성인 value 자리 표시자의 대체 항목으로만 채워져야 합니다.
** `returnValuesOnConditionCheckFailure` **
조건 검사에 실패할 경우 DynamoDB의 항목을 다시 가져올지 여부를 지정합니다. 가져온 항목은 `$ctx.result.cancellationReasons[$index].item`에 있습니다. 여기서 `$index`는 조건 검사에 실패한 요청 항목의 인덱스입니다. 기본값은 true입니다.
# 프로젝션
`GetItem`, `Scan`, `Query`, `BatchGetItem` 및 `TransactGetItems` 작업을 사용하여 DynamoDB에서 객체를 읽을 때 원하는 속성을 식별하는 프로젝션을 선택적으로 지정할 수 있습니다. 프로젝션의 구조는 필터와 비슷하며 다음과 같습니다.
```
"projection" : {
"expression" : "projection expression"
"expressionNames" : {
"#name" : "name",
}
}
```
필드는 다음과 같이 정의됩니다.
**`expression`**
프로젝션 표현식은 문자열입니다. 단일 속성을 가져오려면 속성의 이름을 지정합니다. 여러 속성의 경우 이름은 쉼표로 구분된 값이어야 합니다. 프로젝션 표현식 작성에 대한 자세한 내용은 [DynamoDB 프로젝션 표현식](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ProjectionExpressions.html) 설명서를 참조하세요. 이 필드는 필수 항목입니다.
**`expressionNames`**
표현식 속성 *name* 자리 표시자의 대체 항목으로, 키-값 페어의 형식으로 표시됩니다. 키는 `expression`에 사용된 이름 자리 표시자에 해당합니다. 이 값은 DynamoDB에서 항목의 속성 이름에 해당하는 문자열이어야 합니다. 이 필드는 선택 사항으로, `expression`에 사용된 표현식 속성인 name 자리 표시자의 대체 항목으로만 채워져야 합니다. `expressionNames`에 대한 자세한 내용은 [DynamoDB 설명서](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ExpressionAttributeNames.html)를 참조하세요.
## 예제 1.
다음 예는 DynamoDB에서 `author` 및 `id` 속성만 반환되는 VTL 매핑 템플릿의 프로젝션 섹션입니다.
```
"projection" : {
"expression" : "#author, id",
"expressionNames" : {
"#author" : "author"
}
}
```
**작은 정보**
[\$1context.info.SelectionSetList](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-context-reference.html#aws-appsync-resolver-context-reference-info)를 사용하여 GraphQL 요청 설정에 액세스할 수 있습니다. 이 필드를 사용하면 요구 사항에 따라 프로젝션 표현식을 동적으로 프레이밍할 수 있습니다.
**참고**
`Query` 및 `Scan` 작업과 함께 프로젝션 표현식을 사용하는 경우 `select`의 값은 반드시 `SPECIFIC_ATTRIBUTES`이어야 합니다. 자세한 내용은 [DynamoDB 설명서](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html#DDB-Query-request-Select)를 참조하세요.