在中定義增強型訂閱篩選條件 AWS AppSync

焦點模式

在中定義增強型訂閱篩選條件 AWS AppSync - AWS AppSync GraphQL

定義訂閱建立增強型訂閱篩選條件定義巢狀結構描述欄位的增強型篩選條件從用戶端定義增強型篩選條件其他增強型篩選限制

在中 AWS AppSync，您可以使用支援其他邏輯運算子的篩選條件，直接在 GraphQL API 訂閱解析程式中定義和啟用後端資料篩選的商業邏輯。您可以設定這些篩選條件，與用戶端中訂閱查詢上定義的訂閱引數不同。如需使用訂閱引數的詳細資訊，請參閱使用訂閱引數。如需運算子清單，請參閱AWS AppSync 解析程式映射範本公用程式參考。

基於本文件的目的，我們會將即時資料篩選分為下列類別：

基本篩選 - 根據訂閱查詢中的用戶端定義引數進行篩選。
增強型篩選 - 根據 AWS AppSync 服務後端中集中定義的邏輯進行篩選。

以下各節說明如何設定增強型訂閱篩選條件，並顯示其實際用途。

在 GraphQL 結構描述中定義訂閱

若要使用增強型訂閱篩選條件，請在 GraphQL 結構描述中定義訂閱，然後使用篩選延伸來定義增強型篩選條件。若要說明增強型訂閱篩選的運作方式 AWS AppSync，請使用下列 GraphQL 結構描述，其定義票證管理系統 API，例如：


type Ticket {
	id: ID
	createdAt: AWSDateTime
	content: String
	severity: Int
	priority: Priority
	category: String
	group: String
	status: String
	
}

type Mutation {
	createTicket(input: TicketInput): Ticket
}

type Query {
	getTicket(id: ID!): Ticket
}

type Subscription {
	onSpecialTicketCreated: Ticket @aws_subscribe(mutations: ["createTicket"])
	onGroupTicketCreated(group: String!): Ticket @aws_subscribe(mutations: ["createTicket"])
}



enum Priority {
	none
	lowest
	low
	medium
	high
	highest
}

input TicketInput {
	content: String
	severity: Int
	priority: Priority
	category: String
	group: String

假設您為 API 建立NONE資料來源，然後使用此資料來源將解析程式連接至createTicket變動。您的處理常式可能如下所示：


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

export function request(ctx) {
	return {
		payload: {
			id: util.autoId(),
			createdAt: util.time.nowISO8601(),
			status: 'pending',
			...ctx.args.input,
		},
	};
}

export function response(ctx) {
	return ctx.result;
}

注意

增強型篩選條件會在指定訂閱的 GraphQL 解析程式處理常式中啟用。如需詳細資訊，請參閱解析程式參考。

若要實作增強型篩選條件的行為，您必須使用 extensions.setSubscriptionFilter()函數來定義篩選條件表達式，根據訂閱用戶端可能感興趣的 GraphQL 變動所發佈的資料進行評估。如需篩選延伸模組的詳細資訊，請參閱延伸模組。

下一節說明如何使用篩選延伸模組來實作增強型篩選條件。

使用篩選擴充功能建立增強型訂閱篩選條件

增強型篩選條件會在訂閱解析程式的回應處理常式中寫入 JSON。篩選條件可以分組在稱為的清單中filterGroup。篩選條件是使用至少一個規則來定義，每個規則都有欄位、運算子和值。讓我們為定義新的解析程式onSpecialTicketCreated，以設定增強型篩選條件。您可以在使用 AND 邏輯評估的篩選條件中設定多個規則，而篩選群組中的多個篩選條件則使用 OR 邏輯評估：


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 = {
		or: [
			{ severity: { ge: 7 }, priority: { in: ['high', 'medium'] } },
			{ category: { eq: 'security' }, group: { in: ['admin', 'operators'] } },
		],
	};
	extensions.setSubscriptionFilter(util.transform.toSubscriptionFilter(filter));

  // important: return null in the response
	return null;
}

根據上述範例中定義的篩選條件，如果票證是以下列方式建立，則會自動將重要票證推送至訂閱的 API 用戶端：

priority 關卡high或 medium

AND
severity 層級大於或等於 7(ge)

或

classification 票證設定為 Security

AND
group 指派設定為 admin或 operators

訂閱解析程式中定義的篩選條件（增強型篩選）優先於僅根據訂閱引數（基本篩選）進行篩選。如需使用訂閱引數的詳細資訊，請參閱使用訂閱引數)。

如果在訂閱的 GraphQL 結構描述中定義了引數且需要，則只有在引數在解析程式的 extensions.setSubscriptionFilter()方法中定義為規則時，才會根據指定的引數進行篩選。不過，如果訂閱解析程式中沒有extensions篩選方法，則用戶端中定義的引數只會用於基本篩選。您無法同時使用基本篩選和增強型篩選。

您可以使用訂閱篩選條件延伸邏輯中的 context變數來存取請求的相關內容資訊。例如，使用 Amazon Cognito 使用者集區、OIDC 或 Lambda 自訂授權方進行授權時，您可以在建立訂閱context.identity時擷取中使用者的相關資訊。您可以使用該資訊，根據使用者身分建立篩選條件。

現在假設您想要實作的增強型篩選條件行為onGroupTicketCreated。onGroupTicketCreated 訂閱需要強制group名稱做為引數。建立時，票證會自動指派pending狀態。您可以設定訂閱篩選條件，以僅接收屬於所提供群組的新建立票證：


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 = { group: { eq: ctx.args.group }, status: { eq: 'pending' } };
	extensions.setSubscriptionFilter(util.transform.toSubscriptionFilter(filter));

	return null;
}

使用如下範例中的變動發佈資料時：


mutation CreateTicket {
  createTicket(input: {priority: medium, severity: 2, group: "aws"}) {
    id
    priority
    severity
    status
    group
    createdAt
  }
}

訂閱的用戶端會在建立具有 createTicket 變動的票證時，監聽透過 WebSockets 自動推送的資料：


subscription OnGroup {
  onGroupTicketCreated(group: "aws") {
    category
    status
    severity
    priority
    id
    group
    createdAt
    content
  }
}

用戶端無需引數即可訂閱，因為篩選邏輯是在 AWS AppSync 服務中實作，並具有增強型篩選功能，可簡化用戶端程式碼。只有在符合定義的篩選條件時，用戶端才會接收資料。

定義巢狀結構描述欄位的增強型篩選條件

您可以使用增強型訂閱篩選來篩選巢狀結構描述欄位。假設我們修改了上一節的結構描述，以包含位置和地址類型：


type Ticket {
	id: ID
	createdAt: AWSDateTime
	content: String
	severity: Int
	priority: Priority
	category: String
	group: String
	status: String
	location: ProblemLocation
}

type Mutation {
	createTicket(input: TicketInput): Ticket
}

type Query {
	getTicket(id: ID!): Ticket
}

type Subscription {
	onSpecialTicketCreated: Ticket @aws_subscribe(mutations: ["createTicket"])
	onGroupTicketCreated(group: String!): Ticket @aws_subscribe(mutations: ["createTicket"])
}

type ProblemLocation {
	address: Address
}

type Address {
	country: String
}

enum Priority {
	none
	lowest
	low
	medium
	high
	highest
}

input TicketInput {
	content: String
	severity: Int
	priority: Priority
	category: String
	group: String
	location: AWSJSON

透過此結構描述，您可以使用.分隔符號來表示巢狀。下列範例會在下新增巢狀結構描述欄位的篩選條件規則location.address.country。如果票證的地址設定為，則會觸發訂閱USA：


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

export const request = (ctx) => ({ payload: null });

export function response(ctx) {
	const filter = {
		or: [
			{ severity: { ge: 7 }, priority: { in: ['high', 'medium'] } },
			{ category: { eq: 'security' }, group: { in: ['admin', 'operators'] } },
			{ 'location.address.country': { eq: 'USA' } },
		],
	};
	extensions.setSubscriptionFilter(util.transform.toSubscriptionFilter(filter));
	return null;
}

在上述範例中， location代表巢狀層級一， address 代表巢狀層級二， country代表巢狀層級三，所有這些都是由.分隔符號分隔。

您可以使用 createTicket變動來測試此訂閱：


mutation CreateTicketInUSA {
  createTicket(input: {location: "{\"address\":{\"country\":\"USA\"}}"}) {
    category
    content
    createdAt
    group
    id
    location {
      address {
        country
      }
    }
    priority
    severity
    status
  }
}

從用戶端定義增強型篩選條件

您可以在 GraphQL 中使用基本篩選搭配訂閱引數。在訂閱查詢中進行呼叫的用戶端會定義引數的值。在具有extensions篩選條件的 AWS AppSync 訂閱解析程式中啟用增強型篩選條件時，解析程式中定義的後端篩選條件優先且優先。

使用訂閱中的filter引數設定動態、用戶端定義的增強型篩選條件。當您設定這些篩選條件時，必須更新 GraphQL 結構描述以反映新的引數：


...
type Subscription {
    onSpecialTicketCreated(filter: String): Ticket
        @aws_subscribe(mutations: ["createTicket"])
}
...

然後，用戶端可以傳送訂閱查詢，如下列範例所示：


subscription onSpecialTicketCreated($filter: String) {
     onSpecialTicketCreated(filter: $filter) {
        id
        group
        description
        priority
        severity
     }
 }

您可以設定查詢變數，如下所示：


{"filter" : "{\"severity\":{\"le\":2}}"}

您可以在訂閱回應映射範本中實作util.transform.toSubscriptionFilter()解析程式公用程式，以套用每個用戶端訂閱引數中定義的篩選條件：


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 = ctx.args.filter;
	extensions.setSubscriptionFilter(util.transform.toSubscriptionFilter(filter));
	return null;
}

透過此策略，用戶端可以定義自己的篩選條件，使用增強型篩選邏輯和其他運算子。當指定的用戶端在安全的 WebSocket 連線中調用訂閱查詢時，會指派篩選條件。如需增強型篩選的轉換公用程式的詳細資訊，包括filter查詢變數承載的格式，請參閱 JavaScript 解析程式概觀。

其他增強型篩選限制

以下是幾個使用案例，其中在增強型篩選條件上設定了額外的限制：

增強型篩選條件不支援篩選最上層物件清單。在此使用案例中，來自變動的已發佈資料將忽略增強型訂閱。

AWS AppSync 最多支援五個巢狀層級。將忽略巢狀層級 5 以上結構描述欄位的篩選條件。採取以下 GraphQL 回應。允許中的 continent 欄位，venue.address.country.metadata.continent因為它是層級 5 巢狀。不過， financial venue.address.country.metadata.capital.financial是第六層巢狀，因此篩選條件無法運作：


{
    "data": {
        "onCreateFilterEvent": {
            "venue": {
                "address": {
                    "country": {
                        "metadata": {
                            "capital": {
                                "financial": "New York"
                            },
                            "continent" : "North America"
                        }
                    },
                    "state": "WA"
                },
                "builtYear": 2023
            },
            "private": false,
        }
    }
}

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

建立由無伺服器 WebSockets 提供支援的一般 pub/sub APIs

使用篩選條件取消訂閱 WebSocket 連線

在本頁面

選取您的 Cookie 偏好設定

自訂 Cookie 偏好設定

必要

效能

功能

廣告

無法儲存 Cookie 偏好設定

在中定義增強型訂閱篩選條件 AWS AppSync

在 GraphQL 結構描述中定義訂閱

注意

使用篩選擴充功能建立增強型訂閱篩選條件

定義巢狀結構描述欄位的增強型篩選條件

從用戶端定義增強型篩選條件

其他增強型篩選限制

在本頁面

此頁面是否有幫助？

下一個主題：

上一個主題：

需要協助？

顯示票證篩選查詢的範例

選取您的 Cookie 偏好設定

在 中定義增強型訂閱篩選條件 AWS AppSync

在 GraphQL 結構描述中定義訂閱

注意

使用篩選擴充功能建立增強型訂閱篩選條件

定義巢狀結構描述欄位的增強型篩選條件

從用戶端定義增強型篩選條件

其他增強型篩選限制

在本頁面

此頁面是否有幫助？

下一個主題：

上一個主題：

需要協助？

在中定義增強型訂閱篩選條件 AWS AppSync