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 API GraphQL didefinisikan oleh skema tunggal yang berisi jenis dan bidang yang menjelaskan bagaimana data dari permintaan akan diisi. Data yang mengalir melalui Anda API dan operasi yang dilakukan harus divalidasi terhadap skema.

Secara umum, sistem tipe GraphQL menggambarkan kemampuan server GraphQL dan digunakan untuk menentukan apakah kueri valid. Sistem tipe server sering disebut sebagai skema server dan dapat terdiri dari berbagai jenis objek, jenis skalar, tipe input, dan banyak lagi. GraphQL bersifat deklaratif dan diketik dengan kuat, artinya 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 ini. 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 kueri APIs untuk 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 APIs berkembang dari waktu ke waktu, dan memungkinkan alat pengembang yang kuat. “

Bagian ini mencakup bagian pertama dari implementasi GraphQL Anda, skema. Dengan menggunakan kutipan di atas, skema memainkan peran “memberikan deskripsi data yang lengkap dan dapat dimengerti dalam data AndaAPI”. Dengan kata lain, skema GraphQL adalah representasi tekstual dari data, operasi, dan hubungan layanan Anda di antara mereka. Skema ini 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 untuk meninjau bagian Skema sebelum melanjutkan.

Untuk mengutip bagian Skema, skema GraphQL ditulis dalam Schema Definition Language (). SDL SDLterdiri 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-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 ingin kemampuan untuk menambah atau mengambil buku dan penulis. UMLRepresentasi sederhana dari hubungan ini mungkin terlihat seperti ini:

Dalam GraphQL, Author entitas Book dan mewakili dua jenis 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 tipe 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 adalah di mana ia 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 jenis objek khusus mendasar: kueri, mutasi, dan langganan. Untuk informasi selengkapnya, lihat Objek khusus.

Karena getAuthor dan getBook keduanya meminta data, mereka akan ditempatkan dalam jenis 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 jenis 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 jenis objek Mutation khusus. Namun, dari halaman Types, kita juga tahu bahwa input langsung merujuk Objek tidak diperbolehkan karena mereka benar-benar tipe output. 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 jenisnya 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 kita lakukan:

Seperti yang Anda lihat, proses pembuatan skema membutuhkan banyak konsep dari pemodelan data (terutama pemodelan basis data) secara umum. Anda dapat menganggap skema sesuai dengan bentuk data dari sumbernya. Ini juga berfungsi sebagai model yang akan diterapkan oleh 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 bernamaschema.graphql. AWS AppSync memungkinkan pengguna untuk membuat skema baru untuk APIs GraphQL mereka menggunakan berbagai metode. Dalam contoh ini, kita akan membuat kosong API bersama dengan skema kosong.

Console

1. Masuk ke AWS Management Console dan buka AppSynckonsol.

   1. Di Dasbor, pilih Buat API.

   2. Di bawah APIopsi, pilih APIsGraphQL, Desain dari awal, lalu Berikutnya.

      1. Untuk APInama, ubah nama yang sudah terisi menjadi apa yang dibutuhkan aplikasi Anda.

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

      3. Di bawah APIKonfigurasi pribadi, Anda dapat mengaktifkan API fitur pribadi. Private hanya API dapat diakses dari VPC endpoint (VPCE) yang dikonfigurasi. Untuk informasi selengkapnya, lihat Pribadi APIs.

         Kami tidak menyarankan 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 spesifik AndaAPI. Anda bisa tahu karena API nama akan berada di bagian atas dasbor. Jika ini bukan masalahnya, Anda dapat memilih APIsdi Sidebar, lalu pilih API di APIsdasbor.

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

3. Di editor Skema, Anda dapat mengonfigurasi schema.graphql file Anda. 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 menggunakanCLI, pastikan Anda memiliki izin yang benar untuk mengakses dan membuat sumber daya dalam layanan. Anda mungkin ingin menetapkan kebijakan hak istimewa paling sedikit 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 perintah. create-graphql-api

   Anda harus mengetikkan dua parameter untuk perintah khusus ini:

   1. nameDari AndaAPI.

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

   catatan

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

   Contoh perintah mungkin terlihat seperti ini:

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

   Output akan dikembalikan diCLI. 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 gumpalan basis-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 basis-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 asinkron, sehingga Anda dapat memeriksa status output bahkan saat skema masih dibuat.

CDK

Tip

Sebelum Anda menggunakanCDK, kami sarankan untuk meninjau dokumentasi CDK resmi beserta AWS AppSyncCDKreferensi.

Langkah-langkah yang tercantum di bawah ini hanya akan menampilkan contoh umum dari 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 ini sedikit berbeda. Idealnya, schema.graphql file Anda seharusnya sudah dibuat. Anda hanya perlu membuat file baru dengan ekstensi .graphql file. Ini bisa menjadi 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 API GraphQL, file stack Anda perlu mengimpor layanan: AWS AppSync

   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 API GraphQL, kita akan mengatakan. new appsync.GraphqlApi(args_go_here) Langkah berikut menggambarkan ini.

3. APIGraphQL paling dasar akan menyertakan name a for API the and the path. schema

   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 API GraphQL baru dengan menelepon. appsync.GraphqlApi(scope: Construct, id: string, props: GraphqlApiProps) Ruang lingkupnya adalahthis, yang mengacu pada objek saat ini. Id adalah API_ID, yang akan menjadi nama AWS CloudFormation sumber daya API GraphQL Anda saat dibuat. GraphqlApiPropsBerisi API GraphQL Anda dan file. name schema schemaAkan menghasilkan skema (SchemaFile.fromAsset) dengan mencari path absolut (__dirname) untuk .graphql file (schema_name.graphql). Dalam skenario nyata, file skema Anda mungkin akan berada di dalam CDK aplikasi.

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

Menambahkan tipe ke skema

Sekarang Anda telah 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 jenis objek generik dengan id bidang wajib disimpan sebagaiID, title bidang yang disimpan sebagaiString, dan date bidang yang disimpan sebagaiAWSDateTime. Untuk melihat daftar jenis dan bidang dan apa yang mereka lakukan, lihat Skema. Untuk melihat daftar skalar dan apa yang mereka lakukan, lihat referensi Jenis.

CLI

catatan

Kami merekomendasikan membaca versi konsol terlebih dahulu jika Anda belum melakukannya.

• Anda dapat membuat tipe objek dengan menjalankan create-typeperintah.

  Anda harus memasukkan beberapa parameter untuk perintah khusus ini:

  1. api-idDari AndaAPI.

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

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

  3. formatMasukan 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 diCLI. 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 jenis objek generik dengan id bidang wajib disimpan sebagaiID, title bidang yang disimpan sebagaiString, dan date bidang yang disimpan sebagaiAWSDateTime. Untuk melihat daftar jenis dan bidang dan apa yang mereka lakukan, lihat Skema. Untuk melihat daftar skalar dan apa yang mereka lakukan, lihat Jenis referensi.

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

CDK

Tip

Sebelum Anda menggunakanCDK, kami sarankan untuk meninjau dokumentasi CDK resmi beserta AWS AppSyncCDKreferensi.

Langkah-langkah yang tercantum di bawah ini hanya akan menampilkan contoh umum dari 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 tipe, 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 API GraphQL Anda, Anda harus menerapkan ulang aplikasi.

Jenis 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.

Jenis ID skalar khususnya adalah pengidentifikasi unik yang dapat berupa atauString. Int 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 jenis objek khusus (Query,Mutation, danSubscription), perilaku mereka sangat berbeda karena mereka diekspos sebagai titik masuk untuk AndaAPI. Mereka juga lebih tentang membentuk operasi daripada data. Untuk informasi selengkapnya, lihat Jenis kueri dan mutasi.

Pada topik jenis 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 kueri 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. QueryTipe kami mendefinisikan getObj bidang yang mengembalikan daftar Obj_Type_1 objek. Perhatikan bahwa itu Obj_Type_1 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

Kami merekomendasikan membaca versi konsol terlebih dahulu jika Anda belum melakukannya.

1. Buat schema root dengan query definisi dengan menjalankan create-typeperintah.

   Anda harus memasukkan beberapa parameter untuk perintah khusus ini:

   1. api-idDari AndaAPI.

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

      schema {
        query: Query
      }

   3. formatMasukan 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 diCLI. 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 perintah. update-type 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 AndaAPI.

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

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

      schema {
        query: Query
      }

      Skema setelah menambahkan subscription akan terlihat seperti ini:

      schema {
        query: Query
        subscription: Subscription
      }

   4. formatMasukan 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 diCLI. 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 akan tetap berfungsi dalam contoh ini.

2. Buat Query tipe dengan menjalankan create-typeperintah.

   Anda harus memasukkan beberapa parameter untuk perintah khusus ini:

   1. api-idDari AndaAPI.

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

      type Query {
        getObj: [Obj_Type_1]
      }

   3. formatMasukan 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 diCLI. 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. QueryTipe kami mendefinisikan getObj bidang yang mengembalikan daftar Obj_Type_1 objek.

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

CDK

Tip

Sebelum Anda menggunakanCDK, kami sarankan untuk meninjau dokumentasi CDK resmi beserta AWS AppSyncCDKreferensi.

Langkah-langkah yang tercantum di bawah ini hanya akan menampilkan contoh umum dari 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 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 API GraphQL Anda, Anda harus menerapkan ulang aplikasi.

Anda sekarang telah melihat contoh membuat 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 disebutMutation. SepertiQuery, operasi lapangan di dalam 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 adalah 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_Mutation biasanya 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, itu menerimaid,title, dan date bidang dari Obj_Type_1 objek sebagai parameter. Seperti yang Anda lihat, ini sangat mirip dengan 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 kemudian 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 skema Ekspor 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

Kami merekomendasikan membaca versi konsol terlebih dahulu jika Anda belum melakukannya.

1. Perbarui skema root Anda dengan menjalankan update-typeperintah.

   Anda harus memasukkan beberapa parameter untuk perintah khusus ini:

   1. api-idDari AndaAPI.

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

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

      schema {
        query: Query
        mutation: Mutation
      }

   4. formatMasukan 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 diCLI. 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-typeperintah.

   Anda harus memasukkan beberapa parameter untuk perintah khusus ini:

   1. api-idDari AndaAPI.

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

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

   3. formatMasukan 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 diCLI. 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 menggunakanCDK, kami sarankan untuk meninjau dokumentasi CDK resmi beserta AWS AppSyncCDKreferensi.

Langkah-langkah yang tercantum di bawah ini hanya akan menampilkan contoh umum dari 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 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 API GraphQL 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 umum yang 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 jenis yang mewakili data posting individu:

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

PostWill kami berisi postingan title unikid, posting, dan enum PostStatus yang disebut yang mewakili status posting saat diproses oleh aplikasi. date 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 bisa memiliki beberapa status. Kita mungkin ingin tiga status dasar dipanggil success (post berhasil diproses), pending (post sedang diproses), dan error (post 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 tersebut. Sebagai resolver dilampirkan untuk addPost memproses data, itu akan terus memperbarui poststatus dengan status operasi. Saat ditanyakan, Post akan berisi status akhir data. Perlu diingat, kami hanya menjelaskan bagaimana kami ingin data bekerja dalam skema. Kami mengasumsikan banyak tentang implementasi resolver kami, yang akan menerapkan logika bisnis aktual untuk menangani data guna memenuhi permintaan.

Pertimbangan opsional - Langganan

Langganan di AWS AppSync dipanggil sebagai respons terhadap mutasi. Anda mengonfigurasi ini dengan Subscription tipe dan @aws_subscribe() arahan dalam skema untuk menunjukkan mutasi mana yang memanggil satu atau beberapa langganan. Untuk informasi selengkapnya tentang mengonfigurasi langganan, lihat Data waktu nyata.

Pertimbangan opsional - Hubungan dan pagination

Misalkan Anda memiliki satu juta Posts disimpan dalam tabel DynamoDB, dan Anda ingin mengembalikan beberapa data itu. Namun, contoh query yang diberikan di atas hanya mengembalikan semua posting. Anda tidak ingin mengambil semua ini setiap kali Anda membuat permintaan. Sebaliknya, Anda ingin membuat paginasi 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 tahun AWS AppSync, ini akan terhubung ke Amazon DynamoDB melalui resolver dan secara otomatis dihasilkan sebagai token terenkripsi. Ini mengubah nilai limit argumen ke maxResults parameter dan nextToken argumen ke exclusiveStartKey parameter. Untuk contoh dan contoh templat bawaan di AWS AppSync konsol, lihat Referensi resolusi () JavaScript.