本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

在 APIs中合併 AWS AppSync

隨著 GraphQL 的使用在組織內擴展， API ease-of-use和 API 開發速度之間可能會發生權衡。一方面，組織採用 AWS AppSync 和 GraphQL 來簡化應用程式開發，為開發人員提供彈性，API以使用單一網路呼叫安全地存取、操作和結合來自一或多個資料網域的資料。另一方面，組織內負責將不同資料網域合併到單一 GraphQL API端點的團隊，可能需要能夠獨立建立、管理和部署API更新，以增加其開發速度。

若要解決這種緊張， AWS AppSync 合併APIs功能可讓來自不同資料網域的團隊獨立建立和部署 AWS AppSync APIs （例如 GraphQL 結構描述、解析程式、資料來源和函數），然後可以合併為單一合併的 API。這可讓組織維持簡單易用的跨網域 API，以及不同團隊有助於API快速獨立進行API更新的方式。

使用合併 APIs，組織可以將多個獨立來源的資源匯入 AWS AppSync APIs單一 AWS AppSync合併API端點。若要這麼做， AWS AppSync 可讓您建立 AWS AppSync 來源清單APIs，然後將與來源相關聯的所有中繼資料，APIs包括結構描述、類型、資料來源、解析器和函數合併為新的 AWS AppSync 合併 API。

在合併期間，可能會因為來源API資料內容中的不一致而發生合併衝突，例如在合併多個結構描述時，類型命名衝突。對於來源APIs衝突中沒有定義的簡單使用案例，不需要修改來源API結構描述。產生的合併API只會從原始來源 匯入所有類型、解析程式、資料來源和函數 AWS AppSync APIs。對於發生衝突的複雜使用案例，使用者/團隊必須透過各種方式解決衝突。 為使用者 AWS AppSync 提供數種工具和範例，可減少合併衝突。

在 中設定的後續合併 AWS AppSync 會將來源中所做的變更傳播APIs到相關聯的合併 API。

合併APIs和聯合

GraphQL 社群中有許多解決方案和模式，用於合併 GraphQL 結構描述並透過共用圖形實現團隊協作。 AWS AppSync 合併APIs採用建構時間方法來建構結構描述構成，其中來源APIs合併為單獨的合併 API。另一種方法是跨多個來源APIs或子圖形將執行時間路由器分層。在此方法中，路由器接收請求，參考其作為中繼資料維護的組合結構描述，建構請求計劃，然後將請求元素分佈到其基礎子圖形/伺服器。下表將 AWS AppSync 合併API建置時間方法與以路由器為基礎的執行時間方法與 GraphQL 結構描述構成進行比較：

* AWS AppSync 合併APIs只能與 AWS AppSync 來源 建立關聯APIs。如果您需要跨 AWS AppSync 和非AWS AppSync 子圖形結構描述構成的支援，您可以將一或多個 AWS AppSync GraphQL 和/或合併APIs連接至以路由器為基礎的解決方案。例如，請參閱參考部落格，以使用具有 Apollo Federation v2 的路由器型架構新增 AWS AppSync APIs為子圖：具有 的 Apollo GraphQL Federation AWS AppSync。

合併API衝突解決方案

如果發生合併衝突， AWS AppSync 會提供使用者數個工具和範例，以協助疑難排解 （問題）。

合併API結構描述指令

AWS AppSync 已引入數個 GraphQL 指令，可用於減少或解決來源 之間的衝突APIs：

若要顯示公用程式結構描述指令，請考慮下列範例：

在此範例中，假設我們要合併兩個來源 APIs。我們獲得兩個結構描述，可建立和擷取文章 （例如評論區段或社交媒體文章）。假設類型和欄位非常相似，在合併操作期間發生衝突的機率很高。以下程式碼片段顯示每個結構描述的類型和欄位。

第一個名為 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 非常相似。不過請注意，每種類型的欄位都不同。合併這兩個結構描述時，由於這些差異，將會發生合併衝突。

另請注意 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，該解析器使用名為 的 DynamoDB 資料來源PostDatasource。此解析器將傳回 id和 title Post類型的 。現在，請考慮 Source2.graphql 已在 上設定管道解析程式Post.reviews，該解析程式會執行兩個函數。 Function1 已連接None資料來源以執行自訂授權檢查。 Function2 已連接 DynamoDB 資料來源以查詢reviews資料表。

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

當用戶端對合併API端點執行上述查詢時， AWS AppSync 服務會先Query.getPost從 執行 的單位解析器Source1，這呼叫 PostDatasource並從 DynamoDB 傳回資料。然後，它會執行Post.reviews管道解析程式，其中會Function1執行自訂授權邏輯，並在 id 中找到的 中Function2傳回評論$context.source。服務會將請求視為單一 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
}

嘗試合併這兩個結構描述將產生合併錯誤，因為 AWS AppSync 合併APIs不允許多個來源解析器連接到同一個欄位。若要解決此衝突，您可以實作需要 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的結構描述是從關聯來源 的結構描述建立APIs，因此僅供讀取。這表示必須在來源 中啟動結構描述的變更APIs。在 AWS AppSync 主控台中，您可以使用結構描述視窗上方的API下拉式清單，在合併結構描述與合併中APIs包含的來源的個別結構描述之間切換。

設定授權模式

有多種授權模式可用於保護您的合併 API。若要進一步了解 中的授權模式 AWS AppSync，請參閱授權和身分驗證 。

下列授權模式可用於合併 APIs：

合併的授權模式由合併API擁有者API設定。在合併操作時，合併API必須包含在來源上設定的主要授權模式，API作為其自己的主要授權模式或次要授權模式。否則，它會不相容，合併操作會失敗並產生衝突。在來源 中使用多驗證指令時APIs，合併程序能夠自動將這些指令合併到統一端點。如果來源的主要授權模式與合併 的主要授權模式API不相符API，則會自動新增這些驗證指令，以確保來源中類型的授權模式API一致。

設定執行角色

當您建立合併 時API，您需要定義服務角色。 AWS 服務角色是 AWS Identity and Access Management （IAM） 角色，由 AWS 服務用來代表您執行任務。

在這種情況下，您的合併必須API執行解析程式，以從來源 中設定的資料來源存取資料APIs。此 所需的服務角色是 mergedApiExecutionRole，而且必須具有明確存取權，才能透過 appsync:SourceGraphQL IAM 許可API在合併APIs的來源上執行請求。在執行 GraphQL 請求期間， AWS AppSync 服務將擔任此服務角色，並授權該角色執行appsync:SourceGraphQL動作。

AWS AppSync 支援允許或拒絕請求中特定頂層欄位的此許可，例如IAM授權模式對 IAM 的運作方式APIs。對於 non-top-level 欄位， AWS AppSync 會要求您定義來源APIARN本身的許可。為了限制對合併 中特定 non-top-level欄位的存取API，我們建議您在 Lambda 內實作自訂邏輯，或使用 API @hidden 指令隱藏合併的來源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存取在與合併 位於相同帳戶中APIs的來源中設定的資源API。如果您的來源APIs與合併的 不在同一帳戶中API，您必須先使用 AWS Resource Access Manager （） 共用資源AWS RAM。

APIs 使用 設定跨帳戶合併 AWS RAM

當您建立合併 時API，您可以選擇將APIs來源與透過 AWS Resource Access Manager （AWS RAM） 共用的其他 帳戶建立關聯。 AWS RAM 可協助您跨 AWS 帳戶、組織或組織單位 （OUs） 以及IAM角色和使用者安全地共用資源。

AWS AppSync 與 整合， AWS RAM 以支援從單一合併 APIs跨多個帳戶設定和存取來源API。 AWS RAM 可讓您建立資源共用或資源容器，以及將針對每個帳戶共用的許可集。您可以新增至 AWS AppSync APIs 中的資源共用 AWS RAM。在資源共用中， AWS AppSync 提供可與 AWS AppSync API中的 相關聯的三個不同許可集RAM：

AWS AppSync 也支援客戶管理的許可。當其中一個提供的 AWS受管許可無法使用時，您可以建立自己的客戶受管許可。客戶受管許可是您編寫和維護的受管許可，方法是精確指定哪些動作可以使用 共用資源的條件 AWS RAM。 AWS AppSync 可讓您在建立自己的許可時，從下列動作中進行選擇：

適當地共用來源API或合併後API AWS RAM ，如有必要，資源共用邀請已被接受，當您在合併的 上建立或更新來源API關聯時，會在 AWS AppSync 主控台中顯示API。您也可以透過呼叫 AWS AppSync 和 使用OTHER_ACCOUNTS擁有者篩選條件提供的ListGraphqlApis操作，列出使用 AWS RAM 與 帳戶共用的所有 AWS AppSync APIs ，無論設定了何種許可。

合併

管理合併

合併APIs旨在支援團隊在統一 AWS AppSync 端點上的協作。團隊可以在APIs後端獨立發展自己的隔離來源 GraphQL，同時 AWS AppSync 服務會管理資源整合到單一合併API端點，以減少協作中的摩擦並縮短開發前置時間。

自動合併

與 AWS AppSync 合併APIs相關聯的來源API可以設定為在對來源 進行任何變更API後自動合併 （自動合併） 至合併API。這可確保來源的變更API一律傳播至背景中的合併API端點。只要來源API結構描述未與合併 中的現有定義發生合併衝突，API則合併 中會更新來源結構描述的任何變更API。如果來源中的更新API正在更新解析程式、資料來源或函數，則匯入的資源也會更新。當引入無法自動解決 （自動解決） 的新衝突時，合併API結構描述更新會因為合併操作期間不支援的衝突而被拒絕。狀態為 的每個來源API關聯的主控台中都會提供錯誤訊息MERGE_FAILED。您也可以使用 或使用 AWS CLI類似方式呼叫指定來源API關聯的GetSourceApiAssociation操作來 AWS SDK檢查錯誤訊息：

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自上次更新合併APIs後在來源中發生的任何變更，來源API擁有者可以從 AWS AppSync 主控台或透過 AWS SDK和 中可用的StartSchemaMerge操作叫用手動合併 AWS CLI。

合併的其他支援 APIs

設定訂閱

與以路由器為基礎的 GraphQL 結構描述撰寫方法不同， AWS AppSync Merged 為 GraphQL 訂閱APIs提供內建支援。在您的關聯來源中定義的所有訂閱操作APIs都會自動合併，並在合併中運作，API而不會修改。若要進一步了解如何透過無伺服器 WebSockets 連線 AWS AppSync 支援訂閱，請參閱即時資料 。

設定可觀測性

AWS AppSync 合併透過 Amazon CloudWatchAPIs提供內建日誌記錄、監控和指標。 AWS AppSync 也提供透過 追蹤的內建支援AWS X-Ray。

設定自訂網域

AWS AppSync 合併APIs提供內建支援，讓您將自訂網域與合併 API的 GraphQL 和即時端點搭配使用。

設定快取

AWS AppSync 合併APIs提供內建支援，可選擇性地快取請求層級和/或解析器層級的回應，以及回應壓縮。若要進一步了解，請參閱快取和壓縮 。

設定私有 APIs

AWS AppSync 合併APIs提供 Private 的內建支援APIs，將對合併 API的 GraphQL 和即時端點的存取限制為來自VPC您可以設定 之端點的流量。

設定防火牆規則

AWS AppSync 合併為 APIs提供內建支援 AWS WAF，可讓您APIs定義 Web 應用程式防火牆規則 來保護您的 。

設定稽核日誌

AWS AppSync 合併為 APIs提供內建支援 AWS CloudTrail，可讓您設定和管理稽核日誌 。

合併API限制

開發合併 時APIs，請注意下列規則：

建立合併 APIs

在主控台API中建立合併