요청 매핑 템플릿 응답 매핑 템플릿 Lambda 함수 일괄 처리 응답 Direct Lambda 해석기

AWS AppSync Lambda에 대한 해석기 매핑 템플릿 참조

참고

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

AWS AppSync 함수와 해석기를 사용하여 계정에 있는 Lambda 함수를 호출할 수 있습니다. Lambda 함수의 요청 페이로드와 응답을 구성한 후 클라이언트에 반환할 수 있습니다. 매핑 템플릿을 사용하여 호출할 작업의 특성에 AWS AppSync 대한 힌트를 제공할 수도 있습니다. 이 단원에서는 지원되는 Lambda 작업에 대한 다양한 매핑 템플릿에 대해 설명합니다.

요청 매핑 템플릿

Lambda 요청 매핑 템플릿은 Lambda 함수와 관련된 필드를 처리합니다.


{
  "version": string,
  "operation": Invoke|BatchInvoke,
  "payload": any type,
  "invocationType": RequestResponse|Event
}

해결 시 Lambda 요청 매핑 템플릿의 JSON 스키마 표현입니다.


{
  "definitions": {},
  "$schema": "https://json-schema.org/draft-06/schema#",
  "$id": "https://aws.amazon.com/appsync/request-mapping-template.json",
  "type": "object",
  "properties": {
    "version": {
      "$id": "/properties/version",
      "type": "string",
      "enum": [
        "2018-05-29"
      ],
      "title": "The Mapping template version.",
      "default": "2018-05-29"
    },
    "operation": {
      "$id": "/properties/operation",
      "type": "string",
      "enum": [
        "Invoke",
        "BatchInvoke"
      ],
      "title": "The Mapping template operation.",
      "description": "What operation to execute.",
      "default": "Invoke"
    },
    "payload": {},
    "invocationType": {
      "$id": "/properties/invocationType",
      "type": "string",
      "enum": [
        "RequestResponse",
        "Event"
      ],
      "title": "The Mapping template invocation type.",
      "description": "What invocation type to execute.",
      "default": "RequestResponse"
    }
  },
  "required": [
    "version",
    "operation"
  ],
  "additionalProperties": false
}

다음은 컨텍스트의 인수와 함께 GraphQL 스키마의 getPost 필드가 되는 페이로드 데이터가 있는 invoke 작업을 사용하는 예제입니다.


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

이전 예제가 이제 다음과 같이 보이도록 전체 매핑 문서가 Lambda 함수에 입력으로 전달됩니다.


{
  "version": "2018-05-29",
  "operation": "Invoke",
  "payload": {
    "field": "getPost",
    "arguments": {
      "id": "postId1"
    }
  }
}

버전

모든 요청 매핑 템플릿에 공통적으로 는 템플릿에서 사용하는 버전을 version 정의합니다. version 는 필수이며 정적 값입니다.


"version": "2018-05-29"

Operation

Lambda 데이터 소스를 사용하면 operation 필드에서 Invoke 및 의 두 가지 작업을 정의할 수 있습니다BatchInvoke. Invoke 작업을 통해 모든 GraphQL 필드 해석기에 대해 Lambda 함수를 호출하도록 AWS AppSync 알 수 있습니다. 는 현재 GraphQL 필드에 대한 AWS AppSync 일괄 요청을 BatchInvoke 지시합니다. operation 필드는 필수 사항입니다.

Invoke의 경우 확인된 요청 매핑 템플릿은 Lambda 함수의 입력 페이로드와 일치합니다. 위의 예를 수정해 보겠습니다.


{
  "version": "2018-05-29",
  "operation": "Invoke",
    "payload": {
      "arguments": $util.toJson($context.arguments)
    }
}

이 문제는 해결되어 Lambda 함수로 전달되며 다음과 같을 수 있습니다.


{
  "version": "2018-05-29",
  "operation": "Invoke",
    "payload": {
      "arguments": {
        "id": "postId1"
      }
    }
}

BatchInvoke의 경우 매핑 템플릿은 배치의 모든 필드 해석기에 적용됩니다. 간결성을 위해 는 확인된 모든 매핑 템플릿 payload 값을 매핑 템플릿과 일치하는 단일 객체의 목록에 AWS AppSync 병합합니다. 다음 예제 템플릿을 이러한 병합을 보여줍니다.


{
  "version": "2018-05-29",
  "operation": "BatchInvoke",
  "payload": $util.toJson($context)
}

이 템플릿은 다음 매핑 문서로 해석됩니다.


{
  "version": "2018-05-29",
  "operation": "BatchInvoke",
  "payload": [
    {...}, // context for batch item 1
    {...}, // context for batch item 2
    {...}  // context for batch item 3
  ]
}

payload 목록의 각 요소는 단일 배치 항목에 해당합니다. 또한 Lambda 함수는 요청에 전송된 항목의 순서와 일치하는 목록 형식 응답을 반환해야 합니다.


[
  { "data": {...}, "errorMessage": null, "errorType": null }, // result for batch item 1
  { "data": {...}, "errorMessage": null, "errorType": null }, // result for batch item 2
  { "data": {...}, "errorMessage": null, "errorType": null }  // result for batch item 3
]

페이로드

payload 필드는 잘 구성된 를 Lambda 함수에 전달하는 JSON 데 사용되는 컨테이너입니다. operation 필드가 로 설정된 경우 는 기존 payload 값을 목록에 BatchInvoke AWS AppSync 래핑합니다. payload 필드는 선택 사항입니다.

호출 유형

Lambda 데이터 소스를 사용하면 RequestResponse 및 의 두 가지 호출 유형을 정의할 수 있습니다Event. 호출 유형은 Lambda API에 정의된 호출 유형과 동의어입니다. RequestResponse 호출 유형을 사용하면 Lambda 함수를 동기적으로 AWS AppSync 호출하여 응답을 기다릴 수 있습니다. Event 호출을 사용하면 Lambda 함수를 비동기적으로 호출할 수 있습니다. Lambda가 Event 호출 유형 요청을 처리하는 방법에 대한 자세한 내용은 비동기 호출을 참조하세요. invocationType 필드는 선택 사항입니다. 이 필드가 요청에 포함되지 않은 경우 RequestResponse 기본적으로 호출 유형이 AWS AppSync 됩니다.

모든 invocationType 필드에 대해 확인된 요청은 Lambda 함수의 입력 페이로드와 일치합니다. 위의 예를 수정해 보겠습니다.


{
  "version": "2018-05-29",
  "operation": "Invoke",
  "invocationType": "Event"
  "payload": {
    "arguments": $util.toJson($context.arguments)
  }
}

이 문제는 해결되어 Lambda 함수로 전달되며 다음과 같을 수 있습니다.


{
  "version": "2018-05-29",
  "operation": "Invoke",
  "invocationType": "Event",
  "payload": {
    "arguments": {
      "id": "postId1"
    }
  }
}

Event 호출 유형 필드와 함께 BatchInvoke 작업을 사용하는 경우 는 위에서 언급한 것과 동일한 방식으로 필드 해석기를 AWS AppSync 병합하고 요청은 값 payload 목록이 인 비동기 이벤트로 Lambda 함수로 전달됩니다. Event 호출 유형 해석기에 대한 해석기 캐싱은 캐시 적중이 발생한 경우 Lambda로 전송되지 않으므로 비활성화하는 것이 좋습니다.

응답 매핑 템플릿

다른 데이터 소스와 마찬가지로 Lambda 함수는 GraphQL 유형으로 변환해야 AWS AppSync 하는 응답을 에 전송합니다.

Lambda 함수의 결과는 Velocity 템플릿 언어(VTL) $context.result 속성을 통해 사용할 수 있는 context 객체에 설정됩니다.

Lambda 함수 응답의 모양이 GraphQL 유형의 모양과 정확히 일치하는 경우 다음 응답 매핑 템플릿을 사용하여 응답을 전달할 수 있습니다.


$util.toJson($context.result)

응답 매핑 템플릿에 적용되는 필수 필드 또는 모양 제한이 없습니다. 하지만 GraphQL은 강력한 형식이므로 해석된 매핑 템플릿이 필요한 GraphQL 유형과 일치해야 합니다.

Lambda 함수 일괄 처리 응답

operation 필드가 AWS AppSync로 설정된 경우 는 Lambda 함수에서 항목 목록을 다시 BatchInvoke예상합니다. 각 결과를 원래 요청 항목에 다시 AWS AppSync 매핑하려면 응답 목록이 크기와 순서로 일치해야 합니다. 응답 목록에 null 항목이 있는 것은 유효하며, $ctx.result는 그에 따라 null로 설정됩니다.

Direct Lambda 해석기

매핑 템플릿 사용을 완전히 피하려면 Lambda 함수에 기본 페이로드를 제공하고 GraphQL 유형에 기본 Lambda 함수 응답을 AWS AppSync 제공할 수 있습니다. 요청 템플릿, 응답 템플릿 또는 둘 다를 제공하도록 선택하고 그에 따라 AWS AppSync 처리할 수 있습니다.

Direct Lambda 요청 매핑 템플릿

요청 매핑 템플릿이 제공되지 않으면 는 Context 객체를 Invoke 작업으로 Lambda 함수로 직접 AWS AppSync 보냅니다. Context 객체의 구조에 대한 자세한 내용은 AWS AppSync 해석기 매핑 템플릿 컨텍스트 참조 단원을 참조하세요.

Direct Lambda 응답 매핑 템플릿

응답 매핑 템플릿이 제공되지 않은 경우 는 Lambda 함수의 응답을 수신할 때 두 가지 중 하나를 AWS AppSync 수행합니다. 요청 매핑 템플릿을 제공하지 않았거나 버전 와 함께 요청 매핑 템플릿을 제공한 경우 2018-05-29응답은 다음 응답 매핑 템플릿과 동일합니다.


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

버전이 인 템플릿을 제공한 경우 응답 로직2017-02-28은 다음 응답 매핑 템플릿과 동등하게 작동합니다.


$util.toJson($ctx.result)

표재적으로 매핑 템플릿 우회는 이전 예제와 같이 특정 매핑 템플릿을 사용하는 것과 유사하게 작동합니다. 그러나 내부에서는 매핑 템플릿에 대한 평가가 완전히 우회됩니다. 템플릿 평가 단계가 우회되므로 일부 시나리오에서는 평가해야 하는 응답 매핑 템플릿이 있는 Lambda 함수에 비해 응답 중에 애플리케이션이 오버헤드와 지연 시간을 덜 경험할 수 있습니다.

Direct Lambda 해석기 응답에서의 사용자 지정 오류 처리

사용자 지정 예외를 발생시켜 Direct Lambda 해석기가 호출하는 Lambda 함수의 오류 응답을 사용자 지정할 수 있습니다. 다음 예제에서는 를 사용하여 사용자 지정 예외를 생성하는 방법을 보여줍니다 JavaScript.


class CustomException extends Error {
  constructor(message) {
    super(message);
    this.name = "CustomException";
  }
}
 
throw new CustomException("Custom message");

예외가 발생하는 경우 errorType 및 errorMessage는 각각 발생한 사용자 지정 오류의 name 및 message입니다.

errorType 가 AWS AppSync이면 는 사용자 지정 메시지 대신 기본 메시지("You are not authorized to make this call.")를 UnauthorizedException반환합니다.

다음 조각은 사용자 지정 을 보여주는 예제 GraphQL 응답입니다errorType.


{
  "data": {
    "query": null
  },
  "errors": [
    {
      "path": [
        "query"
      ],
      "data": null,
      "errorType": "CustomException",
      "errorInfo": null,
      "locations": [
        {
          "line": 5,
          "column": 10,
          "sourceName": null
        }
      ],
      "message": "Custom Message"
    }
  ]
}

Direct Lambda 해석기: 일괄 처리 활성화

해석기에 maxBatchSize를 구성하여 Direct Lambda 해석기에 대한 일괄 처리를 활성화할 수 있습니다. maxBatchSize 가 0 Direct Lambda 해석기보다 큰 값으로 설정된 경우 AWS AppSync 는 최대 크기의 요청을 Lambda 함수로 일괄 전송합니다maxBatchSize.

Direct Lambda 해석기0에서 를 maxBatchSize 로 설정하면 배치가 꺼집니다.

Lambda 해석기를 사용한 일괄 처리 작동 방식에 대한 자세한 내용은 고급 사용 사례: 일괄 처리 단원을 참조하세요.

요청 매핑 템플릿

배치가 활성화되고 요청 매핑 템플릿이 제공되지 않은 경우 는 BatchInvoke 작업으로 Context 객체 목록을 Lambda 함수로 직접 AWS AppSync 보냅니다.

응답 매핑 템플릿

일괄 처리가 활성화되고 응답 매핑 템플릿이 제공되지 않은 경우, 응답 로직은 다음 응답 매핑 템플릿과 동일합니다.


#if( $context.result && $context.result.errorMessage )
      $utils.error($context.result.errorMessage, $context.result.errorType,
      $context.result.data)
#else
      $utils.toJson($context.result.data)
#end

Lambda 함수는 전송된 Context 객체 목록과 동일한 순서로 결과 목록을 반환해야 합니다. 특정 결과에 대해 errorMessage 및 errorType을 제공하여 개별 오류를 반환할 수 있습니다. 목록에서 각 결과는 다음 형식이어야 합니다.


{
   "data" : { ... }, // your data
   "errorMessage" : { ... }, // optional, if included an error entry is added to the "errors" object in the AppSync response 
   "errorType" : { ... } // optional, the error type
}

참고

결과 객체의 다른 필드는 현재 무시됩니다.

Lambda의 오류 처리

Lambda 함수에서 예외 또는 오류를 발생시켜 모든 결과에 대해 오류를 반환할 수 있습니다. 배치 요청의 페이로드 요청 또는 응답 크기가 너무 크면 Lambda는 오류를 반환합니다. 이 경우 maxBatchSize를 줄이거나 응답 페이로드의 크기를 줄이는 것을 고려해야 합니다.

개별 오류 처리에 대한 자세한 내용은 개별 오류 반환을 참조하세요.

샘플 Lambda 함수

아래 스키마를 사용하여 Post.relatedPosts 필드 해석기에 대한 Direct Lambda 해석기를 생성하고 maxBatchSize 위의 를 설정하여 배치화를 활성화할 수 있습니다0.


schema {
    query: Query
    mutation: Mutation
}

type Query {
    getPost(id:ID!): Post
    allPosts: [Post]
}

type Mutation {
    addPost(id: ID!, author: String!, title: String, content: String, url: String): Post!
}

type Post {
    id: ID!
    author: String!
    title: String
    content: String
    url: String
    ups: Int
    downs: Int
    relatedPosts: [Post]
}

다음 쿼리에서는 relatedPosts 해결 요청을 일괄 처리하여 Lambda 함수를 호출합니다.


query getAllPosts {
  allPosts {
    id
    relatedPosts {
      id
    }
  }
}

Lambda 함수의 간단한 구현은 다음과 같습니다.


const posts = {
  1: {
    id: '1',
    title: 'First book',
    author: 'Author1',
    url: 'https://amazon.com/',
    content:
      'SAMPLE TEXT AUTHOR 1 SAMPLE TEXT AUTHOR 1 SAMPLE TEXT AUTHOR 1 SAMPLE TEXT AUTHOR 1 SAMPLE TEXT AUTHOR 1 SAMPLE TEXT AUTHOR 1',
    ups: '100',
    downs: '10',
  },
  2: {
    id: '2',
    title: 'Second book',
    author: 'Author2',
    url: 'https://amazon.com',
    content: 'SAMPLE TEXT AUTHOR 2 SAMPLE TEXT AUTHOR 2 SAMPLE TEXT',
    ups: '100',
    downs: '10',
  },
  3: { id: '3', title: 'Third book', author: 'Author3', url: null, content: null, ups: null, downs: null },
  4: {
    id: '4',
    title: 'Fourth book',
    author: 'Author4',
    url: 'https://www.amazon.com/',
    content:
      'SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4 SAMPLE TEXT AUTHOR 4',
    ups: '1000',
    downs: '0',
  },
  5: {
    id: '5',
    title: 'Fifth book',
    author: 'Author5',
    url: 'https://www.amazon.com/',
    content: 'SAMPLE TEXT AUTHOR 5 SAMPLE TEXT AUTHOR 5 SAMPLE TEXT AUTHOR 5 SAMPLE TEXT AUTHOR 5 SAMPLE TEXT',
    ups: '50',
    downs: '0',
  },
}

const relatedPosts = {
  1: [posts['4']],
  2: [posts['3'], posts['5']],
  3: [posts['2'], posts['1']],
  4: [posts['2'], posts['1']],
  5: [],
}
exports.handler = async (event) => {
  console.log('event ->', event)
  // retrieve the ID of each post
  const ids = event.map((context) => context.source.id)
  // fetch the related posts for each post id
  const related = ids.map((id) => relatedPosts[id])

  // return the related posts; or an error if none were found
  return related.map((r) => {
    if (r.length > 0) {
      return { data: r }
    } else {
      return { data: null, errorMessage: 'Not found', errorType: 'ERROR' }
    }
  })
}

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

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

문서 규칙

에 대한 해석기 매핑 템플릿 참조 OpenSearch

에 대한 해석기 매핑 템플릿 참조 EventBridge