Pemecahan masalah Azure Cosmos DB

Solusi untuk masalah umum emulator, konektivitas, dan konfigurasi skema Azure Cosmos DB di Data API builder.

Pertanyaan umum

Apa itu dukungan Azure Cosmos DB di DAB?

Penyusun API Data mendukung Azure Cosmos DB sebagai back end NoSQL. DAB terhubung ke Cosmos DB menggunakan Azure Cosmos DB .NET SDK dan mengekspos entitas sebagai jenis GraphQL. Dukungan REST untuk Cosmos DB tidak tersedia; semua kueri disajikan melalui titik akhir GraphQL.

API apa yang digunakan DAB dengan Cosmos DB?

DAB menggunakan Azure Cosmos DB untuk NoSQL API (sebelumnya SQL API). API Cosmos DB lainnya seperti MongoDB, Gremlin, dan Table tidak didukung. Pastikan akun Cosmos DB Anda dibuat dengan Azure Cosmos DB for NoSQL API.

Apakah emulator Cosmos DB didukung?

Ya. Emulator Azure Cosmos DB didukung untuk pengembangan lokal. Atur string koneksi ke titik akhir default emulator: AccountEndpoint=https://localhost:8081/;AccountKey=<emulator-key>;. Anda harus mempercayai sertifikat emulator yang ditandatangani sendiri pada komputer pengembangan sebelum DAB dapat terhubung.

Masalah umum

Sertifikat emulator tidak tepercaya

Gejala: DAB gagal terhubung ke emulator dengan kesalahan validasi SSL atau sertifikat.

Menyebabkan: Emulator Azure Cosmos DB menggunakan sertifikat yang ditandatangani sendiri yang tidak dipercaya secara default pada sistem operasi.

Resolusi: Ekspor dan instal sertifikat emulator dari https://localhost:8081/_explorer/emulator.pem ke penyimpanan sertifikat akar tepercaya komputer lokal. Di Windows, buka file sertifikat dan instal ke Komputer Lokal > Otoritas Sertifikasi Akar Tepercaya. Mulai ulang DAB setelah menginstal sertifikat.

Tidak dapat tersambung ke emulator

Gejala: DAB gagal memulai dengan The remote name could not be resolved: 'localhost' atau koneksi menolak kesalahan yang menunjuk ke port 8081.

Menyebabkan: Emulator tidak berjalan, atau titik akhir atau kunci akun dalam string koneksi salah.

Resolusi: Mulai emulator Azure Cosmos DB dari menu Mulai atau dengan menjalankan emulator yang dapat dieksekusi. Konfirmasikan bahwa string koneksi menggunakan AccountEndpoint=https://localhost:8081/ dan kunci emulator yang benar, yang ditampilkan di halaman penjelajah data emulator di https://localhost:8081/_explorer/index.html.

File skema GraphQL tidak ditemukan

Gejala: DAB gagal memulai dengan kesalahan seperti Schema file not found atau graphql-schema path is invalid.

Menyebabkan: Jalur graphql.schema dalam dab-config.json titik ke file yang tidak ada atau menggunakan jalur relatif yang salah.

Resolusi: Verifikasi bahwa file skema ada di jalur yang ditentukan dalam dab-config.json. Jalur relatif terhadap lokasi file konfigurasi. Jalankan dab init dengan --cosmosdb_nosql-schema untuk meregenerasi konfigurasi dengan jalur skema yang benar, lalu konfirmasikan bahwa file .gql atau .graphql ada di lokasi tersebut.

Kueri mengembalikan hasil kosong

Gejala: Kueri GraphQL mengembalikan daftar kosong meskipun kontainer memiliki data.

Menyebabkan: Nama kontainer atau jalur kunci partisi dalam konfigurasi entitas tidak cocok dengan kontainer Cosmos DB yang sebenarnya, atau nama database salah.

Resolusi: Periksa nilai entitas source di dab-config.json dan konfirmasikan cocok dengan nama kontainer yang tepat (peka huruf besar/kecil). Verifikasi bidang di database bawah data-source cocok dengan nama database Cosmos DB. Di portal Microsoft Azure, buka Data Explorer untuk akun dan konfirmasikan database dan nama kontainer.

Koneksi TCP dalam mode langsung gagal dengan emulator Linux

Gejala: DAB macet atau kehabisan waktu saat menyambungkan ke emulator Cosmos DB Linux di Docker, bahkan dengan set AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE=127.0.0.1. Permintaan terhenti saat mengulang koneksi.

Penyebab: DAB saat ini menggunakan secara keras ConnectionMode.Direct, yang menyebabkan Cosmos SDK menemukan titik akhir partisi fisik (seperti 172.17.0.2:1025010255) dan membuka koneksi TCP dengan mereka. Dari komputer host, alamat kontainer tersebut tidak dapat dijangkau. Mode gateway akan merutekan semua lalu lintas melalui satu titik akhir HTTPS (port 8081 pada emulator) dan menghindari masalah sepenuhnya. Ini adalah batasan yang diketahui yang dilacak dalam masalah GitHub #3401.

Resolusi: Atur AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE=127.0.0.1 saat memulai kontainer emulator. Ini memaksa emulator untuk mengiklankan 127.0.0.1 sebagai alamatnya, membuat titik akhir yang ditemukan dapat dijangkau dari host. Hingga mode Gateway dapat dikonfigurasi di DAB, penimpaan IP adalah solusi yang direkomendasikan untuk pengembangan lokal.

Autentikasi On-Behalf-Of (OBO) tidak didukung

Gejala: Mengonfigurasi autentikasi On-Behalf-Of (OBO) untuk instans DAB yang didukung Azure Cosmos DB gagal atau token tidak diteruskan seperti yang diharapkan.

Menyebabkan: Autentikasi OBO saat ini hanya didukung untuk SQL Server dan Azure SQL. Dukungan untuk Azure Cosmos DB belum diterapkan. Ini adalah batasan yang diketahui yang dilacak dalam masalah GitHub #3159.

Resolusi: Gunakan metode autentikasi yang didukung seperti kunci akun Cosmos DB atau identitas terkelola. Ikuti masalah GitHub untuk pembaruan saat dukungan OBO diperluas ke database non-SQL Server.

GraphQL pada filter gagal pada Cosmos DB

Gejala: Kueri GraphQL yang menggunakan operator in terhadap entitas yang didukung oleh Cosmos DB gagal pada runtime dengan Tidak dapat membangun operasi predikat IN yang tidak diketahui, meskipun 'in' muncul dalam skema melalui introspeksi.

Menyebabkan: Operator in diekspos dalam skema GraphQL yang dihasilkan untuk IdFilterInput dan StringFilterInput, tetapi logika terjemahan filter Cosmos DB yang mendasar tidak mengimplementasikannya. Ketidakcocokan antara skema dan pelaksana kueri ini adalah bug yang diketahui yang dilacak dalam masalah GitHub #3061.

Resolusi: Hindari menggunakan operator "in" dalam kueri GraphQL terhadap entitas Cosmos DB. Gunakan salah satu solusi ini sebagai gantinya:

Ganti "in" dengan beberapa ekspresi atau ekspresi +q untuk daftar nilai yang tetap dan kecil.
Gunakan beberapa alias baca titik-titik (item_by_pk) saat melakukan kueri berdasarkan daftar ID yang diketahui.
Filter di sisi klien setelah mengambil kumpulan hasil yang lebih luas.

Agregasi tidak didukung untuk Cosmos DB

Gejala: Kueri agregat GraphQL (seperti hitungan, jumlah, atau vg) terhadap entitas yang didukung Cosmos DB gagal atau tidak tersedia dalam skema.

Menyebabkan: Penyusun API Data saat ini tidak mendukung operasi agregasi untuk Azure Cosmos DB. Agregasi hanya tersedia untuk database relasional. Ini adalah batasan yang diketahui yang dilacak dalam masalah GitHub #2849.

Resolusi: Saat ini tidak ada solusi dalam DAB. Lakukan agregasi sisi klien setelah mengambil kumpulan hasil, atau gunakan API kueri bawaan Cosmos DB secara langsung untuk operasi agregat. Ikuti isu GitHub untuk mendapatkan pembaruan.

Kueri plural (daftar) tidak dapat dinonaktifkan untuk memberlakukan pembacaan titik secara eksklusif

Gejala: Klien dapat melakukan kueri untuk daftar item secara luas terhadap entitas Cosmos DB, mengonsumsi RU dalam jumlah tinggi, padahal tujuannya hanyalah untuk mengizinkan pembacaan satuan melalui item_by_pk.

Penyebab: Penyusun API Data saat ini tidak menyediakan opsi konfigurasi untuk menekan kueri plural dan membatasi entitas hanya untuk pembacaan individu. Ini adalah batasan yang diketahui yang dilacak dalam masalah GitHub #2433.

Resolusi: Sebagai solusi parsial, batasi aksi daftar dalam izin entitas untuk membatasi peran mana yang bisa melakukan kueri daftar. Penghapusan penuh jenis kueri plural dari skema belum didukung.

Kunci partisi hierarkis (MultiHash) tidak didukung

Gejala: Mutasi terhadap kontainer Cosmos DB yang menggunakan kunci partisi hierarkis (lebih dari satu jalur kunci partisi) gagal dengan kesalahan Nilai 'jenis' 'MultiHash' yang ditentukan dalam definisi kunci partisi tidak valid. Pilih jenis partisi 'Hash'.

Menyebabkan: Pembuat API Data hanya mendukung definisi kunci partisi kunci tunggal (Hash). Kontainer yang dikonfigurasi dengan kunci partisi hierarkis (MultiHash) tidak didukung. Ini adalah batasan yang diketahui yang dilacak dalam masalah GitHub #1733.

Resolusi: Saat ini tidak ada solusi dalam DAB. Jika memungkinkan, desain ulang kontainer untuk menggunakan satu kunci partisi. Jika kunci partisi hierarkis diperlukan oleh model data Anda, ikuti masalah GitHub untuk pembaruan saat dukungan multi-hash ditambahkan.

Kunci partisi multiHash tidak didukung

Gejala: Mutasi terhadap kontainer Cosmos DB yang menggunakan kunci partisi hierarkis (multi-hash) gagal dengan nilai 'jenis' 'MultiHash' yang ditentukan dalam definisi kunci partisi tidak valid. Pilih jenis partisi 'Hash'.

Menyebabkan: Penyusun API Data hanya mendukung kunci partisi Hash nilai tunggal untuk Azure Cosmos DB. Kontainer yang dikonfigurasi dengan kunci partisi hierarkis (MultiHash) misalnya, /TenantId, /EntityType, /EntityId tidak didukung. Ini adalah batasan yang diketahui yang dilacak dalam masalah GitHub #1733.

Resolusi: Saat ini tidak ada solusi dalam DAB. Gunakan kontainer dengan satu kunci partisi Hash sebagai gantinya. Jika partisi hierarkis diperlukan, pertimbangkan untuk merestrukturisasi kontainer atau mengikuti masalah GitHub untuk pembaruan saat dukungan kunci partisi MultiHash ditambahkan.

Beberapa mutasi tidak atomik pada Cosmos DB

Gejala: Ketika beberapa mutasi GraphQL dalam satu permintaan dikirim terhadap entitas Cosmos DB, kegagalan dalam satu mutasi tidak membatalkan yang lainnya. Penulisan parsial dapat terjadi.

Penyebab: Pembuat API data tidak membungkus beberapa mutasi Cosmos DB dalam batch transaksional. Tidak seperti database relasional, di mana beberapa mutasi dalam permintaan dijalankan secara atomik, mutasi Cosmos DB dikeluarkan secara independen. Ini adalah batasan yang diketahui yang dilacak dalam masalah GitHub #1621.

Resolusi: Rancang aplikasi Anda untuk memperlakukan setiap mutasi Cosmos DB sebagai independen. Jika atomisitas diperlukan, gunakan langsung Cosmos DB SDK dengan dukungan batch transaksi dalam lingkup item pada partisi logis yang sama. Ikuti isu GitHub untuk pembaruan ketika dukungan mutasi transaksional ditambahkan untuk Cosmos DB.

Nama jenis GraphQL dalam file skema tidak cocok dengan konfigurasi entitas

Gejala: DAB dimulai tanpa kesalahan tetapi kueri mengembalikan hasil yang tidak terduga atau jenis yang salah, karena nama jenis GraphQL yang ditentukan dalam schema.gql tidak cocok dengan nama jenis tunggal yang dikonfigurasi untuk entitas di dab-config.json.

Menyebabkan: Penyusun API Data saat ini tidak memvalidasi bahwa nama jenis GraphQL dalam file skema cocok dengan nama jenis tunggal yang dideklarasikan untuk entitas. Ketidakcocokan secara diam-diam menghasilkan skema yang tidak konsisten. Ini adalah batasan yang diketahui yang dilacak dalam masalah GitHub #1556.

Resolusi: Verifikasi secara manual bahwa nama jenis dalam schema.gql (diatur melalui direktif @model ) cocok dengan nilai tunggal dalam konfigurasi graphql.type entitas di dab-config.json. Misalnya, jika dab-config.json menyatakan "tunggal": "Lokasi", file skema harus berisi ype @model(name:"Lokasi".

Nama jenis GraphQL dalam file skema tidak cocok dengan nama jenis tunggal entitas

Menyebabkan: Penyusun API Data saat ini tidak memvalidasi bahwa @model nama direktif dalam file skema GraphQL cocok dengan nama jenis tunggal yang ditetapkan untuk entitas. Ketika berbeda, ketidakcocokan secara diam-diam menghasilkan perilaku skema yang salah. Ini adalah batasan yang diketahui yang dilacak dalam masalah GitHub #1556.

Resolusi: Pastikan nama jenis secara manual di schema.gql sama persis dengan nilai tunggal dalam konfigurasi graphql.type entitas di dab-config.json. Misalnya, jika entitas mendefinisikan "tunggal": "Lokasi", file skema harus mendeklarasikan Lokasi @model(nameype :"Lokasi"). Jalankan validasi dab setelah membuat perubahan untuk menangkap kesalahan konfigurasi lainnya.

Jenis enum dalam file skema GraphQL menyebabkan kegagalan penyusunan skema

Gejala: DAB gagal memulai dengan HotChocolate.SchemaException: Tidak dapat mengatasi referensi jenis ... Kesalahan OrderByInput ketika file schema.gql Cosmos DB menentukan jenis num GraphQL yang digunakan pada bidang jenis objek.

Menyebabkan: Penyusun API Data saat ini tidak mendukung jenis enum GraphQL dalam file skema Cosmos DB. Ketika enum digunakan sebagai jenis bidang, pembuat skema tidak dapat menghasilkan jenis OrderByInput yang sesuai dan melemparkan pengecualian yang tidak tertangani. Ini adalah batasan yang diketahui yang dilacak dalam masalah GitHub #748.

Resolusi: Ganti bidang enum dengan setara skalarnya (misalnya, gunakan String alih-alih jenis enum kustom) dalam schema.gql. Terapkan validasi enum di lapisan aplikasi Anda daripada dalam definisi skema DAB.

Jenis enum dalam skema GraphQL menyebabkan DAB gagal saat startup

Gejala: DAB gagal memulai dengan kesalahan HotChocolate.SchemaException seperti 'Tidak dapat menyelesaikan referensi tipe: None: FooOrderByInput' ketika file skema Cosmos DB GraphQL menentukan jenis enum yang digunakan pada model.

Penyebab: Penyusun skema API Data tidak menangani jenis enum GraphQL yang ditentukan dalam schema.gql dengan benar. Ketika enum dirujuk sebagai jenis bidang pada model, pembuatan jenis OrderByInput internal gagal memprosesnya, menghentikan inisialisasi skema. Ini adalah batasan yang diketahui yang dilacak dalam masalah GitHub #748.

Resolusi: Hindari menentukan jenis enum GraphQL dalam schema.gql untuk entitas Cosmos DB. Sebagai solusinya, ganti bidang enum dengan String dan terapkan nilai yang valid di lapisan aplikasi. Ikuti isu GitHub untuk pembaruan saat dukungan enum ditambahkan.

Pemetaan kolom (alias) tidak didukung untuk entitas Cosmos DB

Gejala: Suatu bagian pemetaan yang ditentukan untuk entitas Cosmos DB di dab-config.json tidak berpengaruh, karena nama-nama bidang asli masih diekspos dalam skema GraphQL alih-alih menggunakan alias yang telah dikonfigurasikan.

Menyebabkan: Fitur pemetaan, yang memungkinkan mengekspos nama kolom database di bawah nama bidang yang berbeda di API, diimplementasikan hanya untuk database relasional. Entitas Cosmos DB saat ini tidak mendukung pemetaan bidang. Ini adalah batasan yang diketahui yang dilacak dalam masalah GitHub #1512.

Resolusi: Gunakan nama bidang persis seperti yang muncul di dokumen Cosmos DB. Jika alias diperlukan, terapkan di lapisan aplikasi klien. Ikuti isu GitHub untuk mendapatkan pembaruan ketika dukungan pemetaan ditambahkan untuk Cosmos DB.

Variabel mutasi GraphQL tidak diselesaikan nama variabel yang disimpan alih-alih nilai

Gejala: Mutasi GraphQL yang menggunakan variabel (misalnya, createExample(item: { id: , name: })) menyimpan nama variabel "" dan "" dalam database alih-alih nilai aktual yang diteruskan dalam payload ariables.

Menyebabkan: Penyusun API Data saat ini tidak menyelesaikan referensi variabel GraphQL dalam input mutasi untuk Cosmos DB. Substitusi variabel diabaikan dan nama variabel secara literal ditulis sebagai nilai kolom. Ini adalah bug yang diketahui yang dilacak dalam masalah GitHub #1482.

Resolusi: Sebariskan nilai variabel langsung dalam isi mutasi alih-alih menggunakan variabel GraphQL. Misalnya, ganti id: dengan id: "1234". Ini tidak ideal untuk penggunaan produksi, jadi ikuti issue di GitHub untuk pembaruan saat penanganan variabel diperbaiki dalam mutasi Cosmos DB.

Jenis union dalam file skema GraphQL menyebabkan kesalahan 500

Gejala: DAB mengembalikan kode status 500 pada semua permintaan GraphQL saat schema.gql menentukan jenis serikat GraphQL. Log startup menunjukkan HotChocolate.SchemaException: Tidak dapat menyelesaikan referensi tipe ... OrderByInput.

Menyebabkan: Penyusun API Data tidak mendukung jenis serikat GraphQL dalam file skema Cosmos DB. Seperti jenis enum, jenis union menyebabkan penyusun skema gagal saat menghasilkan jenis input pengurutan/filter. Ini adalah bug yang diketahui yang dilacak dalam masalah GitHub #1384.

Resolusi: Hapus definisi jenis union dari schema.gql. Model data polimorfik menggunakan jenis objek tunggal dengan bidang opsional, atau pisahkan data di seluruh entitas terpisah. Ikuti isu GitHub untuk pembaruan saat dukungan tipe union ditambahkan.

Membuat mutasi gagal pada runtime ketika id didefinisikan sebagai nullable dalam skema

Gejala: Mutasi pembuatan mengembalikan kesalahan runtime meskipun skema tampak valid. Kesalahan terjadi karena bidang id tidak disediakan atau null.

Menyebabkan: Cosmos DB memerlukan bidang id untuk setiap dokumen dan menggunakannya sebagai bagian dari kunci partisi. Jika schema.gql menyatakan id sebagai nullable (misalnya, id: ID daripada id: ID!), DAB menerima skema tersebut tetapi akan mengalami kegagalan saat runtime ketika mutasi pembuatan tidak menyertakan bidang tersebut. Skema harus memberlakukan non-null pada waktu validasi skema, tetapi saat ini tidak. Celah ini dilacak dalam masalah GitHub #1238.

Resolusi: Selalu deklarasikan bidang id sebagai non-null dalam skema Cosmos DB GraphQL Anda:

graphql type MyEntity @model(name: "MyEntity") { id: ID! ... }

Memastikan id: ID! menyebabkan klien menerima kesalahan tingkat skema yang jelas jika id dihilangkan, bukan kegagalan runtime yang tidak jelas.

Hubungan GraphQL melingkar menyebabkan pengecualian kelebihan tumpukan saat startup

Gejala: DAB mengalami crash saat startup dengan pengecualian luapan tumpukan ketika schema.gql mendefinisikan jenis yang saling mereferensikan dalam siklus (misalnya, Pemain mereferensikan Game, dan Game mereferensikan Player).

Menyebabkan: Penyusun skema memandu semua referensi jenis secara rekursif untuk menghasilkan jenis input mutasi. Hubungan melingkar menyebabkan rekursi tak terbatas, menghabiskan tumpukan panggilan. Ini adalah bug yang diketahui yang dilacak dalam masalah GitHub #746.

Resolusi: Hindari referensi jenis melingkar dalam schema.gql. Putuskan siklus dengan menghapus rujukan balik dari salah satu jenis, atau modelkan hubungan sebagai daftar ID (bidang skalar) daripada jenis objek bersarang. Ikuti isu GitHub untuk pembaruan mengenai dukungan untuk hubungan melingkar.

Kunci partisi selalu id, dan jalur kunci partisi kustom tidak didukung.

Gejala: DAB hanya berfungsi dengan kontainer Cosmos DB yang menggunakan /id sebagai kunci partisi. Kontainer yang dipartisi oleh bidang lain (misalnya, /userId atau /category) tidak dapat dikueri atau dimutasi dengan benar.

Penyebab: Pembangun API Data menetapkan id sebagai kunci partisi untuk semua entitas Cosmos DB. Tidak ada cara untuk menentukan jalur kunci partisi kustom baik di dab-config.json atau schema.gql. Ini adalah batasan yang diketahui yang dilacak dalam masalah GitHub #747.

Resolusi: Desain kontainer baru dengan /id sebagai kunci partisi saat menggunakan DAB. Untuk kontainer yang ada dengan kunci partisi yang berbeda, DAB saat ini tidak didukung. Ikuti isu GitHub untuk mendapatkan pembaruan terkait penambahan kunci partisi yang dapat dikonfigurasi.

Kueri array berlapis dalam dokumen (penggabungan dalam item) tidak didukung

Gejala: Anda tidak dapat memfilter atau melintasi properti array berlapis dalam dokumen Cosmos DB menggunakan DAB. Kueri yang memerlukan JOIN di Cosmos DB untuk elemen-elemen array tidak mengembalikan hasil apa pun atau menghasilkan kesalahan.

Menyebabkan: Penyusun API Data tidak mendukung gabungan intra-dokumen Cosmos DB (juga disebut gabungan dalam item), yang diperlukan untuk mengkueri array berlapis dalam satu dokumen. Ini adalah batasan yang diketahui yang dilacak dalam masalah GitHub #262.

Resolusi: Ratakan array berlapis ke dalam entitas terpisah atau dokumen anak jika Anda perlu memfilter kontennya. Atau, lakukan pasca-pemrosesan dokumen lengkap di lapisan aplikasi Anda. Pantau isu di GitHub untuk pembaruan saat dukungan penyatuan intra-dokumen ditambahkan.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-04-02