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

AWS AppSync ikhtisar template 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 bagaimana 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 output JSON dokumen 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 perulangan argumen untuk membangun item sebelum memasukkan item ke DynamoDB.

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

Penyelesai unit

Resolver unit adalah entitas mandiri yang hanya menyertakan template permintaan dan respons. Gunakan ini untuk operasi tunggal sederhana seperti mencantumkan item dari satu sumber data.

Penyelesai pipa

Pipeline resolver berisi satu atau lebih fungsi yang dilakukan secara berurutan. Setiap fungsi menyertakan template permintaan dan template respons. Pipeline resolver juga memiliki template before dan after template yang mengelilingi urutan fungsi yang berisi template. Template after memetakan ke tipe output bidang GraphQL. Pipeline resolver berbeda dari resolver unit dalam cara template respon memetakan output. Pipeline resolver dapat memetakan ke output apa pun yang Anda inginkan, termasuk input untuk fungsi lain atau template setelah resolver pipeline.

Fungsi resolver 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 resolver unit, berisi format template pemetaan permintaan dan respons yang sama.

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

Pipeline resolver berisi superset fungsionalitas yang didukung oleh unit resolver, dan banyak lagi, dengan biaya yang sedikit lebih rumit.

Anatomi penyelesai pipa

Pipeline resolver terdiri dari template Sebelum pemetaan, template After mapping, dan daftar fungsi. Setiap fungsi memiliki template pemetaan permintaan dan respons yang dijalankan terhadap sumber data. Karena penyelesai pipa mendelegasikan eksekusi ke daftar fungsi, oleh karena itu tidak ditautkan ke sumber data apa pun. Resolver dan fungsi unit adalah primitif yang menjalankan operasi terhadap sumber data. Lihat ikhtisar template pemetaan Resolver untuk informasi selengkapnya.

Sebelum memetakan template

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

Daftar fungsi

Daftar fungsi resolver pipeline akan berjalan secara berurutan. Hasil evaluasi template pemetaan permintaan penyelesai pipa dibuat 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 pipa, atau langkah Setelah, 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 pipeline resolver sebagai atau. $ctx.prev.result $ctx.result

Aliran eksekusi

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

Berguna Apache Velocity Template Bahasa () VTL utilitas

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

$ ctx.simpanan

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

$ctx.prev.result

$ctx.prev.resultIni merupakan hasil dari operasi sebelumnya yang dijalankan di resolver pipa.

Jika operasi sebelumnya adalah template Sebelum pemetaan 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 pipa. 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)

#return(data: Object)Arahan ini berguna jika Anda perlu kembali sebelum waktunya dari template pemetaan apa pun. #return(data: Object)analog dengan kata kunci return dalam bahasa pemrograman karena kembali dari blok logika cakupan 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 pada bidang data GraphQL. Selain itu, menggunakan #return(data: Object) dari 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 akan segera menimbulkan kesalahan bidang, yang mencegah fungsi selanjutnya dieksekusi. 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, itu menandakan ada kesalahan dengan bidang, tetapi memungkinkan template untuk dievaluasi dan akibatnya mengembalikan data. Menggunakan fungsi $util.appendError di dalam 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 resolver Unit pada bidang getPost(id:ID!) bernama yang mengembalikan Post tipe dengan query 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 yang berikutJSON:

     {
    "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 ke dalam 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 terhadap 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, template pemetaan respons adalah passthrough data yang sederhana, sebagian besar berbeda jika Anda mengembalikan item individual atau daftar item. Untuk item individual passthrough adalah:

$util.toJson($context.result)

Untuk daftar passthrough biasanya:

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

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

Aturan deserialisasi template pemetaan yang dievaluasi

Template pemetaan mengevaluasi ke string. Dalam AWS AppSync, string output harus mengikuti JSON struktur agar valid.

Selain itu, aturan deserialisasi berikut diberlakukan.

Kunci duplikat tidak diperbolehkan dalam objek JSON

Jika string template pemetaan yang dievaluasi mewakili JSON objek 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 templat 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 JSON objek.

Karakter trailing tidak diperbolehkan dalam objek JSON

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

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

Contoh karakter tertinggal dalam templat pemetaan permintaan yang dievaluasi:

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

Untuk memperbaiki kesalahan ini, pastikan bahwa template yang dievaluasi secara ketat mengevaluasiJSON.