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

使用 中的篩選條件取消訂閱 WebSocket 連線 AWS AppSync

在 中 AWS AppSync，您可以根據特定篩選邏輯強制取消訂閱並關閉 （驗證） WebSocket 已連線用戶端的連線。這在授權相關案例中非常有用，例如當您從群組中移除使用者時。

訂閱失效是回應突變中定義的承載而發生。我們建議您將用於使訂閱連線失效的突變視為 API和範圍許可中的管理操作，方法是將其使用限制為管理員使用者、群組或後端服務。例如，使用結構描述授權指令，例如 @aws_auth(cognito_groups: ["Administrators"])或 @aws_iam。如需詳細資訊，請參閱使用其他授權模式。

無效篩選條件使用與增強型訂閱篩選條件相同的語法和邏輯。使用以下公用程式定義這些篩選條件：

如需失效篩選延伸模組的詳細資訊，請參閱JavaScript 解析程式概觀 。

使用訂閱失效

若要查看訂閱失效如何在 中運作 AWS AppSync，請使用下列 GraphQL 結構描述：

type User {
  userId: ID!
  groupId: ID!
}
    
type Group {
  groupId: ID!
  name: String!
  members: [ID!]!
}

type GroupMessage {
  userId: ID!
  groupId: ID!
  message: String!
}

type Mutation {
    createGroupMessage(userId: ID!, groupId : ID!, message: String!): GroupMessage
    removeUserFromGroup(userId: ID!, groupId : ID!) : User @aws_iam
}

type Subscription {
    onGroupMessageCreated(userId: ID!, groupId : ID!): GroupMessage
        @aws_subscribe(mutations: ["createGroupMessage"])
}

type Query {
	none: String
}

在removeUserFromGroup突變解析程式程式碼中定義失效篩選條件：

import { extensions } from '@aws-appsync/utils';

export function request(ctx) {
	return { payload: null };
}

export function response(ctx) {
	const { userId, groupId } = ctx.args;
	extensions.invalidateSubscriptions({
		subscriptionField: 'onGroupMessageCreated',
		payload: { userId, groupId },
	});
	return { userId, groupId };
}

調用突變時，payload物件中定義的資料會用來取消訂閱 中定義的訂閱subscriptionField。失效篩選條件也會在onGroupMessageCreated訂閱的回應映射範本中定義。

如果extensions.invalidateSubscriptions()承載包含符合篩選條件中定義的訂閱用戶端IDs的 ID，則會取消訂閱對應的訂閱。此外， WebSocket 連線已關閉。定義訂閱的onGroupMessageCreated訂閱解析程式程式碼：

import { util, extensions } from '@aws-appsync/utils';

export function request(ctx) {
	// simplfy return null for the payload
	return { payload: null };
}

export function response(ctx) {
	const filter = { groupId: { eq: ctx.args.groupId } };
	extensions.setSubscriptionFilter(util.transform.toSubscriptionFilter(filter));

	const invalidation = { groupId: { eq: ctx.args.groupId }, userId: { eq: ctx.args.userId } };
	extensions.setSubscriptionInvalidationFilter(util.transform.toSubscriptionFilter(invalidation));

	return null;
}

請注意，訂閱回應處理常式可以同時定義訂閱篩選條件和失效篩選條件。

例如，假設用戶端 A group-1使用下列訂閱請求，將 ID 為 的新使用者訂閱user-1至 ID 為 的群組：

onGroupMessageCreated(userId : "user-1", groupId: :"group-1"){...}

AWS AppSync 會執行訂閱解析程式，其會產生訂閱和失效篩選條件，如上述onGroupMessageCreated回應映射範本所定義。對於用戶端 A，訂閱篩選條件僅允許將資料傳送至 group-1，並同時為 user-1和 定義失效篩選條件group-1。

現在假設用戶端 B group-2使用下列訂閱請求，將 ID 為 的使用者訂閱user-2至 ID 為 的群組：

onGroupMessageCreated(userId : "user-2", groupId: :"group-2"){...}

AWS AppSync 會執行訂閱解析程式，產生訂閱和失效篩選條件。對於用戶端 B，訂閱篩選條件僅允許將資料傳送至 group-2，並同時為 user-2和 定義失效篩選條件group-2。

接下來，假設具有 ID 的新群組訊息message-1是使用突變請求建立的，如下列範例所示：

createGroupMessage(id: "message-1", groupId :
      "group-1", message: "test message"){...}

符合定義篩選條件的訂閱用戶端會透過 自動接收下列資料承載 WebSockets：

{
  "data": {
    "onGroupMessageCreated": {
      "id": "message-1",
      "groupId": "group-1",
      "message": "test message",
    }
  }
}

用戶端 A 會收到訊息，因為篩選條件符合定義的訂閱篩選條件。不過，用戶端 B 不會收到訊息，因為使用者不屬於 的一部分group-1。此外，請求與訂閱解析程式中定義的訂閱篩選條件不相符。

最後，假設 user-1 group-1已從使用下列突變請求移除：

removeUserFromGroup(userId: "user-1", groupId : "group-1"){...}

該突變會如其extensions.invalidateSubscriptions()解析程式回應處理常式程式碼所定義啟動訂閱失效。 AWS AppSync 然後取消訂閱用戶端 A 並關閉其 WebSocket 連線。用戶端 B 不受影響，因為突變中定義的無效承載與其使用者或群組不相符。

當連線 AWS AppSync 失效時，用戶端會收到確認已取消訂閱的訊息：

{
  "message": "Subscription complete."
}

在訂閱失效篩選條件中使用內容變數

與增強型訂閱篩選條件一樣，您可以在訂閱失效篩選條件延伸中使用 context 變數來存取特定資料。

例如，可以將電子郵件地址設定為突變中的無效承載，然後比對該電子郵件地址與使用 Amazon Cognito 使用者集區或 OpenID Connect 授權之訂閱使用者的電子郵件屬性或宣告。extensions.setSubscriptionInvalidationFilter() 訂閱無效器中定義的無效篩選條件會檢查由突變extensions.invalidateSubscriptions()承載設定的電子郵件地址是否與 中使用者JWT權杖擷取的電子郵件地址相符context.identity.claims.email，進而啟動無效。