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

참고

이제 우리는 주로 APPSYNC_JS 런타임과 해당 문서를 지원합니다. 여기에서 APPSYNC_JS 런타임과 해당 안내서를 사용해 보세요.

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

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

버전 매트릭스에 따른 데이터 원본 작업 가용성

지원되지 않는 작업/버전	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 버전만 지원됩니다.

유닛 해석기 매핑 템플릿에 대한 버전 변경

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

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

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

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

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

함수에 대한 버전 변경

함수의 경우 버전은 함수 객체에 대한 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

동작 변경

• 데이터 원본 호출 결과가 null이면 응답 매핑 템플릿이 실행됩니다.

• 데이터 원본을 호출했는데 오류가 발생하면 오류는 직접 처리해야 합니다. 평가된 응답 매핑 템플릿은 항상 GraphQL 응답 data 블록 내에 배치됩니다.

추론

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

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

$util.toJson($ctx.result)

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

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

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

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

$util.toJson($ctx.result)

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

호출 오류 다시 실행

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

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

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

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

다른 오류 실행

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

#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)가 발생하면 응답은 다음과 같이 표시됩니다.

{
    "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
                }
            ]
        }
    ]
}

반환 데이터에 오류 추가

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

#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)가 발생하면 응답은 다음과 같이 표시됩니다.

{
    "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로 마이그레이션

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

2017-02-28에서 2018-05-29로 동일한 실행 동작 보존

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

예: DynamoDB PutItem

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

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

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

$util.toJson($ctx.result)

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

{
    "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" : {
       ...
    }
}

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

## 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

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

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

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

## 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로 마이그레이션하면 이러한 템플릿은 다음과 같이 변경됩니다.

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

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

## 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

특성

• 데이터 원본 호출 결과가 null이면 응답 매핑 템플릿이 실행되지 않습니다.

• 데이터 원본 호출 시 오류가 발생하면 응답 매핑 템플릿이 실행되고 평가된 결과가 GraphQL 응답 errors.data 블록 내에 배치됩니다.