Menyiapkan penyusun API Data untuk Azure Cosmos DB untuk NoSQL

Azure Cosmos DB untuk NoSQL adalah database dokumen skema-agnostik. Tidak seperti database relasional, Azure Cosmos DB tidak memiliki skema yang telah ditentukan sebelumnya yang dapat diintrospeksi oleh penyusun API Data (DAB) secara otomatis. Panduan ini menjelaskan cara membuat file skema GraphQL dan mengonfigurasi DAB untuk bekerja dengan kontainer Azure Cosmos DB Anda.

Prasyarat

  • Azure Cosmos DB untuk akun NoSQL dengan setidaknya satu database dan kontainer
  • CLI pembangun API Data. Menginstal CLI

Memahami persyaratan skema

Karena Azure Cosmos DB for NoSQL tidak memberlakukan skema, DAB tidak dapat secara otomatis menghasilkan jenis GraphQL dari data Anda. Sebagai gantinya, Anda perlu menyediakan file skema GraphQL yang menentukan:

  • Jenis objek yang mewakili struktur dokumen kontainer Anda
  • Direktif @model yang memetakan jenis GraphQL ke nama entitas dalam konfigurasi DAB Anda
  • Direktif @authorize (opsional) yang membatasi akses tingkat bidang ke peran tertentu

Anda dapat membuat skema dengan menggunakan contoh berikut atau menghasilkannya dari data Cosmos DB yang ada dengan dab export perintah .

Membuat file skema GraphQL

Buat .gql file yang menjelaskan model data Anda. File skema menggunakan GraphQL Schema Definition Language (SDL) standar dengan arahan kustom untuk DAB.

Contoh skema dasar

Contoh ini mendefinisikan tipe Book dengan bidang umum yang ditemukan dalam wadah buku:

type Book @model(name: "Book") {
  id: ID
  title: String
  year: Int
  pages: Int
  Authors: [Author]
}

type Author @model(name: "Author") {
  id: ID
  firstName: String
  lastName: String
}

Membuat skema dari data Cosmos DB

Jika Anda sudah memiliki data dalam kontainer, Anda dapat mengambil sampelnya untuk membuat skema awal. Perintah ini menulis file skema GraphQL yang disimpulkan ke direktori output yang Anda tentukan dengan -o.

dab export \
  --graphql \
  --generate \
  -o ./schema-out

Secara default, pengambilan sampel menggunakan TopNExtractor.

Mode pengambilan sampel yang didukung adalah TopNExtractor, , EligibleDataSamplerdan TimePartitionedSampler.

Nota

Parameter -o/--output diperlukan. Jika Anda tidak menentukan nama file skema, DAB menghasilkan schema.gql di direktori output.

Untuk mode dan opsi lainnya, lihat referensi CLI untuk dab export.

Direktif @model diperlukan. Ini memetakan jenis GraphQL ke nama entitas dalam file konfigurasi DAB Anda. Parameter name harus sama persis dengan nama entitas.

Nota

Bidang Authors: [Author] mewakili array yang disematkan dalam dokumen Buku, bukan hubungan dengan kontainer terpisah. Di Azure Cosmos DB for NoSQL, data terkait harus disematkan dalam dokumen yang sama daripada disimpan dalam kontainer terpisah.

Skema dengan otorisasi

Untuk membatasi akses ke bidang tertentu, gunakan direktif @authorize . Arahan roles ini menerima parameter yang menentukan peran mana yang dapat mengakses bidang.

type Book @model(name: "Book") {
  id: ID
  title: String @authorize(roles: ["authenticated", "metadataviewer"])
  internalNotes: String @authorize(roles: ["editor"])
  Authors: [Author]
}

Dalam contoh ini:

  • Bidang title hanya dapat diakses oleh pengguna dengan authenticated peran atau metadataviewer
  • Bidang internalNotes ini hanya dapat diakses oleh pengguna dengan editor peran
  • Bidang tanpa @authorize dapat diakses berdasarkan izin tingkat entitas

Anda juga dapat menerapkan @authorize pada tingkat jenis untuk membatasi akses ke seluruh jenis:

type InternalReport @model(name: "InternalReport") @authorize(roles: ["editor", "auditor"]) {
  id: ID
  title: String
  confidentialData: String
}

Penting

Direktif @authorize berfungsi sebagai tambahan izin tingkat entitas yang ditentukan dalam konfigurasi runtime. Izin direktif @authorize dan entitas harus memungkinkan akses agar permintaan berhasil.

Misalnya, jika bidang memiliki @authorize(roles: ["editor"]), tetapi entitas tidak memiliki entri izin untuk peran tersebut editor , akses ke bidang tersebut ditolak.

Peringatan

@authorize(policy: "...") tidak didukung dalam alur skema ini. Gunakan @authorize(roles: [...]).

Mengonfigurasi Runtime DAB

Setelah membuat file skema Anda, konfigurasikan DAB untuk menggunakannya dengan akun Azure Cosmos DB Anda.

Menginisialisasi konfigurasi

Gunakan perintah dab init untuk membuat file konfigurasi untuk Azure Cosmos DB:

dab init \
  --database-type cosmosdb_nosql \
  --cosmosdb_nosql-database <your-database-name> \
  --graphql-schema schema.gql \
  --connection-string "<your-connection-string>"

Ganti <your-database-name> dengan nama database Azure Cosmos DB Anda dan <your-connection-string> dengan string koneksi Anda.

Secara opsional, sertakan --cosmosdb_nosql-container <your-container-name> untuk mengatur kontainer default dalam konfigurasi sumber data.

Petunjuk / Saran

Untuk lingkungan produksi, gunakan variabel lingkungan untuk string koneksi alih-alih melakukan hardcoding:

dab init \
    --database-type cosmosdb_nosql \
    --cosmosdb_nosql-database <your-database-name> \
    --graphql-schema schema.gql \
    --connection-string "@env('COSMOSDB_CONNECTION_STRING')"

Menambahkan entitas

Tambahkan entitas yang sesuai dengan kontainer Anda. Nama entitas harus cocok dengan @model(name: "...") nilai dalam skema Anda:

dab add Book \
  --source Book \
  --permissions "anonymous:read"

Parameter --source menerima baik <container-name> atau <database-name>.<container-name>. Gunakan format dua bagian saat Anda ingin eksplisit tentang database dan kontainer.

Contoh file konfigurasi

Setelah inisialisasi, file konfigurasi Anda akan terlihat mirip dengan contoh berikut:

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/download/v1.2.11/dab.draft.schema.json",
  "data-source": {
    "database-type": "cosmosdb_nosql",
    "options": {
      "database": "Library",
      "schema": "schema.gql"
    },
    "connection-string": "@env('COSMOSDB_CONNECTION_STRING')"
  },
  "entities": {
    "Book": {
      "source": "Book",
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["read"]
        },
        {
          "role": "metadataviewer",
          "actions": ["read"]
        }
      ]
    }
  }
}

Nota

Jalur schema dalam file konfigurasi relatif terhadap lokasi file konfigurasi DAB. Pastikan file skema GraphQL Anda berada di direktori yang benar.

URL ini $schema menunjuk ke rilis DAB tertentu. Gunakan URL skema yang cocok dengan versi DAB Anda.

Akses bidang berbasis peran

Saat menggunakan direktif @authorize dengan peran, pertimbangkan bagaimana peran ditetapkan:

Skenario Penetapan peran Akses ke @authorize kolom
Permintaan anonim Tidak ada peran yang ditetapkan Ditolak
Permintaan terautentikasi Peran sistem authenticated ditetapkan secara otomatis Diizinkan jika peran cocok
Permintaan peran kustom Sertakan X-MS-API-ROLE header dengan nama peran Diizinkan jika peran cocok

Tabel ini berlaku untuk bidang atau jenis yang secara eksplisit menyertakan @authorize. Untuk bidang tanpa @authorize, izin pada tingkat entitas menentukan akses.

Untuk permintaan terautentikasi yang memerlukan peran kustom, kirim X-MS-API-ROLE header:

GET /graphql HTTP/1.1
Host: localhost:5000
Authorization: Bearer <your-jwt-token>
X-MS-API-ROLE: metadataviewer

Kueri lintas kontainer

Operasi GraphQL di seluruh kontainer tidak didukung di Azure Cosmos DB untuk NoSQL.

Jika Anda mencoba mengonfigurasi hubungan antara entitas dalam kontainer yang berbeda dengan menggunakan dab add atau dab update, validasi CLI gagal.

Pesan kesalahan CLI adalah: Adding/updating Relationships is currently not supported in CosmosDB.

Untuk detail konfigurasi hubungan (didukung untuk database lain), lihat Konfigurasi hubungan.

Mengatasi batasan lintas kontainer

Untuk mengatasi batasan ini, pertimbangkan untuk merestrukturisasi model data Anda untuk menggunakan dokumen yang disematkan dalam satu kontainer. Pendekatan ini sering lebih efisien untuk Azure Cosmos DB dan selaras dengan praktik terbaik pemodelan data NoSQL.

Misalnya, alih-alih menggunakan kontainer Book dan Author yang terpisah dengan hubungan:

// Embedded model in a single container
{
  "id": "book-1",
  "title": "Introduction to DAB",
  "authors": [
    {
      "firstName": "Jane",
      "lastName": "Developer"
    }
  ]
}

Untuk informasi selengkapnya tentang strategi pemodelan data, lihat Pemodelan data di Azure Cosmos DB.

Ketersediaan REST API

Penyusun API Data tidak menghasilkan titik akhir REST untuk Azure Cosmos DB untuk NoSQL karena Azure Cosmos DB sudah menyediakan REST API asli yang komprehensif untuk operasi dokumen.

Saat Anda menggunakan DAB dengan Azure Cosmos DB untuk NoSQL, DAB hanya mengekspos titik akhir GraphQL dan tidak menghasilkan OpenAPI. Untuk mengakses data Anda melalui REST, gunakan Azure Cosmos DB REST API secara langsung.

Masalah konfigurasi umum

File skema tidak ditemukan

  • Kesalahan: GraphQL schema file not found
  • Solusi: Pastikan schema path dalam konfigurasi Anda relatif terhadap lokasi file konfigurasi.

Nama entitas tidak cocok

  • Kesalahan: Entity '<name>' not found in schema
  • Solusi: Verifikasi nama entitas dalam konfigurasi Anda cocok dengan direktif @model(name: "...") dengan tepat. Nama adalah peka terhadap huruf besar/kecil.

Akses kolom tanpa izin

  • Kesalahan: Kesalahan otorisasi GraphQL (misalnya, ketika peran tidak diizinkan)
  • Solusi: Periksa apakah @authorize peran dan izin entitas memungkinkan akses ke peran pemohon.

Langkah selanjutnya

Quickstart: Gunakan penyusun API Data dengan NoSQL

Konten terkait

  • Last updated on