에서 Amazon OpenSearch Service 해석기 사용 AWS AppSync - AWS AppSync
원클릭 설치새 OpenSearch 서비스 도메인 생성 OpenSearch 서비스용 데이터 소스 구성해석기 연결검색 수정 OpenSearch 서비스에 데이터 추가단일 문서 가져오기쿼리 및 변형 수행모범 사례

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

에서 Amazon OpenSearch Service 해석기 사용 AWS AppSync

참고

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

AWS AppSync 는 에 없는 경우 자신의 AWS 계정에 프로비저닝한 도메인에서 Amazon OpenSearch Service를 사용할 수 있도록 지원합니다VPC. 도메인을 프로비저닝한 후에는 도메인을 데이터 원본에 연결할 수 있으며, 이때 쿼리, 변형 및 구독 등 GraphQL 작업을 수행하도록 스키마의 해석기를 구성할 수 있습니다. 이 자습서에서는 몇 가지 일반적인 예제를 살펴봅니다.

자세한 내용은 에 대한 해석기 매핑 템플릿 참조 OpenSearch를 참조하세요.

원클릭 설치

Amazon OpenSearch Service가 구성된 AWS AppSync 에서 GraphQL 엔드포인트를 자동으로 설정하려면 다음 AWS CloudFormation 템플릿을 사용할 수 있습니다.

Blue button labeled "Launch Stack" with an arrow icon indicating an action to start.

AWS CloudFormation 배포가 완료되면 실행 중인 GraphQL 쿼리 및 돌연변이 로 바로 건너뛸 수 있습니다.

새 OpenSearch 서비스 도메인 생성

이 자습서를 시작하려면 기존 OpenSearch 서비스 도메인이 필요합니다. 아직 없는 경우 다음 샘플을 사용할 수 있습니다. OpenSearch 서비스 도메인을 생성하려면 최대 15분이 걸릴 수 있으며, 이 경우 서비스 도메인을 데이터 소스와 통합할 수 있습니다 AWS AppSync.

aws cloudformation create-stack --stack-name AppSyncOpenSearch \
--template-url https://s3.us-west-2.amazonaws.com/awsappsync/resources/elasticsearch/ESResolverCFTemplate.yaml \
--parameters ParameterKey=OSDomainName,ParameterValue=ddtestdomain ParameterKey=Tier,ParameterValue=development \
--capabilities CAPABILITY_NAMED_IAM

AWS 계정의 미국 서부 2(오레곤) 리전에서 다음 AWS CloudFormation 스택을 시작할 수 있습니다.

Blue button labeled "Launch Stack" with an arrow icon indicating an action to start.

OpenSearch 서비스용 데이터 소스 구성

OpenSearch 서비스 도메인이 생성된 후 AWS AppSync GraphQL로 이동하여 데이터 소스 탭을 API 선택합니다. 새로 만들기를 선택하고 'oss'와 같은 데이터 소스에 사용할 친숙한 이름을 입력합니다. 그런 다음 데이터 소스 유형 에 대해 Amazon OpenSearch 도메인을 선택하고 적절한 리전을 선택하면 OpenSearch 서비스 도메인이 나열됩니다. 선택한 후에는 새 역할을 생성하고 역할에 적합한 권한을 AWS AppSync 할당하거나 다음과 같은 인라인 정책이 있는 기존 역할을 선택할 수 있습니다.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Stmt1234234",
            "Effect": "Allow",
            "Action": [
                "es:ESHttpDelete",
                "es:ESHttpHead",
                "es:ESHttpGet",
                "es:ESHttpPost",
                "es:ESHttpPut"
            ],
            "Resource": [
                "arn:aws:es:REGION:ACCOUNTNUMBER:domain/democluster/*"
            ]
        }
    ]
}

또한 해당 역할에 AWS AppSync 대해 와 신뢰 관계를 설정해야 합니다.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "appsync.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

또한 OpenSearch 서비스 도메인에는 Amazon OpenSearch Service 콘솔을 통해 수정할 수 있는 자체 액세스 정책이 있습니다. OpenSearch 서비스 도메인에 대한 적절한 작업 및 리소스와 함께 다음과 유사한 정책을 추가해야 합니다. 보안 주체는 콘솔에서 생성하도록 허용하는 경우 콘솔에서 찾을 수 있는 AppSync 데이터 소스 역할입니다IAM.

{
    "Version": "2012-10-17",
    "Statement": [
        {
        "Effect": "Allow",
        "Principal": {
            "AWS": "arn:aws:iam::ACCOUNTNUMBER:role/service-role/APPSYNC_DATASOURCE_ROLE"
        },
        "Action": [
            "es:ESHttpDelete",
            "es:ESHttpHead",
            "es:ESHttpGet",
            "es:ESHttpPost",
            "es:ESHttpPut"
        ],
        "Resource": "arn:aws:es:REGION:ACCOUNTNUMBER:domain/DOMAIN_NAME/*"
        }
    ]
}

해석기 연결

이제 데이터 소스가 OpenSearch 서비스 도메인에 연결되었으므로 다음 예제와 같이 해석기를 사용하여 GraphQL 스키마에 연결할 수 있습니다.

 schema {
   query: Query
   mutation: Mutation
 }

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

 type Mutation {
   addPost(id: ID!, author: String, title: String, url: String, ups: Int, downs: Int, content: String): AWSJSON
 }

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

사용자 정의 Post 유형과 id 필드가 있습니다. 다음 예제에서는 이 유형을 OpenSearch 서비스 도메인에 배치하는 프로세스(자동화할 수 있음)가 있다고 가정합니다. 이 프로세스는 의 경로 루트에 매핑되며/post/_doc, 여기서 post는 인덱스입니다. 이 루트 경로에서 개별 문서 검색, /id/post*를 사용한 와일드카드 검색 또는 /post/_search 경로를 사용한 다중 문서 검색을 수행할 수 있습니다. 예를 들어, User라는 다른 유형이 있는 경우 user라는 새 인덱스로 문서를 색인한 다음 /user/_search의 경로로 검색을 수행할 수 있습니다.

AWS AppSync 콘솔의 스키마 편집기에서 searchPosts 쿼리를 포함하도록 이전 Posts 스키마를 수정합니다.

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

스키마를 저장합니다. 오른쪽에 있는 searchPosts에서 Attach resolver(해석기 연결)를 선택합니다. 작업 메뉴 에서 런타임 업데이트를 선택한 다음 Unit Resolver(VTL만 해당)를 선택합니다. 그런 다음 OpenSearch 서비스 데이터 소스를 선택합니다. request mapping template(요청 매핑 템플릿) 섹션에서 Query posts(게시물 쿼리)의 드롭다운을 선택하여 기본 템플릿을 가져옵니다. path를 /post/_search로 수정합니다. 이 템플릿은 다음과 같습니다.

{
    "version":"2017-02-28",
    "operation":"GET",
    "path":"/post/_search",
    "params":{
        "headers":{},
        "queryString":{},
        "body":{
            "from":0,
            "size":50
        }
    }
}

이렇게 하면 앞의 스키마에 post 필드에서 OpenSearch Service에서 인덱싱된 문서가 있다고 가정합니다. 데이터를 다르게 구조화하는 경우 그에 맞게 업데이트해야 합니다.

응답 매핑 템플릿 섹션에서 OpenSearch 서비스 쿼리에서 데이터 결과를 다시 가져와 GraphQL 로 변환하려면 적절한 _source 필터를 지정해야 합니다. 다음 템플릿을 사용합니다.

[
    #foreach($entry in $context.result.hits.hits)
    #if( $velocityCount > 1 ) , #end
    $utils.toJson($entry.get("_source"))
    #end
]

검색 수정

이전 요청 매핑 템플릿은 모든 레코드에 대해 단순 쿼리를 수행합니다. 특정 작성자별로 검색하려 한다고 가정하겠습니다. 또한, 작성자를 GraphQL 쿼리에 정의된 인수로 사용하려 한다고 가정하겠습니다. 콘솔의 AWS AppSync 스키마 편집기에서 allPostsByAuthor 쿼리를 추가합니다.

type Query {
  getPost(id: ID!): Post
  allPosts: [Post]
  allPostsByAuthor(author: String!): [Post]
  searchPosts: [Post]
}

이제 해석기 연결을 선택하고 OpenSearch 서비스 데이터 소스를 선택하지만 응답 매핑 템플릿 에서 다음 예제를 사용합니다.

{
    "version":"2017-02-28",
    "operation":"GET",
    "path":"/post/_search",
    "params":{
        "headers":{},
        "queryString":{},
        "body":{
            "from":0,
            "size":50,
            "query":{
                "match" :{
                    "author": $util.toJson($context.arguments.author)
                }
            }
        }
    }
}

body가 author 필드에 대한 쿼리 용어로 채워져서 클라이언트에서 인수로 전달됩니다. 또한 원할 경우 표준 텍스트 같은 미리 채워진 정보를 사용하거나 다른 유틸리티를 사용할 수도 있습니다.

이 해석기를 사용하려는 경우 이전 예와 동일한 정보를 Response Mapping Template(응답 매핑 템플릿)에 입력합니다.

OpenSearch 서비스에 데이터 추가

GraphQL 돌연변이로 인해 OpenSearch 서비스 도메인에 데이터를 추가할 수 있습니다. 이는 검색 및 다른 목적으로 사용할 때 유용한 메커니즘입니다. GraphQL 구독을 사용하여 데이터를 실시간으로 만들 수 있으므로 OpenSearch 서비스 도메인의 데이터에 대한 업데이트를 클라이언트에 알리는 메커니즘 역할을 합니다.

AWS AppSync 콘솔의 스키마 페이지로 돌아가서 addPost() 돌연변이에 대한 해석기 연결을 선택합니다. OpenSearch 서비스 데이터 소스를 다시 선택하고 Posts 스키마에 다음 응답 매핑 템플릿을 사용합니다.

{
    "version":"2017-02-28",
    "operation":"PUT",
    "path": $util.toJson("/post/_doc/$context.arguments.id"),
    "params":{
        "headers":{},
        "queryString":{},
        "body":{
            "id": $util.toJson($context.arguments.id),
            "author": $util.toJson($context.arguments.author),
            "ups": $util.toJson($context.arguments.ups),
            "downs": $util.toJson($context.arguments.downs),
            "url": $util.toJson($context.arguments.url),
            "content": $util.toJson($context.arguments.content),
            "title": $util.toJson($context.arguments.title)
        }
    }
}

전과 마찬가지로, 이 코드도 데이터의 구조화 방식을 보여주는 예입니다. 다양한 필드 이름 또는 인덱스가 있으면 해당되는 경우 path 및 body를 업데이트해야 합니다. 이 예제는 $context.arguments를 사용하여 GraphQL 변형 인수에서 템플릿을 채우는 방법도 보여줍니다.

계속 진행하기 전에 다음 응답 매핑 템플릿을 사용하여 뮤테이션 작업 결과 또는 오류 정보를 출력으로 반환합니다.

#if($context.error)
    $util.toJson($ctx.error)
#else
    $util.toJson($context.result)
#end

단일 문서 가져오기

마지막으로 스키마의 getPost(id:ID) 쿼리를 사용하여 개별 문서를 반환하려면 콘솔의 스키마 편집기에서 이 쿼리를 AWS AppSync 찾아 해석기 연결을 선택합니다. OpenSearch 서비스 데이터 소스를 다시 선택하고 다음 매핑 템플릿을 사용합니다.

{
    "version":"2017-02-28",
    "operation":"GET",
    "path": $util.toJson("post/_doc/$context.arguments.id"),
    "params":{
        "headers":{},
        "queryString":{},
        "body":{}
    }
}

위의 path에서 빈 본문과 함께 id 인수를 사용하므로 이 문은 단일 문서를 반환합니다. 하지만 지금은 목록이 아니라 단일 항목을 반환하려고 하므로 다음과 같은 응답 매핑 템플릿을 사용해야 합니다.

$utils.toJson($context.result.get("_source"))

쿼리 및 변형 수행

이제 OpenSearch 서비스 도메인에 대해 GraphQL 작업을 수행할 수 있습니다. AWS AppSync 콘솔의 쿼리 탭으로 이동하여 새 레코드를 추가합니다.

mutation addPost {
    addPost (
        id:"12345"
        author: "Fred"
        title: "My first book"
        content: "This will be fun to write!"
        url: "publisher website",
        ups: 100,
        downs:20 
       )
}

오른쪽에 뮤테이션 결과가 표시됩니다. 마찬가지로 이제 OpenSearch 서비스 도메인에 대해 searchPosts 쿼리를 실행할 수 있습니다.

query searchPosts {
    searchPosts {
        id
        title
        author
        content
    }
}

모범 사례

  • OpenSearch 서비스는 기본 데이터베이스가 아닌 데이터를 쿼리하기 위한 것이어야 합니다. GraphQL 해석기 결합 에 설명된 대로 Amazon DynamoDB와 함께 OpenSearch 서비스를 사용할 수 있습니다.

  • AWS AppSync 서비스 역할이 클러스터에 액세스하도록 허용해야만 도메인에 액세스할 수 있습니다.

  • 최저 비용 클러스터를 제공하는 간단한 개발부터 시작하여, 프로덕션으로 들어가면서 고가용성(HA)을 제공하는 대규모 클러스터로 이동할 수 있습니다.