

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# AWS AppSync 해석기 매핑 템플릿 변경 로그

**참고**  
이제 우리는 주로 APPSYNC\_JS 런타임과 해당 문서를 지원합니다. [여기](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)에서 APPSYNC\_JS 런타임과 해당 안내서를 사용해 보세요.

해석기 및 함수 매핑 템플릿에는 버전이 지정됩니다. `2018-05-29` 등 매핑 템플릿 버전은 다음을 결정합니다.
+ 요청 템플릿에서 제공하는 데이터 소스 요청 구성의 예상 모양
+ 요청 매핑 템플릿 및 응답 매핑 템플릿의 실행 동작

버전은 YYYY-MM-DD 형식으로 표시되는데, 이후 날짜는 최신 버전에 해당합니다. 이 페이지에는 AWS AppSync에서 현재 지원되는 매핑 템플릿 버전 간의 차이가 나와 있습니다.

**Topics**
+ [버전 매트릭스에 따른 데이터 원본 작업 가용성](#aws-appsync-resolver-mapping-template-operation-availability-per-version)
+ [유닛 해석기 매핑 템플릿에 대한 버전 변경](#changing-the-version-on-a-unit-resolver-mapping-template)
+ [함수에 대한 버전 변경](#changing-the-version-on-a-function)
+ [2018-05-29](#aws-appsync-resolver-mapping-template-version-2018-05-29)
+ [2017-02-28](#aws-appsync-resolver-mapping-template-version-2017-02-28)

## 버전 매트릭스에 따른 데이터 원본 작업 가용성
<a name="aws-appsync-resolver-mapping-template-operation-availability-per-version"></a>


| 지원되지 않는 작업/버전 | 2017-02-28 | 2018-05-29 | 
| --- | --- | --- | 
| AWS Lambda 간접 호출 | 예 | 예 | 
| AWS Lambda BatchInvoke | 예 | 예 | 
| None Datasource | 예 | 예 | 
| Amazon OpenSearch GET | 예 | 예 | 
| Amazon OpenSearch POST | 예 | 예 | 
| Amazon OpenSearch PUT | 예 | 예 | 
| Amazon OpenSearch DELETE | 예 | 예 | 
| Amazon OpenSearch GET | 예 | 예 | 
| DynamoDB GetItem | 예 | 예 | 
| DynamoDB Scan | 예 | 예 | 
| DynamoDB Query | 예 | 예 | 
| DynamoDB DeleteItem | 예 | 예 | 
| DynamoDB PutItem | 예 | 예 | 
| DynamoDB BatchGetItem | 아니요 | 예 | 
| DynamoDB BatchPutItem | 아니요 | 예 | 
| DynamoDB BatchDeleteItem | 아니요 | 예 | 
| HTTP | 아니요 | 예 | 
| Amazon RDS | 아니요 | 예 | 

 **참고**: 현재, 함수에서는 **2018-05-29** 버전만 지원됩니다.

## 유닛 해석기 매핑 템플릿에 대한 버전 변경
<a name="changing-the-version-on-a-unit-resolver-mapping-template"></a>

유닛 해석기의 경우 버전은 요청 매핑 템플릿 본문의 일부로 지정됩니다. 버전을 업데이트하려면 `version` 필드를 새 버전으로 업데이트하기만 하면 됩니다.

예를 들어 AWS Lambda 템플릿에서 버전을 업데이트하려면

```velocity
{
    "version": "2017-02-28",
    "operation": "Invoke",
    "payload": {
        "field": "getPost",
        "arguments": $utils.toJson($context.arguments)
    }
}
```

아래와 같이 버전 필드를 `2017-02-28`에서 `2018-05-29`로 업데이트해야 합니다.

```velocity
{
    "version": "2018-05-29", ## Note the version
    "operation": "Invoke",
    "payload": {
        "field": "getPost",
        "arguments": $utils.toJson($context.arguments)
    }
}
```

## 함수에 대한 버전 변경
<a name="changing-the-version-on-a-function"></a>

함수의 경우 버전은 함수 객체에 대한 `functionVersion` 필드로 지정됩니다. 버전을 업데이트하려면 `functionVersion`을 업데이트하기만 하면 됩니다. *참고:* 현재, 함수에는 `2018-05-29`만 지원됩니다.

다음은 기존 함수 버전을 업데이트하기 위한 CLI 명령 예제입니다.

```
aws appsync update-function \
--api-id REPLACE_WITH_API_ID \
--function-id REPLACE_WITH_FUNCTION_ID \
--data-source-name "PostTable" \
--function-version "2018-05-29" \
--request-mapping-template "{...}" \
--response-mapping-template "\$util.toJson(\$ctx.result)"
```

 **참고:** 적용되지 않을 것이기 때문에 버전 필드는 함수 요청 매핑 템플릿에서 생략하는 것이 좋습니다. 함수 요청 매핑 템플릿 내에서 버전을 지정하면 `functionVersion` 필드의 값으로 버전이 재지정됩니다.

## 2018-05-29
<a name="aws-appsync-resolver-mapping-template-version-2018-05-29"></a>

### 동작 변경
<a name="behavior-change"></a>
+ 데이터 원본 호출 결과가 `null`이면 응답 매핑 템플릿이 실행됩니다.
+ 데이터 원본을 호출했는데 오류가 발생하면 오류는 직접 처리해야 합니다. 평가된 응답 매핑 템플릿은 **항상** GraphQL 응답 `data` 블록 내에 배치됩니다.

### 추론
<a name="reasoning"></a>
+ `null` 호출 결과에는 의미가 있는데, 일부 애플리케이션 사용 사례에서는 사용자 지정 방식으로 `null` 결과를 처리하고자 할 수 있습니다. 예를 들어, 애플리케이션이 권한 부여 확인을 수행하기 위해 Amazon DynamoDB 테이블에 레코드가 있는지 확인하려고 할 수 있습니다. 이러한 경우 `null` 호출 결과는 사용자가 인증되지 않았을 수 있음을 의미합니다. 이제, 응답 매핑 템플릿을 실행하면 권한 없음 오류를 발생시킬 수 있습니다. 이 동작은 API 설계자에게 더 정확한 제어 권한을 제공합니다.

다음 응답 매핑 템플릿에 대해 생각해 보겠습니다.

```velocity
$util.toJson($ctx.result)
```

이전에는 `2017-02-28`을 사용했을 때 `$ctx.result`가 null을 반환하면 응답 매핑 템플릿이 실행되지 않았습니다. 이제, `2018-05-29`를 사용하면 이 시나리오를 처리할 수 있습니다. 예를 들어, 다음과 같이 권한 부여 오류가 실행되도록 선택할 수 있습니다.

```velocity
# throw an unauthorized error if the result is null
#if ( $util.isNull($ctx.result) )
    $util.unauthorized()
#end
$util.toJson($ctx.result)
```

 **참고:** 데이터 원본에서 반환되는 오류는 때때로 치명적이지 않고 심지어 예측되는 경우도 있는데, 이는 응답 매핑 템플릿에 호출 오류를 처리하고 해당 오류를 무시하거나, 다시 실행하거나, 다른 오류를 실행할지 여부를 결정할 수 있는 유연성이 있어야 하기 때문입니다.

다음 응답 매핑 템플릿에 대해 생각해 보겠습니다.

```velocity
$util.toJson($ctx.result)
```

이전에 `2017-02-28`을 사용했을 때 호출 오류가 발생하면 응답 매핑 템플릿이 평가되고 그 결과가 GraphQL 응답의 `errors` 블록에 자동으로 배치되었습니다. 이제, `2018-05-29`를 사용하면 오류와 관련해 수행할 작업을 선택하거나, 오류를 다시 실행하거나, 다른 오류를 실행하거나, 데이터를 반환하는 동안 오류를 추가할 수 있습니다.

### 호출 오류 다시 실행
<a name="re-raise-an-invocation-error"></a>

다음 응답 템플릿에서는 데이터 원본에서 반환되는 것과 동일한 오류를 실행합니다.

```velocity
#if ( $ctx.error )
    $util.error($ctx.error.message, $ctx.error.type)
#end
$util.toJson($ctx.result)
```

호출 오류(예: `$ctx.error` is present)가 발생하면 응답은 다음과 같이 표시됩니다.

```json
{
    "data": {
        "getPost": null
    },
    "errors": [
        {
            "path": [
                "getPost"
            ],
            "errorType": "DynamoDB:ConditionalCheckFailedException",
            "message": "Conditional check failed exception...",
            "locations": [
                {
                    "line": 5,
                    "column": 5
                }
            ]
        }
    ]
}
```

### 다른 오류 실행
<a name="raise-a-different-error"></a>

다음 응답 템플릿에서는 데이터 원본에서 반환되는 오류를 처리한 후 고유한 사용자 지정 오류를 실행합니다.

```velocity
#if ( $ctx.error )
    #if ( $ctx.error.type.equals("ConditionalCheckFailedException") )
        ## we choose here to change the type and message of the error for ConditionalCheckFailedExceptions
        $util.error("Error while updating the post, try again. Error: $ctx.error.message", "UpdateError")
    #else
        $util.error($ctx.error.message, $ctx.error.type)
    #end
#end
$util.toJson($ctx.result)
```

호출 오류(예: `$ctx.error` is present)가 발생하면 응답은 다음과 같이 표시됩니다.

```json
{
    "data": {
        "getPost": null
    },
    "errors": [
        {
            "path": [
                "getPost"
            ],
            "errorType": "UpdateError",
            "message": "Error while updating the post, try again. Error: Conditional check failed exception...",
            "locations": [
                {
                    "line": 5,
                    "column": 5
                }
            ]
        }
    ]
}
```

### 반환 데이터에 오류 추가
<a name="append-an-error-to-return-data"></a>

다음 응답 템플릿에서는 응답 내에서 데이터를 반환하는 동안 데이터 원본에서 반환되는 것과 동일한 오류를 추가합니다. 이를 부분 응답이라고도 합니다.

```velocity
#if ( $ctx.error )
    $util.appendError($ctx.error.message, $ctx.error.type)
    #set($defaultPost = {id: "1", title: 'default post'})
    $util.toJson($defaultPost)
#else
    $util.toJson($ctx.result)
#end
```

호출 오류(예: `$ctx.error` is present)가 발생하면 응답은 다음과 같이 표시됩니다.

```json
{
    "data": {
        "getPost": {
            "id": "1",
            "title: "A post"
        }
    },
    "errors": [
        {
            "path": [
                "getPost"
            ],
            "errorType": "ConditionalCheckFailedException",
            "message": "Conditional check failed exception...",
            "locations": [
                {
                    "line": 5,
                    "column": 5
                }
            ]
        }
    ]
}
```

#### *2017-02-28*에서 *2018-05-29*로 마이그레이션
<a name="migrating-from-2017-02-28-to-2018-05-29"></a>

**2017-02-28**에서 **2018-05-29**로 마이그레이션은 간단합니다. 해석기 요청 매핑 템플릿 또는 함수 버전 객체에서 버전 필드를 변경합니다. 그러나 **2018-05-29** 실행은 **2017-02-28** 실행과 다르게 동작하는데, 동작 변경 사항은 [여기](#aws-appsync-resolver-mapping-template-version-2018-05-29)에 간단하게 정리되어 있습니다.

#### *2017-02-28*에서 *2018-05-29*로 동일한 실행 동작 보존
<a name="preserving-the-same-execution-behavior-from-2017-02-28-to-2018-05-29"></a>

경우에 따라 **2018-05-29** 버전의 템플릿을 실행하는 동안 **2017-02-28** 버전과 동일한 실행 동작을 유지할 수 있습니다.

### 예: DynamoDB PutItem
<a name="example-dynamodb-putitem"></a>

다음과 같은 **2017-02-28** DynamoDB PutItem 요청 템플릿이 있습니다.

```velocity
{
    "version" : "2017-02-28",
    "operation" : "PutItem",
    "key": {
        "foo" : ... typed value,
        "bar" : ... typed value
    },
    "attributeValues" : {
        "baz" : ... typed value
    },
    "condition" : {
       ...
    }
}
```

응답 템플릿은 다음과 같습니다.

```velocity
$util.toJson($ctx.result)
```

**2018-05-29**로 마이그레이션하면 이러한 템플릿은 다음과 같이 변경됩니다.

```velocity
{
    "version" : "2018-05-29", ## Note the new 2018-05-29 version
    "operation" : "PutItem",
    "key": {
        "foo" : ... typed value,
        "bar" : ... typed value
    },
    "attributeValues" : {
        "baz" : ... typed value
    },
    "condition" : {
       ...
    }
}
```

응답 템플릿은 다음과 같이 변경됩니다.

```velocity
## If there is a datasource invocation error, we choose to raise the same error
## the field data will be set to null.
#if($ctx.error)
  $util.error($ctx.error.message, $ctx.error.type, $ctx.result)
#end

## If the data source invocation is null, we return null.
#if($util.isNull($ctx.result))
  #return
#end

$util.toJson($ctx.result)
```

따라서 오류를 처리하는 것은 고객의 책임입니다. 여기서는 DynamoDB에서 반환된 `$util.error()`를 사용하여 동일한 오류를 실행하도록 선택합니다. 이 코드 조각은 매핑 템플릿을 **2018-05-29**로 변환하도록 수정할 수 있습니다. 응답 템플릿이 다른 경우에는 실행 동작의 변경을 고려해야 합니다.

### 예: DynamoDB GetItem
<a name="example-dynamodb-getitem"></a>

다음과 같은 **2017-02-28** DynamoDB GetItem 요청 템플릿이 있습니다.

```velocity
{
    "version" : "2017-02-28",
    "operation" : "GetItem",
    "key" : {
        "foo" : ... typed value,
        "bar" : ... typed value
    },
    "consistentRead" : true
}
```

응답 템플릿은 다음과 같습니다.

```velocity
## map table attribute postId to field Post.id
$util.qr($ctx.result.put("id", $ctx.result.get("postId")))

$util.toJson($ctx.result)
```

**2018-05-29**로 마이그레이션하면 이러한 템플릿은 다음과 같이 변경됩니다.

```velocity
{
    "version" : "2018-05-29", ## Note the new 2018-05-29 version
    "operation" : "GetItem",
    "key" : {
        "foo" : ... typed value,
        "bar" : ... typed value
    },
    "consistentRead" : true
}
```

응답 템플릿은 다음과 같이 변경됩니다.

```velocity
## If there is a datasource invocation error, we choose to raise the same error
#if($ctx.error)
  $util.error($ctx.error.message, $ctx.error.type)
#end

## If the data source invocation is null, we return null.
#if($util.isNull($ctx.result))
  #return
#end

## map table attribute postId to field Post.id
$util.qr($ctx.result.put("id", $ctx.result.get("postId")))

$util.toJson($ctx.result)
```

**2017-02-28** 버전에서 데이터 원본 호출이 `null`이었으면 이는 키를 일치시키는 DynamoDB 테이블에 항목이 없음을 의미해 응답 매핑 템플릿이 실행되지 않았을 것입니다. 대부분의 경우 이러한 결과는 괜찮을 수 있지만, `$ctx.result`가 `null`이 아니길 기대하는 경우에는 이제, 해당 시나리오를 처리해야 합니다.

## 2017-02-28
<a name="aws-appsync-resolver-mapping-template-version-2017-02-28"></a>

### 특성
<a name="characteristics"></a>
+ 데이터 원본 호출 결과가 `null`이면 응답 매핑 템플릿이 실행되지 **않습니다**.
+ 데이터 원본 호출 시 오류가 발생하면 응답 매핑 템플릿이 실행되고 평가된 결과가 GraphQL 응답 `errors.data` 블록 내에 배치됩니다.