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

# 在 中使用即時資料應用程式的訂閱 AWS AppSync
<a name="aws-appsync-real-time-data"></a>

**重要**  
自 2025 年 3 月 13 日起，您可以使用 AWS AppSync Events 建置由 WebSockets 支援的即時 PubSub API。如需詳細資訊，請參閱《AppSync Events 開發人員指南》中的[透過 WebSocket 發佈](https://docs.aws.amazon.com/appsync/latest/eventapi/publish-websocket.html)事件。 *AWS AppSync *

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

## GraphQL 結構描述訂閱指令
<a name="graphql-schema-subscription-directives"></a>

訂閱 in AWS AppSync 被調用為對變動的回應。這表示您可以在變動上指定 GraphQL 結構描述指令，讓任何資料來源 in AWS AppSync 即時。

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

**注意**  
若要控制訂閱的連線時間授權，您可以使用 AWS Identity and Access Management (IAM) AWS Lambda、Amazon Cognito 身分集區或 Amazon Cognito 使用者集區進行欄位層級授權。對於訂閱的精細存取控制，您可以將解析程式連接至訂閱欄位，並使用發起人身分和 AWS AppSync 資料來源執行邏輯。如需詳細資訊，請參閱[設定授權和身分驗證來保護 GraphQL APIs](security-authz.md)。

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

以下範例示範如何使用 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 用戶端建置用戶端應用程式](building-a-client-app.md)。

## 使用訂閱引數
<a name="using-subscription-arguments"></a>

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

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

在預設範例中，用戶端可以使用`Todo``onUpdateTodo``subscription`沒有引數的 訂閱任何 的更新：

```
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 值具有意義
<a name="argument-null-value-has-meaning"></a>

進行訂閱查詢 in 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
  }
}
```

**注意**  
**自 2022 年 1 月 1 日起，MQTT over WebSockets 不再提供做為 GraphQL 訂閱 AWS AppSync APIs通訊協定。Pure WebSockets 是 中唯一支援的通訊協定 AWS AppSync。**  
以 AWS AppSync SDK 或 Amplify 程式庫為基礎的用戶端，在 2019 年 11 月之後發行，預設會自動使用純 WebSockets 將用戶端升級至最新版本可讓用戶端使用 AWS AppSync純 WebSockets 引擎。  
Pure WebSockets 隨附更大的承載大小 (240 KB)、更廣泛的用戶端選項，以及改善的 CloudWatch 指標。如需使用純 WebSocket 用戶端的詳細資訊，請參閱 [建置即時 WebSocket 用戶端 in AWS AppSync](real-time-websocket-client.md)。