Referensi skema konfigurasi penyusun API Data

Mesin pembuat API Data memerlukan file konfigurasi. File konfigurasi Data API Builder menyediakan pendekatan terstruktur dan komprehensif untuk menyiapkan API Anda, merinci semuanya mulai dari variabel lingkungan hingga konfigurasi khusus entitas. Dokumen berformat JSON ini dimulai dengan properti $schema. Penyetelan ini memvalidasi dokumen.

Properti database-type dan connection-string memastikan integrasi yang mulus dengan sistem database, dari Azure SQL Database ke Cosmos DB NoSQL API.

File konfigurasi dapat mencakup opsi seperti:

• Layanan database dan informasi koneksi
• Opsi konfigurasi global dan runtime
• Set entitas yang diekspos
• Metode autentikasi
• Aturan keamanan diperlukan untuk mengakses identitas
• Aturan pemetaan nama antara API dan database
• Hubungan antar entitas yang tidak dapat disimpulkan
• Fitur unik untuk layanan database tertentu

Gambaran umum sintaks

Berikut adalah perincian cepat dari "bagian" utama dalam file konfigurasi.

{
  "$schema": "...",
  "data-source": { ... },
  "data-source-files": [ ... ],
  "runtime": {
    "rest": { ... },
    "graphql": { .. },
    "host": { ... },
    "cache": { ... },
    "telemetry": { ... },
    "pagination": { ... }
  }
  "entities": [ ... ]
}

Properti tingkat atas

Berikut deskripsi properti tingkat atas dalam format tabel:

Konfigurasi sampel

Berikut adalah contoh file konfigurasi yang hanya menyertakan properti yang diperlukan untuk satu entitas sederhana. Sampel ini dimaksudkan untuk mengilustrasikan skenario minimal.

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')"
  },
  "entities": {
    "User": {
      "source": "dbo.Users",
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["*"]
        }
      ]
    }
  }
}

Untuk contoh skenario yang lebih kompleks, lihat konfigurasi sampel end-to-end.

Lingkungan

File konfigurasi penyusun API Data dapat mendukung skenario di mana Anda perlu mendukung beberapa lingkungan, mirip dengan file appSettings.json di ASP.NET Core. Kerangka kerja ini menyediakan tiga nilai lingkungan umum ; Development, Staging, dan Production; tetapi Anda dapat memilih untuk menggunakan nilai lingkungan apa pun yang Anda pilih. Lingkungan yang digunakan penyusun Api Data harus dikonfigurasi menggunakan variabel lingkungan DAB_ENVIRONMENT.

Pertimbangkan contoh di mana Anda menginginkan konfigurasi dasar dan konfigurasi khusus pengembangan. Contoh ini memerlukan dua file konfigurasi:

Untuk menggunakan konfigurasi khusus pengembangan, Anda harus mengatur variabel lingkungan DAB_ENVIRONMENT ke Development.

File konfigurasi khusus lingkungan mengambil alih nilai properti dalam file konfigurasi dasar. Dalam contoh ini, jika nilai connection-string diatur dalam kedua file, nilai dari file *.Development.json digunakan.

Lihat matriks ini untuk lebih memahami nilai mana yang digunakan tergantung di mana nilai tersebut ditentukan (atau tidak ditentukan) dalam salah satu file.

Untuk contoh penggunaan beberapa file konfigurasi, lihat menggunakan penyusun API Data dengan lingkungan.

Properti konfigurasi

Bagian ini mencakup semua kemungkinan properti konfigurasi yang tersedia untuk file konfigurasi.

Skema

Setiap file konfigurasi dimulai dengan properti $schema, menentukan skema JSON untuk validasi.

Format

{
  "$schema": <string>
}

Contoh

File skema tersedia untuk versi 0.3.7-alpha dan seterusnya pada URL tertentu, memastikan Anda menggunakan versi yang benar atau skema terbaru yang tersedia.

https://github.com/Azure/data-api-builder/releases/download/<VERSION>-<suffix>/dab.draft.schema.json

Ganti VERSION-suffix dengan versi yang Anda inginkan.

https://github.com/Azure/data-api-builder/releases/download/v0.3.7-alpha/dab.draft.schema.json

Versi terbaru skema selalu tersedia di https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json.

Berikut adalah beberapa contoh nilai skema yang valid.

Sumber data

Bagian data-source menentukan database dan akses ke database melalui string koneksi. Ini juga mendefinisikan opsi database. Properti data-source mengonfigurasi kredensial yang diperlukan untuk menyambungkan ke database cadangan. Bagian data-source menguraikan konektivitas database backend, menentukan database-type dan connection-string.

Format

{
  "data-source": {
    "database-type": <string>,
    "connection-string": <string>,
    
    // mssql-only
    "options": {
      "set-session-context": <true> (default) | <false>
    },
    
    // cosmosdb_nosql-only
    "options": {
      "database": <string>,
      "container": <string>,
      "schema": <string>
    }
  }
}

Properti

Jenis database

String enum yang digunakan untuk menentukan jenis database yang akan digunakan sebagai sumber data.

Format

{
  "data-source": {
    "database-type": <string>
  }
}

Ketik nilai

Properti type menunjukkan jenis database backend.

String koneksi

String nilai yang berisi string koneksi yang valid untuk menyambungkan ke layanan database target. String koneksi ADO.NET untuk menyambungkan ke database backend. Untuk informasi selengkapnya, lihat ADO.NET string koneksi.

Format

{
  "data-source": {
    "connection-string": <string>
  }
}

Ketahanan koneksi

Pembuat API Data secara otomatis mencoba kembali permintaan database setelah mendeteksi kesalahan sementara. Logika coba lagi mengikuti strategi Backoff Eksponensial di mana jumlah maksimum percobaan ulang lima. Durasi backoff coba lagi setelah permintaan berikutnya dihitung menggunakan rumus ini (dengan asumsi upaya coba lagi saat ini r): $r^2$

Dengan menggunakan rumus ini, Anda dapat menghitung waktu untuk setiap upaya coba lagi dalam hitungan detik.

Azure SQL dan SQL Server

Penyusun API Data menggunakan pustaka SqlClient untuk menyambungkan ke Azure SQL atau SQL Server menggunakan string koneksi yang Anda sediakan dalam file konfigurasi. Daftar semua opsi string koneksi yang didukung tersedia di sini: Properti SqlConnection.ConnectionString.

Penyusun API Data juga dapat terhubung ke database target menggunakan Identitas Layanan Terkelola (MSI) saat penyusun API Data dihosting di Azure. DefaultAzureCredential yang ditentukan dalam pustaka Azure.Identity digunakan untuk menyambungkan menggunakan identitas yang diketahui saat Anda tidak menentukan nama pengguna atau kata sandi dalam string koneksi Anda. Untuk informasi selengkapnya, lihat contoh DefaultAzureCredential.

• Identitas Terkelola yang Ditetapkan Pengguna (UMI): Tambahkan properti Autentikasi dan Id Pengguna ke string koneksi Anda saat menggantikan id klien Identitas Terkelola yang Ditetapkan Pengguna Anda: .
• System Assigned Managed Identity (SMI): Tambahkan properti Autentikasi dan kecualikan UserId dan argumen Kata Sandi dari string koneksi Anda: . Tidak adanya UserId dan properti string koneksi Kata Sandi akan memberi sinyal KEPADA DAB untuk mengautentikasi menggunakan identitas terkelola yang ditetapkan sistem.

Untuk informasi selengkapnya tentang mengonfigurasi Identitas Layanan Terkelola dengan Azure SQL atau SQL Server, lihat identitas terkelola di Microsoft Entra untuk Azure SQL.

Contoh

Nilai yang digunakan untuk string koneksi sebagian besar tergantung pada layanan database yang digunakan dalam skenario Anda. Anda selalu dapat memilih untuk menyimpan string koneksi dalam variabel lingkungan dan mengaksesnya menggunakan fungsi @env().

Sampel ini hanya menggambarkan bagaimana setiap jenis database mungkin dikonfigurasi. Skenario Anda mungkin unik, tetapi sampel ini adalah tempat awal yang baik. Ganti tempat penampung seperti myserver, myDataBase, mylogin, dan myPassword dengan nilai aktual khusus untuk lingkungan Anda.

• mssql

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

  • Format string koneksi umum: "Server=tcp:myserver.database.windows.net,1433;Initial Catalog=myDataBase;Persist Security Info=False;User ID=mylogin;Password=myPassword;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"

• postgresql

  "data-source": {
    "database-type": "postgresql",
    "connection-string": "$env('my-connection-string')"
  }
  

  • Format string koneksi umum: "Host=myserver.postgres.database.azure.com;Database=myDataBase;Username=mylogin@myserver;Password=myPassword;"

• mysql

  "data-source": {
    "database-type": "mysql",
    "connection-string": "$env('my-connection-string')"
  }
  

  • Format string koneksi umum: "Server=myserver.mysql.database.azure.com;Database=myDataBase;Uid=mylogin@myserver;Pwd=myPassword;"

• cosmosdb_nosql

  "data-source": {
    "database-type": "cosmosdb_nosql",
    "connection-string": "$env('my-connection-string')",
    "options": {
      "database": "Your_CosmosDB_Database_Name",
      "container": "Your_CosmosDB_Container_Name",
      "schema": "Path_to_Your_GraphQL_Schema_File"
    }
  }
  

  • Format string koneksi umum: "AccountEndpoint=https://mycosmosdb.documents.azure.com:443/;AccountKey=myAccountKey;"

• cosmosdb_postgresql

  "data-source": {
    "database-type": "cosmosdb_postgresql",
    "connection-string": "$env('my-connection-string')"
  }
  

  • Format string koneksi umum: "Host=mycosmosdb.postgres.database.azure.com;Database=myDataBase;Username=mylogin@mycosmosdb;Password=myPassword;Port=5432;SSL Mode=Require;"

Pilihan

Bagian opsional dari parameter kunci-nilai tambahan untuk koneksi database tertentu.

Apakah bagian options diperlukan atau tidak sebagian besar tergantung pada layanan database yang digunakan.

Format

{
  "data-source": {
    "options": {
      "<key-name>": <string>
    }
  }
}

options: { set-session-context: boolean }

Untuk Azure SQL dan SQL Server, pembuat 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 SESSION_CONTEXT tersedia untuk database selama koneksi database hingga koneksi tersebut ditutup. Untuk informasi selengkapnya, lihat konteks sesi.

Contoh Prosedur Tersimpan SQL:

CREATE PROC GetUser @userId INT AS
BEGIN
    -- Check if the current user has access to the requested userId
    IF SESSION_CONTEXT(N'user_role') = 'admin' 
        OR SESSION_CONTEXT(N'user_id') = @userId
    BEGIN
        SELECT Id, Name, Age, IsAdmin
        FROM Users
        WHERE Id = @userId;
    END
    ELSE
    BEGIN
        RAISERROR('Unauthorized access', 16, 1);
    END
END;

Contoh Konfigurasi JSON:

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')",
    "options": {
      "set-session-context": true
    }
  },
  "entities": {
    "User": {
      "source": {
        "object": "dbo.GetUser",
        "type": "stored-procedure",
        "parameters": {
          "userId": "number"
        }
      },
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["execute"]
        }
      ]
    }
  }
}

Penjelasan:

1. Prosedur Tersimpan (GetUser):

   • Prosedur memeriksa SESSION_CONTEXT untuk memvalidasi apakah pemanggil memiliki peran admin atau cocok dengan userId yang disediakan.
   • Akses tidak sah menghasilkan kesalahan.

2. Konfigurasi JSON :

   • set-session-context diaktifkan untuk meneruskan metadata pengguna dari token akses ke database.
   • Properti parameters memetakan parameter userId yang diperlukan oleh prosedur tersimpan.
   • Blok permissions memastikan hanya pengguna terautentikasi yang dapat menjalankan prosedur tersimpan.

File sumber data

Penyusun API Data mendukung beberapa file konfigurasi untuk sumber data yang berbeda, dengan satu ditunjuk sebagai file tingkat atas yang mengelola pengaturan runtime. Semua konfigurasi memiliki skema yang sama, memungkinkan pengaturan runtime dalam file apa pun tanpa kesalahan. Konfigurasi anak bergabung secara otomatis, tetapi referensi melingkar harus dihindari. Entitas dapat dibagi menjadi file terpisah untuk manajemen yang lebih baik, tetapi hubungan antar entitas harus dalam file yang sama.

Format

{
  "data-source-files": [ <string> ]
}

Pertimbangan file konfigurasi

• Setiap file konfigurasi harus menyertakan properti data-source.
• Setiap file konfigurasi harus menyertakan properti entities.
• Pengaturan runtime hanya digunakan dari file konfigurasi tingkat atas, bahkan jika disertakan dalam file lain.
• File konfigurasi anak juga dapat menyertakan file anak mereka sendiri.
• File konfigurasi dapat diatur ke dalam subfolder seperti yang diinginkan.
• Nama entitas harus unik di semua file konfigurasi.
• Hubungan antar entitas dalam file konfigurasi yang berbeda tidak didukung.

Contoh

{
  "data-source-files": [
    "dab-config-2.json"
  ]
}

{
  "data-source-files": [
    "dab-config-2.json", 
    "dab-config-3.json"
  ]
}

Sintaks subfolder juga didukung:

{
  "data-source-files": [
    "dab-config-2.json",
    "my-folder/dab-config-3.json",
    "my-folder/my-other-folder/dab-config-4.json"
  ]
}

Runtime

Bagian runtime menguraikan opsi yang memengaruhi perilaku runtime dan pengaturan untuk semua entitas yang terekspos.

Format

{
  "runtime": {
    "rest": {
      "path": <string> (default: /api),
      "enabled": <true> (default) | <false>,
      "request-body-strict": <true> (default) | <false>
    },
    "graphql": {
      "path": <string> (default: /graphql),
      "enabled": <true> (default) | <false>,
      "allow-introspection": <true> (default) | <false>
    },
    "host": {
      "mode": "production" (default) | "development",
      "cors": {
        "origins": ["<array-of-strings>"],
        "allow-credentials": <true> | <false> (default)
      },
      "authentication": {
        "provider": "StaticWebApps" (default) | ...,
        "jwt": {
          "audience": "<client-id>",
          "issuer": "<issuer-url>"
        }
      }
    }
  },
  "cache": {
    "enabled": <true> | <false> (default),
    "ttl-seconds": <integer; default: 5>
  },
  "pagination": {
    "max-page-size": <integer; default: 100000>,
    "default-page-size": <integer; default: 100>,
    "max-response-size-mb": <integer; default: 158>
  },
  "telemetry": {
    "application-insights": {
      "connection-string": <string>,
      "enabled": <true> | <false> (default)
    }
  }
}

Properti

Contoh

Berikut adalah contoh bagian runtime dengan beberapa parameter default umum yang ditentukan.

{
  "runtime": {
    "rest": {
      "enabled": true,
      "path": "/api",
      "request-body-strict": true
    },
    "graphql": {
      "enabled": true,
      "path": "/graphql",
      "allow-introspection": true
    },
    "host": {
      "mode": "development",
      "cors": {
        "allow-credentials": false,
        "origins": [
          "*"
        ]
      },
      "authentication": {
        "provider": "StaticWebApps",
        "jwt": {
          "audience": "<client-id>",
          "issuer": "<identity-provider-issuer-uri>"
        }
      }
    },
    "cache": {
      "enabled": true,
      "ttl-seconds": 5
    },
    "pagination": {
      "max-page-size": -1 | <integer; default: 100000>,
      "default-page-size": -1 | <integer; default: 100>,
      "max-response-size-mb": <integer; default: 158>
    },
    "telemetry": {
      "application-insights": {
        "connection-string": "<connection-string>",
        "enabled": true
      }
    }
  }
}

GraphQL (runtime)

Objek ini menentukan apakah GraphQL diaktifkan dan nama yang digunakan untuk mengekspos entitas sebagai jenis GraphQL. Objek ini bersifat opsional dan hanya digunakan jika nama atau pengaturan default tidak cukup. Bagian ini menguraikan pengaturan global untuk titik akhir GraphQL.

Format

{
  "runtime": {
    "graphql": {
      "path": <string> (default: /graphql),
      "enabled": <true> (default) | <false>,
      "depth-limit": <integer; default: none>,
      "allow-introspection": <true> (default) | <false>,
      "multiple-mutations": <object>
    }
  }
}

Properti

Diaktifkan (runtime GraphQL)

Menentukan apakah akan mengaktifkan atau menonaktifkan titik akhir GraphQL secara global. Jika dinonaktifkan secara global, tidak ada entitas yang dapat diakses melalui permintaan GraphQL terlepas dari pengaturan entitas individual.

Format

{
  "runtime": {
    "graphql": {
      "enabled": <true> (default) | <false>
    }
  }
}

Contoh

Dalam contoh ini, titik akhir GraphQL dinonaktifkan untuk semua entitas.

{
  "runtime": {
    "graphql": {
      "enabled": false
    }
  }
}

Batas kedalaman (runtime GraphQL)

Kedalaman kueri maksimum yang diizinkan dari kueri.

Kemampuan GraphQL untuk menangani kueri berlapis berdasarkan definisi hubungan adalah fitur yang luar biasa, memungkinkan pengguna mengambil data terkait yang kompleks dalam satu kueri. Namun, karena pengguna terus menambahkan kueri berlapis, kompleksitas kueri meningkat, yang akhirnya dapat membahayakan performa dan keandalan database dan titik akhir API. Untuk mengelola situasi ini, properti runtime/graphql/depth-limit mengatur kedalaman maksimum yang diizinkan dari kueri GraphQL (dan mutasi). Properti ini memungkinkan pengembang untuk mencapai keseimbangan, memungkinkan pengguna untuk menikmati manfaat kueri berlapis sambil menempatkan batas untuk mencegah skenario yang dapat membahayakan performa dan kualitas sistem.

Contoh

{
  "runtime": {
    "graphql": {
      "depth-limit": 2
    }
  }
}

Jalur (runtime GraphQL)

Menentukan jalur URL tempat titik akhir GraphQL tersedia. Misalnya, jika parameter ini diatur ke /graphql, titik akhir GraphQL diekspos sebagai /graphql. Secara default, jalurnya adalah /graphql.

Format

{
  "runtime": {
    "graphql": {
      "path": <string> (default: /graphql)
    }
  }
}

Contoh

Dalam contoh ini, URI GraphQL akar /query.

{
  "runtime": {
    "graphql": {
      "path": "/query"
    }
  }
}

Izinkan introspeksi (runtime GraphQL)

Bendera Boolean ini mengontrol kemampuan untuk melakukan kueri introspeksi skema pada titik akhir GraphQL. Mengaktifkan introspeksi memungkinkan klien untuk mengkueri skema untuk informasi tentang jenis data yang tersedia, jenis kueri yang dapat mereka lakukan, dan mutasi yang tersedia.

Fitur ini berguna selama pengembangan untuk memahami struktur API GraphQL dan untuk alat yang secara otomatis menghasilkan kueri. Namun, untuk lingkungan produksi, mungkin dinonaktifkan untuk mengaburkan detail skema API dan meningkatkan keamanan. Secara default, introspeksi diaktifkan, memungkinkan eksplorasi langsung dan komprehensif dari skema GraphQL.

Format

{
  "runtime": {
    "graphql": {
      "allow-introspection": <true> (default) | <false>
    }
  }
}

Contoh

Dalam contoh ini, introspeksi dinonaktifkan.

{
  "runtime": {
    "graphql": {
      "allow-introspection": false
    }
  }
}

Beberapa mutasi (runtime GraphQL)

Mengonfigurasi semua beberapa operasi mutasi untuk runtime GraphQL.

Format

{
  "runtime": {
    "graphql": {
      "multiple-mutations": {
        "create": {
          "enabled": <true> (default) | <false>
        }
      }
    }
  }
}

Properti

Beberapa mutasi - buat (runtime GraphQL)

Mengonfigurasi beberapa operasi pembuatan untuk runtime GraphQL.

Format

{
  "runtime": {
    "graphql": {
      "multiple-mutations": {
        "create": {
          "enabled": <true> (default) | <false>
        }
      }
    }
  }
}

Properti

Contoh

Berikut ini menunjukkan cara mengaktifkan dan menggunakan beberapa mutasi dalam runtime bahasa umum GraphQL. Dalam hal ini, operasi create dikonfigurasi untuk memungkinkan pembuatan beberapa rekaman dalam satu permintaan dengan mengatur properti runtime.graphql.multiple-mutations.create.enabled ke true.

Contoh Konfigurasi

Konfigurasi ini memungkinkan beberapa mutasi create:

{
  "runtime": {
    "graphql": {
      "multiple-mutations": {
        "create": {
          "enabled": true
        }
      }
    }
  },
  "entities": {
    "User": {
      "source": "dbo.Users",
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["create"]
        }
      ]
    }
  }
}

Contoh Mutasi GraphQL

Dengan menggunakan konfigurasi di atas, mutasi berikut membuat beberapa rekaman User dalam satu operasi:

mutation {
  createUsers(input: [
    { name: "Alice", age: 30, isAdmin: true },
    { name: "Bob", age: 25, isAdmin: false },
    { name: "Charlie", age: 35, isAdmin: true }
  ]) {
    id
    name
    age
    isAdmin
  }
}

REST (runtime)

Bagian ini menguraikan pengaturan global untuk titik akhir REST. Pengaturan ini berfungsi sebagai default untuk semua entitas tetapi dapat ditimpa berdasarkan per entitas dalam konfigurasi masing-masing.

Format

{
  "runtime": {
    "rest": {
      "path": <string> (default: /api),
      "enabled": <true> (default) | <false>,
      "request-body-strict": <true> (default) | <false>
    }
  }
}

Properti

Diaktifkan (runtime REST)

Bendera Boolean yang menentukan ketersediaan global titik akhir REST. Jika dinonaktifkan, entitas tidak dapat diakses melalui REST, terlepas dari pengaturan entitas individual.

Format

{
  "runtime": {
    "rest": {
      "enabled": <true> (default) | <false>,
    }
  }
}

Contoh

Dalam contoh ini, titik akhir REST API dinonaktifkan untuk semua entitas.

{
  "runtime": {
    "rest": {
      "enabled": false
    }
  }
}

Jalur (runtime REST)

Mengatur jalur URL untuk mengakses semua titik akhir REST yang terekspos. Misalnya, mengatur path ke /api membuat titik akhir REST dapat diakses di /api/<entity>. Subpath tidak diizinkan. Bidang ini bersifat opsional, dengan /api sebagai default.

Format

{
  "runtime": {
    "rest": {
      "path": <string> (default: /api)
    }
  }
}

Contoh

Dalam contoh ini, URI REST API akar /data.

{
  "runtime": {
    "rest": {
      "path": "/data"
    }
  }
}

Isi Permintaan Ketat (REST Runtime)

Pengaturan ini mengontrol seberapa ketat isi permintaan untuk operasi mutasi REST (misalnya, POST, PUT, PATCH) divalidasi.

• true (default): Bidang tambahan dalam isi permintaan yang tidak dipetakan ke kolom tabel menyebabkan pengecualian BadRequest.
• false: Bidang tambahan diabaikan, dan hanya kolom yang valid yang diproses.

Pengaturan ini tidak berlaku untuk permintaan GET, karena isi permintaannya selalu diabaikan.

Perilaku dengan Konfigurasi Kolom Tertentu

• Kolom dengan nilai default() diabaikan selama INSERT hanya ketika nilainya dalam payload null. Kolom dengan default() tidak diabaikan selama UPDATE terlepas dari nilai payload.
• Kolom komputasi selalu diabaikan.
• Kolom yang dihasilkan secara otomatis selalu diabaikan.

Format

{
  "runtime": {
    "rest": {
      "request-body-strict": <true> (default) | <false>
    }
  }
}

Contoh

CREATE TABLE Users (
    Id INT PRIMARY KEY IDENTITY,
    Name NVARCHAR(50) NOT NULL,
    Age INT DEFAULT 18,
    IsAdmin BIT DEFAULT 0,
    IsMinor AS IIF(Age <= 18, 1, 0)
);

Contoh Konfigurasi

{
  "runtime": {
    "rest": {
      "request-body-strict": false
    }
  }
}

Perilaku INSERT dengan request-body-strict: false

Meminta Payload:

{
  "Id": 999,
  "Name": "Alice",
  "Age": null,
  "IsAdmin": null,
  "IsMinor": false,
  "ExtraField": "ignored"
}

Pernyataan Sisipkan yang Dihasilkan:

INSERT INTO Users (Name) VALUES ('Alice');
-- Default values for Age (18) and IsAdmin (0) are applied by the database.
-- IsMinor is ignored because it’s a computed column.
-- ExtraField is ignored.
-- The database generates the Id value.

Payload Respons :

{
  "Id": 1,          // Auto-generated by the database
  "Name": "Alice",
  "Age": 18,        // Default applied
  "IsAdmin": false, // Default applied
  "IsMinor": true   // Computed
}

PERBARUI Perilaku dengan request-body-strict: false

Meminta Payload:

{
  "Id": 1,
  "Name": "Alice Updated",
  "Age": null,     // explicitely set to 'null'
  "IsMinor": true, // ignored because computed
  "ExtraField": "ignored"
}

Pernyataan Pembaruan yang Dihasilkan:

UPDATE Users
SET Name = 'Alice Updated', Age = NULL
WHERE Id = 1;
-- IsMinor and ExtraField are ignored.

Payload Respons :

{
  "Id": 1,
  "Name": "Alice Updated",
  "Age": null,
  "IsAdmin": false,
  "IsMinor": false // Recomputed by the database (false when age is `null`)
}

Host (runtime)

Bagian host dalam konfigurasi runtime menyediakan pengaturan penting untuk lingkungan operasional penyusun API Data. Pengaturan ini mencakup mode operasional, konfigurasi CORS, dan detail autentikasi.

Format

{
  "runtime": {
    "host": {
      "mode": "production" (default) | "development",
      "max-response-size-mb": <integer; default: 158>,
      "cors": {
        "origins": ["<array-of-strings>"],
        "allow-credentials": <true> | <false> (default)
      },
      "authentication": {
        "provider": "StaticWebApps" (default) | ...,
        "jwt": {
          "audience": "<client-id>",
          "issuer": "<issuer-url>"
        }
      }
    }
  }
}

Properti

Contoh

Berikut adalah contoh runtime yang dikonfigurasi untuk hosting pengembangan.

{
  "runtime": {
    "host": {
      "mode": "development",
      "cors": {
        "allow-credentials": false,
        "origins": ["*"]
      },
      "authentication": {
        "provider": "Simulator"
      }
    }
  }
}

Mode (Runtime host)

Menentukan apakah mesin pembuat API Data harus berjalan dalam mode development atau production. Nilai default adalah production.

Biasanya, kesalahan database yang mendasar diekspos secara rinci dengan mengatur tingkat detail default agar log Debug saat berjalan dalam pengembangan. Dalam produksi, tingkat detail untuk log diatur ke Error.

Format

{
  "runtime": {
    "host": {
      "mode": "production" (default) | "development"
    }
  }
}

Nilai

Berikut adalah daftar nilai yang diizinkan untuk properti ini:

Perilaku

• Hanya dalam mode development Swagger yang tersedia.
• Hanya dalam mode development tersedia Banana Cake Pop.

Ukuran respons maksimum (Runtime)

Mengatur ukuran maksimum (dalam megabyte) untuk hasil tertentu. Pengaturan ini memungkinkan pengguna untuk mengonfigurasi jumlah data yang dapat ditangani memori platform host mereka saat streaming data dari sumber data yang mendasar.

Saat pengguna meminta tataan hasil besar, pengguna dapat membatasi database dan penyusun API Data. Untuk mengatasi hal ini, max-response-size-mb memungkinkan pengembang membatasi ukuran respons maksimum, yang diukur dalam megabyte, sebagai aliran data dari sumber data. Batas ini didasarkan pada ukuran data keseluruhan, bukan jumlah baris. Karena kolom dapat bervariasi dalam ukuran, beberapa kolom (seperti teks, biner, XML, atau JSON) dapat menampung hingga 2 GB masing-masing, membuat baris individual berpotensi sangat besar. Pengaturan ini membantu pengembang melindungi titik akhir mereka dengan membatasi ukuran respons dan mencegah kelebihan sistem sambil mempertahankan fleksibilitas untuk berbagai jenis data.

Nilai yang diizinkan

Format

{
  "runtime": {
    "host": {
      "max-response-size-mb": <integer; default: 158>
    }
  }
}

CORS (Runtime host)

Pengaturan berbagi sumber daya lintas asal (CORS) untuk host mesin pembuat API Data.

Format

{
  "runtime": {
    "host": {
      "cors": {
        "origins": ["<array-of-strings>"],
        "allow-credentials": <true> | <false> (default)
      }
    }
  }
}

Properti

Izinkan kredensial (Runtime host)

Jika true, atur header CORS Access-Control-Allow-Credentials.

Format

{
  "runtime": {
    "host": {
      "cors": {
        "allow-credentials": <true> (default) | <false>
      }
    }
  }
}

Asal (Runtime host)

Mengatur array dengan daftar asal yang diizinkan untuk CORS. Pengaturan ini memungkinkan kartubebas * untuk semua asal.

Format

{
  "runtime": {
    "host": {
      "cors": {
        "origins": ["<array-of-strings>"]
      }
    }
  }
}

Contoh

Berikut adalah contoh host yang memungkinkan CORS tanpa kredensial dari semua asal.

{
  "runtime": {
    "host": {
      "cors": {
        "allow-credentials": false,
        "origins": ["*"]
      }
    }
  }
}

Autentikasi (Runtime host)

Mengonfigurasi autentikasi untuk host pembuat API Data.

Format

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "StaticWebApps" (default) | ...,
        "jwt": {
          "audience": "<string>",
          "issuer": "<string>"
        }
      }
    }
  }
}

Properti

Autentikasi dan tanggung jawab pelanggan

Penyusun API Data dirancang untuk beroperasi dalam alur keamanan yang lebih luas, dan ada langkah-langkah penting untuk dikonfigurasi sebelum memproses permintaan. Penting untuk dipahami bahwa pembuat API Data tidak mengautentikasi pemanggil langsung (seperti aplikasi web Anda) melainkan pengguna akhir, berdasarkan token JWT yang valid yang disediakan oleh penyedia identitas tepercaya (misalnya, ID Entra). Ketika permintaan mencapai penyusun Data API, ia mengasumsikan token JWT valid dan memeriksanya terhadap prasyarat apa pun yang telah Anda konfigurasi, seperti klaim tertentu. Aturan otorisasi kemudian diterapkan untuk menentukan apa yang dapat diakses atau diubah pengguna.

Setelah otorisasi lolos, penyusun API Data menjalankan permintaan menggunakan akun yang ditentukan dalam string koneksi. Karena akun ini sering memerlukan izin yang ditinggikan untuk menangani berbagai permintaan pengguna, sangat penting untuk meminimalkan hak aksesnya untuk mengurangi risiko. Sebaiknya amankan arsitektur Anda dengan mengonfigurasi Private Link antara aplikasi web front-end Anda dan titik akhir API, dan dengan memperkuat mesin yang menghosting pembuat API Data. Langkah-langkah ini membantu memastikan lingkungan Anda tetap aman, melindungi data Anda, dan meminimalkan kerentanan yang dapat dieksploitasi untuk mengakses, memodifikasi, atau menyelundupkan informasi sensitif.

Penyedia (Runtime host)

Pengaturan authentication.provider dalam konfigurasi host menentukan metode autentikasi yang digunakan oleh penyusun API Data. Ini menentukan bagaimana API memvalidasi identitas pengguna atau layanan yang mencoba mengakses sumber dayanya. Pengaturan ini memungkinkan fleksibilitas dalam penyebaran dan integrasi dengan mendukung berbagai mekanisme autentikasi yang disesuaikan dengan lingkungan dan persyaratan keamanan yang berbeda.

Format

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "StaticWebApps" (default) | ...
      }
    }
  }
}

Nilai

Berikut adalah daftar nilai yang diizinkan untuk properti ini:

Token Web JSON (Runtime host)

Jika penyedia autentikasi diatur ke AzureAD (MICROSOFT Entra ID), maka bagian ini diperlukan untuk menentukan audiens dan penerbit untuk token JSOn Web Tokens (JWT). Data ini digunakan untuk memvalidasi token terhadap penyewa Microsoft Entra Anda.

Diperlukan jika penyedia autentikasi AzureAD untuk ID Microsoft Entra. Bagian ini harus menentukan audience dan issuer untuk memvalidasi token JWT yang diterima terhadap penyewa AzureAD yang dimaksudkan untuk autentikasi.

Format

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "StaticWebApps" (default) | ...,
        "jwt": {
          "audience": "<client-id>",
          "issuer": "<issuer-url>"
        }
      }
    }
  }
}

Properti

Contoh

Pembuat API Data (DAB) menawarkan dukungan autentikasi yang fleksibel, terintegrasi dengan Microsoft Entra Identity dan server JSON Web Token (JWT) kustom. Dalam gambar ini, JWT Server mewakili layanan autentikasi yang mengeluarkan token JWT kepada klien setelah berhasil masuk. Klien kemudian meneruskan token ke DAB, yang dapat menginterogasi klaim dan propertinya.

Berikut ini adalah contoh properti host yang diberikan berbagai pilihan arsitektur yang mungkin Anda buat dalam solusi Anda.

Azure Static Web Apps

{
 "host": {
  "mode": "development",
  "cors": {
   "origins": ["https://dev.example.com"],
   "credentials": true
  },
  "authentication": {
   "provider": "StaticWebApps"
  }
 }
}

Dengan StaticWebApps, pembuat API Data mengharapkan Azure Static Web Apps untuk mengautentikasi permintaan dan header HTTP X-MS-CLIENT-PRINCIPAL ada.

Azure App Service

{
 "host": {
  "mode": "production",
  "cors": {
   "origins": [ "https://api.example.com" ],
   "credentials": false
  },
  "authentication": {
   "provider": "AppService",
   "jwt": {
    "audience": "9e7d452b-7e23-4300-8053-55fbf243b673",
    "issuer": "https://example-appservice-auth.com"
   }
  }
 }
}

Autentikasi didelegasikan ke IdP yang didukung di mana token akses dapat dikeluarkan. Token akses yang diperoleh harus disertakan dengan permintaan masuk ke penyusun API Data. Penyusun API Data kemudian memvalidasi token akses yang disajikan, memastikan bahwa penyusun API Data adalah audiens token yang dimaksudkan.

Microsoft Entra ID

{
 "host": {
  "mode": "production",
  "cors": {
   "origins": [ "https://api.example.com" ],
   "credentials": true
  },
  "authentication": {
   "provider": "AzureAD",
   "jwt": {
    "audience": "c123d456-a789-0abc-a12b-3c4d56e78f90",
    "issuer": "https://login.microsoftonline.com/98765f43-21ba-400c-a5de-1f2a3d4e5f6a/v2.0"
   }
  }
 }
}

Simulator (Khusus pengembangan)

{
 "host": {
  "mode": "development",
  "authentication": {
   "provider": "Simulator"
  }
 }
}

Audiens (Runtime host)

Audiens untuk token JWT.

Format

{
  "runtime": {
    "host": {
      "authentication": {
        "jwt": {
          "audience": "<client-id>"
        }
      }
    }
  }
}

Pengeluar sertifikat (Runtime host)

Penerbit untuk token JWT.

Format

{
  "runtime": {
    "host": {
      "authentication": {
        "jwt": {
          "issuer": "<issuer-url>"
        }
      }
    }
  }
}

Penomoran halaman (Runtime)

Mengonfigurasi batas penomoran halaman untuk titik akhir REST dan GraphQL.

Format

{
  "runtime": {
    "pagination": {
      "max-page-size": <integer; default: 100000>,
      "default-page-size": <integer; default: 100>
    }
  }
}

Properti

Contoh Konfigurasi

{
  "runtime": {
    "pagination": {
      "max-page-size": 1000,
      "default-page-size": 2
    }
  },
  "entities": {
    "Users": {
      "source": "dbo.Users",
      "permissions": [
        {
          "actions": ["read"],
          "role": "anonymous"
        }
      ]
    }
  }
}

Contoh Penomoran Halaman REST

Dalam contoh ini, mengeluarkan permintaan REST GET https://localhost:5001/api/users akan mengembalikan dua rekaman dalam array value karena default-page-size diatur ke 2. Jika ada lebih banyak hasil, penyusun Api Data menyertakan nextLink dalam respons. nextLink berisi parameter $after untuk mengambil halaman data berikutnya.

Minta:

GET https://localhost:5001/api/users

Jawaban:

{
  "value": [
    {
      "Id": 1,
      "Name": "Alice",
      "Age": 30,
      "IsAdmin": true,
      "IsMinor": false
    },
    {
      "Id": 2,
      "Name": "Bob",
      "Age": 17,
      "IsAdmin": false,
      "IsMinor": true
    }
  ],
  "nextLink": "https://localhost:5001/api/users?$after=W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI=="
}

Menggunakan nextLink, klien dapat mengambil serangkaian hasil berikutnya.

Contoh Penomoran Halaman GraphQL

Untuk GraphQL, gunakan bidang hasNextPage dan endCursor untuk penomoran halaman. Bidang-bidang ini menunjukkan apakah lebih banyak hasil tersedia dan menyediakan kursor untuk mengambil halaman berikutnya.

Kueri:

query {
  users {
    items {
      Id
      Name
      Age
      IsAdmin
      IsMinor
    }
    hasNextPage
    endCursor
  }
}

Jawaban:

{
  "data": {
    "users": {
      "items": [
        {
          "Id": 1,
          "Name": "Alice",
          "Age": 30,
          "IsAdmin": true,
          "IsMinor": false
        },
        {
          "Id": 2,
          "Name": "Bob",
          "Age": 17,
          "IsAdmin": false,
          "IsMinor": true
        }
      ],
      "hasNextPage": true,
      "endCursor": "W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI=="
    }
  }
}

Untuk mengambil halaman berikutnya, sertakan nilai endCursor dalam kueri berikutnya:

Kueri dengan Kursor:

query {
  users(after: "W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI==") {
    items {
      Id
      Name
      Age
      IsAdmin
      IsMinor
    }
    hasNextPage
    endCursor
  }
}

Menyesuaikan Ukuran Halaman

REST dan GraphQL memungkinkan penyesuaian jumlah hasil per kueri menggunakan $limit (REST) atau first (GraphQL).

Contoh Kueri REST:

GET https://localhost:5001/api/users?$limit=5

Contoh Kueri GraphQL:

query {
  users(first: 5) {
    items {
      Id
      Name
      Age
      IsAdmin
      IsMinor
    }
  }
}

Ukuran halaman maksimum (runtime penomoran halaman)

Mengatur jumlah maksimum rekaman tingkat atas yang dikembalikan oleh REST atau GraphQL. Jika pengguna meminta lebih dari max-page-size, hasilnya dibatasi pada max-page-size.

Nilai yang diizinkan

Format

{
  "runtime": {
    "pagination": {
      "max-page-size": <integer; default: 100000>
    }
  }
}

Ukuran halaman default (runtime penomoran halaman)

Mengatur jumlah default rekaman tingkat atas yang dikembalikan saat penomoran halaman diaktifkan tetapi tidak ada ukuran halaman eksplisit yang disediakan.

Nilai yang diizinkan

Cache (runtime)

Mengaktifkan dan mengonfigurasi penembolokan untuk seluruh runtime.

Format

{
  "runtime": {
    "cache": <object>
  }
}

Properti

Contoh

Dalam contoh ini, cache diaktifkan dan item kedaluwarsa setelah 30 detik.

{
  "runtime": {
    "cache": {
      "enabled": true,
      "ttl-seconds": 30
    }
  }
}

Diaktifkan (Runtime cache)

Memungkinkan penembolokan secara global untuk semua entitas. Default ke false.

Format

{
  "runtime": {
    "cache":  {
      "enabled": <boolean>
    }
  }
}

Contoh

Dalam contoh ini, cache dinonaktifkan.

{
  "runtime": {
    "cache": {
      "enabled": false
    }
  }
}

TTL dalam hitungan detik (Runtime cache)

Mengonfigurasi nilai time-to-live (TTL) dalam hitungan detik untuk item yang di-cache. Setelah waktu ini berlalu, item secara otomatis diprakarsai dari cache. Nilai defaultnya adalah 5 detik.

Format

{
  "runtime": {
    "cache":  {
        "ttl-seconds": <integer>
    }
  }
}

Contoh

Dalam contoh ini, cache diaktifkan secara global dan semua item kedaluwarsa setelah 15 detik.

{
  "runtime": {
    "cache": {
      "enabled": true,
      "ttl-seconds": 15
    }
  }
}

Telemetri (runtime)

Properti ini mengonfigurasi Application Insights untuk mempusatkan log API. Pelajari selengkapnya.

Format

{
  "runtime": {
    "telemetry": {
      "application-insights": {
        "enabled": <true; default: true> | <false>,
        "connection-string": <string>
      }
    }
  }
}

Application Insights (Runtime telemetri)

Diaktifkan (telemetri Application Insights)

String koneksi (telemetri Application Insights)

Entitas

Bagian entities berfungsi sebagai inti file konfigurasi, membuat jembatan antara objek database dan titik akhir API yang sesuai. Bagian ini memetakan objek database ke titik akhir yang terekspos. Bagian ini juga mencakup pemetaan properti dan definisi izin. Setiap entitas yang diekspos didefinisikan dalam objek khusus. Nama properti objek digunakan sebagai nama entitas untuk diekspos.

Bagian ini menentukan bagaimana setiap entitas dalam database diwakili dalam API, termasuk pemetaan dan izin properti. Setiap entitas dienkapsulasi dalam subbagiannya sendiri, dengan nama entitas bertindak sebagai kunci untuk referensi di seluruh konfigurasi.

Format

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "enabled": <true; default: true> | <false>,
        "path": <string; default: "<entity-name>">,
        "methods": <array of strings; default: ["GET", "POST"]>
      },
      "graphql": {
        "enabled": <true; default: true> | <false>,
        "type": {
          "singular": <string>,
          "plural": <string>
        },
        "operation": <"query" | "mutation"; default: "query">
      },
      "source": {
        "object": <string>,
        "type": <"view" | "stored-procedure" | "table">,
        "key-fields": <array of strings>,
        "parameters": {
          "<parameter-name>": <string | number | boolean>
        }
      },
      "mappings": {
        "<database-field-name>": <string>
      },
      "relationships": {
        "<relationship-name>": {
          "cardinality": <"one" | "many">,
          "target.entity": <string>,
          "source.fields": <array of strings>,
          "target.fields": <array of strings>,
          "linking.object": <string>,
          "linking.source.fields": <array of strings>,
          "linking.target.fields": <array of strings>
        }
      },
      "permissions": [
        {
          "role": <"anonymous" | "authenticated" | "custom-role-name">,
          "actions": <array of strings>,
          "fields": {
            "include": <array of strings>,
            "exclude": <array of strings>
          },
          "policy": {
            "database": <string>
          }
        }
      ]
    }
  }
}

Properti

Contoh

Misalnya, objek JSON ini menginstruksikan pembangun API Data untuk mengekspos entitas GraphQL bernama User dan titik akhir REST yang dapat dijangkau melalui jalur /User. Tabel database dbo.User mendukung entitas dan konfigurasi memungkinkan siapa pun mengakses titik akhir secara anonim.

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["*"]
        }
      ]
    }
  }
}

Contoh ini mendeklarasikan entitas User. Nama ini User digunakan di mana saja dalam file konfigurasi tempat entitas dirujuk. Jika tidak, nama entitas tidak relevan dengan titik akhir.

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table",
        "key-fields": ["Id"],
        "parameters": {} // only when source.type = stored-procedure
      },
      "rest": {
        "enabled": true,
        "path": "/users",
        "methods": [] // only when source.type = stored-procedure
      },
      "graphql": {
        "enabled": true,
        "type": {
          "singular": "User",
          "plural": "Users"
        },
        "operation": "query"
      },
      "mappings": {
        "id": "Id",
        "name": "Name",
        "age": "Age",
        "isAdmin": "IsAdmin"
      },
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"],  // "execute" only when source.type = stored-procedure
          "fields": {
            "include": ["id", "name", "age", "isAdmin"],
            "exclude": []
          },
          "policy": {
            "database": "@claims.userId eq @item.id"
          }
        },
        {
          "role": "admin",
          "actions": ["create", "read", "update", "delete"],
          "fields": {
            "include": ["*"],
            "exclude": []
          },
          "policy": {
            "database": "@claims.userRole eq 'UserAdmin'"
          }
        }
      ]
    }
  }
}

Sumber

Konfigurasi {entity}.source menghubungkan entitas yang diekspos API dan objek database yang mendasarnya. Properti ini menentukan tabel database, tampilan, atau prosedur tersimpan yang diwakili entitas, membuat tautan langsung untuk pengambilan dan manipulasi data.

Untuk skenario langsung di mana entitas memetakan langsung ke tabel database tunggal, properti sumber hanya memerlukan nama objek database tersebut. Kesederhanaan ini memfasilitasi penyiapan cepat untuk kasus penggunaan umum: "source": "dbo.User".

Format

{
  "entities": {
    "<entity-name>": {
      "source": {
        "object": <string>,
        "type": <"view" | "stored-procedure" | "table">, 
        "key-fields": <array of strings>,
        "parameters": {  // only when source.type = stored-procedure
          "<name>": <string | number | boolean>
        }
      }
    }
  }
}

Properti

Contoh

1. Pemetaan Tabel Sederhana:

Contoh ini menunjukkan cara mengaitkan entitas User dengan tabel sumber dbo.Users.

SQL

CREATE TABLE dbo.Users (
  Id INT PRIMARY KEY,
  Name NVARCHAR(100),
  Age INT,
  IsAdmin BIT
);

Konfigurasi

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      }
    }
  }
}

2. Contoh Prosedur Tersimpan:

Contoh ini menunjukkan cara mengaitkan entitas User dengan proc sumber dbo.GetUsers.

SQL

CREATE PROCEDURE GetUsers 
     @IsAdmin BIT 
AS
SELECT Id, Name, Age, IsAdmin
FROM dbo.Users
WHERE IsAdmin = @IsAdmin;

Konfigurasi

{
  "entities": {
    "User": {
      "source": {
        "type": "stored-procedure",
        "object": "GetUsers",
        "parameters": {
          "IsAdmin": "boolean"
        }
      },
      "mappings": {
        "Id": "id",
        "Name": "name",
        "Age": "age",
        "IsAdmin": "isAdmin"
      }
    }
  }
}

Properti mappings bersifat opsional untuk prosedur tersimpan.

Benda

Nama objek database yang akan digunakan. Jika objek milik skema dbo, menentukan skema bersifat opsional. Selain itu, tanda kurung siku di sekitar nama objek (misalnya, [dbo].[Users] vs. dbo.Users) dapat digunakan atau dihilangkan.

Contoh

SQL

CREATE TABLE dbo.Users (
  Id INT PRIMARY KEY,
  Name NVARCHAR(100),
  Age INT,
  IsAdmin BIT
);

Konfigurasi

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      }
    }
  }
}

Notasi Alternatif Tanpa Skema dan Tanda Kurung:

Jika tabel berada dalam skema dbo, Anda dapat menghilangkan skema atau tanda kurung:

{
  "entities": {
    "User": {
      "source": {
        "object": "Users",
        "type": "table"
      }
    }
  }
}

Jenis (entitas)

Properti type mengidentifikasi jenis objek database di belakang entitas, termasuk view, table, dan stored-procedure. Properti ini diperlukan dan tidak memiliki nilai default.

Format

{
  "entities": {
    "<entity-name>": {
      "type": <"view" | "stored-procedure" | "table">
    }
  }
}

Nilai

Contoh

1. Contoh Tabel:

SQL

CREATE TABLE dbo.Users (
  Id INT PRIMARY KEY,
  Name NVARCHAR(100),
  Age INT,
  IsAdmin BIT
);

Konfigurasi

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      }
    }
  }
}

2. Contoh Tampilan:

SQL

CREATE VIEW dbo.AdminUsers AS
SELECT Id, Name, Age
FROM dbo.Users
WHERE IsAdmin = 1;

Konfigurasi

{
  "entities": {
    "AdminUsers": {
      "source": {
        "object": "dbo.AdminUsers",
        "type": "view",
        "key-fields": ["Id"]
      },
      "mappings": {
        "Id": "id",
        "Name": "name",
        "Age": "age"
      }
    }
  }
}

Catatan: Menentukan key-fields penting untuk dilihat karena tidak memiliki kunci primer yang melekat.

3. Contoh Prosedur Tersimpan:

SQL

CREATE PROCEDURE dbo.GetUsers (@IsAdmin BIT)
AS
SELECT Id, Name, Age, IsAdmin
FROM dbo.Users
WHERE IsAdmin = @IsAdmin;

Konfigurasi

{
  "entities": {
    "User": {
      "source": {
        "type": "stored-procedure",
        "object": "GetUsers",
        "parameters": {
          "IsAdmin": "boolean"
        }
      }
    }
  }
}

Bidang kunci

Properti {entity}.key-fields sangat diperlukan untuk entitas yang didukung oleh tampilan, sehingga Data API Builder tahu cara mengidentifikasi dan mengembalikan satu item. Jika type diatur ke view tanpa menentukan key-fields, mesin menolak untuk memulai. Properti ini diizinkan dengan tabel dan prosedur tersimpan, tetapi tidak digunakan dalam kasus tersebut.

Format

{
  "entities": {
    "<entity-name>": {
      "source": {
        "type": <"view" | "stored-procedure" | "table">,
        "key-fields": <array of strings>
      }
    }
  }
}

Contoh: Menampilkan dengan Bidang Kunci

Contoh ini menggunakan tampilan dbo.AdminUsers dengan Id yang ditunjukkan sebagai bidang kunci.

SQL

CREATE VIEW dbo.AdminUsers AS
SELECT Id, Name, Age
FROM dbo.Users
WHERE IsAdmin = 1;

Konfigurasi

{
  "entities": {
    "AdminUsers": {
      "source": {
        "object": "dbo.AdminUsers",
        "type": "view",
        "key-fields": ["Id"]
      }
    }
  }
}

Parameter

Properti parameters dalam entities.{entity}.source digunakan untuk entitas yang didukung oleh prosedur tersimpan. Ini memastikan pemetaan nama parameter dan jenis data yang tepat yang diperlukan oleh prosedur tersimpan.

Format

{
  "entities": {
    "<entity-name>": {
      "source": {
        "type": "stored-procedure",
        "parameters": {
          "<parameter-name-1>": <string | number | boolean>,
          "<parameter-name-2>": <string | number | boolean>
        }
      }
    }
  }
}

Contoh 1: Prosedur Tersimpan Tanpa Parameter

SQL

CREATE PROCEDURE dbo.GetUsers AS
SELECT Id, Name, Age, IsAdmin FROM dbo.Users;

Konfigurasi

{
  "entities": {
    "Users": {
      "source": {
        "object": "dbo.GetUsers",
        "type": "stored-procedure"
      }
    }
  }
}

Contoh 2: Prosedur Tersimpan Dengan Parameter

SQL

CREATE PROCEDURE dbo.GetUser (@userId INT) AS
SELECT Id, Name, Age, IsAdmin FROM dbo.Users
WHERE Id = @userId;

Konfigurasi

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.GetUser",
        "type": "stored-procedure",
        "parameters": {
          "userId": "number"
        }
      }
    }
  }
}

Izin

Bagian ini menentukan siapa yang dapat mengakses entitas terkait dan tindakan apa yang diizinkan. Izin ditentukan dalam hal peran dan operasi CRUD: create, read, update, dan delete. Bagian permissions menentukan peran mana yang dapat mengakses entitas terkait dan menggunakan tindakan mana.

Format

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "actions": ["create", "read", "update", "delete", "execute", "*"]
        }
      ]
    }
  }
}

Contoh

Contoh 1: Peran Anonim pada Entitas Pengguna

Dalam contoh ini, peran anonymous didefinisikan dengan akses ke semua tindakan yang mungkin pada entitas User.

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["*"]
        }
      ]
    }
  }
}

Contoh 2: Tindakan Campuran untuk Peran Anonim

Contoh ini menunjukkan cara mencampur tindakan string dan array objek untuk entitas User.

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            { "action": "read" },
            "create"
          ]        
        }
      ]
    }
  }
}

Peran Anonim: Memungkinkan pengguna anonim membaca semua bidang kecuali bidang sensitif hipotetis (misalnya, secret-field). Menggunakan "include": ["*"] dengan "exclude": ["secret-field"] menyembunyikan secret-field sambil mengizinkan akses ke semua bidang lainnya.

Peran Terautentikasi : Memungkinkan pengguna terautentikasi membaca dan memperbarui bidang tertentu. Misalnya, secara eksplisit termasuk id, name, dan age tetapi tidak termasuk isAdmin dapat menunjukkan bagaimana pengecualian mengambil alih penyertaan.

Peran Admin: Admin dapat melakukan semua operasi (*) pada semua bidang tanpa pengecualian. Menentukan "include": ["*"] dengan array "exclude": [] kosong memberikan akses ke semua bidang.

Konfigurasi ini:

"fields": {
  "include": [],
  "exclude": []
}

secara efektif identik dengan:

"fields": {
  "include": ["*"],
  "exclude": []
}

Pertimbangkan juga penyiapan ini:

"fields": {
  "include": [],
  "exclude": ["*"]
}

Ini menentukan tidak ada bidang yang disertakan secara eksplisit dan semua bidang dikecualikan, yang biasanya membatasi akses sepenuhnya.

Praktis Menggunakan: Konfigurasi seperti itu mungkin tampak berlawanan karena membatasi akses ke semua bidang. Namun, ini dapat digunakan dalam skenario di mana peran melakukan tindakan tertentu (seperti membuat entitas) tanpa mengakses datanya.

Perilaku yang sama, tetapi dengan sintaks yang berbeda, adalah:

"fields": {
  "include": ["Id", "Name"],
  "exclude": ["*"]
}

Penyiapan ini mencoba untuk hanya menyertakan bidang Id dan Name, tetapi mengecualikan semua bidang karena kartubebas di exclude.

Cara lain untuk mengekspresikan logika yang sama adalah:

"fields": {
  "include": ["Id", "Name"],
  "exclude": ["Id", "Name"]
}

Mengingat bahwa exclude lebih diutamakan daripada include, menentukan exclude: ["*"] berarti semua bidang dikecualikan, bahkan yang ada di include. Dengan demikian, pada pandangan pertama, konfigurasi ini mungkin tampaknya mencegah bidang apa pun dapat diakses.

Terbalik : Jika niatnya adalah memberikan akses hanya ke bidang Id dan Name, lebih jelas dan lebih dapat diandalkan untuk menentukan hanya bidang tersebut di bagian include tanpa menggunakan wildcard pengecualian:

"fields": {
  "include": ["Id", "Name"],
  "exclude": []
}

Properti

Peranan

String yang berisi nama peran tempat izin yang ditentukan berlaku. Peran mengatur konteks izin tempat permintaan harus dijalankan. Untuk setiap entitas yang ditentukan dalam konfigurasi runtime, Anda dapat menentukan sekumpulan peran dan izin terkait yang menentukan bagaimana entitas dapat diakses melalui titik akhir REST dan GraphQL. Peran tidak aditif.

Data API Builder mengevaluasi permintaan dalam konteks satu peran:

Format

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "role": <"anonymous" | "authenticated" | "custom-role">,
          "actions": ["create", "read", "update", "delete", "execute", "*"],
          "fields": {
            "include": <array of strings>,
            "exclude": <array of strings>
          }
        }
      ]
    }
  }
}

Contoh

Contoh ini menentukan peran bernama reader hanya dengan izin read pada entitas User.

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "reader",
          "actions": ["read"]
        }
      ]
    }
  }
}

Anda dapat menggunakan <custom-role> saat token akses yang valid disajikan dan header HTTP X-MS-API-ROLE disertakan, menentukan peran pengguna yang juga terkandung dalam klaim peran token akses. Di bawah ini adalah contoh permintaan GET ke entitas User, termasuk token pembawa otorisasi dan header X-MS-API-ROLE, pada /api dasar titik akhir REST di localhost menggunakan bahasa yang berbeda.

GET https://localhost:5001/api/User
Authorization: Bearer <your_access_token>
X-MS-API-ROLE: custom-role

using System.Net.Http;
using System.Net.Http.Headers;

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<your_access_token>");
client.DefaultRequestHeaders.Add("X-MS-API-ROLE", "custom-role");
var response = await client.GetAsync("https://localhost:5001/api/User");

const response = await fetch('https://localhost:5001/api/User', {
  headers: { 
    "Authorization": "Bearer <your_access_token>",
    "X-MS-API-ROLE": "custom-role"
  }
});

import requests

headers = {
  "Authorization": "Bearer <your_access_token>",
  "X-MS-API-ROLE": "custom-role"
}
response = requests.get('https://localhost:5001/api/User', headers=headers)
print(response.json())

Tindakan (string-array)

Array nilai string yang merinci operasi apa yang diizinkan untuk peran terkait. Untuk objek database table dan view, peran dapat menggunakan kombinasi tindakan create, read, update, atau delete. Untuk prosedur tersimpan, peran hanya dapat memiliki tindakan execute.

Contoh

Contoh ini memberikan izin create dan read ke peran bernama contributor dan izin delete ke peran bernama auditor pada entitas User.

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "auditor",
          "actions": ["delete"]
        },
        {
          "role": "contributor",
          "actions": ["read", "create"]
        }
      ]
    }
  }
}

Contoh lain:

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "contributor",
          "actions": ["read", "create"]
        }
      ]
    }
  }
}

Tindakan (object-array)

Array objek tindakan yang merinci operasi yang diizinkan untuk peran terkait. Untuk objek table dan view, peran dapat menggunakan kombinasi create, read, update, atau delete. Untuk prosedur tersimpan, hanya execute yang diizinkan.

Format

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "role": <string>,
          "actions": [
            {
              "action": <string>,
              "fields": <array of strings>,
              "policy": <object>
            }
          ]
        }
      ]
    }
  }
}

Properti

Contoh

Contoh ini hanya memberikan izin read ke peran auditor pada entitas User, dengan pembatasan bidang dan kebijakan.

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "auditor",
          "actions": [
            {
              "action": "read",
              "fields": {
                "include": ["*"],
                "exclude": ["last_login"]
              },
              "policy": {
                "database": "@item.IsAdmin eq false"
              }
            }
          ]
        }
      ]
    }
  }
}

Perbuatan

Menentukan operasi tertentu yang diizinkan pada objek database.

Nilai

Format

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "role": "<role>",
          "actions": [
            {
              "action": "<string>",
              "fields": {
                "include": [/* fields */],
                "exclude": [/* fields */]
              },
              "policy": {
                "database": "<predicate>"
              }
            }
          ]
        }
      ]
    }
  }
}

Contoh

Berikut adalah contoh di mana pengguna anonymous diizinkan untuk execute prosedur tersimpan dan read dari tabel User.

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read"
            }
          ]
        }
      ]
    },
    "GetUser": {
      "source": {
        "object": "dbo.GetUser",
        "type": "stored-procedure",
        "parameters": {
          "userId": "number"
        }
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "execute"
            }
          ]
        }
      ]
    }
  }
}

Bidang

Spesifikasi terperinci di mana bidang tertentu diizinkan akses untuk objek database. Konfigurasi peran adalah jenis objek dengan dua properti internal, include dan exclude. Nilai-nilai ini mendukung secara terperinci menentukan kolom database (bidang) mana yang diizinkan akses di bagian fields.

Format

{
  "entities": {
    <string>: {
      "permissions": [
        {
          "role": <string>,
          "actions": [
            {
              "action": <string>,
              "fields": {
                "include": <array of strings>,
                "exclude": <array of strings>
              },
              "policy": <object>
            }
          ]
        }
      ]
    }
  }
}

Contoh

Dalam contoh ini, peran anonymous diizinkan untuk membaca dari semua bidang kecuali id, tetapi dapat menggunakan semua bidang saat membuat item.

{
  "entities": {
    "Author": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "fields": {
                "include": [ "*" ],
                "exclude": [ "id" ]
              }
            },
            { "action": "create" }
          ]
        }
      ]
    }
  }
}

Sertakan dan kecualikan bekerja sama. Kartubebas * di bagian include menunjukkan semua bidang. Bidang yang dicatat di bagian exclude lebih diutamakan daripada bidang yang dicatat di bagian include. Definisi yang diterjemahkan ke menyertakan semua bidang kecuali untuk bidang 'last_updated.'

"Book": {
    "source": "books",
    "permissions": [
        {
            "role": "anonymous",
            "actions": [ "read" ],
            // Include All Except Specific Fields
            "fields": {
              "include": [ "*" ],
              "exclude": [ "secret-field" ]
            }
        },
        {
            "role": "authenticated",
            "actions": [ "read", "update" ],
            // Explicit Include and Exclude
            "fields": {
              "include": [ "id", "title", "secret-field" ],
              "exclude": [ "secret-field" ]
            }
        },
        {
            "role": "author",
            "actions": [ "*" ],
            // Include All With No Exclusions (default)
            "fields": {
              "include": ["*"],
              "exclude": []
            }
        }
    ]
}

Kebijakan

Bagian policy, yang ditentukan per action, menentukan aturan keamanan tingkat item (kebijakan database) yang membatasi hasil yang dikembalikan dari permintaan. Sub bagian database menunjukkan ekspresi kebijakan database yang dievaluasi selama eksekusi permintaan.

Format

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "role": <string>,
          "actions": [
            {
              "action": <string>,
              "fields": <object>,
              "policy": {
                "database": <string>
              }
            }
          ]
        }
      ]
    }
  }
}

Properti

Deskripsi

Kebijakan database: ekspresi seperti OData yang diterjemahkan ke dalam predikat kueri yang dievaluasi database, termasuk operator seperti eq, lt, dan gt. Agar hasil dikembalikan untuk permintaan, predikat kueri permintaan yang diselesaikan dari kebijakan database harus dievaluasi ke true saat mengeksekusi terhadap database.

predicate adalah ekspresi yang mengevaluasi ke TRUE atau FALSE. Predikat digunakan dalam kondisi pencarian klausa WHERE dan klausa HAVING, kondisi gabungan klausa FROM, dan konstruksi lain di mana nilai Boolean diperlukan. (Microsoft Learn Docs)

Kebijakan database

Dua jenis arahan dapat digunakan untuk mengelola kebijakan database saat menulis ekspresi kebijakan database:

Berikut adalah beberapa contoh kebijakan database:

• @claims.userId eq @item.OwnerId
• @claims.userId gt @item.OwnerId
• @claims.userId lt @item.OwnerId

Penyusun API Data membandingkan nilai klaim UserId dengan nilai bidang database OwnerId. Payload hasil hanya mencakup rekaman yang memenuhi baik metadata permintaan dan ekspresi kebijakan database.

Keterbatasan

Kebijakan database didukung untuk tabel dan tampilan. Prosedur tersimpan tidak dapat dikonfigurasi dengan kebijakan.

Kebijakan database tidak mencegah permintaan dijalankan dalam database. Perilaku ini karena diselesaikan sebagai predikat dalam kueri yang dihasilkan yang diteruskan ke mesin database.

Kebijakan database hanya didukung untuk actionsmembuat, membaca, memperbarui, dan menghapus. Karena tidak ada predikat dalam panggilan prosedur tersimpan, mereka tidak dapat ditambahkan.

Operator seperti OData yang didukung

Untuk informasi selengkapnya, lihat operator biner.

Untuk informasi selengkapnya, lihat operator unary.

Pembatasan nama bidang entitas

• Aturan: Harus dimulai dengan huruf atau garis bawah (_), diikuti hingga 127 huruf, garis bawah (_), atau digit (0-9).
• Impact: Bidang yang tidak mematuhi aturan ini tidak dapat langsung digunakan dalam kebijakan database.
• Solution: Gunakan bagian mappings untuk membuat alias untuk bidang yang tidak memenuhi konvensi penamaan ini; pemetaan memastikan semua bidang dapat disertakan dalam ekspresi kebijakan.

Memanfaatkan mappings untuk bidang yang tidak sesuai

Jika nama bidang entitas Anda tidak memenuhi aturan sintaks OData atau Anda hanya ingin alias karena alasan lain, Anda dapat menentukan alias di bagian mappings konfigurasi Anda.

{
  "entities": {
    "<entity-name>": {
      "mappings": {
        "<field-1-name>": <string>,
        "<field-2-name>": <string>,
        "<field-3-name>": <string>
      }
    }
  }
}

Dalam contoh ini, field-1-name adalah nama bidang database asli yang tidak memenuhi konvensi penamaan OData. Membuat peta ke field-1-name dan field-1-alias memungkinkan bidang ini direferensikan dalam ekspresi kebijakan database tanpa masalah. Pendekatan ini tidak hanya membantu mematuhi konvensi penamaan OData tetapi juga meningkatkan kejelasan dan aksesibilitas model data Anda dalam titik akhir GraphQL dan RESTful.

Contoh

Pertimbangkan entitas bernama Employee dalam konfigurasi API Data yang menggunakan klaim dan arahan item. Ini memastikan akses data dikelola dengan aman berdasarkan peran pengguna dan kepemilikan entitas:

{
  "entities": {
    "Employee": {
      "source": {
        "object": "HRUNITS",
        "type": "table",
        "key-fields": ["employee NUM"],
        "parameters": {}
      },
      "mappings": {
        "employee NUM": "EmployeeId",
        "employee Name": "EmployeeName",
        "department COID": "DepartmentId"
      },
      "policy": {
        "database": "@claims.role eq 'HR' or @claims.userId eq @item.EmployeeId"
      }
    }
  }
}

Definisi Entitas: Entitas Employee dikonfigurasi untuk antarmuka REST dan GraphQL, menunjukkan datanya dapat dikueri atau dimanipulasi melalui titik akhir ini.

Konfigurasi Sumber : Mengidentifikasi HRUNITS dalam database, dengan employee NUM sebagai bidang kunci.

Pemetaan: Alias digunakan untuk memetakan employee NUM, employee Name, dan department COID untuk EmployeeId, EmployeeName, dan DepartmentId, masing-masing, menyederhanakan nama bidang dan berpotensi mengaburkan detail skema database sensitif.

Policy Application: Bagian policy menerapkan kebijakan database menggunakan ekspresi seperti OData. Kebijakan ini membatasi akses data kepada pengguna dengan peran SDM (@claims.role eq 'HR') atau kepada pengguna yang klaim UserId nya cocok dengan EmployeeId - alias bidang - dalam database (@claims.userId eq @item.EmployeeId). Ini memastikan bahwa karyawan hanya dapat mengakses catatan mereka sendiri kecuali mereka termasuk dalam departemen SDM. Kebijakan dapat memberlakukan keamanan tingkat baris berdasarkan kondisi dinamis.

Basis data

Bagian policy, yang ditentukan per action, menentukan aturan keamanan tingkat item (kebijakan database) yang membatasi hasil yang dikembalikan dari permintaan. Sub bagian database menunjukkan ekspresi kebijakan database yang dievaluasi selama eksekusi permintaan.

Format

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "role": <string>,
          "actions": [
            {
              "action": <string>,
              "fields": {
                "include": <array of strings>,
                "exclude": <array of strings>
              },
              "policy": {
                "database": <string>
              }
            }
          ]
        }
      ]
    }
  }
}

Properti ini menunjukkan ekspresi kebijakan database yang dievaluasi selama eksekusi permintaan. String kebijakan adalah ekspresi OData yang diterjemahkan ke dalam kueri yang diprediksi dievaluasi oleh database. Misalnya, ekspresi kebijakan @item.OwnerId eq 2000 diterjemahkan ke predikat kueri WHERE <schema>.<object-name>.OwnerId = 2000.

Agar hasil dikembalikan untuk permintaan, predikat kueri permintaan yang diselesaikan dari kebijakan database harus dievaluasi ke true saat mengeksekusi terhadap database.

Dua jenis arahan dapat digunakan untuk mengelola kebijakan database saat menulis ekspresi kebijakan database:

Contoh

Misalnya, ekspresi kebijakan dasar dapat mengevaluasi apakah bidang tertentu benar dalam tabel. Contoh ini mengevaluasi apakah bidang soft_deletefalse.

{
  "entities": {
    "Manuscripts": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "@item.soft_delete eq false"
              }
            }
          ]
        }
      ]
    }
  }
}

Predikat juga dapat mengevaluasi jenis direktif claims dan item. Contoh ini menarik bidang UserId dari token akses dan membandingkannya dengan bidang owner_id dalam tabel database target.

{
  "entities": {
    "Manuscript": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "@claims.userId eq @item.owner_id"
              }
            }
          ]
        }
      ]
    }
  }
}

Keterbatasan

• Kebijakan database didukung untuk tabel dan tampilan. Prosedur tersimpan tidak dapat dikonfigurasi dengan kebijakan.
• Kebijakan database tidak dapat digunakan untuk mencegah permintaan dijalankan dalam database. Batasan ini karena kebijakan database diselesaikan sebagai predikat kueri dalam kueri database yang dihasilkan. Mesin database pada akhirnya mengevaluasi kueri ini.
• Kebijakan database hanya didukung untuk actionscreate, read, update, dan delete.
• Sintaks ekspresi OData kebijakan database hanya mendukung skenario ini.
  • Operator biner termasuk, tetapi tidak terbatas pada; and, or, eq, gt, dan lt. Untuk informasi selengkapnya, lihat BinaryOperatorKind .
  • Operator unary seperti operator - (meniadakan) dan not. Untuk informasi selengkapnya, lihat UnaryOperatorKind .
• Kebijakan database juga memiliki batasan yang terkait dengan nama bidang.
  • Nama bidang entitas yang dimulai dengan huruf atau garis bawah, diikuti oleh paling banyak 127 huruf, garis bawah, atau digit.
  • Persyaratan ini sesuai spesifikasi OData. Untuk informasi selengkapnya, lihat Bahasa Definisi Skema Umum OData.

GraphQL (entitas)

Objek ini menentukan apakah GraphQL diaktifkan dan nama yang digunakan untuk mengekspos entitas sebagai jenis GraphQL. Objek ini bersifat opsional dan hanya digunakan jika nama atau pengaturan default tidak cukup.

Segmen ini menyediakan untuk mengintegrasikan entitas ke dalam skema GraphQL. Ini memungkinkan pengembang untuk menentukan atau memodifikasi nilai default untuk entitas di GraphQL. Penyiapan ini memastikan skema secara akurat mencerminkan struktur dan konvensi penamaan yang dimaksud.

Format

{
  "entities": {
    "<entity-name>": {
      "graphql": {
        "enabled": <true> (default) | <false>,
        "type": {
          "singular": <string>,
          "plural": <string>
        },
        "operation": "query" (default) | "mutation"
      }
    }
  }
}

{
  "entities": {
    "<entity-name>": {
      "graphql": {
        "enabled": <boolean>,
        "type": <string-or-object>,
        "operation": "query" (default) | "mutation"
      }
    }
  }
}

Properti

Contoh

Kedua contoh ini setara secara fungsional.

{
  "entities": {
    "Author": {
      "graphql": true
    }
  }
}

{
  "entities": {
    "Author": {
      "graphql": {
        "enabled": true
      }
    }
  }
}

Dalam contoh ini, entitas yang ditentukan Book, menunjukkan bahwa kami berurusan dengan sekumpulan data yang terkait dengan buku dalam database. Konfigurasi untuk entitas Book dalam segmen GraphQL menawarkan struktur yang jelas tentang bagaimana entitas tersebut harus diwakili dan berinteraksi dalam skema GraphQL.

Properti yang diaktifkan: Entitas Book disediakan melalui GraphQL ("enabled": true), yang berarti pengembang dan pengguna dapat mengkueri atau membius data buku melalui operasi GraphQL.

Jenis properti: Entitas diwakili dengan nama tunggal "Book" dan nama jamak "Books" dalam skema GraphQL. Perbedaan ini memastikan bahwa saat mengkueri satu buku atau beberapa buku, skema menawarkan jenis bernama intuitif (Book untuk satu entri, Books untuk daftar), meningkatkan kegunaan API.

properti Operasi: Operasi diatur ke "query", menunjukkan bahwa interaksi utama dengan entitas Book melalui GraphQL dimaksudkan untuk mengkueri (mengambil) data daripada mengubah (membuat, memperbarui, atau menghapusnya). Penyiapan ini selaras dengan pola penggunaan umum di mana data buku lebih sering dibaca daripada yang dimodifikasi.

{
  "entities": {
    "Book": {
      ...
      "graphql": {
        "enabled": true,
        "type": {
          "singular": "Book",
          "plural": "Books"
        },
        "operation": "query"
      },
      ...
    }
  }
}

Jenis (entitas GraphQL)

Properti ini menentukan konvensi penamaan untuk entitas dalam skema GraphQL. Ini mendukung nilai string skalar dan jenis objek. Nilai objek menentukan bentuk tunggal dan jamak. Properti ini memberikan kontrol terperinci atas keterbacaan skema dan pengalaman pengguna.

Format

{
  "entities": {
    <entity-name>: {
      "graphql": {
        "type": <string>
      }
    }
  }
}

{
  "entities": {
    <entity-name>: {
      "graphql": {
        "type": {
          "singular": <string>,
          "plural": <string>
        }
      }
    }
  }
}

Properti

Contoh

Untuk kontrol yang lebih besar atas jenis GraphQL, Anda dapat mengonfigurasi bagaimana nama tunggal dan jamak diwakili secara independen.

Jika plural hilang atau dihilangkan (seperti nilai skalar) Penyusun API Data mencoba memangkas nama secara otomatis, ikuti aturan bahasa Inggris untuk pluralisasi (misalnya: https://engdic.org/singular-and-plural-noun-rules-definitions-examples)

{
  "entities" {
    "<entity-name>": {
      ...
      "graphql": {
        ...
        "type": {
          "singular": "User",
          "plural": "Users"
        }
      }
    }
  }
}

Nama entitas kustom dapat ditentukan menggunakan parameter type dengan nilai string. Dalam contoh ini, mesin membedakan secara otomatis antara varian tunggal dan jamak dari nama ini menggunakan aturan bahasa Inggris umum untuk pluralisasi.

{
  "entities": {
    "Author": {
      "graphql": {
        "type": "bookauthor"
      }
    }
  }
}

Jika Anda memilih untuk menentukan nama secara eksplisit, gunakan properti type.singular dan type.plural. Contoh ini secara eksplisit mengatur kedua nama.

{
  "entities": {
    "Author": {
      "graphql": {
        "type": {
          "singular": "bookauthor",
          "plural": "bookauthors"
        }
      }
    }
  }
}

Kedua contoh tersebut setara secara fungsional. Keduanya mengembalikan output JSON yang sama untuk kueri GraphQL yang menggunakan nama entitas bookauthors.

{
  bookauthors {
    items {
      first_name
      last_name
    }
  }
}

{
  "data": {
    "bookauthors": {
      "items": [
        {
          "first_name": "Henry",
          "last_name": "Ross"
        },
        {
          "first_name": "Jacob",
          "last_name": "Hancock"
        },
        ...
      ]
    }
  }
}

Operasi (entitas GraphQL)

Untuk entitas yang dipetakan ke prosedur tersimpan, properti operation menunjuk jenis operasi GraphQL (kueri atau mutasi) tempat prosedur tersimpan dapat diakses. Pengaturan ini memungkinkan organisasi logis dari skema dan kepatuhan terhadap praktik terbaik GraphQL, tanpa memengaruhi fungsionalitas.

Jika hilang, default operation adalah mutation.

Format

{
  "entities": {
    "<entity-name>": {
      "graphql": {
        "operation": "query" (default) | "mutation"
      }
    }
  }
}

Nilai

Berikut adalah daftar nilai yang diizinkan untuk properti ini:

Contoh

Ketika operationmutation, skema GraphQL akan menyerupai:

type Mutation {
  executeGetCowrittenBooksByAuthor(
    searchType: String = "S"
  ): [GetCowrittenBooksByAuthor!]!
}

Ketika operationquery, skema GraphQL akan menyerupai:

Skema GraphQL akan menyerupai:

type Query {
  executeGetCowrittenBooksByAuthor(
    searchType: String = "S"
  ): [GetCowrittenBooksByAuthor!]!
}

Diaktifkan (entitas GraphQL)

Mengaktifkan atau menonaktifkan titik akhir GraphQL. Mengontrol apakah entitas tersedia melalui titik akhir GraphQL. Beralih ke properti enabled memungkinkan pengembang mengekspos entitas secara selektif dari skema GraphQL.

Format

{
  "entities": {
    "<entity-name>": {
      "graphql": {
        "enabled": <true> (default) | <false>
      }
    }
  }
}

REST (entitas)

Bagian rest dari file konfigurasi didedikasikan untuk menyempurnakan titik akhir RESTful untuk setiap entitas database. Kemampuan penyesuaian ini memastikan bahwa REST API yang diekspos cocok dengan persyaratan tertentu, meningkatkan kemampuan utilitas dan integrasinya. Ini mengatasi potensi ketidakcocokan antara pengaturan default yang disimpulkan dan perilaku titik akhir yang diinginkan.

Format

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "enabled": <true> (default) | <false>,
        "path": <string; default: "<entity-name>">,
        "methods": <array of strings; default: ["GET", "POST"]>
      }
    }
  }
}

Properti

Contoh

Kedua contoh ini setara secara fungsional.

{
  "entities": {
    "Author": {
      "source": {
        "object": "dbo.authors",
        "type": "table"
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["*"]
        }
      ],
      "rest": true
    }
  }
}

{
  "entities": {
    "Author": {
      ...
      "rest": {
        "enabled": true
      }
    }
  }
}

Berikut adalah contoh lain konfigurasi REST untuk entitas.

{
  "entities" {
    "User": {
      "rest": {
        "enabled": true,
        "path": "/User"
      },
      ...
    }
  }
}

Diaktifkan (entitas REST)

Properti ini bertindak sebagai pengalih untuk visibilitas entitas dalam REST API. Dengan mengatur properti enabled ke true atau false, pengembang dapat mengontrol akses ke entitas tertentu, memungkinkan permukaan API yang disesuaikan yang selaras dengan persyaratan keamanan dan fungsionalitas aplikasi.

Format

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "enabled": <true> (default) | <false>
      }
    }
  }
}

Jalur (entitas REST)

Properti path menentukan segmen URI yang digunakan untuk mengakses entitas melalui REST API. Penyesuaian ini memungkinkan jalur titik akhir yang lebih deskriptif atau disederhanakan di luar nama entitas default, meningkatkan navigasi API dan integrasi sisi klien. Secara default, jalurnya adalah /<entity-name>.

Format

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "path": <string; default: "<entity-name>">
      }
    }
  }
}

Contoh

Contoh ini mengekspos entitas Author menggunakan titik akhir /auth.

{
  "entities": {
    "Author": {
      "rest": {
        "path": "/auth"
      }
    }
  }
}

Metode (entitas REST)

Berlaku khusus untuk prosedur tersimpan, properti methods menentukan kata kerja HTTP mana (misalnya, GET, POST) yang dapat direspons prosedur. Metode memungkinkan kontrol yang tepat atas bagaimana prosedur tersimpan diekspos melalui REST API, memastikan kompatibilitas dengan standar RESTful dan harapan klien. Bagian ini menggaris bawahi komitmen platform terhadap fleksibilitas dan kontrol pengembang, memungkinkan desain API yang tepat dan intuitif yang disesuaikan dengan kebutuhan spesifik setiap aplikasi.

Jika dihilangkan atau hilang, default methods adalah POST.

Format

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "methods": ["GET" (default), "POST"]
      }
    }
  }
}

Nilai

Berikut adalah daftar nilai yang diizinkan untuk properti ini:

Contoh

Contoh ini menginstruksikan mesin bahwa prosedur tersimpan stp_get_bestselling_authors hanya mendukung tindakan HTTP GET.

{
  "entities": {
    "BestSellingAuthor": {
      "source": {
        "object": "dbo.stp_get_bestselling_authors",
        "type": "stored-procedure",
        "parameters": {
          "depth": "number"
        }
      },
      "rest": {
        "path": "/best-selling-authors",
        "methods": [ "get" ]
      }
    }
  }
}

Pemetaan (entitas)

Bagian mappings memungkinkan konfigurasi alias, atau nama yang diekspos, untuk bidang objek database. Nama yang diekspos yang dikonfigurasi berlaku untuk titik akhir GraphQL dan REST.

Format

{
  "entities": {
    "<entity-name>": {
      "mappings": {
        "<field-1-name>": "<field-1-alias>",
        "<field-2-name>": "<field-2-alias>",
        "<field-3-name>": "<field-3-alias>"
      }
    }
  }
}

Contoh

Dalam contoh ini, bidang sku_title dari objek database dbo.magazines diekspos menggunakan nama title. Demikian pula, bidang sku_status diekspos sebagai status di titik akhir REST dan GraphQL.

{
  "entities": {
    "Magazine": {
      ...
      "mappings": {
        "sku_title": "title",
        "sku_status": "status"
      }
    }
  }
}

Berikut adalah contoh pemetaan lainnya.

{
  "entities": {
    "Book": {
      ...
      "mappings": {
        "id": "BookID",
        "title": "BookTitle",
        "author": "AuthorName"
      }
    }
  }
}

Pemetaan: Objek mappings menautkan bidang database (BookID, BookTitle, AuthorName) ke nama yang lebih intuitif atau standar (id, title, author) yang digunakan secara eksternal. Alias ini melayani beberapa tujuan:

• Clarity and Consistency: Ini memungkinkan penggunaan penamaan yang jelas dan konsisten di seluruh API, terlepas dari skema database yang mendasar. Misalnya, BookID dalam database diwakili sebagai id di API, membuatnya lebih intuitif bagi pengembang yang berinteraksi dengan titik akhir.

• GraphQL Compliance: Dengan menyediakan mekanisme untuk nama bidang alias, ini memastikan bahwa nama yang diekspos melalui antarmuka GraphQL mematuhi persyaratan penamaan GraphQL. Perhatian terhadap nama penting karena GraphQL memiliki aturan ketat tentang nama (misalnya, tanpa spasi, harus dimulai dengan huruf atau garis bawah, dll.). Misalnya, jika nama bidang database tidak memenuhi kriteria ini, nama tersebut dapat dinamai dengan nama yang sesuai melalui pemetaan.

• Fleksibilitas: Aliasing ini menambahkan lapisan abstraksi antara skema database dan API, memungkinkan perubahan dalam satu tanpa mengharukan perubahan di yang lain. Misalnya, perubahan nama bidang dalam database tidak memerlukan pembaruan ke dokumentasi API atau kode sisi klien jika pemetaan tetap konsisten.

• Obfuscation Nama Bidang : Pemetaan memungkinkan obfuscation nama bidang, yang dapat membantu mencegah pengguna yang tidak sah menyimpulkan informasi sensitif tentang skema database atau sifat data yang disimpan.

• Melindungi Informasi Kepemilikan: Dengan mengganti nama bidang, Anda juga dapat melindungi nama kepemilikan atau logika bisnis yang mungkin diisyaratkan melalui nama bidang asli database.

Hubungan (entitas)

Peta bagian ini mencakup sekumpulan definisi hubungan yang memetakan bagaimana entitas terkait dengan entitas lain yang terekspos. Definisi hubungan ini juga dapat secara opsional menyertakan detail pada objek database yang mendasar yang digunakan untuk mendukung dan menegakkan hubungan. Objek yang ditentukan di bagian ini diekspos sebagai bidang GraphQL di entitas terkait. Untuk informasi selengkapnya, lihat perincian hubungan penyusun API Data .

Bagian relationships menguraikan bagaimana entitas berinteraksi dalam penyusun API Data, merinci asosiasi, dan dukungan database potensial untuk hubungan ini. Properti relationship-name untuk setiap hubungan diperlukan dan harus unik di semua hubungan untuk entitas tertentu. Nama kustom memastikan koneksi yang jelas dan dapat diidentifikasi dan mempertahankan integritas skema GraphQL yang dihasilkan dari konfigurasi ini.

Format

{
  "entities": {
    "<entity-name>": {
      "relationships": {
        "<relationship-name>": {
          "cardinality": "one" | "many",
          "target.entity": "<string>",
          "source.fields": ["<string>"],
          "target.fields": ["<string>"],
          "linking.object": "<string>",
          "linking.source.fields": ["<string>"],
          "linking.target.fields": ["<string>"]
        }
      }
    }
  }
}

Properti

Contoh

Saat mempertimbangkan hubungan, yang terbaik adalah membandingkan perbedaan antara satu ke banyak , banyak ke satu , dan hubungan banyak ke banyak.

Satu-ke-banyak

Pertama, mari kita pertimbangkan contoh hubungan dengan entitas yang diekspos memiliki hubungan satu-ke-banyak dengan entitas . Di sini, kardinalitas diatur ke many. Setiap Category dapat memiliki beberapa entitas Book terkait sementara setiap entitas Book hanya dikaitkan dengan satu entitas Category.

{
  "entities": {
    "Book": {
      ...
    },
    "Category": {
      "relationships": {
        "category_books": {
          "cardinality": "many",
          "target.entity": "Book",
          "source.fields": [ "id" ],
          "target.fields": [ "category_id" ]
        }
      }
    }
  }
}

Dalam contoh ini, daftar source.fields menentukan bidang id entitas sumber (Category). Bidang ini digunakan untuk menyambungkan ke item terkait di entitas target. Sebaliknya, daftar target.fields menentukan bidang category_id entitas target (Book). Bidang ini digunakan untuk menyambungkan ke item terkait di entitas source.

Dengan hubungan ini ditentukan, skema GraphQL yang terekspos yang dihasilkan harus menyerupai contoh ini.

type Category
{
  id: Int!
  ...
  books: [BookConnection]!
}

Banyak ke satu

Selanjutnya, pertimbangkan banyak ke satu yang mengatur kardinalitas ke one. Entitas Book yang diekspos dapat memiliki satu entitas Category terkait. Entitas Category dapat memiliki beberapa entitas Book terkait.

{
  "entities": {
    "Book": {
      "relationships": {
        "books_category": {
          "cardinality": "one",
          "target.entity": "Category",
          "source.fields": [ "category_id" ],
          "target.fields": [ "id" ]
        }
      },
      "Category": {
        ...
      }
    }
  }
}

Di sini, daftar source.fields menentukan bahwa bidang category_id entitas sumber (Book) mereferensikan bidang id entitas target terkait (Category). Sebaliknya, daftar target.fields menentukan hubungan terbalik. Dengan hubungan ini, skema GraphQL yang dihasilkan sekarang mencakup pemetaan kembali dari Buku ke Kategori.

type Book
{
  id: Int!
  ...
  category: Category
}

Banyak ke banyak

Akhirnya, hubungan banyak ke banyak didefinisikan dengan kardinalitas dan lebih banyak metadata untuk menentukan objek database mana yang digunakan untuk membuat hubungan dalam database cadangan. Di sini, entitas Book dapat memiliki beberapa entitas Author dan sebaliknya entitas Author dapat memiliki beberapa entitas Book.

{
  "entities": {
    "Book": {
      "relationships": {
        ...,
        "books_authors": {
          "cardinality": "many",
          "target.entity": "Author",
          "source.fields": [ "id" ],
          "target.fields": [ "id" ],
          "linking.object": "dbo.books_authors",
          "linking.source.fields": [ "book_id" ],
          "linking.target.fields": [ "author_id" ]
        }
      },
      "Category": {
        ...
      },
      "Author": {
        ...
      }
    }
  }
}

Dalam contoh ini, source.fields dan target.fields menunjukkan bahwa tabel hubungan menggunakan pengidentifikasi utama (id) dari entitas sumber (Book) dan target (Author). Bidang linking.object menentukan bahwa hubungan ditentukan dalam objek database dbo.books_authors. Selanjutnya, linking.source.fields menentukan bahwa bidang book_id objek penautan mereferensikan bidang id entitas Book dan linking.target.fields menentukan bahwa bidang author_id objek penautan mereferensikan bidang id entitas Author.

Contoh ini dapat dijelaskan menggunakan skema GraphQL yang mirip dengan contoh ini.

type Book
{
  id: Int!
  ...
  authors: [AuthorConnection]!
}

type Author
{
  id: Int!
  ...
  books: [BookConnection]!
}

Kardinalitas

Menentukan apakah entitas sumber saat ini hanya terkait dengan satu instans entitas target atau beberapa.

Nilai

Berikut adalah daftar nilai yang diizinkan untuk properti ini:

Entitas target

Nama entitas yang ditentukan di tempat lain dalam konfigurasi yang merupakan target hubungan.

Bidang sumber

Parameter opsional untuk menentukan bidang yang digunakan untuk pemetaan di entitas sumber yang digunakan untuk menyambungkan ke item terkait di entitas target.

Bidang target

Parameter opsional untuk menentukan bidang yang digunakan untuk pemetaan di entitas target yang digunakan untuk menyambungkan ke item terkait di entitas sumber.

Menautkan objek atau entitas

Untuk hubungan banyak ke banyak, nama objek atau entitas database yang berisi data yang diperlukan untuk menentukan hubungan antara dua entitas lain.

Menautkan bidang sumber

Nama bidang objek atau entitas database yang terkait dengan entitas sumber.

Menautkan bidang target

Nama bidang objek atau entitas database yang terkait dengan entitas target.

Cache (entitas)

Mengaktifkan dan mengonfigurasi penembolokan untuk entitas.

Format

You're right; the formatting doesn't match your style. Here’s the corrected version following your preferred documentation format:

```json
{
  "entities": {
    "<entity-name>": {
      "cache": {
        "enabled": <true> (default) | <false>,
        "ttl-seconds": <integer; default: 5>
      }
    }
  }
}

Properti

Contoh

Dalam contoh ini, cache diaktifkan dan item kedaluwarsa setelah 30 detik.

{
  "entities": {
    "Author": {
      "cache": {
        "enabled": true,
        "ttl-seconds": 30
      }
    }
  }
}

Diaktifkan (Entitas cache)

Mengaktifkan penembolokan untuk entitas.

Dukungan Objek Database

Dukungan Header HTTP

Format

{
  "entities": {
    "<entity-name>": {
      "cache": {
        "enabled": <boolean> (default: false)
      }
    }
  }
}

Contoh

Dalam contoh ini, cache dinonaktifkan.

{
  "entities": {
    "Author": {
      "cache": {
        "enabled": false
      }
    }
  }
}

TTL dalam hitungan detik (Entitas cache)

Mengonfigurasi nilai time-to-live (TTL) dalam hitungan detik untuk item yang di-cache. Setelah waktu ini berlalu, item secara otomatis diprakarsai dari cache. Nilai defaultnya adalah 5 detik.

Format

{
  "entities": {
    "<entity-name>": {
      "cache": {
        "ttl-seconds": <integer; inherited>
      }
    }
  }
}

Contoh

Dalam contoh ini, cache diaktifkan dan item kedaluwarsa setelah 15 detik. Ketika dihilangkan, pengaturan ini mewarisi pengaturan global atau default.

{
  "entities": {
    "Author": {
      "cache": {
        "enabled": true,
        "ttl-seconds": 15
      }
    }
  }
}

Konten terkait

• referensi Functions
• referensi antarmuka baris perintah (CLI)