Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Mendefinisikan filter langganan yang disempurnakan di AWS AppSync

Di AWS AppSync, Anda dapat menentukan dan mengaktifkan logika bisnis untuk pemfilteran data di backend langsung di resolver langganan GraphQL API dengan menggunakan filter yang mendukung operator logis tambahan. Anda dapat mengonfigurasi filter ini, tidak seperti argumen langganan yang ditentukan pada kueri langganan di klien. Untuk informasi selengkapnya tentang menggunakan argumen langganan, lihatMenggunakan argumen langganan. Untuk daftar operator, lihatAWS AppSync referensi utilitas template pemetaan resolver.

Untuk tujuan dokumen ini, kami membagi pemfilteran data real-time ke dalam kategori berikut:

Bagian berikut menjelaskan cara mengonfigurasi filter langganan yang disempurnakan dan menunjukkan penggunaan praktisnya.

Mendefinisikan langganan dalam skema GraphQL Anda

Untuk menggunakan filter langganan yang disempurnakan, Anda menentukan langganan dalam skema GraphQL lalu menentukan filter yang disempurnakan menggunakan ekstensi pemfilteran. Untuk mengilustrasikan cara kerja penyaringan langganan yang disempurnakan AWS AppSync, gunakan skema GraphQL berikut, yang mendefinisikan API sistem manajemen tiket, sebagai contoh:

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
	

Misalkan Anda membuat sumber NONE data untuk API Anda, lalu melampirkan resolver ke createTicket mutasi menggunakan sumber data ini. Handler Anda mungkin terlihat seperti ini:

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;
}

Untuk mengimplementasikan perilaku filter yang disempurnakan, Anda harus menggunakan extensions.setSubscriptionFilter() fungsi untuk menentukan ekspresi filter yang dievaluasi terhadap data yang dipublikasikan dari mutasi GraphQL yang mungkin diminati oleh klien berlangganan. Untuk informasi selengkapnya tentang ekstensi pemfilteran, lihat Ek stensi.

Bagian berikut menjelaskan cara menggunakan ekstensi penyaringan untuk menerapkan filter yang disempurnakan.

Membuat filter langganan yang disempurnakan menggunakan ekstensi pemfilteran

Filter yang disempurnakan ditulis dalam JSON di handler respons resolver langganan. Filter dapat dikelompokkan bersama dalam daftar yang disebut afilterGroup. Filter didefinisikan menggunakan setidaknya satu aturan, masing-masing dengan bidang, operator, dan nilai. Mari kita tentukan resolver baru untuk onSpecialTicketCreated itu mengatur filter yang disempurnakan. Anda dapat mengonfigurasi beberapa aturan dalam filter yang dievaluasi menggunakan logika AND, sementara beberapa filter dalam grup filter dievaluasi menggunakan logika 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;
}

Berdasarkan filter yang ditentukan dalam contoh sebelumnya, tiket penting secara otomatis didorong ke klien API berlangganan jika tiket dibuat dengan:

ATAU

Filter yang ditentukan dalam penyelesai langganan (pemfilteran yang disempurnakan) lebih diutamakan daripada pemfilteran hanya berdasarkan argumen langganan (pemfilteran dasar). Untuk informasi selengkapnya tentang menggunakan argumen langganan, lihat Menggunakan argumen langganan).

Jika argumen didefinisikan dan diperlukan dalam skema GraphQL dari langganan, pemfilteran berdasarkan argumen yang diberikan hanya terjadi jika argumen didefinisikan sebagai aturan dalam metode resolver. extensions.setSubscriptionFilter() Namun, jika tidak ada metode pem extensions filteran di resolver langganan, argumen yang ditentukan dalam klien hanya digunakan untuk pemfilteran dasar. Anda tidak dapat menggunakan pemfilteran dasar dan penyaringan yang disempurnakan secara bersamaan.

Anda dapat menggunakan context variabel dalam logika ekstensi filter langganan untuk mengakses informasi kontekstual tentang permintaan. Misalnya, saat menggunakan Otorisasi khusus Amazon Cognito User Pools, OIDC, atau Lambda untuk otorisasi, Anda dapat mengambil informasi tentang pengguna context.identity saat langganan dibuat. Anda dapat menggunakan informasi tersebut untuk membuat filter berdasarkan identitas pengguna Anda.

Sekarang asumsikan bahwa Anda ingin menerapkan perilaku filter yang disempurnakan untukonGroupTicketCreated. Lang onGroupTicketCreated ganan membutuhkan group nama wajib sebagai argumen. Saat dibuat, tiket secara otomatis diberi pending status. Anda dapat mengatur filter langganan untuk hanya menerima tiket yang baru dibuat milik grup yang disediakan:

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;
}

Ketika data dipublikasikan menggunakan mutasi seperti pada contoh berikut:

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

Klien berlangganan mendengarkan data yang akan didorong secara otomatis WebSockets segera setelah tiket dibuat dengan createTicket mutasi:

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

Klien dapat berlangganan tanpa argumen karena logika penyaringan diimplementasikan dalam AWS AppSync layanan dengan pemfilteran yang ditingkatkan, yang menyederhanakan kode klien. Klien menerima data hanya jika kriteria filter yang ditentukan terpenuhi.

Mendefinisikan filter yang disempurnakan untuk bidang skema bersarang

Anda dapat menggunakan pemfilteran langganan yang disempurnakan untuk memfilter bidang skema bersarang. Misalkan kita memodifikasi skema dari bagian sebelumnya untuk menyertakan jenis lokasi dan alamat:

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

Dengan skema ini, Anda dapat menggunakan . pemisah untuk mewakili bersarang. Contoh berikut menambahkan aturan filter untuk bidang skema bersarang di bawahlocation.address.country. Langganan akan dipicu jika alamat tiket diatur keUSA:

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;
}

Dalam contoh di atas, location mewakili tingkat sarang satu, address mewakili tingkat bersarang dua, dan country mewakili tingkat bersarang tiga, yang semuanya dipisahkan oleh pem . isah.

Anda dapat menguji langganan ini dengan menggunakan createTicket mutasi:

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

Mendefinisikan filter yang disempurnakan dari klien

Anda dapat menggunakan pemfilteran dasar di GraphQL dengan argum https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-real-time-data.html#using-subscription-arguments en langganan. Klien yang membuat panggilan dalam kueri langganan mendefinisikan nilai-nilai argumen. Ketika filter yang disempurnakan diaktifkan di resolver AWS AppSync langganan dengan pem extensions filteran, filter backend yang ditentukan dalam resolver diutamakan dan diprioritaskan.

Konfigurasikan filter dinamis yang disempurnakan yang ditentukan klien menggunakan filter argumen dalam langganan. Saat Anda mengkonfigurasi filter ini, Anda harus memperbarui skema GraphQL untuk mencerminkan argumen baru:

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

Klien kemudian dapat mengirim kueri langganan seperti dalam contoh berikut:

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

Anda dapat mengonfigurasi variabel query seperti contoh berikut:

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

Utilitas util.transform.toSubscriptionFilter() resolver dapat diimplementasikan dalam template pemetaan respons langganan untuk menerapkan filter yang ditentukan dalam argumen langganan untuk setiap klien:

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;
}

Dengan strategi ini, klien dapat menentukan filter mereka sendiri yang menggunakan logika penyaringan yang disempurnakan dan operator tambahan. Filter ditetapkan ketika klien tertentu memanggil kueri langganan dalam koneksi aman WebSocket . Untuk informasi selengkapnya tentang utilitas transformasi untuk pemfilteran yang disempurnakan, termasuk format payload variabel filter kueri, lihat ikhtisar JavaScript resolver.

Pembatasan penyaringan tambahan yang ditingkatkan

Di bawah ini adalah beberapa kasus penggunaan di mana pembatasan tambahan ditempatkan pada filter yang disempurnakan: