Fitur khusus database untuk penyusun API Data

Penyusun API Data memungkinkan setiap database memiliki fitur spesifiknya sendiri. Artikel ini merinci fitur yang didukung untuk setiap database.

Dukungan versi database

Banyak database tradisional memerlukan versi minimum agar kompatibel dengan penyusun Api Data (DAB).

Sebaliknya, layanan database cloud Azure bekerja dengan DAB di luar kotak tanpa memerlukan versi tertentu.

Azure SQL dan SQL Server

Ada beberapa properti khusus yang unik untuk SQL termasuk Azure SQL dan SQL Server.

SESSION_CONTEXT

Azure SQL dan SQL Server mendukung penggunaan SESSION_CONTEXT fungsi untuk mengakses identitas pengguna saat ini. Fitur ini berguna ketika Anda ingin menerapkan dukungan asli untuk keamanan tingkat baris (RLS) yang tersedia di Azure SQL dan SQL Server.

Untuk Azure SQL dan SQL Server, penyusun Api Data dapat memanfaatkan SESSION_CONTEXT untuk mengirim metadata yang ditentukan pengguna ke database yang mendasar. Metadata tersebut tersedia untuk penyusun Api Data berdasarkan klaim yang ada dalam token akses. Data yang dikirim ke database kemudian dapat digunakan untuk mengonfigurasi tingkat keamanan tambahan (misalnya, dengan mengonfigurasi kebijakan Keamanan) untuk lebih mencegah akses ke data dalam operasi seperti SELECT, UPDATE, DELETE. Data SESSION_CONTEXT tersedia untuk database selama koneksi database hingga koneksi tersebut ditutup. Data yang sama juga dapat digunakan di dalam prosedur tersimpan.

Untuk informasi selengkapnya tentang mengatur SESSION_CONTEXT data, lihat sp_set_session_context (Transact-SQL).

Konfigurasikan SESSION_CONTEXToptions menggunakan properti bagian data-source dalam file konfigurasi. Untuk informasi selengkapnya, lihat data-source referensi konfigurasi.

{
  ...
  "data-source": {
    "database-type": "mssql",
    "options": {
      "set-session-context": true
    },
    "connection-string": "<connection-string>"
  },
  ...
}

Atau, gunakan --set-session-context argumen dengan dab init perintah .

dab init --database-type mssql --set-session-context true

Semua klaim yang ada dalam token EasyAuth/JWT dikirim melalui SESSION_CONTEXT ke database yang mendasar. Semua klaim yang ada dalam token diterjemahkan ke dalam pasangan kunci-nilai yang diteruskan melalui SESSION_CONTEXT kueri. Klaim ini termasuk, tetapi tidak terbatas pada:

Untuk informasi selengkapnya tentang klaim, lihat Microsoft Entra ID referensi klaim token akses.

Klaim ini diterjemahkan ke dalam kueri SQL. Contoh terpotong ini menggambarkan bagaimana sp_set_session_context digunakan dalam konteks ini:

EXEC sp_set_session_context 'aud', '<AudienceID>', @read_only = 1;
EXEC sp_set_session_context 'iss', 'https://login.microsoftonline.com/<TenantID>/v2.0', @read_only = 1;
EXEC sp_set_session_context 'iat', '1637043209', @read_only = 1;
...
EXEC sp_set_session_context 'azp', 'a903e2e6-fd13-4502-8cae-9e09f86b7a6c', @read_only = 1;
EXEC sp_set_session_context 'azpacr', 1, @read_only = 1;
..
EXEC sp_set_session_context 'uti', '_sSP3AwBY0SucuqqJyjEAA', @read_only = 1;
EXEC sp_set_session_context 'ver', '2.0', @read_only = 1;

Anda kemudian dapat menerapkan keamanan tingkat baris (RLS) menggunakan data sesi. Untuk informasi selengkapnya, lihat menerapkan keamanan tingkat baris dengan konteks sesi.

Azure Cosmos DB

Ada beberapa properti khusus yang unik untuk berbagai API di Azure Cosmos DB.

Skema dalam API untuk NoSQL

Azure Cosmos DB for NoSQL bersifat skema-agnostik. Untuk menggunakan penyusun Api Data dengan API untuk NoSQL, Anda harus membuat file skema GraphQL yang menyertakan definisi jenis objek yang mewakili model data kontainer Anda. Penyusun API Data juga mengharapkan definisi dan bidang jenis objek GraphQL Anda untuk menyertakan arahan authorize skema GraphQL saat Anda ingin memberlakukan akses baca yang lebih ketat daripada anonymous.

Misalnya, file skema ini mewakili Book item dalam kontainer. Item ini berisi, minimal, title dan Authors properti.

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

Contoh skema ini sesuai dengan konfigurasi entitas berikut dalam file konfigurasi DAB. Untuk informasi selengkapnya, lihat entities referensi konfigurasi.

{
  ...
  "Book": {
    "source": "Book",
    "permissions": [
      {
        "role": "anonymous",
        "actions": [ "read" ]
      },
      {
        "role": "metadataviewer",
        "actions": [ "read" ]
      }
    ]
  }
  ...
}

Direktif @authorize dengan roles:["metadataviewer","authenticated"] membatasi akses ke title bidang hanya untuk pengguna dengan peran metadataviewer dan authenticated. Untuk pemohon terautentikasi, peran authenticated sistem secara otomatis ditetapkan, menghilangkan kebutuhan akan X-MS-API-ROLE header.

Jika permintaan terautentikasi perlu dijalankan dalam konteks metadataviewer, permintaan harus disertai dengan header permintaan jenis X-MS-API-ROLE yang diatur ke metadataviewer. Namun, jika akses anonim diinginkan, Anda harus menghilangkan arahan resmi.

Arahan @model digunakan untuk membuat korelasi antara jenis objek GraphQL ini dan nama entitas yang sesuai dalam konfigurasi runtime. Direktif diformat sebagai: @model(name:"<Entity_Name>")

Sebagai contoh yang lebih dalam, arahan @authorize dapat diterapkan pada definisi jenis tingkat atas. Aplikasi ini membatasi akses ke jenis dan bidangnya secara eksklusif ke peran yang ditentukan dalam arahan.

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

{
  "Book": {
    "source": "Series",
    "permissions": [
      {
        "role": "authenticated",
        "actions": [ "read" ]
      },
      {
        "role": "editor",
        "actions": [ "*" ]
      }
    ]
  }
}

Kueri lintas kontainer di API untuk NoSQL

Operasi GraphQL di seluruh kontainer tidak didukung. Mesin merespons dengan pesan kesalahan yang menyatakan, Adding/updating Relationships is currently not supported in Azure Cosmos DB for NoSQL.

Anda dapat mengatasi batasan ini dengan memperbarui model data Anda untuk menyimpan entitas dalam kontainer yang sama dalam format yang disematkan. Untuk informasi selengkapnya, lihat pemodelan data di Azure Cosmos DB untuk NoSQL.