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 API langganan GraphQL 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 penggunaan argumen langganan, lihatMenggunakan argumen berlangganan. 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 tentukan filter yang disempurnakan menggunakan ekstensi pemfilteran. Untuk mengilustrasikan cara kerja penyaringan langganan yang disempurnakan AWS AppSync, gunakan skema GraphQL berikut, yang mendefinisikan sistem manajemen tiket, sebagai contoh: 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
	

Misalkan Anda membuat sumber NONE data untuk AndaAPI, lalu lampirkan resolver ke createTicket mutasi menggunakan sumber data ini. Penangan 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 tersebut 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 Ekstensi.

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

Membuat filter langganan yang disempurnakan menggunakan ekstensi penyaringan

Filter yang disempurnakan ditulis JSON dalam penangan 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 menyiapkan filter yang disempurnakan. Anda dapat mengonfigurasi beberapa aturan dalam filter yang dievaluasi menggunakan AND logika, 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 API klien berlangganan jika tiket dibuat dengan:

ATAU

Filter yang didefinisikan dalam resolver langganan (penyaringan yang ditingkatkan) lebih diutamakan daripada pemfilteran hanya berdasarkan argumen langganan (pemfilteran dasar). Untuk informasi selengkapnya tentang penggunaan argumen langganan, lihat Menggunakan argumen langganan).

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

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

Sekarang asumsikan bahwa Anda ingin menerapkan perilaku filter yang disempurnakan untukonGroupTicketCreated. onGroupTicketCreatedLangganan 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 penyaringan 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 memasukkan 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 bawah. location.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 bersarang satu, address mewakili tingkat bersarang dua, dan country mewakili tingkat bersarang tiga, yang semuanya dipisahkan oleh pemisah. .

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 argumen langganan. Klien yang membuat panggilan dalam kueri langganan mendefinisikan nilai argumen. Saat filter yang disempurnakan diaktifkan di resolver AWS AppSync langganan dengan extensions pemfilteran, filter backend yang ditentukan dalam resolver akan diutamakan dan diprioritaskan.

Konfigurasikan filter dinamis yang ditingkatkan yang ditentukan klien menggunakan filter argumen dalam langganan. Saat Anda mengonfigurasi 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 pada contoh berikut:

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

Anda dapat mengkonfigurasi 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 WebSocket koneksi aman. Untuk informasi selengkapnya tentang utilitas transformasi untuk penyaringan 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: