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

AWS AppSync ikhtisar templat pemetaan resolver

AWS AppSync memungkinkan Anda menanggapi permintaan GraphQL dengan melakukan operasi pada sumber daya Anda. Untuk setiap bidang GraphQL yang ingin Anda jalankan kueri atau mutasi, resolver harus dilampirkan untuk berkomunikasi dengan sumber data. Komunikasi biasanya melalui parameter atau operasi yang unik untuk sumber data.

Resolver adalah konektor antara GraphQL dan sumber data. Mereka memberi tahu AWS AppSync cara menerjemahkan permintaan GraphQL yang masuk ke dalam instruksi untuk sumber data backend Anda, dan cara menerjemahkan respons dari sumber data itu kembali ke respons GraphQL. Mereka ditulis dalam Apache Velocity Template Language (VTL), yang mengambil permintaan Anda sebagai input dan mengeluarkan dokumen JSON yang berisi instruksi untuk resolver. Anda dapat menggunakan template pemetaan untuk instruksi sederhana, seperti meneruskan argumen dari bidang GraphQL, atau untuk instruksi yang lebih kompleks, seperti mengulang argumen untuk membangun item sebelum memasukkan item ke DynamoDB.

Ada dua jenis resolver AWS AppSync yang memanfaatkan template pemetaan dengan cara yang sedikit berbeda:

Penyelesai unit

Unit resolver adalah entitas mandiri yang menyertakan template permintaan dan respons saja. Gunakan ini untuk operasi tunggal yang sederhana seperti daftar item dari satu sumber data.

Penyelesai pipa

Penyelesai pipa berisi satu atau lebih fungsi yang dilakukan secara berurutan. Setiap fungsi mencakup template permintaan dan template respons. Resolver pipeline juga memiliki template sebelum dan template setelah yang mengelilingi urutan fungsi yang berisi template. Template setelah memetakan ke jenis keluaran bidang GraphQL. Resolver pipa berbeda dari resolver unit dalam cara template respons memetakan output. Resolver pipeline dapat memetakan ke output apa pun yang Anda inginkan, termasuk input untuk fungsi lain atau template setelah resolver pipeline.

Fungsi penyelesai pipa memungkinkan Anda menulis logika umum yang dapat Anda gunakan kembali di beberapa resolver dalam skema Anda. Fungsi dilampirkan langsung ke sumber data, dan seperti unit resolver, berisi format template pemetaan permintaan dan respons yang sama.

Diagram berikut menunjukkan aliran proses resolver unit di sebelah kiri dan resolver pipeline di sebelah kanan.

Resolver pipa berisi superset fungsionalitas yang didukung unit resolver, dan banyak lagi, dengan mengorbankan sedikit lebih banyak kompleksitas.

Anatomi resolver pipa

Resolver pipeline terdiri dari template Be fore mapping, template A fter mapping, dan daftar fungsi. Setiap fungsi memiliki template pemetaan permintaan dan respons yang dieksekusi terhadap sumber data. Karena resolver pipeline mendelegasikan eksekusi ke daftar fungsi, oleh karena itu tidak ditautkan ke sumber data apa pun. Unit resolver dan fungsi adalah primitif yang menjalankan operasi terhadap sumber data. Lihat ikhtis ar templat pemetaan Resolver untuk informasi selengkapnya.

Sebelum template pemetaan

Template pemetaan permintaan dari resolver pipeline, atau langkah Sebelum, memungkinkan Anda untuk melakukan beberapa logika persiapan sebelum menjalankan fungsi yang ditentukan.

Daftar fungsi

Daftar fungsi yang akan dijalankan resolver pipeline secara berurutan. Hasil evaluasi templat pemetaan permintaan penyelesai pipa tersedia untuk fungsi pertama sebagai$ctx.prev.result. Setiap output fungsi tersedia untuk fungsi berikutnya sebagai$ctx.prev.result.

Setelah template pemetaan

Template pemetaan respons dari resolver pipeline, atau langkah A fter, memungkinkan Anda untuk melakukan beberapa logika pemetaan akhir dari output fungsi terakhir ke jenis bidang GraphQL yang diharapkan. Output dari fungsi terakhir dalam daftar fungsi tersedia di template pemetaan resolver pipeline sebagai $ctx.prev.result atau$ctx.result.

Aliran eksekusi

Mengingat resolver pipeline yang terdiri dari dua fungsi, daftar di bawah ini mewakili aliran eksekusi ketika resolver dipanggil:

Utilitas Apache Velocity Template Language (VTL) yang berguna

Ketika kompleksitas aplikasi meningkat, utilitas dan arahan VTL ada di sini untuk memfasilitasi produktivitas pengembangan. Utilitas berikut dapat membantu Anda saat Anda bekerja dengan penyelesai pipa.

$ctx.stash

Stash adalah Map yang tersedia di dalam setiap resolver dan template pemetaan fungsi. Instance stash yang sama hidup melalui eksekusi resolver tunggal. Artinya, Anda dapat menggunakan simpanan untuk meneruskan data arbitrer di seluruh templat pemetaan permintaan dan respons, dan lintas fungsi dalam penyelesai pipeline. Stash mengekspos metode yang sama dengan struktur data peta Java.

$ctx.prev.result

Mer $ctx.prev.result upakan hasil dari operasi sebelumnya yang dieksekusi dalam penyelesai pipa.

Jika operasi sebelumnya adalah template Before mapping dari pipeline resolver, maka $ctx.prev.result mewakili output dari evaluasi template dan tersedia untuk fungsi pertama dalam pipeline. Jika operasi sebelumnya adalah fungsi pertama, maka $ctx.prev.result mewakili output dari fungsi pertama dan tersedia untuk fungsi kedua dalam pipeline. Jika operasi sebelumnya adalah fungsi terakhir, maka $ctx.prev.result mewakili output dari fungsi terakhir dan tersedia untuk template After mapping resolver pipeline.

#return (data: Objek)

Ara #return(data: Object) han ini berguna jika Anda perlu kembali sebelum waktunya dari template pemetaan apa pun. #return(data: Object)adalah analog dengan kata kunci return dalam bahasa pemrograman karena kembali dari blok logika tercakupan terdekat. Apa artinya ini adalah bahwa menggunakan #return di dalam template pemetaan resolver kembali dari resolver. Menggunakan #return(data: Object) dalam set template pemetaan resolver data di bidang GraphQL. Selain itu, menggunakan #return(data: Object) template pemetaan fungsi kembali dari fungsi dan melanjutkan eksekusi ke fungsi berikutnya dalam pipeline atau template pemetaan respons resolver.

#return

Ini sama dengan#return(data: Object), tetapi null akan dikembalikan sebagai gantinya.

$util.error

$util.errorUtilitas ini berguna untuk melempar kesalahan bidang. Menggunakan $util.error di dalam template pemetaan fungsi segera menimbulkan kesalahan bidang, yang mencegah fungsi berikutnya dijalankan. Untuk detail selengkapnya dan $util.error tanda tangan lainnya, kunjungi referensi utilitas template pemetaan Resolver.

$util.appendError

$util.appendErrorIni mirip dengan$util.error(), dengan perbedaan utama bahwa itu tidak mengganggu evaluasi template pemetaan. Sebaliknya, ini menandakan ada kesalahan dengan bidang, tetapi memungkinkan template untuk dievaluasi dan akibatnya mengembalikan data. Menggunakan $util.appendError di dalam fungsi tidak akan mengganggu aliran eksekusi pipa. Untuk detail selengkapnya dan $util.error tanda tangan lainnya, kunjungi referensi utilitas template pemetaan Resolver.

Contoh Templat

Misalkan Anda memiliki sumber data DynamoDB dan Unit resolver pada bidang bernama getPost(id:ID!) yang mengembalikan Post tipe dengan kueri GraphQL berikut:

getPost(id:1){
    id
    title
    content
}

Template resolver Anda mungkin terlihat seperti berikut:

{
    "version" : "2018-05-29",
    "operation" : "GetItem",
    "key" : {
        "id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
    }
}

Ini akan menggantikan nilai parameter id input 1 for ${ctx.args.id} dan menghasilkan JSON berikut:

{
    "version" : "2018-05-29",
    "operation" : "GetItem",
    "key" : {
        "id" : { "S" : "1" }
    }
}

AWS AppSync menggunakan template ini untuk menghasilkan instruksi untuk berkomunikasi dengan DynamoDB dan mendapatkan data (atau melakukan operasi lain yang sesuai). Setelah data kembali, AWS AppSync jalankan melalui template pemetaan respons opsional, yang dapat Anda gunakan untuk melakukan pembentukan data atau logika. Misalnya, ketika kita mendapatkan hasil kembali dari DynamoDB, mereka mungkin terlihat seperti ini:

{
        "id" : 1,
        "theTitle" : "AWS AppSync works offline!",
        "theContent-part1" : "It also has realtime functionality",
        "theContent-part2" : "using GraphQL"
}

Anda dapat memilih untuk menggabungkan dua bidang menjadi satu bidang dengan template pemetaan respons berikut:

{
        "id" : $util.toJson($context.data.id),
        "title" : $util.toJson($context.data.theTitle),
        "content" : $util.toJson("${context.data.theContent-part1} ${context.data.theContent-part2}")
}

Berikut adalah bagaimana data dibentuk setelah template diterapkan ke data:

{
        "id" : 1,
        "title" : "AWS AppSync works offline!",
        "content" : "It also has realtime functionality using GraphQL"
}

Data ini diberikan kembali sebagai respons kepada klien sebagai berikut:

{
        "data": {
                "getPost":      {
                        "id" : 1,
                        "title" : "AWS AppSync works offline!",
                        "content" : "It also has realtime functionality using GraphQL"
                }
        }
}

Perhatikan bahwa dalam sebagian besar keadaan, templat pemetaan respons adalah passthrough data sederhana, sebagian besar berbeda jika Anda mengembalikan item individual atau daftar item. Untuk item individual, passthroughnya adalah:

$util.toJson($context.result)

Untuk daftar, passthrough biasanya:

$util.toJson($context.result.items)

Untuk melihat lebih banyak contoh penyelesai unit dan pipeline, lihat tutorial Resolver.

Aturan deserialisasi template pemetaan yang dievaluasi

Template pemetaan mengevaluasi ke string. Di AWS AppSync, string keluaran harus mengikuti struktur JSON agar valid.

Selain itu, aturan deserialisasi berikut diberlakukan.

Kunci duplikat tidak diperbolehkan dalam objek JSON

Jika string template pemetaan yang dievaluasi mewakili objek JSON atau berisi objek yang memiliki kunci duplikat, template pemetaan mengembalikan pesan kesalahan berikut:

Duplicate field 'aField' detected on Object. Duplicate JSON keys are not allowed.

Contoh kunci duplikat dalam template pemetaan permintaan yang dievaluasi:

{
    "version": "2018-05-29",
    "operation": "Invoke",
    "payload": {
        "field": "getPost",
        "postId": "1",
        "field": "getPost" ## key 'field' has been redefined
    }
}

Untuk memperbaiki kesalahan ini, jangan mendefinisikan ulang kunci dalam objek JSON.

Karakter trailing tidak diperbolehkan dalam objek JSON

Jika string template pemetaan yang dievaluasi mewakili objek JSON dan berisi karakter asing di belakang, template pemetaan mengembalikan pesan kesalahan berikut:

Trailing characters at the end of the JSON string are not allowed.

Contoh karakter trailing dalam template pemetaan permintaan yang dievaluasi:

{
    "version": "2018-05-29",
    "operation": "Invoke",
    "payload": {
        "field": "getPost",
        "postId": "1",
    }
}extraneouschars

Untuk memperbaiki kesalahan ini, pastikan template yang dievaluasi secara ketat mengevaluasi JSON.