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

将 API 合并 AWS AppSync

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

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

下图显示了合并后的 API 工作流程：

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

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

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

合并的 API 和联合

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

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

解决合并的 API 冲突

发生合并冲突时， AWS AppSync 为用户提供多种工具和示例，以帮助解决问题。

合并的 API 架构指令

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

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

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

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

另请注意 how 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已配置单元解析器，该单元解析器使用名为的 DynamoDB 数据源。Query.getPost PostDatasource该解析器将返回 Post 类型的 id 和 title。现在，Consider Source2.graphql 已经配置了一个流水线解析器Post.reviews，它运行两个函数。Function1附加了用于执行自定义授权检查None的数据源。Function2附加了 DynamoDB 数据源来查询该表。reviews

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

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

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

考虑以下情况，我们还在上实现了解析器，以便Query.getPost在字段解析器之外一次提供多个字段。Source2Source1.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 使用声明一个字段，@aws_iam而另一个源 API 声明了相同的字段@aws_api_key，则合并后的字段接受其中一个，并且只持有 API 密钥的客户端可以调用它。

要保持源 API 定义的字段授权，请为该字段添加注解，@canonical并在该字段本身上声明所需的授权指令。在以下示例中，Source1.graphql拥有的解析器protectedRead并需要 IAM 授权：

# This snippet represents a file called Source1.graphql

type Query {
    protectedRead: String @aws_iam @canonical
}

# This snippet represents a file called Source2.graphql

type Query {
    protectedRead: String @aws_api_key
}

当合并发生时，来自的定义优Source1.graphql先：

# This snippet represents a file called MergedSchema.graphql

type Query {
    protectedRead: String @aws_iam
}

如果没有 @canonical 注解，合并的字段将是protectedRead: String @aws_api_key @aws_iam。然后，仅持有合并API的API密钥的客户端可以调用它。

如果您的源 API 拥有该字段的解析器，请在该源 API 中为该字段添加注释，因为其解析器会返回数据。

有两个条件适用：

在现场声明授权指令

@canonical 保留声明的字段。带有注解 @canonical 且本身没有授权指令的字段采用您的源 API 的主要授权模式，该模式可能比您预期的更宽松。

仅在一个源 API 中为字段添加注释

如果两个源 API 将同一个字段注释为权威字段，则合并会失败并出现错误。Multiple subschemas cannot declare the same field as canonical

在字段级别而不是类型级别应用 @canonical 以限制对特定字段的授权。这仍然允许其他源 API 为相同类型提供其他字段。本指南适用于QueryMutation、和上的字段，Subscription也适用于对象类型上的字段。

如果你根本不想让某个字段出现在合并的 API 中，可以改用 @hidden。有关更多信息，请参阅 合并的 API 架构指令。

配置架构

双方负责配置架构以创建合并的 API：

由于合并 API 的架构是根据关联源 API 的架构创建的，因此，它是只读的。这意味着必须在源 API 中启动对架构的更改。在 AWS AppSync 控制台中，您可以使用架构窗口上方的下拉列表在合并架构和合并 API 中包含的源 API 的各个架构之间切换。

配置授权模式

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

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

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

配置执行角色

在创建合并的 API 时，您需要定义服务角色。 AWS 服务角色是一种 AWS 身份和访问管理 (IAM) 角色， AWS 服务使用它来代表您执行任务。

在这种情况下，您的合并 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 资源本身进行授权的子解析器：

JSON

{
    "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"] 
    }] 
}

如果要仅限访问特定的顶级字段，您可以使用如下策略：

JSON

{
    "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 资源访问管理器 (AWS RAM) 共享资源。

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

创建合并 API 时，您可以选择将源 API 与已通过 AWS 资源访问管理器共享的其他账户关联起来 (AWS RAM)。 AWS RAM 帮助您跨 AWS 账户、组织或组织单位 (OU) 内部以及 IAM 角色和用户安全地共享资源。

AWS AppSync 与集成， AWS RAM 以支持通过单个合并的 API 跨多个账户配置和访问源 API。 AWS RAM 允许您创建资源共享或资源容器以及将为每个资源共享的权限集。您可以在中向资源共享添加 AWS AppSync API AWS RAM。在资源共享中， AWS AppSync 提供三种不同的权限集，这些权限集可以与 RAM 中的 AWS AppSync API 相关联：

AWS AppSync 还支持客户管理的权限。当提供的其中一项 AWS管理权限不起作用时，您可以创建自己的客户管理权限。 Customer-managed 权限是指您可以通过精确指定在哪些条件下使用共享资源执行哪些操作来创作和维护的托管权限 AWS RAM。 AWS AppSync 允许您在创建自己的权限时从以下操作中进行选择：

一旦您在中正确共享了源 API 或合并的 API， AWS RAM 并且如有必要，资源共享邀请已被接受，则当您在合并的 API 上创建或更新源 API 关联时，该邀请将在 AWS AppSync 控制台中显示。通过调用提供的ListGraphqlApis操作 AWS AppSync 并使用所有OTHER_ACCOUNTS者筛选器，您还可以列出所有 AWS RAM 与您的账户共享的 AWS AppSync API，无论权限设置如何。

合并

管理合并

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

Auto-merges

可以将与 AWS AppSync 合并的 API 关联的源 API 配置为在对源 API 进行任何更改后自动合并（自动合并）到合并的 API 中。这会确保源 API 中的更改始终在后台传播到合并的 API 终端节点。将在合并的 API 中更新源 API 架构中的任何更改，只要它不会与合并 API 中的现有定义发生合并冲突。如果源 API 中的更新将更新解析器、数据来源或函数，则也会更新导入的资源。在引入无法自动解决的新冲突时，将拒绝合并的 API 架构更新，因为在合并操作期间发生不支持的冲突。对于状态为 MERGE_FAILED 的每个源 API 关联，将在控制台中显示错误消息。您还可以通过使用 AWS SDK 调用给定源 API 关联的GetSourceApiAssociation操作来检查错误消息，或者像这样使用 AWS CLI：

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 中自动进行合并和运行，而无需进行修改。要详细了解如何通过无服务器 WebSockets 连接 AWS AppSync 支持订阅，请参阅Real-time 数据。

配置可观测性

AWS AppSync 合并的 API 通过亚马逊提供内置的日志、监控和指标 CloudWatch。 AWS AppSync 还为通过跟踪提供内置支持AWS X-Ray。

配置自定义域

AWS AppSync 合并的 API 为在合并的 API 的 GraphQL 和 Real-time 终端节点中使用自定义域提供了内置支持。

配置缓存

AWS AppSync 合并的 API 为可选地缓存请求级 and/or解析器级别的响应以及响应压缩提供了内置支持。要了解更多信息，请参阅缓存和压缩。

配置私有 API

AWS AppSync 合并的 API 为私有 API 提供了内置支持，这些私有 API 将对合并后的 GraphQL 和 Real-time 终端节点的访问限制为来自您可以配置的 VPC 终端节点的流量。

配置防火墙规则

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

配置审核日志

AWS AppSync 合并的 API 提供对的内置支持 AWS CloudTrail，使您能够配置和管理审计日志。

合并的 API 限制

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

合并的 API 注意事项

在设计和实现合并的 API 时，请考虑以下几点：

将多个源 API 合并为一个端点会增加 GraphQL 架构和查询的大小和复杂性。随着合并架构的增长，查询可能需要遍历多个解析器才能完成单个请求，这可能会增加整体请求时间的延迟。例如，访问来自多个源 API 的字段的查询可能 AWS AppSync 需要按顺序执行来自每个源 API 的解析器，每个解析器会增加总响应时间。

我们强烈建议您在开发期间和实际负载条件下对合并的 API 进行全面测试，以确保它们满足您的业务需求。特别注意：

考虑实施性能优化，例如缓存、批处理数据源请求和设计源 API 架构，以最大限度地减少常见操作所需的解析器执行次数。

创建合并的 API

在控制台中创建合并的 API