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

Merancang skema GraphQL Anda

Skema GraphQL adalah dasar dari setiap implementasi server GraphQL. Setiap GraphQL API ditentukan oleh skema tunggal yang berisi jenis dan bidang yang menjelaskan bagaimana data dari permintaan akan diisi. Data yang mengalir melalui API Anda dan operasi yang dilakukan harus divalidasi terhadap skema.

Secara umum, sistem tipe GraphQL menjelaskan kemampuan server GraphQL dan digunakan untuk menentukan apakah kueri valid. Sistem tipe server sering disebut sebagai skema server itu dan dapat terdiri dari berbagai jenis objek, tipe skalar, tipe input, dan banyak lagi. GraphQL bersifat deklaratif dan diketik dengan kuat, yang berarti tipe akan didefinisikan dengan baik saat runtime dan hanya akan mengembalikan apa yang ditentukan.

AWS AppSync memungkinkan Anda untuk menentukan dan mengkonfigurasi skema GraphQL. Bagian berikut menjelaskan cara membuat skema GraphQL dari awal menggunakan layanan AWS AppSync.

Penataan Skema GraphQL

GraphQL adalah alat yang ampuh untuk mengimplementasikan layanan API. Menurut situs web GraphQL, GraphQL adalah sebagai berikut:

GraphQL adalah bahasa query untuk API dan runtime untuk memenuhi kueri tersebut dengan data Anda yang ada. GraphQL memberikan deskripsi data yang lengkap dan dapat dimengerti di API Anda, memberi klien kekuatan untuk meminta apa yang mereka butuhkan dan tidak lebih, membuatnya lebih mudah untuk mengembangkan API dari waktu ke waktu, dan memungkinkan alat pengembang yang kuat. ”

Bagian ini mencakup bagian pertama dari implementasi GraphQL Anda, skema. Menggunakan kutipan di atas, skema memainkan peran “memberikan deskripsi data yang lengkap dan dapat dimengerti di API Anda”. Dengan kata lain, skema GraphQL adalah representasi tekstual dari data layanan Anda, operasi, dan hubungan di antara mereka. Skema dianggap sebagai titik masuk utama untuk implementasi layanan GraphQL Anda. Tidak mengherankan, ini sering menjadi salah satu hal pertama yang Anda buat dalam proyek Anda. Kami merekomendasikan meninjau bagian Skema sebelum melanjutkan.

Untuk mengutip bagian Skema, skema GraphQL ditulis dalam Bahasa Definisi S kema (SDL). SDL terdiri dari jenis dan bidang dengan struktur yang mapan:

Skema paling sederhana akan berisi tiga kategori data yang berbeda:

Untuk menempatkan ini ke dalam perspektif, bayangkan Anda membuat layanan yang menyimpan penulis dan buku yang telah mereka tulis. Setiap penulis memiliki nama dan serangkaian buku yang telah mereka tulis. Setiap buku memiliki nama dan daftar penulis terkait. Kami juga menginginkan kemampuan untuk menambah atau mengambil buku dan penulis. Representasi UML sederhana dari hubungan ini mungkin terlihat seperti ini:

Di GraphQL, entitas Author dan Book mewakili dua tipe objek yang berbeda dalam skema Anda:

type Author {
}

type Book {
}

Authorberisi authorName danBooks, sementara Book berisi bookName danAuthors. Ini dapat direpresentasikan sebagai bidang dalam lingkup jenis Anda:

type Author {
  authorName: String
  Books: [Book]
}

type Book {
  bookName: String
  Authors: [Author]
}

Seperti yang Anda lihat, representasi tipe sangat dekat dengan diagram. Namun, metodenya menjadi sedikit lebih rumit. Ini akan ditempatkan di salah satu dari beberapa jenis objek khusus sebagai bidang. Kategorisasi objek khusus mereka tergantung pada perilaku mereka. GraphQL berisi tiga tipe objek khusus mendasar: kueri, mutasi, dan langganan. Untuk informasi selengkapnya, lihat Objek khusus.

Karena getAuthor dan getBook keduanya meminta data, mereka akan ditempatkan dalam tipe objek Query khusus:

type Author {
  authorName: String
  Books: [Book]
}

type Book {
  bookName: String
  Authors: [Author]
}

type Query {
  getAuthor(authorName: String): Author
  getBook(bookName: String): Book
}

Operasi ditautkan ke kueri, yang itu sendiri terkait dengan skema. Menambahkan root skema akan menentukan tipe objek khusus (Querydalam hal ini) sebagai salah satu titik masuk Anda. Ini dapat dilakukan dengan menggunakan schema kata kunci:

schema {
  query: Query
}

type Author {
  authorName: String
  Books: [Book]
}

type Book {
  bookName: String
  Authors: [Author]
}

type Query {
  getAuthor(authorName: String): Author
  getBook(bookName: String): Book
}

Melihat dua metode terakhir, addAuthor dan addBook menambahkan data ke database Anda, sehingga mereka akan didefinisikan dalam tipe objek Mutation khusus. Namun, dari halaman Tipe, kami juga tahu bahwa input yang mereferensikan Objek secara langsung tidak diperbolehkan karena mereka benar-benar tipe keluaran. Dalam hal ini, kita tidak dapat menggunakan Author atauBook, jadi kita perlu membuat tipe input dengan bidang yang sama. Dalam contoh ini, kami menambahkan AuthorInput danBookInput, keduanya menerima bidang yang sama dari tipenya masing-masing. Kemudian, kami membuat mutasi kami menggunakan input sebagai parameter kami:

schema {
  query: Query
  mutation: Mutation
}

type Author {
  authorName: String
  Books: [Book]
}

input AuthorInput {
  authorName: String
  Books: [BookInput]
}

type Book {
  bookName: String
  Authors: [Author]
}

input BookInput {
  bookName: String
  Authors: [AuthorInput]
}

type Query {
  getAuthor(authorName: String): Author
  getBook(bookName: String): Book
}

type Mutation {
  addAuthor(input: [BookInput]): Author
  addBook(input: [AuthorInput]): Book
}

Mari kita tinjau apa yang baru saja kami lakukan:

Seperti yang Anda lihat, proses pembuatan skema membutuhkan banyak konsep dari pemodelan data (terutama pemodelan database) secara umum. Anda dapat menganggap skema sesuai dengan bentuk data dari sumbernya. Ini juga berfungsi sebagai model yang akan diterapkan resolver. Di bagian berikut, Anda akan belajar cara membuat skema menggunakan berbagai alat dan AWS layanan yang didukung.

Membuat skema

Skema Anda akan berada dalam file yang disebutschema.graphql. AWS AppSync memungkinkan pengguna untuk membuat skema baru untuk GraphQL API mereka menggunakan berbagai metode. Dalam contoh ini, kita akan membuat API kosong bersama dengan skema kosong.

Console

1. Masuk ke Konsol Manajemen AWS dan buka AppSync konsol.

   1. Di Dasbor, pilih Buat API.

   2. Di bawah opsi API, pilih GraphQL API, Desain dari awal, lalu Ber ikutnya.

      1. Untuk nama API, ubah nama yang telah diisi sebelumnya sesuai kebutuhan aplikasi Anda.

      2. Untuk detail kontak, Anda dapat memasukkan titik kontak untuk mengidentifikasi manajer untuk API. Ini adalah bidang opsional.

      3. Di bawah konfigurasi API pribadi, Anda dapat mengaktifkan fitur API pribadi. API pribadi hanya dapat diakses dari titik akhir VPC (VPCE) yang dikonfigurasi. Untuk informasi selengkapnya, lihat API pribadi.

         Kami tidak menyarankan untuk mengaktifkan fitur ini untuk contoh ini. Pilih Berikutnya setelah meninjau input Anda.

   3. Di bawah Buat tipe GraphQL, Anda dapat memilih untuk membuat tabel DynamoDB untuk digunakan sebagai sumber data atau melewatkan ini dan melakukannya nanti.

      Untuk contoh ini, pilih Buat sumber daya GraphQL nanti. Kami akan membuat sumber daya di bagian terpisah.

   4. Tinjau input Anda, lalu pilih Buat API.

2. Anda akan berada di dasbor API spesifik Anda. Anda bisa tahu karena nama API akan berada di bagian atas dasbor. Jika tidak demikian, Anda dapat memilih API di Sidebar, lalu pilih API Anda di dasbor API.

   1. Di Sidebar di bawah nama API Anda, pilih Skema.

3. Di editor S kema, Anda dapat mengonfigurasi schema.graphql file Anda. Ini mungkin kosong atau diisi dengan tipe yang dihasilkan dari model. Di sebelah kanan, Anda memiliki bagian Resolvers untuk melampirkan resolver ke bidang skema Anda. Kami tidak akan melihat resolver di bagian ini.

CLI

catatan

Saat menggunakan CLI, pastikan Anda memiliki izin yang benar untuk mengakses dan membuat sumber daya dalam layanan. Anda mungkin ingin menetapkan kebijakan hak istimewa terkecil untuk pengguna non-admin yang perlu mengakses layanan. Untuk informasi selengkapnya tentang AWS AppSync kebijakan, lihat Identitas dan manajemen akses untuk AWS AppSync.

Selain itu, kami sarankan membaca versi konsol terlebih dahulu jika Anda belum melakukannya.

1. Jika Anda belum melakukannya, instal AWS CLI, lalu tambahkan konfigurasi Anda.

2. Buat objek API GraphQL dengan menjalankan create-graphql-api perintah.

   Anda harus mengetikkan dua parameter untuk perintah khusus ini:

   1. API Anda. name

   2. authentication-type, atau jenis kredenSIAL yang digunakan untuk mengakses API (IAM, OIDC, dll.).

   catatan

   Parameter lain seperti Region harus dikonfigurasi tetapi biasanya akan default ke nilai konfigurasi CLI Anda.

   Contoh perintah mungkin terlihat seperti ini:

   aws appsync create-graphql-api --name testAPI123 --authentication-type API_KEY

   Output akan dikembalikan dalam CLI. Inilah contohnya:

   {
       "graphqlApi": {
           "xrayEnabled": false,
           "name": "testAPI123",
           "authenticationType": "API_KEY",
           "tags": {},
           "apiId": "abcdefghijklmnopqrstuvwxyz",
           "uris": {
               "GRAPHQL": "https://zyxwvutsrqponmlkjihgfedcba.appsync-api.us-west-2.amazonaws.com/graphql",
               "REALTIME": "wss://zyxwvutsrqponmlkjihgfedcba.appsync-realtime-api.us-west-2.amazonaws.com/graphql"
           },
           "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz"
       }
   }

3. catatan

   Ini adalah perintah opsional yang mengambil skema yang ada dan mengunggahnya ke AWS AppSync layanan menggunakan blob base-64. Kami tidak akan menggunakan perintah ini demi contoh ini.

   Jalankan perintah start-schema-creation.

   Anda harus mengetikkan dua parameter untuk perintah khusus ini:

   1. Anda api-id dari langkah sebelumnya.

   2. Skema definition adalah gumpalan biner yang dikodekan base-64.

   Contoh perintah mungkin terlihat seperti ini:

    aws appsync start-schema-creation --api-id abcdefghijklmnopqrstuvwxyz --definition "aa1111aa-123b-2bb2-c321-12hgg76cc33v"

   Output akan dikembalikan:

   {
       "status": "PROCESSING"
   }

   Perintah ini tidak akan mengembalikan output akhir setelah diproses. Anda harus menggunakan perintah terpisah, get-schema-creation-status, untuk melihat hasilnya. Perhatikan bahwa kedua perintah ini tidak sinkron, sehingga Anda dapat memeriksa status output bahkan saat skema masih dibuat.

CDK

Tip

Sebelum Anda menggunakan CDK, kami sarankan meninjau dokumentasi resmi CDK bersama dengan AWS AppSync referensi CDK.

Langkah-langkah yang tercantum di bawah ini hanya akan menampilkan contoh umum cuplikan yang digunakan untuk menambahkan sumber daya tertentu. Ini tidak dimaksudkan untuk menjadi solusi yang berfungsi dalam kode produksi Anda. Kami juga menganggap Anda sudah memiliki aplikasi yang berfungsi.

1. Titik awal untuk CDK sedikit berbeda. Idealnya, schema.graphql file Anda seharusnya sudah dibuat. Anda hanya perlu membuat file baru dengan ekstensi .graphql file. Ini bisa berupa file kosong.

2. Secara umum, Anda mungkin harus menambahkan direktif impor ke layanan yang Anda gunakan. Misalnya, mungkin mengikuti formulir:

   import * as x from 'x'; # import wildcard as the 'x' keyword from 'x-service'
   import {a, b, ...} from 'c'; # import {specific constructs} from 'c-service'

   Untuk menambahkan GraphQL API, file stack Anda perlu mengimpor AWS AppSync layanan:

   import * as appsync from 'aws-cdk-lib/aws-appsync';

   catatan

   Ini berarti kami mengimpor seluruh layanan di bawah appsync kata kunci. Untuk menggunakan ini di aplikasi Anda, AWS AppSync konstruksi Anda akan menggunakan formatappsync.construct_name. Misalnya, jika kita ingin membuat GraphQL API, kita akan mengatakannew appsync.GraphqlApi(args_go_here). Langkah berikut menggambarkan ini.

3. GraphQL API paling dasar akan menyertakan a name untuk API dan schema jalur.

   const add_api = new appsync.GraphqlApi(this, 'API_ID', {
     name: 'name_of_API_in_console',
     schema: appsync.SchemaFile.fromAsset(path.join(__dirname, 'schema_name.graphql')),
   });

   catatan

   Mari kita tinjau apa yang dilakukan cuplikan ini. Di dalam lingkupapi, kami membuat GraphQL API baru dengan memanggilappsync.GraphqlApi(scope: Construct, id: string, props: GraphqlApiProps). Ruang lingkupnya adalahthis, yang mengacu pada objek saat ini. Id adalahAPI_ID, yang akan menjadi nama sumber daya GraphQL API Anda CloudFormation saat dibuat. Ini GraphqlApiProps berisi GraphQL API Anda dan. name schema Ini schema akan menghasilkan skema (SchemaFile.fromAsset) dengan mencari jalur absolut (__dirname) untuk .graphql file (schema_name.graphql). Dalam skenario nyata, file skema Anda mungkin akan berada di dalam aplikasi CDK.

   Untuk menggunakan perubahan yang dibuat pada GraphQL API Anda, Anda harus menerapkan ulang aplikasi.

Menambahkan tipe ke skema

Sekarang setelah Anda menambahkan skema Anda, Anda dapat mulai menambahkan jenis input dan output Anda. Perhatikan bahwa tipe di sini tidak boleh digunakan dalam kode nyata; mereka hanya contoh untuk membantu Anda memahami prosesnya.

Pertama, kita akan membuat tipe objek. Dalam kode nyata, Anda tidak harus memulai dengan jenis ini. Anda dapat membuat jenis apa pun yang Anda inginkan kapan saja selama Anda mengikuti aturan dan sintaks GraphQL.

Console

• Anda dapat membuat tipe objek menggunakan type kata kunci bersama dengan nama tipe:

  type Type_Name_Goes_Here {}

  Di dalam cakupan tipe, Anda dapat menambahkan bidang yang mewakili karakteristik objek:

  type Type_Name_Goes_Here {
    # Add fields here
  }

  Inilah contohnya:

  type Obj_Type_1 {
    id: ID!
    title: String
    date: AWSDateTime
  }

  catatan

  Pada langkah ini, kami menambahkan tipe objek generik dengan id bidang wajib disimpan sebagaiID, title bidang disimpan sebagaiString, dan date bidang yang disimpan sebagaiAWSDateTime. Untuk melihat daftar jenis dan bidang dan apa yang dilakukannya, lihat Skema. Untuk melihat daftar skalar dan apa yang mereka lakukan, lihat referensi https://docs.aws.amazon.com/appsync/latest/devguide/type-reference.html Jenis.

CLI

catatan

Sebaiknya baca versi konsol terlebih dahulu jika Anda belum melakukannya.

• Anda dapat membuat tipe objek dengan menjalankan create-type perintah.

  Anda harus memasukkan beberapa parameter untuk perintah khusus ini:

  1. api-iddari API Anda.

  2. Itudefinition, atau konten tipe Anda. Dalam contoh konsol, ini adalah:

     type Obj_Type_1 {
       id: ID!
       title: String
       date: AWSDateTime
     }

  3. mas format ukan Anda. Dalam contoh ini, kita menggunakanSDL.

  Contoh perintah mungkin terlihat seperti ini:

  aws appsync create-type --api-id abcdefghijklmnopqrstuvwxyz --definition "type Obj_Type_1{id: ID! title: String date: AWSDateTime}" --format SDL

  Output akan dikembalikan dalam CLI. Inilah contohnya:

  {
      "type": {
          "definition": "type Obj_Type_1{id: ID! title: String date: AWSDateTime}",
          "name": "Obj_Type_1",
          "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/Obj_Type_1",
          "format": "SDL"
      }
  }

  catatan

  Pada langkah ini, kami menambahkan tipe objek generik dengan id bidang wajib disimpan sebagaiID, title bidang disimpan sebagaiString, dan date bidang yang disimpan sebagaiAWSDateTime. Untuk melihat daftar jenis dan bidang dan apa yang dilakukannya, lihat Skema. Untuk melihat daftar skalar dan apa yang dilakukannya, lihat Refer ensi tipe.

  Pada catatan lebih lanjut, Anda mungkin telah menyadari bahwa memasukkan definisi secara langsung berfungsi untuk tipe yang lebih kecil tetapi tidak mungkin untuk menambahkan tipe yang lebih besar atau beberapa. Anda dapat memilih untuk menambahkan semuanya dalam .graphql file dan kemudian meneruskannya sebagai input.

CDK

Tip

Sebelum Anda menggunakan CDK, kami sarankan meninjau dokumentasi resmi CDK bersama dengan AWS AppSync referensi CDK.

Langkah-langkah yang tercantum di bawah ini hanya akan menampilkan contoh umum cuplikan yang digunakan untuk menambahkan sumber daya tertentu. Ini tidak dimaksudkan untuk menjadi solusi yang berfungsi dalam kode produksi Anda. Kami juga menganggap Anda sudah memiliki aplikasi yang berfungsi.

Untuk menambahkan jenis, Anda perlu menambahkannya ke .graphql file Anda. Misalnya, contoh konsol adalah:

type Obj_Type_1 {
  id: ID!
  title: String
  date: AWSDateTime
}

Anda dapat menambahkan tipe Anda langsung ke skema seperti file lainnya.

catatan

Untuk menggunakan perubahan yang dibuat pada GraphQL API Anda, Anda harus menerapkan ulang aplikasi.

Tipe objek memiliki bidang yang merupakan tipe skalar seperti string dan bilangan bulat. AWS AppSync juga memungkinkan Anda untuk menggunakan jenis skalar yang disempurnakan seperti AWSDateTime selain skalar GraphQL dasar. Juga, bidang apa pun yang berakhir dengan tanda seru diperlukan.

Tipe ID skalar khususnya adalah pengidentifikasi unik yang dapat berupa String atauInt. Anda dapat mengontrol ini dalam kode resolver Anda untuk penugasan otomatis.

Ada kesamaan antara tipe objek khusus seperti Query dan tipe objek “biasa” seperti contoh di atas karena keduanya menggunakan type kata kunci dan dianggap objek. Namun, untuk tipe objek khusus (Query,Mutation, danSubscription), perilakunya sangat berbeda karena mereka diekspos sebagai titik masuk untuk API Anda. Mereka juga lebih tentang membentuk operasi daripada data. Untuk informasi selengkapnya, lihat Jenis kueri dan mutasi.

Pada topik tipe objek khusus, langkah selanjutnya bisa menambahkan satu atau lebih dari mereka untuk melakukan operasi pada data berbentuk. Dalam skenario nyata, setiap skema GraphQL setidaknya harus memiliki tipe kueri root untuk meminta data. Anda dapat menganggap kueri sebagai salah satu titik masuk (atau titik akhir) untuk server GraphQL Anda. Mari tambahkan query sebagai contoh.

Console

• Untuk membuat kueri, Anda cukup menambahkannya ke file skema seperti jenis lainnya. Kueri akan membutuhkan Query tipe dan entri di root seperti ini:

  schema {
    query: Name_of_Query
  }
  
  type Name_of_Query {
    # Add field operation here
  }

  Perhatikan bahwa Name_of_Query dalam lingkungan produksi hanya akan dipanggil Query dalam banyak kasus. Kami merekomendasikan untuk menyimpannya pada nilai ini. Di dalam jenis kueri, Anda dapat menambahkan bidang. Setiap bidang akan melakukan operasi dalam permintaan. Akibatnya, sebagian besar, jika tidak semua, bidang ini akan dilampirkan ke resolver. Namun, kami tidak peduli dengan itu di bagian ini. Mengenai format operasi lapangan, mungkin terlihat seperti ini:

  Name_of_Query(params): Return_Type # version with params
  Name_of_Query: Return_Type # version without params

  Inilah contohnya:

  schema {
    query: Query
  }
  
  type Query {
    getObj: [Obj_Type_1]
  }
  
  type Obj_Type_1 {
    id: ID!
    title: String
    date: AWSDateTime
  }

  catatan

  Pada langkah ini, kami menambahkan Query tipe dan mendefinisikannya di schema root kami. QueryJenis kami mendefinisikan getObj bidang yang mengembalikan daftar Obj_Type_1 objek. Perhatikan bahwa Obj_Type_1 itu adalah objek dari langkah sebelumnya. Dalam kode produksi, operasi lapangan Anda biasanya akan bekerja dengan data yang dibentuk oleh objek sepertiObj_Type_1. Selain itu, bidang seperti biasanya getObj akan memiliki resolver untuk melakukan logika bisnis. Itu akan dibahas di bagian yang berbeda.

  Sebagai catatan tambahan, AWS AppSync secara otomatis menambahkan root skema selama ekspor, jadi secara teknis Anda tidak perlu menambahkannya langsung ke skema. Layanan kami akan secara otomatis memproses skema duplikat. Kami menambahkannya di sini sebagai praktik terbaik.

CLI

catatan

Sebaiknya baca versi konsol terlebih dahulu jika Anda belum melakukannya.

1. Buat schema root dengan query definisi dengan menjalankan create-type perintah.

   Anda harus memasukkan beberapa parameter untuk perintah khusus ini:

   1. api-iddari API Anda.

   2. Itudefinition, atau konten tipe Anda. Dalam contoh konsol, ini adalah:

      schema {
        query: Query
      }

   3. mas format ukan Anda. Dalam contoh ini, kita menggunakanSDL.

   Contoh perintah mungkin terlihat seperti ini:

   aws appsync create-type --api-id abcdefghijklmnopqrstuvwxyz --definition "schema {query: Query}" --format SDL

   Output akan dikembalikan dalam CLI. Inilah contohnya:

   {
       "type": {
           "definition": "schema {query: Query}",
           "name": "schema",
           "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/schema",
           "format": "SDL"
       }
   }

   catatan

   Perhatikan bahwa jika Anda tidak memasukkan sesuatu dengan benar dalam create-type perintah, Anda dapat memperbarui root skema Anda (atau jenis apa pun dalam skema) dengan menjalankan update-type perintah. Dalam contoh ini, kita akan sementara mengubah root skema untuk berisi subscription definisi.

   Anda harus memasukkan beberapa parameter untuk perintah khusus ini:

   1. api-iddari API Anda.

   2. Ti type-name pe Anda. Dalam contoh konsol, ini adalahschema.

   3. Itudefinition, atau konten tipe Anda. Dalam contoh konsol, ini adalah:

      schema {
        query: Query
      }

      Skema setelah menambahkan a subscription akan terlihat seperti ini:

      schema {
        query: Query
        subscription: Subscription
      }

   4. mas format ukan Anda. Dalam contoh ini, kita menggunakanSDL.

   Contoh perintah mungkin terlihat seperti ini:

   aws appsync update-type --api-id abcdefghijklmnopqrstuvwxyz --type-name schema --definition "schema {query: Query subscription: Subscription}" --format SDL

   Output akan dikembalikan dalam CLI. Inilah contohnya:

   {
       "type": {
           "definition": "schema {query: Query subscription: Subscription}",
           "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/schema",
           "format": "SDL"
       }
   }

   Menambahkan file yang telah diformat sebelumnya akan tetap berfungsi dalam contoh ini.

2. Buat Query tipe dengan menjalankan create-type perintah.

   Anda harus memasukkan beberapa parameter untuk perintah khusus ini:

   1. api-iddari API Anda.

   2. Itudefinition, atau konten tipe Anda. Dalam contoh konsol, ini adalah:

      type Query {
        getObj: [Obj_Type_1]
      }

   3. mas format ukan Anda. Dalam contoh ini, kita menggunakanSDL.

   Contoh perintah mungkin terlihat seperti ini:

   aws appsync create-type --api-id abcdefghijklmnopqrstuvwxyz --definition "type Query {getObj: [Obj_Type_1]}" --format SDL

   Output akan dikembalikan dalam CLI. Inilah contohnya:

   {
       "type": {
           "definition": "Query {getObj: [Obj_Type_1]}",
           "name": "Query",
           "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/Query",
           "format": "SDL"
       }
   }

   catatan

   Pada langkah ini, kami menambahkan Query tipe dan mendefinisikannya di schema root Anda. QueryJenis kami mendefinisikan getObj bidang yang mengembalikan daftar Obj_Type_1 objek.

   Dalam kode schema rootquery: Query, query: bagian tersebut menunjukkan bahwa kueri didefinisikan dalam skema Anda, sedangkan Query bagian tersebut menunjukkan nama objek khusus yang sebenarnya.

CDK

Tip

Sebelum Anda menggunakan CDK, kami sarankan meninjau dokumentasi resmi CDK bersama dengan AWS AppSync referensi CDK.

Langkah-langkah yang tercantum di bawah ini hanya akan menampilkan contoh umum cuplikan yang digunakan untuk menambahkan sumber daya tertentu. Ini tidak dimaksudkan untuk menjadi solusi yang berfungsi dalam kode produksi Anda. Kami juga menganggap Anda sudah memiliki aplikasi yang berfungsi.

Anda harus menambahkan kueri dan root skema ke .graphql file. Contoh kami terlihat seperti contoh di bawah ini, tetapi Anda akan ingin menggantinya dengan kode skema Anda yang sebenarnya:

schema {
  query: Query
}

type Query {
  getObj: [Obj_Type_1]
}

type Obj_Type_1 {
  id: ID!
  title: String
  date: AWSDateTime
}

Anda dapat menambahkan tipe Anda langsung ke skema seperti file lainnya.

catatan

Memperbarui root skema adalah opsional. Kami menambahkannya ke contoh ini sebagai praktik terbaik.

Untuk menggunakan perubahan yang dibuat pada GraphQL API Anda, Anda harus menerapkan ulang aplikasi.

Anda sekarang telah melihat contoh pembuatan objek dan objek khusus (query). Anda juga telah melihat bagaimana ini dapat saling berhubungan untuk menggambarkan data dan operasi. Anda dapat memiliki skema hanya dengan deskripsi data dan satu atau lebih kueri. Namun, kami ingin menambahkan operasi lain untuk menambahkan data ke sumber data. Kami akan menambahkan jenis objek khusus lain Mutation yang disebut yang memodifikasi data.

Console

• Mutasi akan dipanggilMutation. SepertiQuery, operasi lapangan di dalamnya Mutation akan menggambarkan operasi dan akan dilampirkan ke resolver. Juga, perhatikan bahwa kita perlu mendefinisikannya di schema root karena ini adalah tipe objek khusus. Berikut contoh mutasi:

  schema {
    mutation: Name_of_Mutation
  }
  
  type Name_of_Mutation {
    # Add field operation here
  }

  Mutasi tipikal akan terdaftar di root seperti kueri. Mutasi didefinisikan menggunakan type kata kunci bersama dengan nama. Name_of_Mutationbiasanya akan dipanggilMutation, jadi kami sarankan untuk tetap seperti itu. Setiap bidang juga akan melakukan operasi. Mengenai format operasi lapangan, mungkin terlihat seperti ini:

  Name_of_Mutation(params): Return_Type # version with params
  Name_of_Mutation: Return_Type # version without params

  Inilah contohnya:

  schema {
    query: Query
    mutation: Mutation
  }
  
  type Obj_Type_1 {
    id: ID!
    title: String
    date: AWSDateTime
  }
  
  type Query {
    getObj: [Obj_Type_1]
  }
  
  type Mutation {
    addObj(id: ID!, title: String, date: AWSDateTime): Obj_Type_1
  }

  catatan

  Pada langkah ini, kami menambahkan Mutation tipe dengan addObj bidang. Mari kita rangkum apa yang dilakukan bidang ini:

  addObj(id: ID!, title: String, date: AWSDateTime): Obj_Type_1

  addObjmenggunakan Obj_Type_1 objek untuk melakukan operasi. Ini jelas karena bidang, tetapi sintaks membuktikan ini dalam tipe : Obj_Type_1 pengembalian. Di dalamaddObj, ia menerima date bidang idtitle,, dan dari Obj_Type_1 objek sebagai parameter. Seperti yang Anda lihat, ini sangat mirip deklarasi metode. Namun, kami belum menjelaskan perilaku metode kami. Seperti yang dinyatakan sebelumnya, skema hanya ada untuk menentukan apa data dan operasi nantinya dan bukan bagaimana mereka beroperasi. Menerapkan logika bisnis yang sebenarnya akan datang nanti ketika kita membuat resolver pertama kita.

  Setelah Anda selesai dengan skema Anda, ada opsi untuk mengekspornya sebagai schema.graphql file. Di editor Skema, Anda dapat memilih Ekspor skema untuk mengunduh file dalam format yang didukung.

  Sebagai catatan tambahan, AWS AppSync secara otomatis menambahkan root skema selama ekspor, jadi secara teknis Anda tidak perlu menambahkannya langsung ke skema. Layanan kami akan secara otomatis memproses skema duplikat. Kami menambahkannya di sini sebagai praktik terbaik.

CLI

catatan

Sebaiknya baca versi konsol terlebih dahulu jika Anda belum melakukannya.

1. Perbarui skema root Anda dengan menjalankan update-type perintah.

   Anda harus memasukkan beberapa parameter untuk perintah khusus ini:

   1. api-iddari API Anda.

   2. Ti type-name pe Anda. Dalam contoh konsol, ini adalahschema.

   3. Itudefinition, atau konten tipe Anda. Dalam contoh konsol, ini adalah:

      schema {
        query: Query
        mutation: Mutation
      }

   4. formatdari masukan Anda. Dalam contoh ini, kita menggunakanSDL.

   Contoh perintah mungkin terlihat seperti ini:

   aws appsync update-type --api-id abcdefghijklmnopqrstuvwxyz --type-name schema --definition "schema {query: Query mutation: Mutation}" --format SDL

   Output akan dikembalikan dalam CLI. Inilah contohnya:

   {
       "type": {
           "definition": "schema {query: Query mutation: Mutation}",
           "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/schema",
           "format": "SDL"
       }
   }

2. Buat Mutation tipe dengan menjalankan create-type perintah.

   Anda harus memasukkan beberapa parameter untuk perintah khusus ini:

   1. api-iddari API Anda.

   2. Itudefinition, atau konten tipe Anda. Dalam contoh konsol, ini adalah

      type Mutation {
        addObj(id: ID!, title: String, date: AWSDateTime): Obj_Type_1
      }

   3. formatdari masukan Anda. Dalam contoh ini, kita menggunakanSDL.

   Contoh perintah mungkin terlihat seperti ini:

   aws appsync create-type --api-id abcdefghijklmnopqrstuvwxyz --definition "type Mutation {addObj(id: ID! title: String date: AWSDateTime): Obj_Type_1}" --format SDL

   Output akan dikembalikan dalam CLI. Inilah contohnya:

   {
       "type": {
           "definition": "type Mutation {addObj(id: ID! title: String date: AWSDateTime): Obj_Type_1}",
           "name": "Mutation",
           "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/Mutation",
           "format": "SDL"
       }
   }

CDK

Tip

Sebelum Anda menggunakan CDK, kami sarankan meninjau dokumentasi resmi CDK bersama dengan AWS AppSync referensi CDK.

Langkah-langkah yang tercantum di bawah ini hanya akan menampilkan contoh umum cuplikan yang digunakan untuk menambahkan sumber daya tertentu. Ini tidak dimaksudkan untuk menjadi solusi yang berfungsi dalam kode produksi Anda. Kami juga menganggap Anda sudah memiliki aplikasi yang berfungsi.

Anda harus menambahkan kueri dan root skema ke .graphql file. Contoh kami terlihat seperti contoh di bawah ini, tetapi Anda akan ingin menggantinya dengan kode skema Anda yang sebenarnya:

schema {
  query: Query
  mutation: Mutation
}

type Obj_Type_1 {
  id: ID!
  title: String
  date: AWSDateTime
}

type Query {
  getObj: [Obj_Type_1]
}

type Mutation {
  addObj(id: ID!, title: String, date: AWSDateTime): Obj_Type_1
}

catatan

Memperbarui root skema adalah opsional. Kami menambahkannya ke contoh ini sebagai praktik terbaik.

Untuk menggunakan perubahan yang dibuat pada GraphQL API Anda, Anda harus menerapkan ulang aplikasi.

Pertimbangan opsional - Menggunakan enum sebagai status

Pada titik ini, Anda tahu cara membuat skema dasar. Namun, ada banyak hal yang dapat Anda tambahkan untuk meningkatkan fungsionalitas skema. Satu hal yang umum ditemukan dalam aplikasi adalah penggunaan enum sebagai status. Anda dapat menggunakan enum untuk memaksa nilai tertentu dari sekumpulan nilai yang akan dipilih saat dipanggil. Ini bagus untuk hal-hal yang Anda tahu tidak akan berubah secara drastis dalam jangka waktu yang lama. Secara hipotetis, kita dapat menambahkan enum yang mengembalikan kode status atau String dalam respons.

Sebagai contoh, mari kita asumsikan kita membuat aplikasi media sosial yang menyimpan data posting pengguna di backend. Skema kami berisi Post tipe yang mewakili data posting individu:

type Post {
  id: ID!
  title: String
  date: AWSDateTime
  poststatus: PostStatus
}

Kami Post akan berisi posting unik idtitle, date posting, dan enum PostStatus yang disebut yang mewakili status posting saat diproses oleh aplikasi. Untuk operasi kami, kami akan memiliki kueri yang mengembalikan semua data posting:

type Query {
  getPosts: [Post]
}

Kami juga akan memiliki mutasi yang menambahkan posting ke sumber data:

type Mutation {
  addPost(id: ID!, title: String, date: AWSDateTime, poststatus: PostStatus): Post
}

Melihat skema kami, PostStatus enum dapat memiliki beberapa status. Kami mungkin ingin tiga status dasar disebut success (posting berhasil diproses), pending (posting sedang diproses), dan error (posting tidak dapat diproses). Untuk menambahkan enum, kita bisa melakukan ini:

enum PostStatus {
  success
  pending
  error
}

Skema lengkap mungkin terlihat seperti ini:

schema {
  query: Query
  mutation: Mutation
}

type Post {
  id: ID!
  title: String
  date: AWSDateTime
  poststatus: PostStatus
}

type Mutation {
  addPost(id: ID!, title: String, date: AWSDateTime, poststatus: PostStatus): Post
}

type Query {
  getPosts: [Post]
}

enum PostStatus {  
  success
  pending
  error
}

Jika pengguna menambahkan a Post dalam aplikasi, addPost operasi akan dipanggil untuk memproses data itu. Ketika resolver dilampirkan untuk mem addPost proses data, ia akan terus memperbarui poststatus dengan status operasi. Ketika ditanyakan, Post akan berisi status akhir data. Perlu diingat, kami hanya menjelaskan bagaimana kami ingin data bekerja dalam skema. Kami berasumsi banyak tentang implementasi resolver kami, yang akan menerapkan logika bisnis aktual untuk menangani data untuk memenuhi permintaan.

Pertimbangan opsional - Langganan

Langganan di AWS AppSync dipanggil sebagai respons terhadap mutasi. Anda mengonfigurasi ini dengan Subscription tipe dan @aws_subscribe() direktif dalam skema untuk menunjukkan mutasi mana yang memanggil satu atau lebih langganan. Untuk informasi selengkapnya tentang mengonfigurasi langganan, lihat Real-time data.

Pertimbangan opsional - Hubungan dan paginasi

Misalkan Anda memiliki satu juta yang Posts disimpan dalam tabel DynamoDB, dan Anda ingin mengembalikan beberapa data itu. Namun, contoh kueri yang diberikan di atas hanya mengembalikan semua posting. Anda tidak ingin mengambil semua ini setiap kali Anda membuat permintaan. Sebagai gantinya, Anda ingin mem- paginate melalui mereka. Buat perubahan berikut pada skema Anda:

schema {
  query: Query
  mutation: Mutation
}

type Post {
  id: ID!
  title: String
  date: AWSDateTime
  poststatus: PostStatus
}

type Mutation {
  addPost(id: ID!, title: String, date: AWSDateTime, poststatus: PostStatus): Post
}

type Query {
  getPosts(limit: Int, nextToken: String): PostIterator
}

enum PostStatus {
  success
  pending
  error
}

type PostIterator {
  posts: [Post]
  nextToken: String
}

PostIteratorJenis ini memungkinkan Anda untuk mengembalikan sebagian dari daftar Post objek dan nextToken untuk mendapatkan bagian berikutnya. Di dalamnyaPostIterator, ada daftar Post item ([Post]) yang dikembalikan dengan token pagination (nextToken). Pada AWS AppSync, ini akan terhubung ke Amazon DynamoDB melalui resolver dan secara otomatis dihasilkan sebagai token terenkripsi. Ini mengubah nilai limit argum maxResults en ke parameter dan nextToken argum exclusiveStartKey en ke parameter. Untuk contoh dan contoh template bawaan di AWS AppSync konsol, lihat Referensi Resolver (JavaScript).