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
**penting**
Mulai 13 Maret 2025, Anda dapat membangun PubSub API real-time yang didukung dengan WebSockets menggunakan AWS AppSync Acara. Untuk informasi selengkapnya, lihat [Mempublikasikan acara melalui WebSocket](https://docs.aws.amazon.com/appsync/latest/eventapi/publish-websocket.html) *Panduan Pengembang AWS AppSync Acara*.
Di AWS AppSync, Anda dapat menentukan dan mengaktifkan logika bisnis untuk pemfilteran data di backend secara 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 penggunaan argumen langganan, lihat[Menggunakan argumen berlangganan](aws-appsync-real-time-data.md#using-subscription-arguments). Untuk daftar operator, lihat[AWS AppSync referensi utilitas template pemetaan resolver](resolver-util-reference.md).
Untuk tujuan dokumen ini, kami membagi pemfilteran data real-time ke dalam kategori berikut:
+ **Pemfilteran dasar** - Pemfilteran berdasarkan argumen yang ditentukan klien dalam kueri langganan.
+ **Penyaringan yang disempurnakan** - Pemfilteran berdasarkan logika yang didefinisikan secara terpusat di backend layanan. AWS AppSync
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 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 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;
}
```
**catatan**
Filter yang disempurnakan diaktifkan di handler GraphQL resolver dalam langganan tertentu. Untuk informasi selengkapnya, lihat [Referensi Resolver](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html).
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](https://docs.aws.amazon.com//appsync/latest/devguide/extensions-js.html).
Bagian berikut menjelaskan cara menggunakan ekstensi penyaringan untuk mengimplementasikan filter yang disempurnakan.
## Membuat filter langganan yang disempurnakan menggunakan ekstensi penyaringan
Filter yang disempurnakan ditulis dalam JSON di handler respons dari resolver langganan. Filter dapat dikelompokkan bersama dalam daftar yang disebut a`filterGroup`. 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 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:
+ `priority`tingkat `high` atau `medium`
DAN
+ `severity`tingkat lebih besar dari atau sama dengan `7` (`ge`)
ATAU
+ `classification`tiket diatur ke `Security`
DAN
+ `group`penugasan diatur ke `admin` atau `operators`
![\[Contoh yang menunjukkan kueri pemfilteran tiket\]](http://docs.aws.amazon.com/id_id/appsync/latest/devguide/images/aws-priority-example.png)
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](https://docs.aws.amazon.com//appsync/latest/devguide/aws-appsync-real-time-data.html#using-subscription-arguments)).
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 [`context`variabel](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-context-reference-js.html) dalam logika ekstensi filter langganan untuk mengakses informasi kontekstual tentang permintaan. Misalnya, saat menggunakan Amazon Cognito User Pools, OIDC, atau otorisasi kustom 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 untuk`onGroupTicketCreated`. `onGroupTicketCreated`Langganan 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 ke`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;
}
```
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.](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-real-time-data.html#using-subscription-arguments) 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 [JavaScriptresolver](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html).
## Pembatasan penyaringan tambahan yang ditingkatkan
Di bawah ini adalah beberapa kasus penggunaan di mana pembatasan tambahan ditempatkan pada filter yang disempurnakan:
+ Filter yang disempurnakan tidak mendukung pemfilteran untuk daftar objek tingkat atas. Dalam kasus penggunaan ini, data yang dipublikasikan dari mutasi akan diabaikan untuk langganan yang ditingkatkan.
+ AWS AppSync mendukung hingga lima tingkat bersarang. Filter pada bidang skema melewati tingkat lima bersarang akan diabaikan. Ambil respons GraphQL di bawah ini. `continent`Bidang di `venue.address.country.metadata.continent` diperbolehkan karena itu adalah sarang tingkat lima. Namun, `financial` in `venue.address.country.metadata.capital.financial` adalah sarang level enam, jadi filter tidak akan berfungsi:
```
{
"data": {
"onCreateFilterEvent": {
"venue": {
"address": {
"country": {
"metadata": {
"capital": {
"financial": "New York"
},
"continent" : "North America"
}
},
"state": "WA"
},
"builtYear": 2023
},
"private": false,
}
}
}
```