자습서: HTTP 해석기

참고

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

AWS AppSync에서는 지원되는 데이터 소스(즉 AWS Lambda, Amazon DynamoDB, Amazon OpenSearch Service 또는 Amazon Aurora)을 사용하여 다양한 작업을 수행하고 모든 임의 HTTP 엔드포인트를 통해 GraphQL 필드를 해석합니다. HTTP 엔드포인트가 사용 가능해진 후에는 데이터 원본에 연결할 수 있습니다. 쿼리, 변형 및 구독 등 GraphQL 작업을 수행하도록 스키마의 해석기를 구성할 수 있습니다. 이 자습서에서는 몇 가지 일반적인 예제를 살펴봅니다.

이 자습서에서는 AWS AppSync GraphQL 엔드포인트에 REST API(Amazon API Gateway 및 Lambda를 사용하여 생성)를 사용합니다.

원클릭 설치

HTTP 엔드포인트가 구성된(Amazon API Gateway 및 Lambda 사용) AWS AppSync에서 GraphQL 엔드포인트를 자동으로 설치하려는 경우 다음 AWS CloudFormation 템플릿을 사용할 수 있습니다.

REST API 만들기

다음 AWS CloudFormation 템플릿을 사용하여 이 자습서에 사용되는 REST 엔드포인트를 설정할 수 있습니다.

AWS CloudFormation 스택은 다음 단계를 수행합니다.

1. 마이크로서비스에 대한 비즈니스 로직이 포함된 Lambda 함수를 설정합니다.

2. 다음 엔드포인트/메서드/콘텐츠 유형 조합으로 API Gateway REST API를 설정합니다.

API 리소스 경로	HTTP 메서드	지원되는 콘텐츠 유형
/v1/사용자	POST	application/json
/v1/사용자	GET	application/json
/v1/사용자/1	GET	application/json
/v1/사용자/1	PUT	application/json
/v1/사용자/1	DELETE	application/json

GraphQL API 생성

AWS AppSync에서 GraphQL API를 생성하려면:

• AWS AppSync 콘솔을 열고 API 생성을 선택합니다.

• API에 UserData를 입력합니다.

• 사용자 지정 스키마를 선택합니다.

• 생성을 선택합니다.

AWS AppSync 콘솔에서 API 키 인증 모드를 사용하여 새 GraphQL API를 생성합니다. 콘솔에서 GraphQL API의 나머지 부분을 설정하고 이 자습서의 나머지 부분에서 이 API에 대한 쿼리를 실행할 수 있습니다.

GraphQL 스키마 생성

GraphQL API가 마련되었으면 GraphQL 스키마를 생성해 보십시오. AWS AppSync 콘솔의 스키마 편집기에서 스키마가 다음 스키마와 일치하는지 확인합니다.

schema {
    query: Query
    mutation: Mutation
}

type Mutation {
    addUser(userInput: UserInput!): User
    deleteUser(id: ID!): User
}

type Query {
    getUser(id: ID): User
    listUser: [User!]!
}

type User {
    id: ID!
    username: String!
    firstname: String
    lastname: String
    phone: String
    email: String
}

input UserInput {
    id: ID!
    username: String!
    firstname: String
    lastname: String
    phone: String
    email: String
}

HTTP 데이터 원본 구성

HTTP 데이터 원본을 구성하려면 다음을 수행하십시오.

• DataSources(데이터 원본) 탭에서 New(새로 만들기)를 선택한 후, 데이터 원본에 대해 친숙한 이름(예: HTTP)을 입력합니다.

• Data source type(데이터 원본 형식)에서 HTTP를 선택합니다.

• 엔드포인트를 생성된 API Gateway 엔드포인트로 설정합니다. 단계 이름을 엔드포인트의 일부로 포함하지 않았는지 확인합니다.

참고: 현재 AWS AppSync는 퍼블릭 엔드포인트만 지원합니다.

참고: AWS AppSync 서비스에서 인식하는 인증 기관에 대한 자세한 내용은 HTTPS 엔드포인트에 대해 AWS AppSync에서 인식하는 인증 기관(CA)을 참조하세요.

해석기 구성

이 단계에서는 http 데이터 원본을 getUser 쿼리에 연결합니다.

해석기를 설정하려면:

• 스키마 탭을 선택합니다.

• 오른쪽에 있는 Data types(데이터 형식) 창의 쿼리 형식에서 getUser 필드를 찾은 다음 연결을 선택합니다.

• Data source name(데이터 원본 이름)에서 HTTP를 선택합니다.

• Configure the request mapping template(요청 매핑 템플릿 구성)에 다음 코드를 붙여 넣습니다.

{
    "version": "2018-05-29",
    "method": "GET",
    "params": {
        "headers": {
            "Content-Type": "application/json"
        }
    },
    "resourcePath": $util.toJson("/v1/users/${ctx.args.id}")
}

• Configure the response mapping template(응답 매핑 템플릿 구성)에 다음 코드를 붙여 넣습니다.

## return the body
#if($ctx.result.statusCode == 200)
    ##if response is 200
    $ctx.result.body
#else
    ##if response is not 200, append the response to error block.
    $utils.appendError($ctx.result.body, "$ctx.result.statusCode")
#end

• 쿼리 탭을 선택한 후, 다음 쿼리를 실행합니다.

query GetUser{
    getUser(id:1){
        id
        username
    }
}

그러면 다음과 같은 응답이 반환됩니다.

{
    "data": {
        "getUser": {
            "id": "1",
            "username": "nadia"
        }
    }
}

• 스키마 탭을 선택합니다.

• 오른쪽에 있는 Data types(데이터 형식) 창의 변형에서 addUser 필드를 찾은 다음 연결을 선택합니다.

• Data source name(데이터 원본 이름)에서 HTTP를 선택합니다.

• Configure the request mapping template(요청 매핑 템플릿 구성)에 다음 코드를 붙여 넣습니다.

{
    "version": "2018-05-29",
    "method": "POST",
    "resourcePath": "/v1/users",
    "params":{
      "headers":{
        "Content-Type": "application/json",
      },
      "body": $util.toJson($ctx.args.userInput)
    }
}

• Configure the response mapping template(응답 매핑 템플릿 구성)에 다음 코드를 붙여 넣습니다.

## Raise a GraphQL field error in case of a datasource invocation error
#if($ctx.error)
    $util.error($ctx.error.message, $ctx.error.type)
#end
## if the response status code is not 200, then return an error. Else return the body **
#if($ctx.result.statusCode == 200)
    ## If response is 200, return the body.
    $ctx.result.body
#else
    ## If response is not 200, append the response to error block.
    $utils.appendError($ctx.result.body, "$ctx.result.statusCode")
#end

• 쿼리 탭을 선택한 후, 다음 쿼리를 실행합니다.

mutation addUser{
    addUser(userInput:{
        id:"2",
        username:"shaggy"
    }){
        id
        username
    }
}

그러면 다음과 같은 응답이 반환됩니다.

{
    "data": {
        "getUser": {
        "id": "2",
        "username": "shaggy"
        }
    }
}

AWS 서비스 간접 호출

HTTP 해석기를 사용하여 AWS 서비스에 대한 GraphQL API 인터페이스를 설정할 수 있습니다. AWS에 대한 HTTP 요청은 서명 버전 4 프로세스로 서명해야 AWS가 요청을 보낸 사람을 식별할 수 있습니다. AWS AppSync는 IAM 역할을 HTTP 데이터 소스와 연결할 때 사용자를 대신하여 서명을 계산합니다.

HTTP 해석기를 사용하여 AWS 서비스를 호출하기 위해 다음 두 개의 추가 구성 요소를 제공합니다.

• AWS 서비스 API를 호출할 권한이 있는 AWS IAM 역할

• 데이터 원본의 서명 구성

예를 들어 HTTP 해석기를 사용하여 ListGraphqlApis 작업을 호출하려면 먼저 다음 정책을 연결하여 AWS AppSync가 가정하는 IAM 역할을 생성합니다.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "appsync:ListGraphqlApis"
            ],
            "Effect": "Allow",
            "Resource": "*"
        }
    ]
}

다음에는 AWS AppSync에 대한 HTTP 데이터 소스를 생성합니다. 이 예에서는 미국 서부(오레곤) 리전에서 AWS AppSync를 호출합니다. 서명 리전과 서비스 이름이 포함된 http.json이라는 파일에서 다음 HTTP 구성을 설정합니다.

{
    "endpoint": "https://appsync.us-west-2.amazonaws.com/",
    "authorizationConfig": {
        "authorizationType": "AWS_IAM",
        "awsIamConfig": {
            "signingRegion": "us-west-2",
            "signingServiceName": "appsync"
        }
    }
}

그런 다음, AWS CLI를 사용하여 다음과 같이 연결된 역할이 있는 데이터 소스를 생성합니다.

aws appsync create-data-source --api-id <API-ID> \
                               --name AWSAppSync \
                               --type HTTP \
                               --http-config file:///http.json \
                               --service-role-arn <ROLE-ARN>

해석기를 스키마의 필드에 연결하는 경우 다음 요청 매핑 템플릿을 사용하여 AWS AppSync를 호출합니다.

{
    "version": "2018-05-29",
    "method": "GET",
    "resourcePath": "/v1/apis"
}

이 데이터 소스에 대해 GraphQL 쿼리를 실행하면 AWS AppSync는 제공한 역할을 사용하여 요청에 서명하고 서명을 요청에 포함시킵니다. 쿼리는 해당 AWS 리전에서 계정에 있는 AWS AppSync GraphQL API의 목록을 반환합니다.