AWS AppSync JavaScript 해석기 개요 - AWS AppSync
지원되는 런타임 기능유닛 해석기JavaScript 파이프라인 해석기의 구조추가 주제

AWS AppSync JavaScript 해석기 개요

AWS AppSync에서는 데이터 소스에 대한 작업을 수행하여 GraphQL 요청에 응답할 수 있습니다. 쿼리, 뮤테이션 또는 구독을 실행하려는 각 GraphQL 필드에 대해 해석기를 첨부해야 합니다.

해석기는 GraphQL과 데이터 소스를 연결하는 커넥터입니다. 들어오는 GraphQL 요청을 백엔드 데이터 소스에 대한 지침으로 변환하는 방법과 해당 데이터 소스를 GraphQL 응답으로 변환하는 방법을 AWS AppSync에 알려줍니다. AWS AppSync를 사용하면 JavaScript를 사용하여 해석기를 작성하고 이를 AWS AppSync(APPSYNC_JS) 환경에서 실행할 수 있습니다.

AWS AppSync를 사용하면 파이프라인에서 여러 AWS AppSync 기능으로 구성된 단위 해석기 또는 파이프라인 해석기를 작성할 수 있습니다.

지원되는 런타임 기능

AWS AppSync JavaScript 런타임은 JavaScript 라이브러리, 유틸리티 및 기능의 하위 집합을 제공합니다. APPSYNC_JS 런타임에서 지원되는 전체 기능 목록은 해석기 및 함수에 대한 JavaScript 런타임 기능을 참조하세요.

유닛 해석기

유닛 해석기는 데이터 소스에 대해 실행되는 요청 및 응답 핸들러를 정의하는 코드로 구성됩니다. 요청 핸들러는 컨텍스트 객체를 인수로 사용하고 데이터 소스를 호출하는 데 사용된 요청 페이로드를 반환합니다. 응답 핸들러는 실행된 요청의 결과와 함께 데이터 소스로부터 페이로드를 다시 받습니다. 응답 핸들러는 페이로드를 GraphQL 응답으로 변환하여 GraphQL 필드를 해결합니다. 아래 예제에서 해석기는 DynamoDB 데이터 소스에서 항목을 검색합니다.

import * as ddb from '@aws-appsync/utils/dynamodb'

export function request(ctx) {
  return ddb.get({ key: { id: ctx.args.id } });
}

export const response = (ctx) => ctx.result;

JavaScript 파이프라인 해석기의 구조

파이프라인 해석기는 요청 핸들러 및 응답 핸들러와 함수 목록을 정의하는 코드로 구성됩니다. 각 함수에는 데이터 소스에 대해 실행되는 요청 및 응답 핸들러가 있습니다. 파이프라인 해석기는 함수 목록에 실행을 위임하기 때문에 자신은 어떠한 데이터 소스에도 연결되지 않습니다. 유닛 해석기와 함수는 데이터 원본에 대해 작업을 실행하는 기본 요소입니다.

파이프라인 해석기 요청 핸들러

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

함수 목록

파이프라인 해석기가 순서대로 실행하는 함수 목록입니다. 파이프라인 해석기 요청 핸들러 평가 결과는 첫 번째 함수에 ctx.prev.result로 사용할 수 있습니다. 각 함수 평가 결과는 다음 함수에 ctx.prev.result로 사용할 수 있습니다.

파이프라인 해석기 응답 핸들러

이 파이프라인 해석기의 응답 핸들러를 사용하면 마지막 함수의 출력에서 예상 GraphQL 필드 유형으로 몇 가지 최종 로직을 수행할 수 있습니다. 함수 목록의 마지막 함수 출력은 파이프라인 해석기 응답 핸들러에서 ctx.prev.result 또는 ctx.result로 사용할 수 있습니다.

실행 흐름

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

  1. 파이프라인 해석기 요청 핸들러

  2. 함수 1: 함수 요청 핸들러

  3. 함수 1: 데이터 원본 호출

  4. 함수 1: 함수 응답 핸들러

  5. 함수 2: 함수 요청 핸들러

  6. 함수 2: 데이터 원본 호출

  7. 함수 2: 함수 응답 핸들러

  8. 파이프라인 해석기 응답 핸들러

GraphQL request flow diagram showing interactions between request, data sources, and response components.

유용한 APPSYNC_JS 런타임 내장 유틸리티

다음 유틸리티는 파이프라인 해석기로 작업할 때 유용할 수 있습니다.

ctx.stash

stash는 각 해석기 및 함수 요청 및 응답 핸들러 내에서 사용할 수 있는 객체입니다. 단일 해석기가 실행되는 동안에는 동일한 stash 인스턴스가 사용됩니다. 즉, stash를 사용하여 요청 및 응답 핸들러와 파이프라인 해석기의 함수 간에 임의의 데이터를 전달할 수 있습니다. 정규 JavaScript 객체처럼 stash를 테스트할 수 있습니다.

ctx.prev.result

ctx.prev.result는 파이프라인에서 실행된 이전 작업의 결과를 나타냅니다. 이전 작업이 파이프라인 해석기 요청 처리기였던 경우, ctx.prev.result는 체인의 첫 번째 함수에서 사용할 수 있게 됩니다. 이전 작업이 첫 번째 함수였으면 ctx.prev.result는 첫 번째 함수의 결과를 나타내고, 파이프라인의 두 번째 함수에 사용할 수 있습니다. 이전 작업이 마지막 함수였으면 ctx.prev.result는 마지막 함수의 결과를 나타내고, 파이프라인 해석기 응답 핸들러에 사용할 수 있습니다.

util.error

util.error 유틸리티는 필드 오류를 발생시키는 데 유용합니다. 함수 요청 또는 응답 핸들러 내에서 util.error를 사용하면 즉시 필드 오류가 발생해 후속 함수가 실행되지 않도록 방지합니다. 자세한 내용과 기타 util.error 서명을 보려면 해석기 및 함수에 대한 JavaScript 런타임 기능을 방문하세요.

util.appendError

util.appendError는 util.error()와 유사하지만 핸들러 평가를 중단하지 않는다는 큰 차이점이 있습니다. 대신 필드에 오류가 있다는 신호를 보내지만 핸들러가 계속해서 평가되도록 하고 이어서 데이터를 반환합니다. 함수 내에서 util.appendError를 사용하면 파이프라인의 실행 흐름이 중단되지 않습니다. 자세한 내용과 기타 util.error 서명을 보려면 해석기 및 함수에 대한 JavaScript 런타임 기능을 방문하세요.

runtime.earlyReturn

이 runtime.earlyReturn 함수를 사용하면 모든 요청 함수에서 조기에 반환할 수 있습니다. runtime.earlyReturn을 해석기 요청 핸들러 내에서 사용하면 해석기에서 반환됩니다. AWS AppSync 함수 요청 핸들러에서 호출하면 함수에서 반환되어 파이프라인의 다음 함수 또는 해석기 응답 핸들러로 계속 실행됩니다.

파이프라인 해석기 작성

파이프라인 해석기에는 파이프라인의 함수 실행을 둘러싼 요청 및 응답 핸들러도 있습니다. 요청 핸들러는 첫 번째 함수 요청 전에 실행되고, 응답 핸들러는 마지막 함수 응답 후에 실행됩니다. 해석기 요청 핸들러는 파이프라인의 함수에서 사용할 데이터를 설정할 수 있습니다. 해석기 응답 핸들러는 GraphQL 필드 출력 유형에 매핑되는 데이터를 반환하는 역할을 합니다. 아래 예에서 해석기 요청 처리기는 allowedGroups를 정의합니다. 반환된 데이터는 이러한 그룹 중 하나에 속해야 합니다. 이 값은 해석기의 함수에서 데이터를 요청하는 데 사용할 수 있습니다. 해석기의 응답 핸들러는 최종 검사를 수행하고 결과를 필터링하여 허용된 그룹에 속한 항목만 반환되도록 합니다.

import { util } from '@aws-appsync/utils';

/**
 * Called before the request function of the first AppSync function in the pipeline.
 *  @param ctx the context object holds contextual information about the function invocation.
 */
export function request(ctx) {
  ctx.stash.allowedGroups = ['admin'];
  ctx.stash.startedAt = util.time.nowISO8601();
  return {};
}
/**
 * Called after the response function of the last AppSync function in the pipeline.
 * @param ctx the context object holds contextual information about the function invocation.
 */
export function response(ctx) {
  const result = [];
  for (const item of ctx.prev.result) {
    if (ctx.stash.allowedGroups.indexOf(item.group) > -1) result.push(item);
  }
  return result;
}

AWS AppSync 함수 작성

AWS AppSync 함수를 사용하면 스키마의 여러 해석기에서 재사용할 수 있는 공통 로직을 작성할 수 있습니다. 예를 들어 Amazon DynamoDB 데이터 소스에서 항목을 쿼리하는 역할을 하는 QUERY_ITEMS라는 AWS AppSync 함수가 하나 있을 수 있습니다. 항목을 쿼리하려는 해석기의 경우 해석기의 파이프라인에 함수를 추가하고 사용할 쿼리 색인을 제공하면 됩니다. 로직을 다시 구현할 필요는 없습니다.

추가 주제

주제