병합된 API - AWS AppSync
병합된 API 및 페더레이션병합된 API 충돌 해결스키마 구성권한 부여 모드 구성실행 역할 구성AWS RAM을 사용하여 교차 계정 병합 API 구성병합병합된 API에 대한 추가 지원병합된 API 제한 사항병합된 API 생성

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

병합된 API

조직 내에서 GraphQL의 사용이 확대됨에 따라 API 사용 편의성과 API 개발 속도 간의 상충 지점이 발생할 수 있습니다. 한편으로 조직은 AWS AppSync와 GraphQL을 채택하여 개발자에게 단일 네트워크 호출로 하나 이상의 데이터 도메인에서 데이터에 안전하게 액세스하고 데이터를 조작 및 결합하는 데 사용할 수 있는 유연한 API를 제공함으로써 애플리케이션 개발을 단순화합니다. 반면, 단일 GraphQL API 엔드포인트로 결합된 여러 데이터 도메인을 담당하는 조직 내 팀은 개발 속도를 높이기 위해 서로 독립적으로 API 업데이트를 생성, 관리 및 배포할 수 있는 기능을 원할 수 있습니다.

이러한 긴장을 해소하기 위해 AWS AppSync 병합 API 기능을 사용하면 서로 다른 데이터 도메인의 팀이 독립적으로 AWS AppSync API(예: GraphQL 스키마, 해석기, 데이터 원본, 함수)를 만들고 배포한 다음 이를 하나의 병합된 API로 결합할 수 있습니다. 이를 통해 조직은 사용이 간편한 교차 도메인 API를 유지 관리하고 해당 API에 기여하는 여러 팀이 빠르고 독립적으로 API 업데이트를 수행할 수 있습니다.

조직은 병합된 API를 사용하여 여러 독립 소스 AWS AppSync API의 리소스를 하나의 AWS AppSync 병합 API 엔드포인트로 가져올 수 있습니다. 이를 위해 AWS AppSync를 사용하면 소스 AWS AppSync 소스 API 목록을 만든 다음 스키마, 형식, 데이터 원본, 해석기, 함수 등 소스 API와 관련된 모든 메타데이터를 새로운 AWS AppSync 병합 API에 병합할 수 있습니다.

병합 중에 소스 API 데이터 콘텐츠의 불일치로 인해 병합 충돌이 발생할 수 있습니다(예: 여러 스키마 결합 시 형식 이름 충돌). 소스 API의 정의가 충돌하지 않는 간단한 사용 사례의 경우 소스 API 스키마를 수정할 필요가 없습니다. 이렇게 생성된 병합된 API는 단순히 원래 소스 AWS AppSync API에서 모든 형식, 해석기, 데이터원본스 및 기능을 가져옵니다. 충돌이 발생하는 복잡한 사용 사례의 경우 사용자/팀은 다양한 방법을 통해 충돌을 해결해야 합니다. AWS AppSync에서는 사용자에게 병합 충돌을 줄일 수 있는 몇 가지 도구와 예를 제공합니다.

AWS AppSync에서 구성된 후속 병합은 소스 API의 변경 사항을 연관된 병합 API에 전파합니다.

병합된 API 및 페더레이션

GraphQL 커뮤니티에는 GraphQL 스키마를 결합하고 공유 그래프를 통해 팀 협업을 가능하게 하는 다양한 솔루션과 패턴이 있습니다. AWS AppSync 병합된 API는 소스 API를 별도의 병합된 API로 결합하는 빌드 타임 방식을 스키마 구성에 채택합니다. 또 다른 방법으로는 런타임 라우터를 여러 소스 API 또는 하위 그래프에 계층화하는 방식이 있습니다. 이 방식에서는 라우터가 요청을 수신하고, 메타데이터로 유지 관리하는 결합된 스키마를 참조하고, 요청 계획을 구성한 다음, 기본 하위 그래프/서버에 요청 요소를 배포합니다. 다음 표에서는 AWS AppSync 병합 API 빌드 타임 방식을 GraphQL 스키마 구성에 대한 라우터 기반 런타임 방식과 비교합니다.

Feature AppSync Merged API Router-based solutions
Sub-graphs managed independently Yes Yes
Sub-graphs addressable independently Yes Yes
Automated schema composition Yes Yes
Automated conflict detection Yes Yes
Conflict resolution via schema directives Yes Yes
Supported sub-graph servers AWS AppSync* Varies
Network complexity Single, merged API means no extra network hops. Multi-layer architecture requires query planning and delegation, sub-query parsing and serialization/deserialization, and reference resolvers in sub-graphs to perform joins.
Observability support Built-in monitoring, logging, and tracing. A single, Merged API server means simplified debugging. Build-your-own observability across router and all associated sub-graph servers. Complex debugging across distributed system.
Authorization support Built in support for multiple authorization modes. Build-your-own authorization rules.
Cross account security Built-in support for cross-AWS cloud account associations. Build-your-own security model.
Subscriptions support Yes No

* AWS AppSync 병합 API는 AWS AppSync 소스 API와만 연결할 수 있습니다. AWS AppSync 하위 그래프 및 AWS AppSync가 아닌 하위 그래프에 스키마 구성 지원이 필요한 경우 하나 이상의 AWS AppSync GraphQL 또는 병합된 API를 라우터 기반 솔루션에 연결할 수 있습니다. 예를 들어 Apollo Federation v2에서 라우터 기반 아키텍처를 사용하여 AWS AppSync API를 하위 그래프로 추가하는 방법에 대해서는 블로그 AWS AppSync와 Apollo GraphQL 페더레이션을 참조하세요.

병합된 API 충돌 해결

AWS AppSync에서는 병합 충돌 발생 시 문제를 해결하는 데 도움이 되는 몇 가지 도구와 예를 제공합니다.

병합된 API 스키마 지시문

AWS AppSync에서는 소스 API 간의 충돌을 줄이거나 해결하는 데 사용할 수 있는 몇 가지 GraphQL 지시문을 도입했습니다.

  • @canonical: 이 지시문은 이름과 데이터가 비슷한 형식/필드의 우선 순위를 설정합니다. 둘 이상의 소스 API에 동일한 GraphQL 형식 또는 필드가 있는 경우 API 중 하나가 형식 또는 필드에 canonical로 주석을 달아 병합 중에 우선 순위가 지정되도록 할 수 있습니다. 다른 소스 API에서 이 지시문으로 주석을 달지 않은 충돌하는 형식/필드는 병합될 때 무시됩니다.

  • @hidden: 이 지시문은 특정 형식/필드를 캡슐화하여 병합 프로세스에서 제거합니다. 팀에서 내부 클라이언트만 특정 형식의 데이터에 액세스할 수 있도록 소스 API에서 특정 형식이나 작업을 제거하거나 숨기고 싶을 수 있습니다. 이 지시문이 연결되면 형식이나 필드가 병합된 API에 병합되지 않습니다.

  • @renamed: 이 지시문은 형식/필드의 이름을 변경하여 이름 충돌을 줄입니다. 서로 다른 API에 동일한 형식 또는 필드 이름이 사용되는 경우가 있습니다. 그러나 이들 모두 병합된 스키마에서 사용할 수 있어야 합니다. 모든 항목을 병합된 API에 포함하는 간단한 방법은 필드 이름을 비슷하지만 다른 이름으로 바꾸는 것입니다.

제공되는 유틸리티 스키마 지시문을 표시하려면 다음 예를 고려해 보세요.

이 예에서는 두 개의 소스 API를 병합한다고 가정합니다. 게시물(예: 댓글 섹션 또는 소셜 미디어 게시물)을 생성하고 검색하는 두 개의 스키마가 제공됩니다. 형식과 필드가 매우 유사하다고 가정하면 병합 작업 중에 충돌이 발생할 가능성이 높습니다. 아래 스니펫은 각 스키마의 형식과 필드를 보여 줍니다.

Source1.graphql이라는 첫 번째 파일은 사용자가 putPost 변형을 사용하여 Posts를 생성할 수 있게 하는 GraphQL 스키마입니다. 각 Post에는 제목과 ID가 포함되어 있습니다. ID는 User 또는 게시자의 정보(이메일 및 주소)와 Message 또는 페이로드(콘텐츠)를 참조하는 데 사용됩니다. User 형식에는 @canonical 태그로 주석이 달립니다.

# This snippet represents a file called Source1.graphql

type Mutation {
    putPost(id: ID!, title: String!): Post
}

type Post {
    id: ID!
    title: String!
}

type Message {
   id: ID!
   content: String
}

type User @canonical {
   id: ID!
   email: String!
   address: String!
}

type Query {
    singlePost(id: ID!): Post
    getMessage(id: ID!): Message
}

Source2.graphql이라는 두 번째 파일은 Source1.graphql과 매우 유사한 작업을 수행하는 GraphQL 스키마입니다. 하지만 각 형식의 필드는 서로 다르다는 점에 유의하세요. 이 두 스키마를 병합하면 이러한 차이로 인해 병합 충돌이 발생합니다.

또한 Source2.graphql에는 이러한 충돌을 줄이기 위한 몇 가지 지시문이 포함되어 있다는 점도 참고하세요. Post 형식에는 병합 작업 중에 자체적으로 난독화할 수 있도록 @hidden 태그가 주석으로 달려 있습니다. Message 형식에는 다른 Message 형식과 이름이 충돌하는 경우 형식 이름을 ChatMessage로 수정할 수 있도록 @renamed 태그가 주석으로 달려 있습니다.

# This snippet represents a file called Source2.graphql

type Post @hidden  {
    id: ID!
    title: String!
    internalSecret: String!
}

type Message @renamed(to: "ChatMessage") {
   id: ID!
   chatId: ID!
   from: User!
   to: User!
}

# Stub user so that we can link the canonical definition from Source1
type User {
   id: ID!
}

type Query {
    getPost(id: ID!): Post
    getMessage(id: ID!): Message @renamed(to: "getChatMessage")
}

병합이 발생하면 다음과 같이 MergedSchema.graphql 파일이 생성됩니다.

# This snippet represents a file called MergedSchema.graphql

type Mutation {
    putPost(id: ID!, title: String!): Post
}

# Post from Source2 was hidden so only uses the Source1 definition. 
type Post {
    id: ID!
    title: String!
}

# Renamed from Message to resolve the conflict
type ChatMessage {
   id: ID!
   chatId: ID!
   from: User!
   to: User!
}

type Message {
   id: ID!
   content: String
}

# Canonical definition from Source1
type User {
   id: ID!
   email: String!
   address: String!
}

type Query {
    singlePost(id: ID!): Post
    getMessage(id: ID!): Message
    
    # Renamed from getMessage
    getChatMessage(id: ID!): ChatMessage
}

병합에서 몇 가지 사항이 발생했습니다.

  • @canonical 주석으로 인해 Source1.graphql의 User 형식이 Source2.graphql의 User 형식보다 우선 순위로 지정되었습니다.

  • Source1.graphql의 Message 형식이 병합에 포함되었습니다. 하지만 Source2.graphql의 Message에 이름 충돌이 발생했습니다. @renamed 주석으로 인해 병합에 함께 포함되었지만 대체 이름인 ChatMessage가 사용되었습니다.

  • Source1.graphql의 Post 형식은 포함되었지만, Source2.graphql의 Post 형식은 포함되지 않았습니다. 일반적으로는 이 형식에서 충돌이 발생하지만 Source2.graphql의 Post 형식에 @hidden 주석이 있으므로 해당 데이터가 난독화되어 병합에 포함되지 않았습니다. 그 결과 충돌은 발생하지 않았습니다.

  • 두 파일의 내용을 모두 포함하도록 Query 형식이 업데이트되었습니다. 그러나 지시문으로 인해 GetMessage 쿼리 하나의 이름이 GetChatMessage로 변경되었습니다. 이를 통해 이름이 같은 두 쿼리 간의 이름 충돌이 해결되었습니다.

충돌하는 유형에 지시문이 추가되지 않는 경우도 있습니다. 여기서, 병합된 형식에는 해당 형식의 모든 소스 정의에 있는 모든 필드의 조합이 포함됩니다. 예를 들어 다음 예제를 고려해 보십시오.

Source1.graphql이라는 이 스키마를 사용하면 Posts를 생성하고 검색할 수 있습니다. 구성은 이전 예제와 비슷하지만 정보가 더 적습니다.

# This snippet represents a file called Source1.graphql

type Mutation {
    putPost(id: ID!, title: String!): Post
}

type Post  {
    id: ID!
    title: String!
}

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

Source2.graphql이라는 이 스키마를 사용하면 Reviews(예: 영화 평점 또는 음식점 리뷰)를 생성하고 검색할 수 있습니다. Reviews는 ID 값이 동일한 Post와 연결됩니다. 여기에는 전체 리뷰 게시물의 제목, 게시물 ID, 페이로드 메시지가 모두 포함됩니다.

병합하면 두 Post 형식 간에 충돌이 발생합니다. 이 문제를 해결할 주석이 없으므로 기본 동작은 충돌하는 형식에 대해 조합 작업을 수행하는 것입니다.

# This snippet represents a file called Source2.graphql

type Mutation {
    putReview(id: ID!, postId: ID!, comment: String!): Review
}

type Post  {
    id: ID!
    reviews: [Review]
}

type Review {
   id: ID!
   postId: ID!
   comment: String!
}

type Query {
    getReview(id: ID!): Review
}

병합이 발생하면 다음과 같이 MergedSchema.graphql 파일이 생성됩니다.

# This snippet represents a file called MergedSchema.graphql

type Mutation {
    putReview(id: ID!, postId: ID!, comment: String!): Review
    putPost(id: ID!, title: String!): Post
}

type Post  {
    id: ID!
    title: String!
    reviews: [Review]
}

type Review {
   id: ID!
   postId: ID!
   comment: String!
}

type Query {
    getPost(id: ID!): Post
    getReview(id: ID!): Review
}

병합에서 몇 가지 사항이 발생했습니다.

  • Mutation 형식은 충돌이 없었고 병합되었습니다.

  • Post 형식 필드는 조합 작업을 통해 결합되었습니다. 이 둘의 조합으로 어떻게 단일 id, title 및 단일 reviews가 생성했는지를 주목해 보세요.

  • Review 형식은 충돌이 없었고 병합되었습니다.

  • Query 형식은 충돌이 없었고 병합되었습니다.

공유 형식의 해석기 관리

위 예제에서 Source1.graphql이 PostDatasource라는 DynamoDB 데이터 원본을 사용하는 Query.getPost에 유닛 해석기를 구성한 경우를 고려해 보세요. 이 해석기는 Post 형식의 id 및 title을 반환합니다. 이제 Source2.graphql에서 두 함수를 실행하는 Post.reviews에 파이프라인 해석기를 구성했다고 가정해 보겠습니다. Function1에는 사용자 지정 권한 부여 검사를 수행할 수 있는 None 데이터 원본이 연결되어 있습니다. Function2에는 reviews 테이블을 쿼리하기 위해 DynamoDB 데이터 원본이 연결되어 있습니다.

query GetPostQuery {
    getPost(id: "1") {
        id,
        title,
        reviews
    }
}

클라이언트가 병합된 API 엔드포인트에 대해 위 쿼리를 실행하면 AWS AppSync 서비스는 먼저 Source1의 Query.getPost에 대해 유닛 해석기를 실행하여 PostDatasource를 호출하고 DynamoDB에서 데이터를 반환합니다. 그런 다음 Function1이 사용자 지정 권한 부여 로직을 수행하고 Function2가 $context.source에서 발견된 id에 제공된 리뷰를 반환하는 Post.reviews 파이프라인 해석기를 실행합니다. 서비스는 요청을 단일 GraphQL 실행으로 처리하며 이 단순한 요청에는 단일 요청 토큰만 필요합니다.

공유 형식의 해석기 충돌 관리

Source2의 필드 해석기 외에도 한 번에 여러 필드를 제공하기 위해 Query.getPost에 해석기도 구현하는 다음과 같은 경우를 생각해 보세요. Source1.graphql은 다음과 같을 수 있습니다.

# This snippet represents a file called Source1.graphql

type Post  {
    id: ID!
    title: String!
    date: AWSDateTime!
}

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

Source2.graphql은 다음과 같을 수 있습니다.

# This snippet represents a file called Source2.graphql

type Post  {
  id: ID!
  content: String!
  contentHash: String! 
  author: String! 
}

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

이 두 스키마를 병합하려고 하면 병합 오류가 발생합니다. AWS AppSync 병합된 API는 여러 소스 해석기를 동일한 필드에 연결할 수 없기 때문입니다. 이 충돌을 해결하려면 Source2.graphql이 Post 형식에서 소유한 필드를 정의하는 별도의 형식을 추가해야 하는 필드 해석기 패턴을 구현할 수 있습니다. 다음 예제에서는 PostInfo라는 형식을 추가하는데, 여기에는 Source2.graphql에서 해석할 내용 및 작성자 필드가 포함되어 있습니다. Source1.graphql은 Query.getPost에 연결된 해석기를 구현하고, Source2.graphql은 이제 Post.postInfo에 해석기를 연결하여 모든 데이터가 성공적으로 검색될 수 있도록 합니다.

type Post  {
  id: ID!
  postInfo: PostInfo
}

type PostInfo {
   content: String!
   contentHash: String!
   author: String!
}

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

이러한 충돌을 해결하려면 소스 API 스키마를 다시 작성하고 잠재적으로 클라이언트도 쿼리를 변경해야 하지만, 이 접근 방식의 장점은 병합된 해석기의 소유권이 소스 팀 간에 명확하게 유지된다는 것입니다.

스키마 구성

두 당사자는 병합된 API를 생성하기 위한 스키마 구성을 담당합니다.

  • 병합된 API 소유자 - 병합된 API 소유자는 병합된 API의 권한 부여 로직과 고급 설정(예: 로깅, 추적, 캐싱, WAF 지원)을 구성해야 합니다.

  • 관련 소스 API 소유자 - 관련 API 소유자는 병합된 API를 구성하는 스키마, 해석기, 데이터 원본을 구성해야 합니다.

병합된 API의 스키마는 관련 소스 API의 스키마에서 생성되므로 읽기 전용입니다. 즉, 스키마 변경은 소스 API에서 시작해야 합니다. AWS AppSync 콘솔에서 스키마 창 위의 드롭다운 목록을 사용하여 병합된 API에 포함된 소스 API의 병합된 스키마와 개별 스키마 사이를 전환할 수 있습니다.

권한 부여 모드 구성

여러 권한 부여 모드를 사용하여 병합된 API를 보호할 수 있습니다. AWS AppSync의 권한 부여 모드에 대해 자세히 알아보려면 권한 부여 및 인증을 참조하세요.

병합된 API와 함께 사용할 수 있는 권한 부여 모드는 다음과 같습니다.

  • API 키: 가장 간단한 권한 부여 전략입니다. 모든 요청에는 x-api-key 요청 헤더 아래에 API 키가 포함되어야 합니다. 만료된 API 키는 만료일 이후 60일 동안 보관됩니다.

  • AWS Identity and Access Management(IAM): AWS IAM 권한 부여 전략은 sigv4로 서명된 모든 요청을 승인합니다.

  • Amazon Cognito 사용자 풀: Amazon Cognito 사용자 풀을 통해 사용자에게 권한을 부여하여 보다 세밀하게 제어할 수 있도록 합니다.

  • AWS Lambda Authorizers: 사용자 지정 로직을 사용하여 AWS AppSync API에 대한 액세스를 인증하고 권한을 부여할 수 있는 서버리스 함수입니다.

  • OpenID Connect: 이 권한 부여 유형은 OIDC 호환 서비스에서 제공하는 OpenID Connect(OIDC) 토큰을 강제로 적용합니다. 애플리케이션에서는 OIDC 공급자가 액세스 제어를 위해 정의한 사용자 및 권한을 활용합니다.

병합된 API의 권한 부여 모드는 병합된 API 소유자가 구성합니다. 병합 작업 시 병합된 API는 소스 API에 구성된 기본 권한 부여 모드를 자체 기본 권한 부여 모드 또는 보조 권한 부여 모드로 포함해야 합니다. 그렇지 않으면 호환되지 않고 충돌이 발생하여 병합 작업이 실패합니다. 소스 API에서 다중 인증 지시문을 사용하는 경우 병합 프로세스에서 이러한 지시문을 통합 엔드포인트에 자동으로 병합할 수 있습니다. 소스 API의 기본 권한 부여 모드가 병합된 API의 기본 권한 부여 모드와 일치하지 않는 경우 소스 API의 형식에 대한 권한 부여 모드가 일관되도록 하기 위해 이러한 인증 지시문을 자동으로 추가합니다.

실행 역할 구성

병합된 API를 생성할 때는 서비스 역할을 정의해야 합니다. AWS 서비스 역할은 AWS 서비스가 사용자를 대신하여 작업을 수행하는 데 사용되는 AWS Identity and Access Management(IAM) 역할입니다.

이러한 맥락에서 병합된 API는 소스 API에 구성된 데이터 원본의 데이터에 액세스하는 해석기를 실행해야 합니다. 이를 위한 필수 서비스 역할은 mergedApiExecutionRole이며, appsync:SourceGraphQL IAM 권한을 통해 병합된 API에 포함된 소스 API에서 요청을 실행할 수 있는 명시적 액세스 권한이 있어야 합니다. GraphQL 요청을 실행하는 동안 AWS AppSync 서비스는 이 서비스 역할을 맡고 appsync:SourceGraphQL 작업을 수행할 역할을 승인합니다.

AWS AppSync에서는 IAM 권한 부여 모드가 IAM API에 작동하는 방식과 같이 요청 내의 특정 최상위 필드에 대해 이 권한을 허용하거나 거부할 수 있습니다. 최상위 수준이 아닌 필드의 경우 AWS AppSync에서는 소스 API ARN 자체에 대한 권한을 정의하도록 요구합니다. 병합된 API의 최상위 수준이 아닌 특정 필드에 대한 액세스를 제한하려면 Lambda 내에서 사용자 지정 로직을 구현하거나 @hidden 지시문을 사용하여 병합된 API에서 소스 API 필드를 숨기는 것이 좋습니다. 역할이 소스 API 내에서 모든 데이터 작업을 수행하도록 허용하려면 아래 정책을 추가할 수 있습니다. 첫 번째 리소스 항목은 모든 최상위 필드에 대한 액세스를 허용하고 두 번째 항목은 소스 API 리소스 자체에서 권한을 부여하는 하위 해석기를 포함합니다.

{
    "Version": "2012-10-17",
    "Statement": [{
        "Effect": "Allow", 
        "Action": [ "appsync:SourceGraphQL"], 
        "Resource": [ 
            "arn:aws:appsync:us-west-2:123456789012:apis/YourSourceGraphQLApiId/*", 
            "arn:aws:appsync:us-west-2:123456789012:apis/YourSourceGraphQLApiId"] 
    }] 
}

특정 최상위 필드로만 액세스를 제한하려면 다음과 같은 정책을 사용할 수 있습니다.

{
    "Version": "2012-10-17",
    "Statement": [{
        "Effect": "Allow", 
        "Action": [ "appsync:SourceGraphQL"], 
        "Resource": [ 
            "arn:aws:appsync:us-west-2:123456789012:apis/YourSourceGraphQLApiId/types/Query/fields/<Field-1>",
            "arn:aws:appsync:us-west-2:123456789012:apis/YourSourceGraphQLApiId"] 
    }] 
}

또한 AWS AppSync 콘솔 API 생성 마법사를 사용하여 서비스 역할을 생성해 병합된 API가 병합된 API와 동일한 계정에 있는 소스 API에 구성된 리소스에 액세스할 수 있도록 허용할 수도 있습니다. 소스 API가 병합된 API와 동일한 계정에 있지 않은 경우 먼저 AWS Resource Access Manager(AWS RAM)를 사용하여 리소스를 공유해야 합니다.

AWS RAM을 사용하여 교차 계정 병합 API 구성

병합된 API를 생성할 때 선택적으로 AWS Resource Access Manager(AWS RAM)를 통해 공유된 다른 계정의 소스 API를 연결할 수 있습니다. AWS RAM은 AWS 계정 간, 조직 또는 조직 단위(OU) 내, IAM 역할 및 사용자와 리소스를 안전하게 공유하는 데 도움이 됩니다.

AWS AppSync는 단일 병합 API에서 여러 계정의 소스 API를 구성하고 액세스할 수 있도록 하기 위해 AWS RAM과 통합됩니다. AWS RAM을 사용하면 리소스 공유를 생성하거나 각 리소스에 대해 공유될 리소스 및 권한 집합의 컨테이너를 생성할 수 있습니다. AWS RAM에서 리소스 공유에 AWS AppSync API를 추가할 수 있습니다. 리소스 공유 내에서 AWS AppSync는 RAM의 AWS AppSync API와 연결할 수 있는 세 가지 권한 집합을 제공합니다.

  1. AWSRAMPermissionAppSyncSourceApiOperationAccess: 다른 권한이 지정되지 않은 경우 AWS RAM에 AWS AppSync API를 공유할 때 추가되는 기본 권한 집합입니다. 이 권한 집합은 병합된 API 소유자와 소스 AWS AppSync API를 공유하는 데 사용됩니다. 이 권한 집합에는 소스 API의 appsync:AssociateMergedGraphqlApi에 대한 권한과 런타임 시 소스 API 리소스에 액세스하는 데 필요한 appsync:SourceGraphQL 권한이 포함됩니다.

  2. AWSRAMPermissionAppSyncMergedApiOperationAccess: 이 권한 집합은 소스 API 소유자와 병합된 API를 공유할 때 구성해야 합니다. 이 권한 집합은 대상 보안 주체가 소유한 모든 소스 API를 병합된 API에 연결하고 병합된 API의 소스 API 연결을 읽고 업데이트하는 기능을 포함하여 병합된 API를 구성할 수 있는 기능을 소스 API에 제공합니다.

  3. AWSRAMPermissionAppSyncAllowSourceGraphQLAccess: 이 권한 집합은 AWS AppSync API에서 appsync:SourceGraphQL 권한이 사용될 수 있도록 합니다. 병합된 API 소유자와 소스 API를 공유하는 데 사용되도록 의도된 권한 집합입니다. 소스 API 작업 액세스를 위한 기본 권한 집합과 달리 이 권한 집합에는 런타임 권한 appsync:SourceGraphQL만 포함됩니다. 사용자가 병합된 API 작업 액세스를 소스 API 소유자와 공유하기로 선택한 경우, 병합된 API 엔드포인트를 통해 런타임 액세스 권한을 가지려면 소스 API의 이 권한을 병합된 API 소유자에게 공유해야 합니다.

AWS AppSync에서는 고객 관리 권한도 지원합니다. 제공된 AWS 관리형 권한 중 하나가 작동하지 않는 경우 고객 관리형 권한을 직접 생성할 수 있습니다. 고객 관리형 권한은 AWS RAM을 사용하여 공유되는 리소스가 어떤 조건에서 어떤 작업을 수행할 수 있는지 정확하게 지정하여 작성하고 유지 관리하는 관리형 권한입니다. AWS AppSync를 사용하면 권한을 직접 생성할 때 다음 작업 중에서 선택할 수 있습니다.

  1. appsync:AssociateSourceGraphqlApi

  2. appsync:AssociateMergedGraphqlApi

  3. appsync:GetSourceApiAssociation

  4. appsync:UpdateSourceApiAssociation

  5. appsync:StartSchemaMerge

  6. appsync:ListTypesByAssociation

  7. appsync:SourceGraphQL

AWS RAM에서 소스 API 또는 병합된 API를 적절하게 공유하고 필요한 경우 리소스 공유 초대를 수락했다면 병합된 API에서 소스 API 연결을 생성하거나 업데이트할 때 AWS AppSync 콘솔에 표시됩니다. AWS AppSync가 제공하는 ListGraphqlApis 작업을 호출하고 OTHER_ACCOUNTS 소유자 필터를 사용하여 설정된 권한에 관계없이 AWS RAM을 사용하여 공유된 모든 AWS AppSync API를 계정에 나열할 수도 있습니다.

참고

AWS RAM을 통해 공유하려면 AWS RAM의 호출자에게 공유 중인 API에서 appsync:PutResourcePolicy 작업을 수행할 권한이 있어야 합니다.

병합

병합 관리

병합된 API는 통합된 AWS AppSync 엔드포인트에서 팀 협업을 지원하는 것이 목적입니다. 팀은 백엔드에서 격리된 자체 소스 GraphQL API를 독립적으로 발전시킬 수 있으며, AWS AppSync 서비스는 단일 병합 API 엔드포인트로의 리소스 통합을 관리하여 협업의 어려움을 줄이고 개발 리드 타임을 줄일 수 있습니다.

자동 병합

소스 API를 변경한 후 AWS AppSync 병합 API에 연결된 소스 API를 병합된 API에 자동으로 병합(자동 병합)하도록 구성할 수 있습니다. 이렇게 하면 소스 API의 변경 사항이 백그라운드에서 병합된 API 엔드포인트로 항상 전달됩니다. 소스 API 스키마의 모든 변경 사항은 병합된 API의 기존 정의와 병합 충돌을 일으키지 않는 한 병합된 API에서 업데이트됩니다. 소스 API의 업데이트가 해석기, 데이터 원본 또는 함수를 업데이트하는 경우 가져온 리소스도 업데이트됩니다. 자동으로 해결(자동 해결)할 수 없는 새로운 충돌이 발생하면 병합 작업 중에 지원되지 않는 충돌로 인해 병합된 API 스키마 업데이트가 거부됩니다. 콘솔에서 상태가 MERGE_FAILED인 각 소스 API 연결에 대한 오류 메시지를 확인할 수 있습니다. 다음과 같이 AWS SDK를 사용하거나 AWS CLI를 사용하여 지정된 소스 API 연결에 대한 GetSourceApiAssociation 작업을 호출하여 오류 메시지를 검사할 수도 있습니다.

aws appsync get-source-api-association --merged-api-identifier <Merged API ARN> --association-id <SourceApiAssociation id>

그러면 다음 형식의 결과가 생성됩니다.

{
    "sourceApiAssociation": {
        "associationId": "<association id>",
        "associationArn": "<association arn>",
        "sourceApiId": "<source api id>",
        "sourceApiArn": "<source api arn>",
        "mergedApiArn": "<merged api arn>",
        "mergedApiId": "<merged api id>",
        "sourceApiAssociationConfig": {
            "mergeType": "MANUAL_MERGE"
        },
        "sourceApiAssociationStatus": "MERGE_FAILED",
        "sourceApiAssociationStatusDetail": "Unable to resolve conflict on object with name title: Merging is not supported for fields with different types."
    }
}

수동 병합

소스 API의 기본 설정은 수동 병합입니다. 병합된 API가 마지막으로 업데이트된 이후 소스 API에서 발생한 변경 사항을 병합하기 위해 소스 API 소유자는 AWS AppSync 콘솔에서 또는 AWS SDK 및 AWS CLI에서 사용할 수 있는 StartSchemaMerge 작업을 통해 수동 병합을 간접적으로 호출할 수 있습니다.

병합된 API에 대한 추가 지원

구독 구성

GraphQL 스키마 구성에 대한 라우터 기반 접근 방식과 달리 AWS AppSync 병합 API는 GraphQL 구독에 대한 기본 지원을 제공합니다. 관련 소스 API에 정의된 모든 구독 작업은 수정 없이 병합된 API에 자동으로 병합되어 작동합니다. AWS AppSync에서 서버리스 WebSocket 연결을 통한 구독을 지원하는 방법에 대해 자세히 알아보려면 실시간 데이터를 참조하세요.

관측성 구성

AWS AppSync 병합 API는 Amazon CloudWatch를 통해 내장된 로깅, 모니터링 및 메트릭을 제공합니다. 또한 AWS AppSync는 AWS X-Ray를 통한 추적을 위한 기본 지원을 제공합니다.

사용자 지정 도메인 구성

AWS AppSync 병합 API는 병합된 API의 GraphQL 및 실시간 엔드포인트와 함께 사용자 지정 도메인을 사용하기 위한 기본 지원을 제공합니다.

캐싱 구성

AWS AppSync 병합된 API는 요청 수준 또는 해석기 수준 응답을 선택적으로 캐싱하고 응답 압축을 위한 기본 지원을 제공합니다. 자세히 알아보려면 캐싱 및 압축을 참조하세요.

프라이빗 API 구성

AWS AppSync 병합된 API는 병합된 API의 GraphQL 및 실시간 엔드포인트에 대한 액세스를 구성 가능한 VPC 엔드포인트에서 발생하는 트래픽으로 제한하는 프라이빗 API에 대한 기본 지원을 제공합니다.

방화벽 규칙 구성

AWS AppSync 병합된 API는 AWS WAF에 대한 기본 지원을 제공하며, 이를 통해 웹 애플리케이션 방화벽 규칙을 정의하여 API를 보호할 수 있습니다.

감사 로그 구성

AWS AppSync 병합된 API는 감사 로그를 구성하고 관리할 수 있는 AWS CloudTrail에 대한 기본 지원을 제공합니다.

병합된 API 제한 사항

병합된 API를 개발하기 전에 다음 규칙을 고려해야 합니다.

  1. 병합된 API는 다른 병합된 API의 소스 API가 될 수 없습니다.

  2. 소스 API는 둘 이상의 병합된 API와 연결할 수 없습니다.

  3. 병합된 API 스키마 문서의 기본 크기 제한은 10MB입니다.

  4. 병합된 API와 연결할 수 있는 소스 API의 수는 기본적으로 10개입니다. 그러나 병합된 API에서 10개 이상의 소스 API가 필요하다면 제한 증가를 요청할 수 있습니다.

병합된 API 생성

콘솔에서 병합된 API를 만드는 방법

  1. AWS Management Console 에 로그인한 다음 AWS AppSync 콘솔을 엽니다.

    1. 대시보드에서 API 생성을 선택합니다.

  2. 병합된 API를 선택한 후 다음을 선택합니다.

  3. API 세부 정보 지정 페이지에서 다음 정보를 입력합니다.

    1. API 세부 정보에서 다음 정보를 입력합니다.

      1. 병합된 API의 API 이름을 지정합니다. 이 필드에서 GraphQL API에 레이블을 지정하여 다른 GraphQL API와 쉽게 구분할 수 있습니다.

      2. 연락처 세부 정보를 지정합니다. 이 필드는 선택 사항이며 GraphQL API에 이름 또는 그룹을 연결합니다. 이 필드는 다른 리소스에 연결되거나 다른 리소스에 의해 생성되지 않으며 API 이름 필드와 매우 유사하게 작동합니다.

    2. 서비스 역할에서 병합된 API에 IAM 실행 역할을 연결해야 AWS AppSync에서 런타임 시 리소스를 안전하게 가져오고 사용할 수 있습니다. 새 서비스 역할 생성 및 사용을 선택하여 AWS AppSync에서 사용할 정책과 리소스를 지정할 수 있습니다. 기존 서비스 역할 사용을 선택한 다음 드롭다운 목록에서 역할을 선택하여 기존 IAM 역할을 가져올 수도 있습니다.

    3. 프라이빗 API 구성에서 프라이빗 API 기능을 활성화할 수 있습니다. 단, 병합된 API를 생성한 후에는 이 선택을 변경할 수 없습니다. 프라이빗 API에 대한 자세한 내용은 AWS AppSync 프라이빗 API 사용을 참조하세요.

      완료했으면 다음을 선택합니다.

  4. 다음으로 병합된 API의 기반으로 사용할 GraphQL API를 추가해야 합니다. 소스 API 선택 페이지에서 다음 정보를 입력합니다.

    1. AWS 계정의 API 테이블에서 소스 API 추가를 선택합니다. GraphQL API 목록의 각 항목에는 다음 데이터가 포함됩니다.

      1. 이름: GraphQL API의 API 이름 필드입니다.

      2. API ID: GraphQL API의 고유한 ID 값입니다.

      3. 기본 인증 모드: GraphQL API의 기본 권한 부여 모드입니다. AWS AppSync의 권한 부여 모드에 대한 자세한 내용은 권한 부여 및 인증을 참조하세요.

      4. 추가 인증 모드: GraphQL API에 구성된 보조 권한 부여 모드입니다.

      5. API의 이름 필드 옆에 있는 확인란을 선택하여 병합된 API에서 사용할 API를 선택합니다. 그런 다음 소스 API 추가를 선택합니다. 선택한 GraphQL API는 AWS 계정의 API 테이블에 표시됩니다.

    2. 다른 AWS 계정의 API 테이블에서 소스 API 추가를 선택합니다. 이 목록에 있는 GraphQL API는 AWS Resource Access Manager(AWS RAM)을 통해 리소스를 공유하는 다른 계정에서 가져옵니다. 이 테이블의 GraphQL API를 선택하는 프로세스는 이전 섹션의 프로세스와 동일합니다. AWS RAM을 통해 리소스를 공유하는 방법에 대한 자세한 내용은 AWS Resource Access Manager이란?을 참조하세요.

      완료했으면 다음을 선택합니다.

    3. 기본 인증 모드를 추가합니다. 자세한 내용은 권한 부여 및 인증을 참조하세요. 다음을 선택합니다.

    4. 입력 내용을 검토한 다음 API 생성을 선택합니다.