Referensi fitur khusus database untuk penyusun API Data

Referensi ini mencakup fitur, perilaku, dan persyaratan yang khusus untuk satu atau beberapa platform database yang didukung oleh penyusun API Data (DAB). Untuk matriks perbandingan fitur lintas database, lihat Ketersediaan fitur.

Dukungan versi database

DAB mendukung platform database berikut. Persyaratan versi minimum berlaku untuk penyebaran yang dikelola sendiri. Database platform-as-a-service (PaaS) tidak memiliki persyaratan versi minimum karena layanan mengelola versi.

Platform database Singkatan Versi minimum Catatan
SQL Server Keluarga SQL 2016
Azure SQL Keluarga SQL N/A (PaaS)
Microsoft Fabric SQL Keluarga SQL N/A (PaaS)
Azure Cosmos DB for NoSQL Cosmos DB N/A (PaaS) Hanya GraphQL; tidak ada titik akhir REST
PostgreSQL PGSQL 11
MySQL MySQL 8
Azure Synapse Analytics (Kumpulan SQL Khusus) SQLDW N/A (PaaS) Kumpulan SQL tanpa server tidak didukung

Penting

Verifikasi bahwa database pengembangan lokal Anda dan database apa pun yang disebarkan memenuhi persyaratan versi minimum. DAB terhubung menggunakan driver yang sama di kedua lingkungan. Versi lama di salah satu lokasi menyebabkan kesalahan runtime.

SQL Server dan Azure SQL

SESSION_CONTEXT

Untuk SQL Server dan Azure SQL, DAB dapat menyebarluaskan klaim pengguna yang diautentikasi ke database dengan memanggil sp_set_session_context sebelum menjalankan setiap kueri. Mekanisme ini memungkinkan kebijakan keamanan tingkat baris asli SQL dan prosedur tersimpan membaca identitas penelepon dari dalam mesin database.

Ketika set-session-context diaktifkan dalam konfigurasi DAB, DAB mengirimkan semua klaim terautentikasi sebagai pasangan kunci-nilai:

EXEC sp_set_session_context 'roles', 'editor', @read_only = 0;
EXEC sp_set_session_context 'oid', 'a1b2c3d4-...', @read_only = 0;
-- Your query executes after claims are set
SELECT * FROM dbo.Documents;

Klaim umum yang dikirim meliputi roles, sub, oid, dan klaim kustom apa pun yang disertakan idP Anda dalam JWT.

Aktifkan SESSION_CONTEXT

Atur --set-session-context true saat memanggil dab init:

dab init \
  --database-type mssql \
  --connection-string "@env('SQL_CONNECTION_STRING')" \
  --set-session-context true

Atau atur properti langsung di dab-config.json:

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')",
    "options": {
      "set-session-context": true
    }
  }
}

Peringatan

Mengaktifkan set-session-context menonaktifkan penembolokan respons untuk sumber data tersebut. Karena setiap set permintaan menetapkan nilai sesi yang berbeda, respons yang di-cache dari sesi satu pengguna tidak boleh dilayani ke sesi lain.

Menggunakan SESSION_CONTEXT di SQL

Setelah mengaktifkan set-session-context, objek SQL Anda dapat membaca nilai klaim:

-- Read a claim in a stored procedure
DECLARE @role NVARCHAR(256) = CAST(SESSION_CONTEXT(N'roles') AS NVARCHAR(256));

-- Use a claim in a row-level security predicate function
CREATE FUNCTION dbo.RlsPredicate(@claimRole NVARCHAR(256))
RETURNS TABLE
WITH SCHEMABINDING
AS RETURN SELECT 1 AS result
WHERE @claimRole = CAST(SESSION_CONTEXT(N'roles') AS NVARCHAR(256));

Untuk panduan lengkap, lihat Menerapkan keamanan tingkat baris dengan konteks sesi.

SESSION_CONTEXT dan pengumpulan koneksi

DAB mengatur ulang semua nilai konteks sesi di awal setiap permintaan. Namun, karena set-session-context memaksa semantik koneksi per pengguna, penggunaan kembali koneksi di seluruh pengguna dihindari secara otomatis saat opsi ini diaktifkan.

Varian string koneksi

DAB menggunakan Microsoft.Data.SqlClient untuk SQL Server dan Azure SQL. Pustaka mendukung format string koneksi ini.

Format umum:

Metode autentikasi Pola string koneksi
Masuk SQL Server=tcp:<server>.database.windows.net;Database=<db>;User ID=<user>;Password=<pwd>;
Identitas yang dikelola Server=tcp:<server>.database.windows.net;Database=<db>;Authentication=Active Directory Managed Identity;
Identitas Terkelola yang Ditugaskan Pengguna Server=tcp:<server>.database.windows.net;Database=<db>;Authentication=Active Directory Managed Identity;User ID=<client-id>;
Kredensial Azure default Server=tcp:<server>.database.windows.net;Database=<db>;Authentication=Active Directory Default;

Petunjuk / Saran

Simpan string koneksi dalam variabel lingkungan dan referensikan dengan @env('SQL_CONNECTION_STRING'). Untuk penyebaran produksi, simpan string koneksi di Azure Key Vault dan referensikan dengan @akv().

Jenis data yang tidak didukung

Jenis data SQL Server dan Azure SQL berikut ini tidak didukung oleh DAB:

Jenis data Alasan
geography Jenis geospasial; serialisasi tidak didukung
geometry Jenis spasial planar; serialisasi tidak didukung
hierarchyid Jenis data hierarkis; serialisasi tidak didukung
json Jenis JSON asli (saat ini dalam pratinjau)
rowversion Jenis penerapan versi baris; tidak disertakan dalam respons API
sql_variant Kolom jenis variabel; inferensi tipe tidak didukung
vector Jenis vektor (saat ini dalam pratinjau)
xml Jenis XML; serialisasi tidak didukung

Azure Cosmos DB for NoSQL

Persyaratan skema

Tidak seperti database relasional, Azure Cosmos DB for NoSQL bersifat skema-agnostik. DAB tidak dapat mengintrospiksi kontainer Cosmos DB untuk menghasilkan jenis GraphQL. Anda harus menyediakan file skema GraphQL (.gql) yang menentukan struktur dokumen Anda.

File skema menggunakan GraphQL Schema Definition Language (SDL) standar dengan dua arahan kustom:

Direktif Required Description
@model Yes Memetakan jenis GraphQL ke nama entitas DAB
@authorize No Membatasi bidang atau mengetik akses ke peran tertentu

@model Direktif

Arahan @model(name: "...") diperlukan pada setiap jenis GraphQL yang Anda ekspos melalui DAB. Nilai name harus sama persis dengan nama entitas dalam file konfigurasi DAB Anda.

type Book @model(name: "Book") {
  id: ID
  title: String
  year: Int
}

@authorize Direktif

Direktif @authorize ini menyediakan kontrol akses tingkat bidang dan tingkat jenis untuk kueri Cosmos DB GraphQL. Ini menerima parameter yang roles mencantumkan peran yang dapat mengakses bidang atau jenis.

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

Anda juga dapat menerapkan @authorize pada tingkat jenis:

type InternalReport @model(name: "InternalReport") @authorize(roles: ["auditor"]) {
  id: ID
  summary: String
}

Penting

Direktif @authorizeditambahkan ke izin tingkat entitas. Baik direktif maupun blok izin entitas harus memungkinkan permintaan akses berhasil. Jika bidang memiliki @authorize(roles: ["editor"]) tetapi entitas tidak memiliki entri izin untuk editor, permintaan ditolak.

Nota

@authorize(policy: "...") tidak didukung. Gunakan @authorize(roles: [...]) saja.

Untuk panduan penyiapan lengkap, lihat Menyiapkan penyusun API Data untuk Azure Cosmos DB for NoSQL.

Tidak tersedianya REST API

DAB tidak menghasilkan titik akhir REST untuk Azure Cosmos DB untuk NoSQL. Azure Cosmos DB menyediakan REST API asli yang komprehensif untuk operasi dokumen. Hanya titik akhir GraphQL yang dihasilkan. Dokumen OpenAPI tidak dihasilkan untuk entitas Cosmos DB.

Untuk mengakses data melalui REST, gunakan REST API Azure Cosmos DB secara langsung.

Fitur yang tidak didukung untuk Cosmos DB

Fitur berikut ini tidak didukung untuk Azure Cosmos DB untuk NoSQL:

Feature Catatan
Titik akhir REST Gunakan REST API Cosmos DB asli sebagai gantinya
Kebijakan database Predikat kebijakan memerlukan semantik kueri relasional
Prosedur yang disimpan Tidak didukung sebagai entitas DAB
Hubungan Hubungan lintas kontainer tidak didukung
Pengurutan ($orderby) Tidak didukung dalam kueri GraphQL
Aggregation Tidak didukung
Beberapa mutasi Tidak didukung
Konteks sesi Fitur khusus SQL

PostgreSQL

Versi minimum

PostgreSQL 11 atau yang lebih baru diperlukan. DAB menggunakan Npgsql sebagai driver PostgreSQL-nya.

Jenis data yang tidak didukung

Jenis data PostgreSQL berikut ini tidak didukung oleh DAB:

Jenis data Catatan
bytea String biner; serialisasi tidak didukung
date Gunakan timestamp atau timestamptz
smalldatetime Bukan jenis PostgreSQL asli
datetime2 Bukan asli; biasanya ditangani oleh timestamp
timestamptz Tanda waktu dengan zona waktu; tidak didukung
time Waktu hari tanpa tanggal
localtime Waktu berbasis jam sistem

Prosedur yang disimpan

Prosedur tersimpan tidak didukung untuk entitas PostgreSQL. Gunakan tabel dan tampilan sebagai gantinya.

MySQL

Versi minimum

MySQL 8 atau yang lebih baru diperlukan.

Jenis data yang tidak didukung

Jenis data MySQL berikut ini tidak didukung oleh DAB:

Jenis data Catatan
UUID Pengidentifikasi Unik Universal
DATE Tanggal kalender
SMALLDATETIME Penyimpanan tanggal dan waktu yang kurang tepat
DATETIME2 Bukan asli; Menggunakan datetime
DATETIMEOFFSET Tanggal dan waktu dengan zona waktu
TIME Waktu hari tanpa tanggal
LOCALTIME Waktu saat ini berdasarkan jam sistem

Prosedur yang disimpan

Prosedur tersimpan tidak didukung untuk entitas MySQL. Gunakan tabel sebagai gantinya.

Azure Synapse Analytics (Kumpulan SQL Khusus)

Objek yang didukung

Kumpulan SQL khusus mendukung tabel, tampilan, dan prosedur tersimpan—sama seperti SQL Server dan Azure SQL. Kumpulan SQL tanpa server tidak didukung.

Fitur yang tidak didukung

Feature Catatan
Beberapa mutasi Tidak didukung

Konten terkait

  • Last updated on