Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

合并的 API

随着在组织中越来越多地使用 GraphQL，可能需要在 API 易用性和 API 开发速度之间进行权衡。一方面，组织采用 Amazon AppSync 和 GraphQL 为开发人员提供灵活的 API，他们可以通过单个网络调用安全地访问、处理和合并来自一个或多个数据域的数据，从而简化应用程序开发。另一方面，组织中负责将不同数据域合并为单个 GraphQL API 终端节点的团队可能希望能够相互独立地创建、管理和部署 API 更新，从而提高开发速度。

为了消除这种紧张关系，Amazon AppSync 合并 API 功能允许来自不同数据域的团队独立创建和部署 Amazon AppSync API（例如 GraphQL 架构、解析器、数据源和函数），然后将它们合并为一个合并的 API。这使组织能够维护简单易用的跨域 API，并为对该 API 做出贡献的不同团队提供一种方法，以快速独立地进行 API 更新。

通过使用合并的 API，组织可以将多个独立源 Amazon AppSync API 的资源导入到单个 Amazon AppSync 合并 API 终端节点中。为此，Amazon AppSync 允许您创建一个 Amazon AppSync 源 API 列表，然后将与源 API 关联的所有元数据（包括架构、类型、数据源、解析器和函数）合并为一个新的 Amazon AppSync 合并 API。

在合并过程中，由于源 API 数据内容不一致（例如，在合并多个架构时发生的类型命名冲突），可能会发生合并冲突。对于源 API 中的定义不发生冲突的简单使用案例，无需修改源 API 架构。生成的合并 API 直接从原始源 Amazon AppSync API 导入所有类型、解析器、数据源和函数。对于发生冲突的复杂使用案例，用户/团队必须通过各种方法解决冲突。Amazon AppSync 为用户提供了一些可以减少合并冲突的工具和示例。

Amazon AppSync 中配置的后续合并将源 API 中所做的更改传播到关联的合并 API。

合并的 API 和联合

在 GraphQL 社区中提供很多合并 GraphQL 架构的解决方案和模式，并通过共享图实现团队协作。Amazon AppSync合并的 API 采用构建时方法进行架构组合，其中源 API 合并为一个单独的合并 API。另一种方法是在多个源 API 或子图之间添加运行时路由器。在这种方法中，路由器接收请求，引用它作为元数据维护的合并架构，构建请求计划，然后在其底层子图/服务器之间分配请求元素。下表将 Amazon AppSync 合并 API 构建时方法与基于路由器的运行时 GraphQL 架构组合方法进行了比较：

* Amazon AppSync 合并 API 只能与 Amazon AppSync 源 API 相关联。如果您需要支持跨 Amazon AppSync 和非 Amazon AppSync 子图的架构组合，您可以将一个或多个 Amazon AppSync GraphQL 和/或合并 API 连接到基于路由器的解决方案。例如，请参阅以下参考博客，以了解如何将基于路由器的架构与 Apollo Federation v2 一起使用以将 Amazon AppSync API 添加为子图：Apollo GraphQL Federation with Amazon AppSync。

解决合并的 API 冲突

如果发生合并冲突，Amazon AppSync 为用户提供了一些工具和示例以帮助解决问题。

合并的 API 架构指令

Amazon AppSync 引入了一些 GraphQL 指令，可用于减少或解决源 API 之间的冲突：

要显示架构指令提供的功能，请考虑以下示例：

在该示例中，假设我们要合并两个源 API。我们有两个创建和检索文章（例如，评论部分或社交媒体文章）的架构。假设这些类型和字段非常相似，在合并操作期间很可能会发生冲突。下面的代码片段显示每个架构的类型和字段。

第一个文件名为 Source1.graphql，它是一个 GraphQL 架构，允许用户使用 putPost 变更创建 Posts。每个 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，它是一个 GraphQL 架构，其功能与 Source1.graphql 非常相似。但请注意，每种类型的字段是不同的。在合并这两个架构时，由于这些差异，将会发生合并冲突。

另请注意，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
}

在合并过程中发生了以下情况：

还有一种情况是，不会将任何指令添加到冲突的类型中。此处，合并的类型包括该类型的所有源定义中的所有字段的联合。例如，请考虑以下示例：

该架构名为 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
}

在合并过程中发生了以下情况：

管理共享类型上的解析器

在上面的示例中，考虑 Source1.graphql 在 Query.getPost 上配置了单位解析器的情况，该解析器使用名为 PostDatasource 的 DynamoDB 数据源。该解析器将返回 Post 类型的 id 和 title。现在，考虑 Source2.graphql 在 Post.reviews 上配置了管道解析器的情况，该解析器运行两个函数。Function1 附加了一个 None 数据源以执行自定义授权检查。Function2 附加了一个 DynamoDB 数据源以查询 reviews 表。

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

在客户端对合并的 API 终端节点运行上述查询时，Amazon AppSync 服务先从 Source1 中运行 Query.getPost 的单位解析器，该解析器调用 PostDatasource 并从 DynamoDB 中返回数据。然后，它运行 Post.reviews 管道解析器，其中 Function1 执行自定义授权逻辑，并且 Function2 返回位于 $context.source 中的给定 id 的评价。该服务将请求作为单个 GraphQL 运行进行处理，并且该简单请求仅需要一个请求令牌。

管理共享类型上的解析器冲突

考虑以下情况，我们还在 Query.getPost 上实施了一个解析器，以便每次在 Source2 中的字段解析器以外提供多个字段。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
}

尝试合并这两个架构将发生合并错误，因为 Amazon AppSync 合并 API 不允许将多个源解析器附加到同一字段。为了解决该冲突，您可以实施一种字段解析器模式，该模式要求 Source2.graphql 添加一个单独的类型以定义它从 Post 类型中拥有的字段。在以下示例中，我们添加一个名为 PostInfo 的类型，其中包含由 Source2.graphql 解析的 content 和 author 字段。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 中启动对架构的更改。在 Amazon AppSync 控制台中，您可以使用架构窗口上面的下拉列表，在合并架构与合并 API 中包含的源 API 的各个架构之间进行切换。

配置授权模式

可以使用多种授权模式保护您的合并 API。要了解 Amazon AppSync 中的授权模式的更多信息，请参阅授权和身份验证。

可以将以下授权模式与合并的 API 一起使用：

合并的 API 的授权模式是由合并的 API 所有者配置的。在执行合并操作时，合并的 API 必须包含在源 API 上配置的主要授权模式，以作为自己的主要授权模式或辅助授权模式。否则，将会不兼容，并且合并操作由于冲突而失败。在源 API 中使用多重授权指令时，合并过程能够自动将这些指令合并到统一的终端节点中。如果源 API 的主要授权模式与合并 API 的主要授权模式不匹配，它自动添加这些授权指令，以确保源 API 中的类型的授权模式一致。

配置执行角色

在创建合并的 API 时，您需要定义服务角色。Amazon 服务角色是一个 Amazon Identity and Access Management (IAM) 角色，Amazon 服务使用该角色代表您执行任务。

在这种情况下，您的合并 API 需要运行解析器以访问源 API 中配置的数据源中的数据。这种情况所需的服务角色是 mergedApiExecutionRole，它必须具有明确的访问权限，以通过 appsync:SourceGraphQL IAM 权限对合并 API 中包含的源 API 运行请求。在 GraphQL 请求运行期间，Amazon AppSync 服务担任该服务角色，并授权该角色执行 appsync:SourceGraphQL 操作。

Amazon AppSync 支持为请求中的特定顶级字段允许或拒绝该权限，例如，如何将 IAM 授权模式用于 IAM API。对于非顶级字段，Amazon 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"] 
    }] 
}

您也可以使用 Amazon AppSync 控制台 API 创建向导生成服务角色，以允许您的合并 API 访问源 API 中配置的资源，这些源 API 与合并的 API 位于同一账户中。如果您的源 API 没有位于与合并 API 相同的账户中，您必须先使用 Amazon Resource Access Manager (Amazon RAM) 共享您的资源。

使用 Amazon RAM 配置跨账户的合并 API

在创建合并的 API 时，您可以选择关联已通过 Amazon Resource Access Manager (Amazon RAM) 共享的其他账户中的源 API。Amazon RAM 帮助您在 Amazon 账户之间、在您的组织或组织单位 (OU) 内以及与 IAM 角色和用户安全地共享资源。

Amazon AppSync 与 Amazon RAM 集成在一起，以支持从单个合并的 API 中配置和访问多个账户中的源 API。Amazon RAM 允许您创建资源共享，即资源容器以及为每个资源共享的权限集。您可以将 Amazon AppSync API 添加到 Amazon RAM 中的资源共享。在资源共享中，Amazon AppSync 提供了三种不同的权限集，它们可以与 RAM 中的 Amazon AppSync API 相关联：

Amazon AppSync 还支持客户托管权限。在提供的 Amazon 托管权限之一不起作用时，您可以创建自己的客户托管权限。客户托管权限是您编写和维护的托管权限，您精确指定可以在哪些条件下对使用 Amazon RAM 共享的资源执行哪些操作。Amazon AppSync 允许您在创建自己的权限时选择以下操作：

在 Amazon RAM 中正确共享源 API 或合并的 API 并接受资源共享邀请（如有必要）后，在为合并的 API 创建或更新源 API 关联时，将在 Amazon AppSync 控制台中显示该信息。您也可以调用 Amazon AppSync 提供的 ListGraphqlApis 操作并使用 OTHER_ACCOUNTS 所有者筛选条件，以列出已使用 Amazon RAM 与您的账户共享的所有 Amazon AppSync API，而无论权限集如何。

合并

管理合并

合并的 API 旨在支持统一 Amazon AppSync 终端节点上的团队协作。团队可以在后端独立开发自己的隔离源 GraphQL API，而 Amazon AppSync 服务管理将资源集成到单个合并 API 终端节点的过程，以减少协作中的摩擦并缩短开发前期时间。

自动合并

可以配置与您的 Amazon AppSync 合并 API 关联的源 API，以在对源 API 进行任何更改后自动合并到合并的 API 中。这会确保源 API 中的更改始终在后台传播到合并的 API 终端节点。将在合并的 API 中更新源 API 架构中的任何更改，只要它不会与合并 API 中的现有定义发生合并冲突。如果源 API 中的更新将更新解析器、数据源或函数，则也会更新导入的资源。在引入无法自动解决的新冲突时，将拒绝合并的 API 架构更新，因为在合并操作期间发生不支持的冲突。对于状态为 MERGE_FAILED 的每个源 API 关联，将在控制台中显示错误消息。您也可以使用 Amazon SDK 或 Amazon 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 所有者可以从 Amazon AppSync 控制台中或通过 Amazon SDK 和 Amazon CLI 中提供的 StartSchemaMerge 操作调用手动合并。

对合并 API 的额外支持

配置订阅

与基于路由器的 GraphQL 架构组合方法不同，Amazon AppSync 合并 API 为 GraphQL 订阅提供内置支持。关联的源 API 中定义的所有订阅操作将在合并 API 中自动进行合并和运行，而无需进行修改。要了解 Amazon AppSync 如何通过无服务器 WebSockets 连接支持订阅的更多信息，请参阅实时数据。

配置可观测性

Amazon AppSync 合并 API 通过 Amazon CloudWatch 提供内置日志记录、监控和指标。Amazon AppSync 还通过 Amazon X-Ray 提供内置的跟踪支持。

配置自定义域

Amazon AppSync 合并 API 提供内置支持，以将自定义域与合并 API 的 GraphQL 和实时终端节点一起使用。

配置缓存

Amazon AppSync 合并 API 提供内置支持，可以选择缓存请求级和/或解析器级响应以及响应压缩。要了解更多信息，请参阅缓存和压缩。

配置私有 API

Amazon AppSync 合并 API 为私有 API 提供内置支持，这些 API 仅限来自您可以配置的 VPC 终端节点的流量访问合并 API 的 GraphQL 和实时终端节点。

配置防火墙规则

Amazon AppSync 合并 API 为 Amazon WAF 提供内置支持，以使您能够定义 Web 应用程序防火墙规则以保护您的 API。

配置审核日志

Amazon AppSync 合并 API 为 Amazon CloudTrail 提供内置支持，以使您能够配置和管理审核日志。

合并的 API 限制

在开发合并 API 时，请注意以下规则：

创建合并的 API

在控制台中创建合并的 API