해석기 구성(VTL)

참고

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

GraphQL 해석기는 형식 스키마의 필드를 데이터 원본에 연결합니다. 해석기는 요청을 이행하는 메커니즘입니다. AWS 코드를 작성할 필요 없이 AppSync에서는 스키마로부터 해석기를 자동으로 생성해 연결하거나 기존 테이블에서 스키마를 생성해 해석기를 연결할 수 있습니다.

AWS AppSync의 해석기는 JavaScript를 사용하여 GraphQL 식을 데이터 원본에서 사용할 수 있는 형식으로 변환합니다. 또는 Apache Velocity Template Language(VTL)로 작성된 매핑 템플릿을 사용하여 GraphQL 식을 데이터 원본이 사용할 수 있는 형식으로 변환할 수 있습니다.

이 섹션에서는 VTL을 사용하여 해석기를 구성하는 방법을 보여 줍니다. 해석기 작성을 위한 소개 자습서 스타일의 프로그래밍 가이드는 해석기 매핑 템플릿 프로그래밍 안내서에서 찾을 수 있으며 프로그래밍 시 사용할 수 있는 헬퍼 유틸리티는 해석기 매핑 템플릿 컨텍스트 참조에서 찾을 수 있습니다. AWS 또한 AppSync에는 처음부터 편집 또는 작성할 때 사용할 수 있는 기본 테스트 및 디버깅 흐름이 포함되어 있습니다. 자세한 내용은 해석기 테스트 및 디버깅을 참조하세요.

앞서 언급한 자습서를 사용하기 전에 이 안내서를 확인하는 것이 좋습니다.

이 섹션에서는 해석기를 생성하고, 변형에 대해 해석기를 추가하고, 고급 구성을 사용하는 방법을 알아봅니다.

첫 번째 해석기 생성

이전 섹션의 예제에 따라 첫 번째 단계는 Query 유형에 맞는 해석기를 만드는 것입니다.

Console

AWS Management Console에 로그인한 다음 AppSync 콘솔을 엽니다.
1. API 대시보드에서 GraphQL API를 선택합니다.
2. 사이드바에서 스키마를 선택합니다.
페이지 오른쪽에 해석기라는 창이 있습니다. 이 상자에는 페이지 왼쪽의 스키마 창에 정의된 유형 및 필드 목록이 있습니다. 필드에 해석기를 연결할 수 있습니다. 예를 들어 쿼리 유형에서 getTodos 필드 옆에 있는 첨부를 선택합니다.
해석기 생성 페이지에서 데이터 원본 연결 안내서에서 만든 데이터 원본을 선택합니다. 매핑 템플릿 구성 창에서 오른쪽의 드롭다운 목록을 사용하여 일반 요청 및 응답 매핑 템플릿을 모두 선택하거나 직접 작성할 수 있습니다.

참고
요청 매핑 템플릿과 응답 매핑 템플릿의 쌍을 이루는 것을 단위 해석기라고 합니다. 단위 해석기는 일반적으로 기계적 작업을 수행하는 것이 목적이므로 데이터 원본 수가 적은 단일 작업에만 사용하는 것이 좋습니다. 더 복잡한 작업의 경우 여러 데이터 원본에서 순차적으로 여러 작업을 실행할 수 있는 파이프라인 해석기를 사용하는 것이 좋습니다.
요청과 응답 매핑 템플릿의 차이점에 대한 자세한 정보는 단위 해석기를 참조하세요.
파이프라인 해석기 사용에 대한 자세한 내용은 파이프라인 해석기를 참조하세요.
일반적으로 AWS AppSync 콘솔에는 데이터 원본에서 항목을 가져오는 데 사용할 수 있는 내장 템플릿이 있습니다(예: 모든 항목 쿼리, 개별 조회 등). 예를 들어 getTodos에 페이지 매김이 없는 스키마 설계의 간단한 스키마 버전에서 항목을 나열하기 위한 요청 매핑 템플릿은 다음과 같습니다.
```
{
    "version" : "2017-02-28",
    "operation" : "Scan"
}
```
요청과 동반되는 응답 매핑 템플릿은 항상 필요합니다. 콘솔은 다음과 같은 목록에 대한 패스스루 값과 함께 기본값을 제공합니다.
```
$util.toJson($ctx.result.items)
```
이 예제에서 항목의 목록에 대한 context 객체(별칭 $ctx)는 $context.result.items 양식을 갖습니다. GraphQL 작업이 단일 항목을 반환하는 경우 이는 $context.result입니다. AWS AppSync는 이전에 나열된 $util.toJson 함수와 같은 일반 작업에 대해 헬퍼 함수를 제공하여 적절한 응답 형식을 지정합니다. 전체 함수 목록은 해석기 매핑 템플릿 유틸리티 참조를 참조하세요.
해석기 저장 을 선택합니다.

API

CreateResolver API를 호출하여 해석기 객체를 생성합니다.
UpdateResolver API를 호출하여 해석기의 필드를 수정할 수 있습니다.

CLI

create-resolver 명령을 실행하여 해석기를 생성합니다.

이 특정 명령에 대해 6개의 파라미터를 입력해야 합니다.

API의 api-id.
스키마에서 수정하려는 유형의 type-name. 콘솔 예제에서는 Query였습니다.
유형에서 수정하려는 필드의 field-name. 콘솔 예제에서는 getTodos였습니다.
데이터 원본 연결 안내서에서 만든 데이터 원본의 data-source-name.
요청의 본문인 request-mapping-template. 콘솔 예제에서는 다음과 같았습니다.
```
{
    "version" : "2017-02-28",
    "operation" : "Scan"
}
```
응답의 본문인 response-mapping-template. 콘솔 예제에서는 다음과 같았습니다.
```
$util.toJson($ctx.result.items)
```

예를 들어 명령은 다음과 같을 수 있습니다.


aws appsync create-resolver --api-id abcdefghijklmnopqrstuvwxyz --type-name Query --field-name getTodos --data-source-name TodoTable --request-mapping-template "{ "version" : "2017-02-28", "operation" : "Scan", }" --response-mapping-template ""$"util.toJson("$"ctx.result.items)"

CLI에서 출력이 반환됩니다. 다음은 그 예입니다:


{
    "resolver": {
        "kind": "UNIT",
        "dataSourceName": "TodoTable",
        "requestMappingTemplate": "{ version : 2017-02-28, operation : Scan, }",
        "resolverArn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/Query/resolvers/getTodos",
        "typeName": "Query",
        "fieldName": "getTodos",
        "responseMappingTemplate": "$util.toJson($ctx.result.items)"
    }
}

해석기의 필드 또는 매핑 템플릿을 수정하려면 update-resolver 명령을 실행합니다.

api-id 파라미터를 제외하고 create-resolver 명령에 사용된 파라미터는 update-resolver 명령의 새 값으로 덮어써집니다.

변형에 대한 해석기 추가

다음 단계는 Mutation 유형에 맞는 해석기를 생성하는 것입니다.

Console

AWS Management Console에 로그인한 다음 AppSync 콘솔을 엽니다.
1. API 대시보드에서 GraphQL API를 선택합니다.
2. 사이드바에서 스키마를 선택합니다.
변형 유형에서 addTodo 필드 옆에 있는 연결을 선택합니다.
해석기 생성 페이지에서 데이터 원본 연결 안내서에서 만든 데이터 원본을 선택합니다.

DynamoDB에 새 항목을 추가하는 경우 요청 템플릿이 변형이므로 매핑 템플릿 구성 창에서 요청 템플릿을 수정해야 합니다. 다음 요청 매핑 템플릿을 사용합니다.


{
    "version" : "2017-02-28",
    "operation" : "PutItem",
    "key" : {
        "id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
    },
    "attributeValues" : $util.dynamodb.toMapValuesJson($ctx.args)
}

AWS AppSync는 GraphQL 스키마의 addTodo 필드에 정의된 인수를 DynamoDB 작업으로 자동으로 변환합니다. 이전 예에서는 변형 인수에서 전달된 id의 키를 $ctx.args.id로 사용하여 DynamoDB에 레코드를 저장합니다. 전달하는 다른 모든 필드는 $util.dynamodb.toMapValuesJson($ctx.args)을 사용하여 DynamoDB 특성에 자동으로 매핑됩니다.

이 해석기의 경우 다음 응답 매핑 템플릿을 사용합니다.
```
$util.toJson($ctx.result)
```
AWS AppSync는 또한 해석기 편집을 위한 테스트 및 디버그 워크플로를 지원합니다. 모의 context 객체를 사용하여 호출 전에 템플릿의 변환된 값을 확인할 수 있습니다. 선택적으로 쿼리를 실행할 때 대화식으로 데이터 원본에 대한 전체 요청 실행을 볼 수 있습니다. 자세한 내용은 해석기 테스트 및 디버깅 및 모니터링 및 로깅을 참조하세요.
해석기 저장 을 선택합니다.

API

첫 번째 해석기 생성 섹션의 명령과 이 섹션의 파라미터 세부 정보를 활용하여 API로 이 작업을 수행할 수도 있습니다.

CLI

첫 번째 해석기 생성 섹션의 명령과 이 섹션의 파라미터 세부 정보를 활용하여 CLI에서 이 작업을 수행할 수도 있습니다.

이 시점에서 고급 해석기를 사용하지 않는 경우 API 사용에서 설명하는 것과 같이 GraphQL API 사용을 시작할 수 있습니다.

고급 해석기

고급 섹션을 따르고 있으며, 스키마 설계의 샘플 스키마를 빌드하여 페이지 지정 스캔을 수행하는 경우 getTodos 필드에 대한 다음 요청 템플릿을 대신 사용합니다.


{
    "version" : "2017-02-28",
    "operation" : "Scan",
    "limit": $util.defaultIfNull(${ctx.args.limit}, 20),
    "nextToken": $util.toJson($util.defaultIfNullOrBlank($ctx.args.nextToken, null))
}

이러한 페이지 매김 사용 사례의 경우 응답 매핑에는 커서가 포함되어 있고(따라서 클라이언트가 다음에 시작할 페이지를 알 수 있음) 결과 집합이 포함되어 있어야 하기 때문에 응답 매핑은 단순한 패스스루 이상입니다. 매핑 템플릿은 다음과 같습니다.


{
    "todos": $util.toJson($context.result.items),
    "nextToken": $util.toJson($context.result.nextToken)
}

이전 응답 매핑 템플릿의 필드가 TodoConnection 형식에 정의된 필드와 일치해야 합니다.

Comments 테이블이 있고 Todo 형식에 대한 주석 필드를 해석하는 관계의 경우([Comment]의 형식 반환) 두 번째 테이블을 기준으로 쿼리를 실행하는 매핑 템플릿을 사용할 수 있습니다. 이를 수행하려면 데이터 원본 연결에서 설명하는 것과 같이 Comments 테이블에 대한 데이터 원본이 이미 생성되어야 합니다.

참고

두 번째 테이블을 기준으로 쿼리 작업을 사용하는 것은 설명을 돕기 위한 목적일 뿐입니다. 대신 DynamoDB에 대해 다른 작업을 사용할 수 있습니다. 뿐만 아니라 관계를 GraphQL 스키마에서 제어하기 때문에 AWS Lambda 또는 Amazon OpenSearch Service 등과 같은 다른 데이터 원본에서 데이터를 가져올 수도 있습니다.

Console

AWS Management Console에 로그인한 다음 AppSync 콘솔을 엽니다.
1. API 대시보드에서 GraphQL API를 선택합니다.
2. 사이드바에서 스키마를 선택합니다.
Todo 유형에서 comments 필드 옆에 있는 연결을 선택합니다.
해석기 생성 페이지에서 주석 테이블 데이터 원본을 선택합니다. 빠른 시작 안내서에서 주석 테이블의 기본 이름은 AppSyncCommentTable이지만, 지정한 이름에 따라 달라질 수 있습니다.

요청 매핑 템플릿에 다음 스니펫을 추가합니다.


{
    "version": "2017-02-28",
    "operation": "Query",
    "index": "todoid-index",
    "query": {
        "expression": "todoid = :todoid",
        "expressionValues": {
            ":todoid": {
                "S": $util.toJson($context.source.id)
            }
        }
    }
}

context.source는 해석 중인 현재 필드의 상위 객체를 참조합니다. 이 예제에서 source.id는 개별 Todo 객체를 참조하고, 이는 쿼리 표현식에 사용됩니다.

다음과 같이 패스스루 응답 매핑 템플릿을 사용할 수 있습니다.
```
$util.toJson($ctx.result.items)
```
해석기 저장 을 선택합니다.
마지막으로 콘솔의 스키마 페이지로 돌아가서 addComment 필드에 해석기를 연결하고, Comments 테이블에 대한 데이터 원본을 지정합니다. 이 경우의 요청 매핑 템플릿은 인수로서 주석 처리된 특정 todoid가 포함된 단순한 PutItem이지만, $utils.autoId() 유틸리티를 사용하여 다음과 같이 주석에 대한 고유한 정렬 키를 생성할 수 있습니다.
```
{
    "version": "2017-02-28",
    "operation": "PutItem",
    "key": {
        "todoid": { "S": $util.toJson($context.arguments.todoid) },
        "commentid": { "S": "$util.autoId()" }
    },
    "attributeValues" : $util.dynamodb.toMapValuesJson($ctx.args)
}
```
다음과 같이 패스스루 응답 템플릿을 사용합니다.
```
$util.toJson($ctx.result)
```

API

첫 번째 해석기 생성 섹션의 명령과 이 섹션의 파라미터 세부 정보를 활용하여 API로 이 작업을 수행할 수도 있습니다.

CLI

첫 번째 해석기 생성 섹션의 명령과 이 섹션의 파라미터 세부 정보를 활용하여 CLI에서 이 작업을 수행할 수도 있습니다.

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

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

문서 규칙

파이프라인 해석기(JavaScript)

직접 Lambda 해석기(VTL)