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

在 中使用即時資料應用程式的訂閱 AWS AppSync

AWS AppSync 可讓您使用訂閱實作即時應用程式更新、推播通知等。當用戶端叫用 GraphQL 訂閱操作時， 會自動建立和維護安全 WebSocket 連線 AWS AppSync。然後，應用程式可以即時將資料從資料來源分發給訂閱者，同時 AWS AppSync 持續管理應用程式的連線和擴展需求。以下各節將向您展示訂閱 AWS AppSync的運作方式。

GraphQL 結構描述訂閱指令

中的訂閱 AWS AppSync 會叫用為對突變的回應。這表示您可以透過在突變上指定 GraphQL 結構描述指令， AWS AppSync 即時產生任何資料來源。

AWS Amplify 用戶端程式庫會自動處理訂閱連線管理。程式庫使用純 WebSockets 作為用戶端和服務之間的網路通訊協定。

會從變動觸發訂閱且會將變動選擇設定傳送給訂閱者。

以下範例示範如何使用 GraphQL 訂閱。它不會指定資料來源，因為資料來源可能是 Lambda、Amazon DynamoDB 或 Amazon OpenSearch Service。

若要開始使用訂閱，您必須將訂閱項目點新增至您的結構描述，如下所示：

schema {
    query: Query
    mutation: Mutation
    subscription: Subscription
}

假設您有一個部落格文章網站，以及您想要訂閱新部落格和變更現有的部落格。若要執行此操作，請將以下 Subscription 定義新增至結構描述：

type Subscription {
    addedPost: Post
    updatedPost: Post
    deletedPost: Post
}

假設您有以下變動：

type Mutation {
    addPost(id: ID! author: String! title: String content: String url: String): Post!
    updatePost(id: ID! author: String! title: String content: String url: String ups: Int! downs: Int! expectedVersion: Int!): Post!
    deletePost(id: ID!): Post!
}

您可以透過為您希望接收通知的每個訂閱新增 @aws_subscribe(mutations: ["mutation_field_1", "mutation_field_2"]) 指示 (如下所示) 讓這些欄位變得即時：

type Subscription {
    addedPost: Post
    @aws_subscribe(mutations: ["addPost"])
    updatedPost: Post
    @aws_subscribe(mutations: ["updatePost"])
    deletedPost: Post
    @aws_subscribe(mutations: ["deletePost"])
}

由於 @aws_subscribe(mutations: ["",..,""])會採用突變輸入陣列，因此您可以指定多個突變，以啟動訂閱。如果您是從用戶端進行訂閱，您的 GraphQL 查詢可能如下所示：

subscription NewPostSub {
    addedPost {
        __typename
        version
        title
        content
        author
        url
    }
}

用戶端連線和工具需要此訂閱查詢。

使用純 WebSockets 用戶端時，每個用戶端都會完成選取集篩選，因為每個用戶端都可以定義自己的選取集。在此情況下，訂閱選項集必須是變動選項集的子集。例如，連結至變動 addPost(...){id author title url version} 的訂閱 addedPost{author title} 僅接收文章的作者和標題。而沒有接收其他欄位。但是，如果變動缺少其選項集中的作者，則訂閱者將取得作者欄位的 null 值 (或者如果作者欄位在結構描述中被定義為必要/非 null，則會出現錯誤)。

使用純 時，訂閱選擇集至關重要 WebSockets。如果訂閱中未明確定義欄位，則 AWS AppSync 不會傳回 欄位。

在上述範例中，訂閱沒有引數。假設您的結構描述看起來如下所示：

type Subscription {
    updatedPost(id:ID! author:String): Post
    @aws_subscribe(mutations: ["updatePost"])
}

在此情況下，您的用戶端定義訂閱如下：

subscription UpdatedPostSub {
    updatedPost(id:"XYZ", author:"ABC") {
        title
        content
    }
}

在結構描述 subscription 欄位的傳回類型必須與對應變動欄位的傳回類型相符。在上述範例中，這是以 addPost 類型形式傳回做為 addedPost 和 Post 而顯示。

若要在用戶端上設定訂閱，請參閱 使用 Amplify 用戶端建置用戶端應用程式。

使用訂閱引數

使用 GraphQL 訂閱的重要部分是了解何時及如何使用引數。您可以進行細微的變更，以修改通知客戶已發生突變的方式和時間。若要執行此操作，請參閱快速入門章節的範例結構描述，該章節會建立「待辦事項」。對於此範例結構描述，定義了下列突變：

type Mutation {
    createTodo(input: CreateTodoInput!): Todo
    updateTodo(input: UpdateTodoInput!): Todo
    deleteTodo(input: DeleteTodoInput!): Todo
}

在預設範例中，用戶端可以使用無引數TodoonUpdateTodosubscription的 訂閱任何 的更新：

subscription OnUpdateTodo {
  onUpdateTodo {
    description
    id
    name
    when
  }
}

您可以使用 的引數subscription來篩選 。例如，若要僅在更新todo具有特定 ID的 subscription時觸發 ，請指定 ID值：

subscription OnUpdateTodo {
  onUpdateTodo(id: "a-todo-id") {
    description
    id
    name
    when
  }
}

您也可以傳遞多個引數。例如，以下subscription示範如何在特定地點和時間收到任何Todo更新的通知：

subscription todosAtHome {
  onUpdateTodo(when: "tomorrow", where: "at home") {
    description
    id
    name
    when
    where
  }
}

請注意，所有引數都是選用的。如果您未在 中指定任何引數subscription，則會訂閱應用程式內發生的所有Todo更新。不過，您可以更新 subscription的欄位定義，以要求 ID引數。這將強制特定 的回應，todo而不是所有 todo的回應：

onUpdateTodo(
  id: ID!,
  name: String,
  when: String,
  where: String,
  description: String
): Todo

引數 Null 值具有意義

在 中提出訂閱查詢時 AWS AppSync，null引數值會篩選結果，與完全忽略引數不同。

讓我們回到待辦事項API範例，在這裡我們可以建立待辦事項。請參閱快速入門章節的範例結構描述。

讓我們修改結構描述，在 Todo 類型上包含一個新owner欄位，描述擁有者是誰。欄位不是必要owner欄位，只能在 上設定UpdateTodoInput。請參閱下列簡化的結構描述版本：

type Todo {
  id: ID!
  name: String!
  when: String!
  where: String!
  description: String!
  owner: String
}

input CreateTodoInput {
  name: String!
  when: String!
  where: String!
  description: String!
}

input UpdateTodoInput {
  id: ID!
  name: String
  when: String
  where: String
  description: String
  owner: String
}

type Subscription {
    onUpdateTodo(
        id: ID,
        name: String,
        when: String,
        where: String,
        description: String
    ): Todo @aws_subscribe(mutations: ["updateTodo"])
}

下列訂閱會傳回所有Todo更新：

subscription MySubscription {
  onUpdateTodo {
    description
    id
    name
    when
    where
  }
}

如果您修改上述訂閱以新增欄位引數 owner: null，您現在會提出不同的問題。此訂閱現在會註冊用戶端，以收到尚未提供擁有者的所有Todo更新通知。

subscription MySubscription {
  onUpdateTodo(owner: null) {
    description
    id
    name
    when
    where
  }
}