API yang digabungkan - AWS AppSync
Gabungan API dan FederasiResolusi konflik API yang digabungkanMengkonfigurasi skemaMengkonfigurasi mode otorisasiMengkonfigurasi peran eksekusiMengonfigurasi API Gabungan lintas akun menggunakan AWS RAMPenggabunganDukungan tambahan untuk API GabunganBatasan API yang digabungkanMembuat API Gabungan

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

API yang digabungkan

Karena penggunaan GraphQL meluas dalam suatu organisasi, trade-off antara ease-of-use kecepatan pengembangan API dan API dapat muncul. Di satu sisi, organisasi mengadopsi AWS AppSync dan GraphQL untuk menyederhanakan pengembangan aplikasi dengan memberi pengembang API fleksibel yang dapat mereka gunakan untuk mengakses, memanipulasi, dan menggabungkan data dengan aman dari satu atau lebih domain data dengan satu panggilan jaringan. Di sisi lain, tim dalam organisasi yang bertanggung jawab atas domain data yang berbeda digabungkan menjadi satu titik akhir API GraphQL mungkin menginginkan kemampuan untuk membuat, mengelola, dan menerapkan pembaruan API secara independen satu sama lain untuk meningkatkan kecepatan pengembangan mereka.

Untuk mengatasi ketegangan ini, fitur AWS AppSync Merged API memungkinkan tim dari domain data yang berbeda untuk secara independen membuat dan menerapkan AWS AppSync API (misalnya, skema GraphQL, resolver, sumber data, dan fungsi), yang kemudian dapat digabungkan menjadi satu API gabungan. Ini memberi organisasi kemampuan untuk mempertahankan API lintas domain yang mudah digunakan, dan cara bagi tim yang berbeda yang berkontribusi pada API tersebut kemampuan untuk secara cepat dan mandiri membuat pembaruan API.

Dengan menggunakan API Gabungan, organisasi dapat mengimpor sumber daya dari beberapa AWS AppSync API sumber independen ke dalam satu titik akhir API AWS AppSync Gabungan. Untuk melakukannya, Anda AWS AppSync dapat membuat daftar API sumber AWS AppSync sumber, lalu menggabungkan semua metadata yang terkait dengan API sumber termasuk skema, tipe, sumber data, resolver, dan fungsi, ke dalam API gabungan baru. AWS AppSync

Selama penggabungan, ada kemungkinan konflik penggabungan akan terjadi karena ketidakkonsistenan dalam konten data API sumber seperti konflik penamaan tipe saat menggabungkan beberapa skema. Untuk kasus penggunaan sederhana di mana tidak ada definisi dalam konflik API sumber, tidak perlu memodifikasi skema API sumber. API Gabungan yang dihasilkan hanya mengimpor semua jenis, resolver, sumber data, dan fungsi dari API sumber asli. AWS AppSync Untuk kasus penggunaan kompleks di mana konflik muncul, pengguna/tim harus menyelesaikan konflik melalui berbagai cara. AWS AppSyncmemberi pengguna beberapa alat dan contoh yang dapat mengurangi konflik penggabungan.

Penggabungan berikutnya yang dikonfigurasi AWS AppSync akan menyebarkan perubahan yang dibuat di API sumber ke API Gabungan terkait.

Gabungan API dan Federasi

Ada banyak solusi dan pola dalam komunitas GraphQL untuk menggabungkan skema GraphQL dan memungkinkan kolaborasi tim melalui grafik bersama. AWS AppSync API gabungan mengadopsi pendekatan waktu pembuatan untuk komposisi skema, di mana API sumber digabungkan menjadi API Gabungan yang terpisah. Pendekatan alternatif adalah dengan melapisi router run time di beberapa API sumber atau sub-grafik. Dalam pendekatan ini, router menerima permintaan, mereferensikan skema gabungan yang dipertahankannya sebagai metadata, membuat rencana permintaan, dan kemudian mendistribusikan elemen permintaan di seluruh sub-grafik/server yang mendasarinya. Tabel berikut membandingkan pendekatan build-time API Gabungan dengan pendekatan run-time berbasis router untuk komposisi skema GraphQL: AWS AppSync

Feature AppSync Merged API Router-based solutions
Sub-graphs managed independently Yes Yes
Sub-graphs addressable independently Yes Yes
Automated schema composition Yes Yes
Automated conflict detection Yes Yes
Conflict resolution via schema directives Yes Yes
Supported sub-graph servers AWS AppSync* Varies
Network complexity Single, merged API means no extra network hops. Multi-layer architecture requires query planning and delegation, sub-query parsing and serialization/deserialization, and reference resolvers in sub-graphs to perform joins.
Observability support Built-in monitoring, logging, and tracing. A single, Merged API server means simplified debugging. Build-your-own observability across router and all associated sub-graph servers. Complex debugging across distributed system.
Authorization support Built in support for multiple authorization modes. Build-your-own authorization rules.
Cross account security Built-in support for cross-AWS cloud account associations. Build-your-own security model.
Subscriptions support Yes No

* API AWS AppSync gabungan hanya dapat dikaitkan dengan API AWS AppSync sumber. Jika Anda memerlukan dukungan untuk komposisi skema di seluruh AWS AppSync dan AWS AppSync non-sub-grafik, Anda dapat menghubungkan satu atau beberapa AWS AppSync GraphQL dan/atau API Gabungan ke dalam solusi berbasis router. Misalnya, lihat blog referensi untuk menambahkan AWS AppSync API sebagai sub-grafik menggunakan arsitektur berbasis router dengan Apollo Federation v2: Apollo GraphQL Federation with. AWS AppSync

Resolusi konflik API yang digabungkan

Jika terjadi konflik gabungan, AWS AppSync berikan beberapa alat dan contoh kepada pengguna untuk membantu memecahkan masalah.

Arahan skema API yang digabungkan

AWS AppSynctelah memperkenalkan beberapa arahan GraphQL yang dapat digunakan untuk- mengurangi atau menyelesaikan konflik di seluruh API sumber:

  • @canonical: Arahan ini menetapkan prioritas tipe/bidang dengan nama dan data yang serupa. Jika dua atau lebih API sumber memiliki tipe atau bidang GraphQL yang sama, salah satu API dapat membuat anotasi jenis atau bidangnya sebagai kanonik, yang akan diprioritaskan selama penggabungan. Jenis/bidang yang bertentangan yang tidak dianotasi dengan arahan ini di API sumber lain diabaikan saat digabungkan.

  • @hidden: Arahan ini merangkum jenis/bidang tertentu untuk menghapusnya dari proses penggabungan. Tim mungkin ingin menghapus atau menyembunyikan jenis atau operasi tertentu di API sumber sehingga hanya klien internal yang dapat mengakses data tertentu yang diketik. Dengan direktif ini dilampirkan, tipe atau bidang tidak digabungkan ke dalam API Gabungan.

  • @renamed: Arahan ini mengubah nama jenis/bidang untuk mengurangi konflik penamaan. Ada situasi di mana API yang berbeda memiliki jenis atau nama bidang yang sama. Namun, semuanya harus tersedia dalam skema gabungan. Cara sederhana untuk memasukkan semuanya ke dalam API Gabungan adalah dengan mengganti nama bidang menjadi sesuatu yang serupa tetapi berbeda.

Untuk menunjukkan arahan skema utilitas yang disediakan, pertimbangkan contoh berikut:

Dalam contoh ini, mari kita asumsikan bahwa kita ingin menggabungkan dua API sumber. Kami diberi dua skema yang membuat dan mengambil posting (misalnya, bagian komentar atau posting media sosial). Dengan asumsi bahwa tipe dan bidangnya sangat mirip, ada kemungkinan besar konflik selama operasi penggabungan. Cuplikan di bawah ini menunjukkan jenis dan bidang setiap skema.

File pertama, yang disebut Source1.graphQL, adalah skema GraphQL yang memungkinkan pengguna untuk membuat menggunakan mutasi. Posts putPost Masing-masing Post berisi judul dan ID. ID digunakan untuk referensiUser, atau informasi poster (email dan alamat), danMessage, atau muatan (konten). UserJenis ini dianotasi dengan tag @canonical.

# This snippet represents a file called Source1.graphql

type Mutation {
    putPost(id: ID!, title: String!): Post
}

type Post {
    id: ID!
    title: String!
}

type Message {
   id: ID!
   content: String
}

type User @canonical {
   id: ID!
   email: String!
   address: String!
}

type Query {
    singlePost(id: ID!): Post
    getMessage(id: ID!): Message
}

File kedua, yang disebut Source2.graphQL, adalah skema GraphQL yang melakukan hal yang sangat mirip dengan Source1.graphQL. Namun, perhatikan bahwa bidang masing-masing jenis berbeda. Saat menggabungkan kedua skema ini, akan ada konflik penggabungan karena perbedaan ini.

Perhatikan juga bagaimana Source2.graphQL juga berisi beberapa arahan untuk mengurangi konflik ini. PostJenis ini dianotasi dengan tag @hidden untuk mengaburkan dirinya sendiri selama operasi penggabungan. MessageTipe dianotasi dengan tag @renamed untuk memodifikasi nama tipe jika terjadi konflik penamaan dengan tipe lainMessage. ChatMessage

# This snippet represents a file called Source2.graphql

type Post @hidden  {
    id: ID!
    title: String!
    internalSecret: String!
}

type Message @renamed(to: "ChatMessage") {
   id: ID!
   chatId: ID!
   from: User!
   to: User!
}

# Stub user so that we can link the canonical definition from Source1
type User {
   id: ID!
}

type Query {
    getPost(id: ID!): Post
    getMessage(id: ID!): Message @renamed(to: "getChatMessage")
}

Ketika penggabungan terjadi, hasilnya akan menghasilkan MergedSchema.graphql file:

# This snippet represents a file called MergedSchema.graphql

type Mutation {
    putPost(id: ID!, title: String!): Post
}

# Post from Source2 was hidden so only uses the Source1 definition. 
type Post {
    id: ID!
    title: String!
}

# Renamed from Message to resolve the conflict
type ChatMessage {
   id: ID!
   chatId: ID!
   from: User!
   to: User!
}

type Message {
   id: ID!
   content: String
}

# Canonical definition from Source1
type User {
   id: ID!
   email: String!
   address: String!
}

type Query {
    singlePost(id: ID!): Post
    getMessage(id: ID!): Message
    
    # Renamed from getMessage
    getChatMessage(id: ID!): ChatMessage
}

Beberapa hal terjadi dalam penggabungan:

  • UserJenis dari source1.graphQL diprioritaskan daripada User from Source2.graphQL karena anotasi @canonical.

  • MessageJenis dari source1.graphQL disertakan dalam penggabungan. Namun, Message from Source2.graphQL memiliki konflik penamaan. Karena anotasi @renamed, itu juga termasuk dalam penggabungan tetapi dengan nama alternatif. ChatMessage

  • PostJenis dari source1.graphQL disertakan, tetapi Post tipe dari Source2.graphQL tidak. Biasanya, akan ada konflik pada tipe ini, tetapi karena Post tipe dari Source2.graphQL memiliki anotasi @hidden, datanya dikaburkan dan tidak termasuk dalam penggabungan. Hal ini mengakibatkan tidak ada konflik.

  • QueryJenis diperbarui untuk menyertakan konten dari kedua file. Namun, satu GetMessage kueri diganti namanya GetChatMessage karena arahan. Ini menyelesaikan konflik penamaan antara dua kueri dengan nama yang sama.

Ada juga kasus tidak ada arahan yang ditambahkan ke tipe yang bertentangan. Di sini, tipe gabungan akan mencakup penyatuan semua bidang dari semua definisi sumber dari jenis itu. Misalnya, perhatikan contoh berikut:

Skema ini, yang disebut Source1.graphQL, memungkinkan untuk membuat dan mengambil. Posts Konfigurasinya mirip dengan contoh sebelumnya, tetapi dengan informasi yang lebih sedikit.

# This snippet represents a file called Source1.graphql

type Mutation {
    putPost(id: ID!, title: String!): Post
}

type Post  {
    id: ID!
    title: String!
}

type Query {
    getPost(id: ID!): Post
}

Skema ini, yang disebut Source2.graphQL, memungkinkan untuk membuat dan mengambil Reviews (misalnya, rating film atau ulasan restoran). Reviewsdikaitkan dengan Post nilai ID yang sama. Bersama-sama, mereka berisi judul, ID posting, dan pesan payload dari posting ulasan lengkap.

Saat bergabung, akan ada konflik antara kedua Post jenis tersebut. Karena tidak ada anotasi untuk mengatasi masalah ini, perilaku defaultnya adalah melakukan operasi gabungan pada tipe yang bertentangan.

# This snippet represents a file called Source2.graphql

type Mutation {
    putReview(id: ID!, postId: ID!, comment: String!): Review
}

type Post  {
    id: ID!
    reviews: [Review]
}

type Review {
   id: ID!
   postId: ID!
   comment: String!
}

type Query {
    getReview(id: ID!): Review
}

Ketika penggabungan terjadi, hasilnya akan menghasilkan MergedSchema.graphql file:

# This snippet represents a file called MergedSchema.graphql

type Mutation {
    putReview(id: ID!, postId: ID!, comment: String!): Review
    putPost(id: ID!, title: String!): Post
}

type Post  {
    id: ID!
    title: String!
    reviews: [Review]
}

type Review {
   id: ID!
   postId: ID!
   comment: String!
}

type Query {
    getPost(id: ID!): Post
    getReview(id: ID!): Review
}

Beberapa hal terjadi dalam penggabungan:

  • MutationTipe tidak menghadapi konflik dan digabung.

  • Bidang Post tipe digabungkan melalui operasi serikat pekerja. Perhatikan bagaimana penyatuan antara keduanya menghasilkan satuid, satutitle, dan satureviews.

  • ReviewTipe tidak menghadapi konflik dan digabung.

  • QueryTipe tidak menghadapi konflik dan digabung.

Mengelola resolver pada tipe bersama

Dalam contoh di atas, pertimbangkan kasus di mana Source1.graphQL telah mengkonfigurasi resolver unit, Query.getPost yang menggunakan sumber data DynamoDB bernama. PostDatasource Resolver ini akan mengembalikan id dan dari title tipe. Post Sekarang, pertimbangkan Source2.graphQL telah mengonfigurasi resolver pipeline, yang menjalankan dua fungsi. Post.reviews Function1memiliki sumber None data yang dilampirkan untuk melakukan pemeriksaan otorisasi khusus. Function2memiliki sumber data DynamoDB yang dilampirkan untuk menanyakan tabel. reviews

query GetPostQuery {
    getPost(id: "1") {
        id,
        title,
        reviews
    }
}

Ketika kueri di atas dijalankan oleh klien ke titik akhir Merged API, AWS AppSync layanan pertama-tama menjalankan unit resolver for Query.getPost fromSource1, yang memanggil PostDatasource dan mengembalikan data dari DynamoDB. Kemudian, ia menjalankan resolver Post.reviews pipeline di mana Function1 melakukan logika otorisasi khusus dan Function2 mengembalikan ulasan yang diberikan yang ditemukan diid. $context.source Layanan memproses permintaan sebagai satu GraphQL run, dan permintaan sederhana ini hanya akan memerlukan satu token permintaan.

Mengelola konflik resolver pada tipe bersama

Pertimbangkan kasus berikut di mana kami juga menerapkan resolver untuk menyediakan beberapa bidang sekaligus di luar penyelesai bidang di. Query.getPost Source2 source1.graphQL mungkin terlihat seperti ini:

# This snippet represents a file called Source1.graphql

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

type Query {
    getPost(id: ID!): Post
}

Source2.graphQL mungkin terlihat seperti ini:

# This snippet represents a file called Source2.graphql

type Post  {
  id: ID!
  content: String!
  contentHash: String! 
  author: String! 
}

type Query {
    getPost(id: ID!): Post
}

Mencoba menggabungkan kedua skema ini akan menghasilkan kesalahan AWS AppSync penggabungan karena API Gabungan tidak mengizinkan beberapa resolver sumber dilampirkan ke bidang yang sama. Untuk mengatasi konflik ini, Anda dapat menerapkan pola penyelesai bidang yang memerlukan Source2.graphQL untuk menambahkan tipe terpisah yang akan menentukan bidang yang dimilikinya dari tipe tersebut. Post Dalam contoh berikut, kami menambahkan tipe yang disebutPostInfo, yang berisi bidang konten dan penulis yang akan diselesaikan oleh Source2.graphQL. Source1.graphQL akan mengimplementasikan resolver yang dilampirkanQuery.getPost, sementara Source2.graphQL sekarang akan melampirkan resolver untuk memastikan bahwa semua data dapat berhasil diambil: Post.postInfo

type Post  {
  id: ID!
  postInfo: PostInfo
}

type PostInfo {
   content: String!
   contentHash: String!
   author: String!
}

type Query {
    getPost(id: ID!): Post
}

Sementara menyelesaikan konflik semacam itu membutuhkan skema API sumber untuk ditulis ulang dan, berpotensi, klien untuk mengubah kueri mereka, keuntungan dari pendekatan ini adalah bahwa kepemilikan resolver gabungan tetap jelas di seluruh tim sumber.

Mengkonfigurasi skema

Dua pihak bertanggung jawab untuk mengonfigurasi skema untuk membuat API Gabungan:

  • Pemilik API yang digabungkan - Pemilik API yang digabungkan harus mengonfigurasi logika otorisasi Gabungan API dan pengaturan lanjutan seperti pencatatan, penelusuran, caching, dan dukungan WAF.

  • Pemilik API sumber terkait - Pemilik API terkait harus mengonfigurasi skema, resolver, dan sumber data yang membentuk API Gabungan.

Karena skema API Gabungan Anda dibuat dari skema API sumber terkait, skema tersebut hanya dibaca. Ini berarti perubahan skema harus dimulai di API sumber Anda. Di AWS AppSync konsol, Anda dapat beralih antara skema Gabungan dan skema individual dari API sumber yang disertakan dalam API Gabungan menggunakan daftar drop-down di atas jendela Skema.

Mengkonfigurasi mode otorisasi

Beberapa mode otorisasi tersedia untuk melindungi API Gabungan Anda. Untuk mempelajari lebih lanjut tentang mode otorisasiAWS AppSync, lihat Otorisasi dan otentikasi.

Mode otorisasi berikut tersedia untuk digunakan dengan API Gabungan:

  • Kunci API: Strategi otorisasi paling sederhana. Semua permintaan harus menyertakan kunci API di bawah header x-api-key permintaan. Kunci API yang kedaluwarsa disimpan selama 60 hari setelah tanggal kedaluwarsa.

  • AWSIdentity and Access Management (IAM): Strategi otorisasi AWS IAM mengotorisasi semua permintaan yang ditandatangani sigv4.

  • Kumpulan Pengguna Amazon Cognito: Otorisasi pengguna Anda melalui Kumpulan Pengguna Amazon Cognito untuk mencapai kontrol yang lebih halus.

  • AWSLambda Authorizers: Fungsi tanpa server yang memungkinkan Anda untuk mengautentikasi dan mengotorisasi akses ke API Anda menggunakan logika kustom. AWS AppSync

  • OpenID Connect: Jenis otorisasi ini memberlakukan token OpenID connect (OIDC) yang disediakan oleh layanan yang sesuai dengan OIDC. Aplikasi Anda dapat memanfaatkan pengguna dan hak istimewa yang ditentukan oleh penyedia OIDC Anda untuk mengontrol akses.

Mode otorisasi API Gabungan dikonfigurasi oleh pemilik API Gabungan. Pada saat operasi gabungan, API Gabungan harus menyertakan mode otorisasi utama yang dikonfigurasi pada API sumber baik sebagai mode otorisasi utamanya sendiri atau sebagai mode otorisasi sekunder. Jika tidak, itu akan tidak kompatibel, dan operasi penggabungan akan gagal dengan konflik. Saat menggunakan arahan multi-auth di API sumber, proses penggabungan dapat secara otomatis menggabungkan arahan ini ke titik akhir terpadu. Jika mode otorisasi utama dari API sumber tidak cocok dengan mode otorisasi utama API Gabungan, mode ini akan secara otomatis menambahkan arahan autentikasi ini untuk memastikan bahwa mode otorisasi untuk tipe di API sumber konsisten.

Mengkonfigurasi peran eksekusi

Saat membuat API Gabungan, Anda perlu menentukan peran layanan. Peran AWS layanan adalah peran AWS Identity and Access Management (IAM) and Access Management (IAM) yang digunakan oleh AWS layanan untuk melakukan tugas atas nama Anda.

Dalam konteks ini, API Gabungan Anda perlu menjalankan resolver yang mengakses data dari sumber data yang dikonfigurasi di API sumber Anda. Peran layanan yang diperlukan untuk ini adalahmergedApiExecutionRole, dan harus memiliki akses eksplisit untuk menjalankan permintaan pada API sumber yang disertakan dalam API gabungan Anda melalui izin appsync:SourceGraphQL IAM. Selama menjalankan permintaan GraphQL, AWS AppSync layanan akan mengambil peran layanan ini dan mengotorisasi peran untuk melakukan tindakan. appsync:SourceGraphQL

AWS AppSyncmendukung mengizinkan atau menolak izin ini pada bidang tingkat atas tertentu dalam permintaan seperti cara kerja mode otorisasi IAM untuk API IAM. Untuk non-top-level bidang, AWS AppSync mengharuskan Anda untuk menentukan izin pada sumber API ARN itu sendiri. Untuk membatasi akses ke non-top-level bidang tertentu di API Gabungan, sebaiknya terapkan logika kustom dalam Lambda Anda atau menyembunyikan bidang API sumber dari API Gabungan menggunakan direktif @hidden. Jika Anda ingin mengizinkan peran menjalankan semua operasi data dalam API sumber, Anda dapat menambahkan kebijakan di bawah ini. Perhatikan bahwa entri sumber daya pertama memungkinkan akses ke semua bidang tingkat atas dan entri kedua mencakup resolver turunan yang mengotorisasi sumber daya API sumber itu sendiri: 

{
    "Version": "2012-10-17",
    "Statement": [{
        "Effect": "Allow", 
        "Action": [ "appsync:SourceGraphQL"], 
        "Resource": [ 
            "arn:aws:appsync:us-west-2:123456789012:apis/YourSourceGraphQLApiId/*", 
            "arn:aws:appsync:us-west-2:123456789012:apis/YourSourceGraphQLApiId"] 
    }] 
}

Jika Anda ingin membatasi akses hanya ke bidang tingkat atas tertentu, Anda dapat menggunakan kebijakan seperti ini:

{
    "Version": "2012-10-17",
    "Statement": [{
        "Effect": "Allow", 
        "Action": [ "appsync:SourceGraphQL"], 
        "Resource": [ 
            "arn:aws:appsync:us-west-2:123456789012:apis/YourSourceGraphQLApiId/types/Query/fields/<Field-1>",
            "arn:aws:appsync:us-west-2:123456789012:apis/YourSourceGraphQLApiId"] 
    }] 
}

Anda juga dapat menggunakan wizard pembuatan API AWS AppSync konsol untuk menghasilkan peran layanan agar API Gabungan dapat mengakses sumber daya yang dikonfigurasi dalam API sumber yang berada di akun yang sama dengan API gabungan Anda. Jika API sumber Anda tidak berada di akun yang sama dengan API gabungan, Anda harus terlebih dahulu membagikan sumber daya menggunakan AWS Resource Access Manager (AWS RAM).

Mengonfigurasi API Gabungan lintas akun menggunakan AWS RAM

Saat membuat API Gabungan, Anda dapat mengaitkan API sumber secara opsional dari akun lain yang telah dibagikan melalui AWS Resource Access Manager ()AWS RAM. AWS RAMmembantu Anda berbagi sumber daya dengan aman di seluruh AWS akun, dalam organisasi atau unit organisasi (OU) Anda, dan dengan peran dan pengguna IAM.

AWS AppSyncterintegrasi dengan AWS RAM untuk mendukung konfigurasi dan mengakses API sumber di beberapa akun dari satu API Gabungan. AWS RAMmemungkinkan Anda membuat pembagian sumber daya, atau wadah sumber daya dan set izin yang akan dibagikan untuk masing-masing sumber daya. Anda dapat menambahkan AWS AppSync API ke pembagian sumber daya diAWS RAM. Dalam pembagian sumber daya, AWS AppSync berikan tiga set izin berbeda yang dapat dikaitkan dengan AWS AppSync API di RAM:

  1. AWSRAMPermissionAppSyncSourceApiOperationAccess: Set izin default yang ditambahkan saat berbagi AWS AppSync API AWS RAM jika tidak ada izin lain yang ditentukan. Set izin ini digunakan untuk berbagi AWS AppSync API sumber dengan pemilik API Gabungan. Set izin ini mencakup izin untuk appsync:AssociateMergedGraphqlApi pada API sumber serta appsync:SourceGraphQL izin yang diperlukan untuk mengakses sumber daya API sumber saat runtime.

  2. AWSRAMPermissionAppSyncMergedApiOperationAccess: Set izin ini harus dikonfigurasi saat berbagi API Gabungan dengan pemilik API sumber. Set izin ini akan memberi API sumber kemampuan untuk mengonfigurasi API Gabungan termasuk kemampuan untuk mengaitkan API sumber apa pun yang dimiliki oleh prinsipal target ke API Gabungan dan untuk membaca dan memperbarui asosiasi API sumber dari API Gabungan.

  3. AWSRAMPermissionAppSyncAllowSourceGraphQLAccess: Set izin ini memungkinkan appsync:SourceGraphQL izin untuk digunakan dengan AWS AppSync API. Ini dimaksudkan untuk digunakan untuk berbagi API sumber dengan pemilik API Gabungan. Berbeda dengan izin default yang ditetapkan untuk akses operasi API sumber, set izin ini hanya menyertakan izin appsync:SourceGraphQL runtime. Jika pengguna memilih untuk membagikan akses operasi Gabungan API ke pemilik API sumber, mereka juga perlu membagikan izin ini dari API sumber kepada pemilik API Gabungan agar memiliki akses runtime melalui titik akhir API Gabungan.

AWS AppSyncjuga mendukung izin yang dikelola pelanggan. Jika salah satu izin AWS -managed yang disediakan tidak berfungsi, Anda dapat membuat izin yang dikelola pelanggan sendiri. Izin yang dikelola pelanggan adalah izin terkelola yang Anda buat dan pertahankan dengan menentukan secara tepat tindakan mana yang dapat dilakukan dalam kondisi mana dengan sumber daya yang digunakan bersama. AWS RAM AWS AppSyncmemungkinkan Anda memilih dari tindakan berikut saat membuat izin Anda sendiri:

  1. appsync:AssociateSourceGraphqlApi

  2. appsync:AssociateMergedGraphqlApi

  3. appsync:GetSourceApiAssociation

  4. appsync:UpdateSourceApiAssociation

  5. appsync:StartSchemaMerge

  6. appsync:ListTypesByAssociation

  7. appsync:SourceGraphQL

Setelah Anda membagikan API sumber atau API Gabungan dengan benar AWS RAM dan, jika perlu, undangan berbagi sumber daya telah diterima, undangan tersebut akan terlihat di AWS AppSync konsol saat Anda membuat atau memperbarui asosiasi API sumber pada API Gabungan Anda. Anda juga dapat mencantumkan semua AWS AppSync API yang telah dibagikan menggunakan AWS RAM akun Anda terlepas dari izin yang ditetapkan dengan memanggil ListGraphqlApis operasi yang disediakan oleh AWS AppSync dan menggunakan filter OTHER_ACCOUNTS pemilik.

catatan

Berbagi melalui AWS RAM memerlukan pemanggil AWS RAM untuk memiliki izin untuk melakukan appsync:PutResourcePolicy tindakan pada API apa pun yang sedang dibagikan.

Penggabungan

Mengelola penggabungan

API gabungan dimaksudkan untuk mendukung kolaborasi tim pada titik akhir terpaduAWS AppSync. Tim dapat secara independen mengembangkan API GraphQL sumber terisolasi mereka sendiri di backend sementara AWS AppSync layanan mengelola integrasi sumber daya ke dalam titik akhir API Gabungan tunggal untuk mengurangi gesekan dalam kolaborasi dan mengurangi waktu tunggu pengembangan.

Penggabungan otomatis

API sumber yang terkait dengan API AWS AppSync Gabungan Anda dapat dikonfigurasi untuk menggabungkan (auto-merge) secara otomatis ke dalam API Gabungan setelah perubahan apa pun dilakukan pada API sumber. Ini memastikan bahwa perubahan dari API sumber selalu disebarkan ke titik akhir API Gabungan di latar belakang. Setiap perubahan dalam skema API sumber akan diperbarui di API Gabungan selama tidak menimbulkan konflik gabungan dengan definisi yang ada di API Gabungan. Jika pembaruan di API sumber memperbarui resolver, sumber data, atau fungsi, sumber daya yang diimpor juga akan diperbarui.Ketika konflik baru diperkenalkan yang tidak dapat diselesaikan secara otomatis (diselesaikan secara otomatis), pembaruan skema API Gabungan ditolak karena konflik yang tidak didukung selama operasi penggabungan. Pesan kesalahan tersedia di konsol untuk setiap asosiasi API sumber yang memiliki statusMERGE_FAILED. Anda juga dapat memeriksa pesan kesalahan dengan memanggil GetSourceApiAssociation operasi untuk asosiasi API sumber tertentu menggunakan AWS SDK atau menggunakan AWS CLI seperti ini:

aws appsync get-source-api-association --merged-api-identifier <Merged API ARN> --association-id <SourceApiAssociation id>

Ini akan menghasilkan hasil dalam format berikut:

{
    "sourceApiAssociation": {
        "associationId": "<association id>",
        "associationArn": "<association arn>",
        "sourceApiId": "<source api id>",
        "sourceApiArn": "<source api arn>",
        "mergedApiArn": "<merged api arn>",
        "mergedApiId": "<merged api id>",
        "sourceApiAssociationConfig": {
            "mergeType": "MANUAL_MERGE"
        },
        "sourceApiAssociationStatus": "MERGE_FAILED",
        "sourceApiAssociationStatusDetail": "Unable to resolve conflict on object with name title: Merging is not supported for fields with different types."
    }
}

Penggabungan manual

Pengaturan default untuk API sumber adalah penggabungan manual. Untuk menggabungkan perubahan apa pun yang terjadi di API sumber sejak API Gabungan terakhir diperbarui, pemilik API sumber dapat memanggil penggabungan manual dari AWS AppSync konsol atau melalui StartSchemaMerge operasi yang tersedia di SDK AWS dan CLI. AWS

Dukungan tambahan untuk API Gabungan

Mengkonfigurasi langganan

Tidak seperti pendekatan berbasis router untuk komposisi skema GraphQL, API Gabungan menyediakan dukungan bawaan untuk langganan AWS AppSync GraphQL. Semua operasi langganan yang ditentukan dalam API sumber terkait Anda akan secara otomatis bergabung dan berfungsi di API Gabungan Anda tanpa modifikasi. Untuk mempelajari selengkapnya tentang cara AWS AppSync mendukung langganan melalui WebSockets koneksi tanpa server, lihat Data waktu nyata.

Mengkonfigurasi observabilitas

AWS AppSyncAPI gabungan menyediakan pencatatan, pemantauan, dan metrik bawaan melalui Amazon. CloudWatch AWS AppSyncjuga menyediakan dukungan bawaan untuk melacak via AWS X-Ray.

Mengkonfigurasi domain kustom

AWS AppSyncAPI gabungan menyediakan dukungan bawaan untuk menggunakan domain khusus dengan GraphQL dan titik akhir Real-time API Gabungan Anda.

Mengkonfigurasi caching

AWS AppSyncAPI yang digabungkan memberikan dukungan bawaan untuk melakukan cache respons tingkat permintaan dan/atau tingkat resolver secara opsional serta kompresi respons. Untuk mempelajari lebih lanjut, lihat Caching dan kompresi.

Mengkonfigurasi API pribadi

AWS AppSyncAPI gabungan menyediakan dukungan bawaan untuk API Pribadi yang membatasi akses ke GraphQL API Gabungan dan titik akhir Real-time untuk lalu lintas yang berasal dari titik akhir VPC yang dapat Anda konfigurasi.

Mengkonfigurasi aturan firewall

AWS AppSyncAPI gabungan menyediakan dukungan bawaan untukAWS WAF, yang memungkinkan Anda untuk melindungi API Anda dengan mendefinisikan aturan firewall aplikasi web.

Mengkonfigurasi log audit

AWS AppSyncAPI gabungan menyediakan dukungan bawaan untuk AWS CloudTrail, yang memungkinkan Anda mengonfigurasi dan mengelola log audit.

Batasan API yang digabungkan

Saat mengembangkan API Gabungan, perhatikan aturan berikut:

  1. API Gabungan tidak dapat menjadi API sumber untuk API Gabungan lainnya.

  2. API sumber tidak dapat dikaitkan dengan lebih dari satu API Gabungan.

  3. Batas ukuran default untuk dokumen skema API Gabungan adalah 10 MB.

  4. Jumlah default API sumber yang dapat dikaitkan dengan API Gabungan adalah 10. Namun, Anda dapat meminta peningkatan batas jika membutuhkan lebih dari 10 API sumber di API Gabungan.

Membuat API Gabungan

Untuk membuat API Gabungan di konsol

  1. Masuk ke AWS Management Console dan buka AWS AppSynckonsol.

    1. Di Dashboard, pilih Create API.

  2. Pilih API Gabungan, lalu pilih Berikutnya.

  3. Di halaman Tentukan detail API, masukkan informasi berikut:

    1. Di bawah Detail API, masukkan informasi berikut:

      1. Tentukan nama API gabungan Anda. Bidang ini adalah cara untuk memberi label GraphQL API Anda agar mudah membedakannya dari API GraphQL lainnya.

      2. Tentukan detail Kontak. Bidang ini bersifat opsional dan melampirkan nama atau grup ke GraphQL API. Ini tidak ditautkan atau dihasilkan oleh sumber daya lain dan berfungsi seperti bidang nama API.

    2. Di bawah peran Layanan, Anda harus melampirkan peran eksekusi IAM ke API gabungan Anda sehingga AWS AppSync dapat mengimpor dan menggunakan sumber daya Anda dengan aman saat runtime. Anda dapat memilih untuk membuat dan menggunakan peran layanan baru, yang akan memungkinkan Anda untuk menentukan kebijakan dan sumber daya yang AWS AppSync akan digunakan. Anda juga dapat mengimpor peran IAM yang ada dengan memilih Gunakan peran layanan yang ada, lalu memilih peran dari daftar drop-down.

    3. Di bawah konfigurasi API Pribadi, Anda dapat memilih untuk mengaktifkan fitur API pribadi. Perhatikan bahwa pilihan ini tidak dapat diubah setelah membuat API gabungan. Untuk informasi selengkapnya tentang API pribadi, lihat Menggunakan API AWS AppSync Pribadi.

      Pilih Berikutnya setelah Anda selesai.

  4. Selanjutnya, Anda harus menambahkan GraphQL API yang akan digunakan sebagai dasar untuk API gabungan Anda. Di halaman Pilih sumber API, masukkan informasi berikut:

    1. Di API dari tabel AWS akun Anda, pilih Tambahkan API Sumber. Dalam daftar GraphQL API, setiap entri akan berisi data berikut:

      1. Nama: Bidang nama API GraphQL API.

      2. API ID: Nilai ID unik GraphQL API.

      3. Mode autentikasi primer: Mode otorisasi default untuk GraphQL API. Untuk informasi selengkapnya tentang mode otorisasiAWS AppSync, lihat Otorisasi dan otentikasi.

      4. Mode autentikasi tambahan: Mode otorisasi sekunder yang dikonfigurasi di GraphQL API.

      5. Pilih API yang akan Anda gunakan di API gabungan dengan memilih kotak centang di sebelah bidang Nama API. Setelah itu, pilih Add Source API. GraphQL API yang dipilih akan muncul di API dari AWS tabel akun Anda.

    2. Di tabel API dari AWS akun lain, pilih Tambahkan API Sumber. API GraphQL dalam daftar ini berasal dari akun lain yang membagikan sumber dayanya ke akun Anda AWS Resource Access Manager melalui (). AWS RAM Proses untuk memilih GraphQL API dalam tabel ini sama dengan proses di bagian sebelumnya. Untuk informasi selengkapnya tentang berbagi sumber dayaAWS RAM, lihat Apa ituAWS Resource Access Manager? .

      Pilih Berikutnya setelah Anda selesai.

    3. Tambahkan mode autentikasi utama Anda. Lihat Otorisasi dan otentikasi untuk informasi selengkapnya. Pilih Berikutnya.

    4. Tinjau input Anda, lalu pilih Buat API.