유닛 해석기 파이프라인 해석기 예제 템플릿 평가된 맵핑 템플릿 역직렬화 규칙

AWS AppSync 해석기 매핑 템플릿 개요

참고

이제 APPSYNC_JS 런타임과 해당 설명서를 주로 지원합니다. 여기에서 APPSYNC_JS 런타임 및 해당 가이드를 사용하는 것이 좋습니다.

AWS AppSync 를 사용하면 리소스에 대한 작업을 수행하여 GraphQL 요청에 응답할 수 있습니다. 쿼리 또는 변형을 실행하려는 각 GraphQL 필드에 대해 데이터 소스와 통신하려면 해석기를 연결해야 합니다. 일반적으로 이 통신은 데이터 소스에 대해 고유한 파라미터 또는 작업을 통해 이루어집니다.

해석기는 GraphQL과 데이터 소스를 연결하는 커넥터입니다. 수신되는 GraphQL 요청을 백엔드 데이터 소스에 대한 지침으로 변환하는 AWS AppSync 방법과 해당 데이터 소스의 응답을 GraphQL 응답으로 다시 변환하는 방법을 설명합니다. 이는 Apache Velocity 템플릿 언어(VTL)로 작성되며, 이 언어는 요청을 입력으로 받아 해석기에 대한 지침이 포함된 JSON 문서를 출력합니다. GraphQL 필드의 인수 전달과 같은 단순 명령은 물론, 항목을 DynamoDB에 삽입하기 전에 인수를 루핑하여 항목을 빌드하는 등 복잡한 명령에도 매핑 템플릿을 사용할 수 있습니다.

에는 약간 다른 방식으로 매핑 템플릿을 AWS AppSync 활용하는 두 가지 유형의 해석기가 있습니다.

유닛 해석기
파이프라인 해석기

유닛 해석기

유닛 해석기는 요청 및 응답 템플릿만 포함하는 독립형 객체입니다. 단일 데이터 원본에서 항목 나열과 같은 간단한 단일 작업에 사용합니다.

요청 템플릿: GraphQL 작업이 구문 분석된 후 들어오는 요청을 받아서 선택한 데이터 소스 작업에 대한 요청 구성으로 변환합니다.
응답 템플릿: 데이터 소스의 응답을 해석하여 GraphQL 필드 출력 유형의 셰이프에 매핑합니다.

파이프라인 해석기

파이프라인 해석기에는 순차적으로 실행되는 함수가 하나 이상 포함되어 있습니다. 각 함수에는 요청 템플릿과 응답 템플릿이 포함되어 있습니다. 파이프라인 해석기에는 템플릿에 포함된 함수 시퀀스를 둘러싸는 이전 템플릿과 이후 템플릿도 있습니다. 이후 템플릿은 GraphQL 필드 출력 유형에 매핑됩니다. 파이프라인 해석기는 응답 템플릿이 출력을 매핑하는 방식이 유닛 해석기와 다릅니다. 파이프라인 해석기는 다른 함수의 입력값이나 파이프라인 해석기의 이후 템플릿을 포함하여 원하는 모든 출력에 매핑할 수 있습니다.

파이프라인 해석기 함수를 사용하면 스키마의 여러 해석기에서 재사용할 수 있는 공통 로직을 작성할 수 있습니다. 함수는 데이터 소스에 직업 연결되고 유닛 해석기와 마찬가지로 동일한 요청 및 응답 매핑 템플릿 형식을 포함하고 있습니다.

다음 다이어그램은 왼쪽은 유닛 해석기, 오른쪽은 파이프라인 해석기의 프로세스 흐름을 보여줍니다.

단일 데이터 소스와 통신하는 유닛 해석기 다이어그램과 여러 데이터 소스와 통신하는 파이프라인 해석기 다이어그램입니다.

파이프라인 해석기에는 유닛 해석기가 지원하는 기능의 상위 집합이 포함되어 있지만 약간 더 복잡합니다.

파이프라인 해석기의 구조

파이프라인 해석기는 이전 매핑 템플릿, 이후 매핑 템플릿과 함수 목록으로 구성됩니다. 각 함수에는 데이터 소스에 대해 실행되는 요청 및 응답 매핑 템플릿이 있습니다. 파이프라인 해석기는 함수 목록에 실행을 위임하기 때문에 자신은 어떠한 데이터 원본에도 연결되지 않습니다. 유닛 해석기와 함수는 데이터 원본에 대해 작업을 실행하는 기본 요소입니다. 자세한 내용은 해석기 매핑 템플릿 개요를 참조하세요.

이전 매핑 템플릿

이 파이프라인 해석기의 요청 매핑 템플릿(또는 이전 단계)을 사용하면 정의된 함수를 실행하기 전에 몇 가지 준비 로직을 수행할 수 있습니다.

함수 목록

파이프라인 해석기가 순서대로 실행하는 함수 목록입니다. 파이프라인 해석기 요청 매핑 템플릿 평가 결과는 첫 번째 함수에 $ctx.prev.result로 사용할 수 있습니다. 각 함수 출력은 다음 함수에 $ctx.prev.result로 사용할 수 있습니다.

After 매핑 템플릿

이 파이프라인 해석기의 응답 매핑 템플릿(또는 이후 단계)을 사용하면 마지막 함수의 출력에서 예상 GraphQL 필드 유형으로 몇 가지 최종 매핑 로직을 수행할 수 있습니다. 함수 목록의 마지막 함수 출력은 파이프라인 해석기 매핑 템플릿에서 $ctx.prev.result 또는 $ctx.result로 사용할 수 있습니다.

실행 흐름

함수 2개로 구성된 파이프라인 해석기의 경우, 아래 목록은 해석기 호출 시 실행 흐름을 나타냅니다.

GraphQL request flow diagram showing template processing and data source interactions.

파이프라인 해석기 이전 매핑 템플릿
함수 1: 함수 요청 매핑 템플릿
함수 1: 데이터 원본 호출
함수 1: 함수 응답 매핑 템플릿
함수 2: 함수 요청 매핑 템플릿
함수 2: 데이터 원본 호출
함수 2: 함수 응답 매핑 템플릿
파이프라인 해석기 이후 매핑 템플릿

참고

파이프라인 해석기 실행 흐름은 단방향이고 해석기에서 정적으로 정의됩니다.

유용한 Apache Velocity 템플릿 언어(VTL) 유틸리티

애플리케이션의 복잡성이 증가함에 따라 VTL 유틸리티와 지침은 개발 생산성을 높이기 위해 존재합니다. 다음 유틸리티는 파이프라인 해석기로 작업할 때 유용할 수 있습니다.

$ctx.stash

stash는 각 해석기 및 함수 매핑 템플릿 내에서 사용할 수 있는 Map입니다. 단일 해석기가 실행되는 동안에는 동일한 stash 인스턴스가 사용됩니다. 이는 파이프라인 해석기 내에서 stash를 사용해 요청 및 응답 매핑 템플릿 간에 그리고 함수 간에 임의 데이터를 전달할 수 있다는 의미입니다. stash는 동일한 메서드를 Java 맵 데이터 구조로 노출합니다.

$ctx.prev.result

$ctx.prev.result는 파이프라인 해석기에서 실행된 이전 작업의 결과를 나타냅니다.

이전 작업이 파이프라인 해석기의 이전 매핑 템플릿인 경우 $ctx.prev.result는 템플릿 평가의 출력을 나타내며 파이프라인의 첫 번째 함수에서 사용할 수 있게 됩니다. 이전 작업이 첫 번째 함수였으면 $ctx.prev.result는 첫 번째 함수의 결과를 나타내고, 파이프라인의 두 번째 함수에 사용할 수 있습니다. 이전 작업이 마지막 함수였으면 $ctx.prev.result는 마지막 함수의 결과를 나타내고, 파이프라인 해석기 이후 매핑 템플릿에 사용할 수 있습니다.

#return(data: Object)

#return(data: Object) 명령은 임의의 매핑 템플릿에서 영구적으로 반환해야 하는 경우 유용합니다. 로직의 가장 가까운 범위 지정 블록에서 반환하기 때문에 #return(data: Object)은 프로그래밍 언어의 return 키워드와 유사합니다. 이는 해석기 매핑 템플릿 내에서 #return을 사용하면 해석기에서 반환함을 의미합니다. 해석기 매핑 템플릿에서 #return(data: Object)를 사용하면 GraphQL 필드에 data가 설정됩니다. 또는 함수 매핑 템플릿의 #return(data: Object)를 사용하면 함수에서 반환하고, 파이프라인의 다음 함수 또는 해석기 응답 매핑 템플릿으로 실행합니다.

#return

이는 #return(data: Object)와 동일하지만 대신 null이 반환됩니다.

$util.error

$util.error 유틸리티는 필드 오류를 발생시키는 데 유용합니다. 함수 매핑 템플릿 내에서 $util.error를 사용하면 즉시 필드 오류가 발생해 후속 함수가 실행되지 않도록 방지합니다. 세부 정보 및 기타 $util.error 서명은 해석기 매핑 템플릿 유틸리티 참조를 참조하세요.

$util.appendError

$util.appendError는 $util.error()와 유사하지만 매핑 템플릿 평가를 중단하지 않는다는 큰 차이점이 있습니다. 대신 필드에 오류가 있다는 신호를 보내지만 템플릿이 계속해서 평가되도록 하고 이어서 데이터를 반환합니다. 함수 내에서 $util.appendError를 사용하면 파이프라인의 실행 흐름이 중단되지 않습니다. 세부 정보 및 기타 $util.error 서명은 해석기 매핑 템플릿 유틸리티 참조를 참조하세요.

예제 템플릿

다음 GraphQL 쿼리를 사용하여 Post 유형을 반환하는 getPost(id:ID!)라는 필드에 DynamoDB 데이터 소스와 단위 해석기가 있다고 가정해 보겠습니다.


getPost(id:1){
    id
    title
    content
}

해석기 템플릿은 다음과 같습니다.


     {
    "version" : "2018-05-29",
    "operation" : "GetItem",
    "key" : {
        "id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
    }
}

이렇게 하면 의 id 입력 파라미터 값이 1로 대체${ctx.args.id}되고 다음 가 생성됩니다JSON.


     {
    "version" : "2018-05-29",
    "operation" : "GetItem",
    "key" : {
        "id" : { "S" : "1" }
    }
}

AWS AppSync 는 이 템플릿을 사용하여 DynamoDB와 통신하고 데이터를 가져오는(또는 적절한 경우 다른 작업을 수행하는) 지침을 생성합니다. 데이터가 반환되면 는 데이터 셰이핑 또는 로직을 수행하는 데 사용할 수 있는 선택적 응답 매핑 템플릿을 통해 데이터를 AWS AppSync 실행합니다. 예를 들어 DynamoDB에서 결과를 가져오는 경우 결과는 다음과 같습니다.


{
        "id" : 1,
        "theTitle" : "AWS AppSync works offline!",
        "theContent-part1" : "It also has realtime functionality",
        "theContent-part2" : "using GraphQL"
}

다음 응답 매핑 템플릿을 사용하여 필드 중 두 개를 단일 필드로 결합할 수 있습니다.


{
        "id" : $util.toJson($context.data.id),
        "title" : $util.toJson($context.data.theTitle),
        "content" : $util.toJson("${context.data.theContent-part1} ${context.data.theContent-part2}")
}

템플릿이 데이터에 적용된 이후의 데이터 형태 형성은 다음과 같습니다.


{
        "id" : 1,
        "title" : "AWS AppSync works offline!",
        "content" : "It also has realtime functionality using GraphQL"
}

이 데이터는 다음과 같이 클라이언트에 대한 응답으로 제공됩니다.


{
        "data": {
                "getPost":      {
                        "id" : 1,
                        "title" : "AWS AppSync works offline!",
                        "content" : "It also has realtime functionality using GraphQL"
                }
        }
}

대부분 환경에서 응답 매핑 템플릿은 데이터의 단순 전달로, 개별 항목 또는 항목 목록을 반환하는 경우 대부분 달라집니다. 개별 항목에 대한 전달:


$util.toJson($context.result)

목록에 대한 전달:


$util.toJson($context.result.items)

유닛 해석기와 파이프라인 해석기 둘 다에 대한 예를 더 보려면 해석기 자습서를 참조하세요.

평가된 맵핑 템플릿 역직렬화 규칙

매핑 템플릿은 문자열로 평가됩니다. 에서 AWS AppSync출력 문자열은 유효한 JSON 구조를 따라야 합니다.

또한 다음과 같은 역직렬화 규칙이 적용됩니다.

JSON 객체에서는 중복 키가 허용되지 않습니다.

평가된 매핑 템플릿 문자열이 JSON 객체를 나타내거나 중복 키가 있는 객체를 포함하는 경우 매핑 템플릿은 다음 오류 메시지를 반환합니다.

Duplicate field 'aField' detected on Object. Duplicate JSON keys are not allowed.

평가된 요청 매핑 템플릿의 중복 키 예:


{
    "version": "2018-05-29",
    "operation": "Invoke",
    "payload": {
        "field": "getPost",
        "postId": "1",
        "field": "getPost" ## key 'field' has been redefined
    }
}

이 오류를 해결하려면 JSON 객체에서 키를 재정의하지 마세요.

JSON 객체에서는 추적 문자가 허용되지 않습니다.

평가된 매핑 템플릿 문자열이 JSON 객체를 나타내고 후행 외부 문자가 포함된 경우 매핑 템플릿은 다음 오류 메시지를 반환합니다.

Trailing characters at the end of the JSON string are not allowed.

평가된 요청 매핑 템플릿의 후행 문자 예:


{
    "version": "2018-05-29",
    "operation": "Invoke",
    "payload": {
        "field": "getPost",
        "postId": "1",
    }
}extraneouschars

이 오류를 해결하려면 평가된 템플릿이 에 엄격하게 평가되는지 확인합니다JSON.

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

해석기 매핑 템플릿 참조(VTL)

해석기 매핑 템플릿 프로그래밍 안내서