マージド API - AWS AppSync
マージド API とフェデレーションマージド API の競合の解決スキーマの設定承認モードの設定実行ロールの設定AWS RAM を使用したクロスアカウントマージ API の設定マージマージ API に対するその他のサポートマージド API の制限マージド API の作成

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

マージド API

組織内で GraphQL の使用が拡大するにつれて、API の使いやすさと API の開発速度の間でトレードオフが生じる可能性があります。一方では、組織は AWS AppSync と GraphQL を採用してアプリケーション開発を簡素化します。開発者は、1 つのネットワーク呼び出しで 1 つ以上のデータドメインのデータに安全にアクセスし、操作して組み合わせることができる柔軟な 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 サブグラフ全体ののスキーマ構成のサポートが必要な場合は、1 つ以上の AWS AppSync GraphQL および/またはマージド APIをルーターベースのソリューションに接続できます。例えば、Apollo Federation v2 でルーターベースのアーキテクチャを使用して AWS AppSync APIをサブグラフとして追加するリファレンスブログ「AWS AppSync を使用したApollo GraphQLフェデレーション」を参照してください

マージド API の競合の解決

マージによる競合が発生した場合に、AWS AppSync では問題のトラブルシューティングに役立ついくつかのツールとサンプルをユーザーに提供します。

マージド API スキーマのディレクティブ

AWS AppSync には、ソース API 間の競合を軽減または解決するために使用できるいくつかの GraphQL ディレクティブが導入されています。

  • @canonical: このディレクティブは、名前とデータが似ている型/フィールドの優先順位を設定します。2 つ以上のソース API が同じ GraphQL タイプまたはフィールドを持つ場合、いずれかの API がタイプまたはフィールドに標準として注釈を付けることができ、マージ時に優先順位が付けられます。他のソース API でこのディレクティブでアノテーションが付けられていない競合するタイプ/フィールドは、マージ時に無視されます。

  • @hidden: このディレクティブは特定の型/フィールドをカプセル化して、マージプロセスから削除します。チームは、内部クライアントだけが特定の型付きデータにアクセスできるように、ソース API の特定のタイプや操作を削除または非表示にしたい場合があります。このディレクティブをアタッチすると、タイプやフィールドはマージド API にマージされません。

  • @renamed: このディレクティブは、名前の競合を減らすためにタイプ/フィールドの名前を変更します。異なる API が同じタイプまたはフィールド名を持つ場合があります。ただし、これらはすべて、マージされたスキーマで使用可能である必要があります。これらすべてをマージド API に含める簡単な方法は、フィールドの名前を似ているが別の名前に変更することです。

ユーティリティスキーマのディレクティブを示すには、次の例を考えます。

この例では、2 つのソース API をマージすると仮定します。投稿 (コメントセクションやソーシャルメディア投稿など) を作成および取得する 2 つのスキーマが与えられます。タイプとフィールドが似ていると、マージ操作中に競合が発生する可能性が高くなります。以下のスニペットは、各スキーマのタイプとフィールドを示しています。

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
}

2 つ目のファイルは Source2.graphQL と呼ばれ、Source1.graphql とよく似た処理を行う GraphQL スキーマです。ただし、各タイプのフィールドは異なることに注意してください。これら 2 つのスキーマをマージすると、これらの違いによりマージによる競合が発生します。

また、Source2.graphQL には、これらの競合を減らすためのディレクティブがいくつか含まれていることにも注意してください。Post タイプには @hidden タグのアノテーションが付いており、マージ操作中にわかりにくくなります。Message タイプには @renamed タグのアノテーションが付いており、別の Message タイプと名前が競合した場合にタイプ名が ChatMessage に変更されます。

# 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 タイプは両方のファイルの内容を含むように更新されました。ただし、このディレクティブにより、1 つの GetMessage クエリの名前が GetChatMessage に変更されました。これにより、同じ名前の 2 つのクエリ間の名前の競合が解決されました。

また、競合するタイプにディレクティブが追加されない場合もあります。この場合、マージされたタイプには、そのタイプのすべてのソース定義のすべてのフィールドの和集合が含まれます。例えば、次の例を考えてみます。

このスキーマは 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、ペイロードメッセージが含まれます。

マージすると、この 2 つの 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 タイプフィールドはユニオンオペレーションによって結合されました。この 2 つのユニオンによって、単一の id、title、および単一の reviews が生成されることに注目してください。

  • Review のタイプは競合せず、マージされました。

  • Query のタイプは競合せず、マージされました。

共有タイプのリゾルバーの管理

上記の例で、Source1.graphql が PostDatasource という名前の DynamoDB データ・ソースを使用する、Query.getPost 上のユニット・リゾルバを構成している場合を考えてみましょう。このリゾルバーは Post タイプの id と title を返します。ここで、Source2.graphql が Post.reviews でパイプラインリゾルバ－を設定し、2 つの関数を実行しているとします。Function1 には、カスタムの権限チェックを実行するための None データ・ソースがアタッチされています。Function2 には　reviews テーブルをクエリするための DynamoDB データソースがアタッチされています。

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

クライアントがマージド API エンドポイントに対して上記のクエリを実行すると、AWS AppSync サービスはまず Source1 から Query.getPost のユニットリゾルバーを実行し、DynamoDB から PostDatasource を呼び出します。次に、Post.reviews パイプラインリゾルバーを実行し、そこで Function1 がカスタム認可ロジックを実行して、Function2 が $context.source で見つかった id に付与されたレビューを返します。サービスはリクエストを単一の GraphQL 実行として処理し、この単純なリクエストには 1 つのリクエストトークンのみが必要です。

共有タイプのリゾルバー競合の管理

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 では複数のソースリゾルバーを同じフィールドにアタッチできないため、これら 2 つのスキーマをマージしようとするとマージエラーが発生します。この競合を解決するには、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 を作成するためのスキーマの設定は、次の 2 つの関係者が担当します。

  • マージド 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 Authorizer: カスタムロジックを使用して 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 API の IAM 承認モードの仕組みなど、リクエスト内の特定の最上位フィールドに対するこの権限の許可または拒否をサポートします。トップレベル以外のフィールドでは、AWS AppSync にはソース API ARN 自体で権限を定義する必要があります。マージド API の特定の非トップレベルフィールドへのアクセスを制限するには、Lambda 内にカスタムロジックを実装するか、@hidden ディレクティブを使用してソース API フィールドをマージド API から非表示にすることをお勧めします。ソース API 内のすべてのデータ操作をロールに実行させたい場合は、以下のポリシーを追加できます。最初のリソースエントリはすべての最上位フィールドへのアクセスを許可し、2 番目のエントリはソース 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 に設定されたリソースに Merged API がアクセスできるようにすることもできます。ソース API がマージド API と同じアカウントにない場合は、まず AWSResource Access Manager (AWS RAM) を使用してリソースを共有する必要があります。

AWS RAM を使用したクロスアカウントマージ API の設定

マージド API を作成する場合、オプションで AWS Resource Access Manager (AWS RAM) を介して共有されている他のアカウントのソース API を関連付けることができます。AWS RAM はリソースを AWS アカウント間、組織内、組織単位 (OU) 内、IAM ロールやユーザーと安全に共有します。

AWS AppSync は AWS RAM と統合することで、1 つのマージド API から複数のアカウントにわたるソース API の設定とアクセスをサポートします。AWS RAM により、リソース共有、またはリソースと各リソースで共有される権限セットのコンテナを作成できます。AWS AppSync API を AWS RAM でリソース共有に追加できます。リソース共有内には、RAM 内の AWS AppSync API に関連付けることができる 3 つの異なる権限セットが用意されています。

  1. AWSRAMPermissionAppSyncSourceApiOperationAccess: 他の権限が指定されていない場合に AWS RAM で AWS AppSync API を共有するときに追加されるデフォルトの権限セット。このアクセス許可セットは、ソース AWS AppSync API をマージド API 所有者と共有するために使用されます。このアクセス許可には、ソース API appsync:AssociateMergedGraphqlApi に対する権限と、ランタイムにソース API リソースにアクセスするために必要な appsync:SourceGraphQL アクセス許可が含まれます。

  2. AWSRAMPermissionAppSyncMergedApiOperationAccess: このアクセス許可セットは、マージド API をソース API 所有者と共有する場合に設定する必要があります。このアクセス許可セットにより、ソース API は Merged API を設定できるようになります。これには、ターゲットプリンシパルが所有するソース API をMerged API に関連付ける機能や、マージド API のソース API 関連付けを読み取って更新する機能が含まれます。

  3. AWSRAMPermissionAppSyncAllowSourceGraphQLAccess: このアクセス許可セットにより、appsync:SourceGraphQL アクセス許可を AWS AppSync API で使用できるようになります。これは、ソース API をマージド API の所有者と共有するためのものです。ソース API 操作アクセス用のデフォルトの権限セットとは対照的に、この権限セットにはランライムアクセス許可 appsync:SourceGraphQL のみが含まれます。マージド API オペレーションへのアクセス権をソース API 所有者と共有することを選択した場合、マージド API エンドポイントを通じてランタイムアクセスできるようにするには、ソース API からのこの権限を Merged API 所有者にも共有する必要があります。

AWS AppSync は、顧客管理のアクセス権限もサポートしています。提供されているAWSマネージド許可の 1 つが機能しない場合、独自の顧客に管理された許可を作成することができます。顧客管理アクセス許可とは、共有リソースを 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

ソース API またはマージド API をAWS RAM で適切に共有し、必要に応じてリソース共有の招待が承認されると、Merged API のソース API アソシエーションを作成または更新したときに、その招待が AWS AppSync コンソールに表示されます。また、自分のアカウントで AWS RAM を使用して共有されている全てのAWS AppSync APIを、設定されているアクセス許可に関係なく、AWS AppSync によって提供され ListGraphqlApis オペレーションを呼び出し、OTHER_ACCOUNTS オーナーフィルターを使用することで、一覧表示することができます。

注記

AWS RAM 経由で共有するには、AWS RAM の呼び出し元が共有されている API に対して appsync:PutResourcePolicy アクションを実行する許可を持っている必要があります。

マージ

マージの管理

マージド API は、統一された AWS AppSync エンドポイントでのチームコラボレーションをサポートするためのものです。チームがバックエンドで独自の独立したソース GraphQL API を独自に進化させながら、AWS AppSync サービスが単一のマージド API エンドポイントへのリソースの統合を管理することで、コラボレーションにおける摩擦を減らし、開発リードタイムを短縮できます。

自動マージ

AWS AppSync マージド API に関連付けられているソース API は、ソース API に変更が加えられた後に自動的にマージ (自動マージ) するように設定できます。これにより、ソース API からの変更が常にバックグラウンドでマージド API エンドポイントに反映されます。ソース API スキーマの変更は、Merged 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 での サーバーレス WebSockets 接続によるサブスクリプションのサポート方法の詳細については、「リアルタイムデータ」を参照してください。

オブザーバビリティの設定

AWS AppSyncマージド API では、Amazon CloudWatch を介してロギング、モニタリング、メトリクスが組み込まれています。AWS AppSync では AWS X-Ray によるトレーシングのサポートも組み込まれています。

カスタムドメインの設定

AWS AppSync マージド API には、マージド API の GraphQL エンドポイントとリアルタイムエンドポイントでカスタムドメインを使用するためのサポートが組み込まれています。

キャッシュの設定

AWS AppSync マージド API には、リクエストレベルやリゾルバーレベルのレスポンスのキャッシュ、レスポンスの圧縮をオプションでサポートする機能が組み込まれています。詳細については、「キャッシュと圧縮」を参照してください。

プライベート API の設定

AWS AppSync マージド API にはプライベート API のサポートが組み込まれており、マージド API の GraphQL エンドポイントと Real-Time エンドポイントへのアクセスを、設定可能な VPC エンドポイントから発信されるトラフィックに制限します。

ファイアウォールルールの設定

AWS AppSync マージド API には AWS WAF　に対するサポートが組み込まれているため、Web アプリケーションのファイアウォールルールを定義して API を保護できます。

監査ログ記録の設定

AWS AppSync マージド API には、監査ログの設定と管理を可能にする AWS CloudTrail のサポートが組み込まれています。

マージド API の制限

マージド API を開発するときは、以下のルールに注意してください。

  1. マージド API を別のマージド API のソース API にすることはできません。

  2. ソース API を複数のマージド API に関連付けることはできません。

  3. マージド API スキーマドキュメントのデフォルトのサイズ制限は 10 MB です。

  4. マージド API に関連付けることができるソース API のデフォルト数は 10 です。ただし、マージド API に 10 個を超えるソース API が必要な場合は、制限の引き上げをリクエストできます。

マージド API の作成

コンソールでマージド API を作成するには

  1. AWS Management Console にサインインして、AWS AppSync コンソール を開きます。

    1. ダッシュボードで、[API の作成] を選択します。

  2. [マージド API] を選択し、[次へ] を選択します。

  3. [API の詳細を指定] ページで、次の情報を入力します。

    1. [認証情報] で以下の情報を入力します。

      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 の作成] を選択します。