即時資料

AWS AppSync允許您使用訂閱來實現實時應用程序更新，推送通知等。當用戶端叫用 GraphQL 訂閱作業時，會由 AWS AppSync. WebSocket 然後，應用程式可以從資料來源即時將資料分發給訂閱者，同時AWS AppSync 持續管理應用程式的連線和擴展需求。以下部分將向您展示訂閱的AWS AppSync工作方式。

結 GraphQL 述訂閱指令

會呼叫 AWS AppSync 中的訂閱做為變動的回應。這表示您可以透過對變動指定 GraphQL 結構描述指令來在 AWS AppSync 中即時製作任何資料來源。

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

注意

若要在連線到訂閱時控制授權，您可以使用 AWS Identity and Access Management (IAM) AWS Lambda、Amazon Cognito 身分集區或 Amazon Cognito 使用者集區進行欄位層級授權。若要對訂閱進行精細分級的存取控制，您可以將解析程式連接至訂閱欄位，並使用呼叫者的身分和 AWS AppSync 資料來源來執行邏輯。如需詳細資訊，請參閱授權與驗證。

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

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

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

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，則會出現錯誤)。

使用 pure 時，訂閱選擇組是必不可少的 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 而顯示。

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

使用訂閱引數

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

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

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

subscription OnUpdateTodo {
  onUpdateTodo {
    description
    id
    name
    when
  }
}

您可以使用其參數subscription來篩選您的。例如，要僅在更新具todo有特ID定功能的subscription時候觸發 a，請指定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 s 的響應：

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

引數 Null 值具有意義

在 AWS AppSync 中進行訂閱查詢時，null 引數值與整個忽略該引數時的情況不同，會以不同方式篩選結果。

讓我們回到待辦事項 API 示例，我們可以創建待辦事項。請參閱快速入門一章中的範例結構描述。

讓我們修改我們的模式，以包括一個新的ownerTodo字段，描述誰是所有者。此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 以上 WebSockets 版本已不再作為 API 中 GraphQL 訂閱的通訊協定提供。AWS AppSyncPure WebSockets 是中唯一支援的通訊協定AWS AppSync。

2019 年 11 月之後發行的 AWS AppSync SDK 或 Amplify 程式庫的用戶端會自動使用純 WebSockets 預設值。將客戶端升級到最新版本允許他們使用AWS AppSync的純 WebSockets 引擎。

Pure 具 WebSockets 有更大的承載大小（240 KB），更多種客戶端選項以及改進的 CloudWatch 指標。如需使用純用 WebSocket 戶端的詳細資訊，請參閱建立即時 WebSocket 用戶端。