Runtime

Pengaturan konfigurasi yang menentukan perilaku runtime.

Pengaturan pagination

Property	Default	Description
ukuran halaman runtime.pagination.max	Menentukan rekaman maksimum per halaman
runtime.pagination.default-page-size	Mengatur rekaman default per respons

Pengaturan REST

Property	Default	Description
runtime.rest.path	`"/api"`	Jalur dasar untuk titik akhir REST
runtime.rest.enabled	`true`	Memungkinkan mengaktifkan atau menonaktifkan permintaan REST untuk semua entitas
runtime.rest.request-body-strict	`true`	Melarang bidang asing dalam isi permintaan ketika benar

Pengaturan GraphQL

Property	Default	Description
runtime.graphql.allow-introspection	`true`	Memungkinkan kueri skema GraphQL yang mendasar
runtime.graphql.path	`"/graphql"`	Jalur dasar untuk titik akhir GraphQL
runtime.graphql.enabled	`true`	Memungkinkan mengaktifkan atau menonaktifkan permintaan GraphQL untuk semua entitas
runtime.graphql.depth-limit	`null`	Kedalaman maksimum kueri GraphQL yang diizinkan
runtime.graphql.multiple-mutations.create.enabled	`false`	Memungkinkan mutasi beberapa buat untuk semua entitas

Pengaturan host

Property	Default	Description
runtime.host.max-response-size-mb	`158`	Ukuran maksimum (MB) respons database yang diizinkan dalam satu hasil
runtime.host.mode	`"production"`	Mode berjalan; `"production"` atau `"development"`

Pengaturan CORS

Property	Default	Description
runtime.host.cors.origins	`[]`	Asal CORS yang diizinkan
runtime.host.cors.allow-credentials	`false`	Mengatur nilai untuk header Access-Control-Allow-Credentials

Pengaturan autentikasi

Property	Default	Description
runtime.host.authentication.provider	`null`	Penyedia autentikasi
runtime.host.authentication.jwt.audience	`null`	Audiens JWT
runtime.host.authentication.jwt.issuer	`null`	Penerbit JWT

Pengaturan cache

Property	Default	Description
runtime.cache.enabled	`false`	Memungkinkan penembolokan respons secara global
runtime.cache.ttl-seconds	`5`	Waktu hidup (detik) untuk cache global

Pengaturan telemetri

Property	Default	Description
runtime.telemetry.application-insights.connection-string	`null`	String koneksi Application Insights
runtime.telemetry.application-insights.enabled	`false`	Mengaktifkan atau menonaktifkan telemetri Application Insights
runtime.telemetry.open-telemetry.endpoint	`null`	URL pengumpul OpenTelemetry
runtime.telemetry.open-telemetry.headers	`{}`	Header ekspor OpenTelemetry
runtime.telemetry.open-telemetry.service-name	`"dab"`	Nama layanan OpenTelemetry
runtime.telemetry.open-telemetry.exporter-protocol	`"grpc"`	Protokol OpenTelemetry ("grpc" atau "httpprotobuf")
runtime.telemetry.open-telemetry.enabled	`true`	Mengaktifkan atau menonaktifkan OpenTelemetry
runtime.telemetry.log-level.namespace	`null`	Penimpaan tingkat log khusus namespace layanan
runtime.health.enabled	`true`	Mengaktifkan atau menonaktifkan titik akhir pemeriksaan kesehatan secara global
runtime.health.roles	`null`	Peran yang diizinkan untuk titik akhir kesehatan yang komprehensif
runtime.health.cache-ttl-seconds	`5`	Waktu hidup (detik) untuk entri cache laporan pemeriksaan kesehatan
runtime.health.max-query-parallelism	`4`	Kueri pemeriksaan kesehatan bersamaan maksimum (rentang: 1-8)

Gambaran umum format

{
  "runtime": {
    "pagination": {
      "max-page-size": <integer|null> (default: `100000`),
      "default-page-size": <integer|null> (default: `100`)
    },
    "rest": {
      "path": <string> (default: "/api"),
      "enabled": <true>|<false>,
      "request-body-strict": <true>|<false> (default: `true`)
    },
    "graphql": {
      "path": <string> (default: "/graphql"),
      "enabled": <true>|<false>,
      "allow-introspection": <true>|<false>,
      "depth-limit": <integer|null> (default: `null`),
      "multiple-mutations": {
        "create": {
          "enabled": <true>|<false> (default: `false`)
        }
      }
    },
    "host": {
      "mode": <"production"> (default) | <"development">,
      "max-response-size-mb": <integer|null> (default: `158`),
      "cors": {
        "origins": [ "<string>" ],
        "allow-credentials": <true>|<false> (default: `false`)
      },
      "authentication": {
        "provider": <string> (default: "AppService"),
        "jwt": {
          "audience": "<string>",
          "issuer": "<string>"
        }
      }
    }
  },
  "cache": {
    "enabled": <true>|<false> (default: `false`),
    "ttl-seconds": <integer> (default: `5`)
  },
  "telemetry": {
    "application-insights": {
      "connection-string": "<string>",
      "enabled": <true>|<false> (default: `true`)
    },
    "open-telemetry": {
      "endpoint": "<string>",
      "headers": "<string>",
      "service-name": <string> (default: "dab"),
      "exporter-protocol": <"grpc"> (default) | <"httpprotobuf">,
      "enabled": <true>|<false> (default: `true`)
    },
    "log-level": {
      // namespace keys
      "<namespace>": <"trace"|"debug"|"information"|"warning"|"error"|"critical"|"none"|null>
    }
  },
  "health": {
    "enabled": <true>|<false> (default: `true`),
    "roles": [ "<string>" ],
    "cache-ttl-seconds": <integer> (default: `5`),
    "max-query-parallelism": <integer> (default: `4`)
  }
}

Mode (Runtime host)

Parent	Property	Type	Required	Default
`runtime`	`host`	enum (`production` \| `development`)	❌ Tidak	`production`

Perilaku pengembangan

Diaktifkan Nitro (sebelumnya Banana Cake Pop) untuk pengujian GraphQL
Mengaktifkan UI Swagger untuk pengujian REST
Mengaktifkan pemeriksaan kesehatan anonim
Peningkatan verbositas pengelogan (Debug)

Format

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

Ukuran respons maksimum (Runtime host)

Parent	Property	Type	Required	Default
`runtime.host`	`max-response-size-mb`	integer	❌ Tidak	158

Mengatur ukuran maksimum (dalam megabyte) untuk hasil tertentu. Karena respons besar dapat membatasi sistem, max-response-size-mb membatasi ukuran total (berbeda dari jumlah baris) untuk mencegah kelebihan beban, yang terutama dengan kolom besar seperti teks atau JSON.

Value	Result
belum diatur	Gunakan default
`null`	Gunakan default
`integer`	Bilangan bulat 32-bit positif
`<= 0`	Tidak didukung

Format

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

GraphQL (runtime)

Parent	Property	Type	Required	Default
`runtime`	`graphql`	objek	❌ Tidak	-

Konfigurasi Global GraphQL.

Properti berlapis

Parent	Property	Type	Required	Default
`runtime.graphql`	`enabled`	boolean	❌ Tidak	None
`runtime.graphql`	`path`	string	❌ Tidak	"/graphql"
`runtime.graphql`	`depth-limit`	integer	❌ Tidak	Tidak ada (tidak terbatas)
`runtime.graphql`	`allow-introspection`	boolean	❌ Tidak	True
`runtime.graphql`	`multiple-mutations.create.enabled`	boolean	❌ Tidak	False

Catatan properti

Sub-jalur tidak diperbolehkan untuk path properti .
Gunakan depth-limit untuk membatasi kueri berlapis.
Atur allow-introspection ke false untuk menyembunyikan skema GraphQL.
Gunakan multiple-mutations untuk menyisipkan beberapa entitas dalam satu mutasi.

Format

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

Contoh: beberapa mutasi

Configuration

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

Mutasi GraphQL

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)

Parent	Property	Type	Required	Default
`runtime`	`rest`	objek	❌ Tidak	-

Konfigurasi REST global.

Properti berlapis

Parent	Property	Type	Required	Default
`runtime.rest`	`enabled`	boolean	❌ Tidak	None
`runtime.rest`	`path`	string	❌ Tidak	"/api"
`runtime.rest`	`request-body-strict`	boolean	❌ Tidak	True

Catatan properti

Jika global enabled adalah false, tingkat enabled entitas individu tidak masalah.
Properti path tidak mendukung nilai subpath seperti /api/data.
request-body-strict diperkenalkan untuk membantu menyederhanakan objek POCO .NET.

`request-body-strict`	Behavior
`true`	Bidang tambahan dalam isi permintaan menyebabkan `BadRequest` pengecualian.
`false`	Bidang tambahan dalam isi permintaan diabaikan.

Format

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

Note

Saat menyebarkan penyusun API Data menggunakan Static Web Apps (pratinjau), layanan Azure secara otomatis menyuntikkan subpath /data-api lain ke url. Perilaku ini memastikan kompatibilitas dengan fitur Static Web App yang ada. Titik akhir yang dihasilkan akan /data-api/api/<entity>. Catatan ini hanya relevan dengan Static Web Apps.

Contoh: request-body-strict

Kolom dengan default() nilai diabaikan hanya selama INSERT nilainya dalam payload adalah null. Sebagai konsekuensinya, INSERT operasi ke dalam default() kolom, kapan request-body-strict adalah true, tidak dapat menghasilkan nilai eksplisit null . Untuk mencapai hal ini, UPDATE diperlukan operasi.
Kolom dengan default() tidak diabaikan selama UPDATE terlepas dari nilai payload.
Kolom komputasi selalu diabaikan.
Kolom yang dibuat secara otomatis selalu diabaikan.

Tabel contoh

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

Permintaan muatan

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

Sisipkan perilaku saat `request-body-strict = false`

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.

Isi Muatan Respons

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

Memperbarui perilaku saat `request-body-strict = false`

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

Isi Muatan Respons

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

CORS (runtime host)

Parent	Property	Type	Required	Default
`runtime.host`	`cors`	objek	❌ Tidak	-

Konfigurasi CORS global.

Tip

CORS adalah singkatan dari "Berbagi Sumber Daya Lintas Asal." Ini adalah fitur keamanan browser yang mengontrol apakah halaman web dapat membuat permintaan ke domain yang berbeda dari yang melayaninya.

Properti berlapis

Parent	Property	Type	Required	Default
`runtime.host.cors`	`allow-credentials`	boolean	❌ Tidak	False
`runtime.host.cors`	`origins`	larik string	❌ Tidak	None

Note

Properti allow-credentials mengatur Access-Control-Allow-Credentials header CORS.

Format

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

Note

Kartubebas * valid sebagai nilai untuk origins.

Penyedia (Runtime host autentikasi)

Parent	Property	Type	Required	Default
`runtime.host.authentication`	`provider`	enum (`AppServiceSimulator` \| \| `EntraId` \| `Custom`)	❌ Tidak	`AppService`

Menentukan metode autentikasi yang digunakan oleh penyusun API Data.

Khusus anonim (penyedia autentikasi)

{
 "host": {
    // omit the authentication section
 }
}

Ketika seluruh authentication bagian dihilangkan dari file dab-config.json, tidak ada penyedia autentikasi yang digunakan. Dalam hal ini, pembuat API Data beroperasi dalam mode "tanpa autentikasi". Dalam mode ini, DAB tidak mencari token atau Authorization header apa pun. Header X-MS-API-ROLE juga diabaikan dalam konfigurasi ini.

[! Catatan] Setiap permintaan yang masuk ke mesin secara otomatis dan segera diberi peran sistem .anonymous Kontrol akses kemudian ditangani secara eksklusif oleh izin yang Anda tentukan pada setiap entitas.

Contoh izin entitas.

{
  "entities": {
    "Book": {
      "source": "dbo.books",
      "permissions": [
        {
          "role": "anonymous",
          "actions": [ "read" ]
        }
      ]
    }
  }
}

Dalam contoh ini, karena tidak ada authentication penyedia yang dikonfigurasi, semua permintaan masuk secara otomatis dianggap berasal dari anonymous pengguna. Array permissions untuk Book entitas secara eksplisit memberikan anonymous peran kemampuan untuk melakukan read operasi. Setiap upaya untuk melakukan tindakan lain (seperti create, , updatedelete) atau mengakses entitas lain yang tidak dikonfigurasi untuk anonymous akses ditolak.

StaticWebApps (penyedia auth) [tidak digunakan lagi]

{
 "host": {
  "authentication": {
   "provider": "StaticWebApps"
  }
 }
}

Penyedia ini tidak digunakan lagi karena fitur Data Connections pratinjau Static Web Apps dihentikan pada November 2025. Meskipun tetap fungsional, ini dirancang untuk implementasi autentikasi warisan di Azure Static Web Apps. Pengembang harus bermigrasi ke AppService penyedia untuk dukungan jangka panjang dan konsistensi yang lebih baik dengan platform "Easy Auth" Azure yang lebih luas.

[! Catatan] Migrasi tidak sesingkat mengubah nama penyedia dalam file konfigurasi. Penyedia StaticWebApps dan AppService mengharapkan struktur JSON yang berbeda dalam x-ms-client-principal header untuk memproses peran.

AppService (penyedia autentikasi)

{
 "host": {
  "authentication": {
   "provider": "AppService"
  }
 }
}

Penyedia ini untuk aplikasi yang dihosting di Azure App Service, seperti Azure Container Apps. Lingkungan hosting Azure menangani autentikasi lalu meneruskan informasi identitas pengguna ke aplikasi melalui header permintaan. Ini ditujukan untuk pengembang yang menginginkan solusi autentikasi yang sederhana dan siap pakai yang dikelola oleh platform Azure.

Penyedia ini tidak menggunakan token JWT dari Authorization header. Ini bergantung pada header khusus, X-MS-CLIENT-PRINCIPAL, disuntikkan oleh platform App Service. Header ini berisi objek JSON yang dikodekan base64 dengan detail identitas pengguna.

Anonim: Jika penyedia dikonfigurasi AppService tetapi permintaan tiba tanpa X-MS-CLIENT-PRINCIPAL header, permintaan ditetapkan ke peran anonymoussistem .

JSON yang didekodekan dari X-MS-CLIENT-PRINCIPAL header biasanya terlihat seperti ini:

{
  "auth_typ": "aad",
  "claims": [
    {"typ": "roles", "val": "admin"},
    {"typ": "roles", "val": "contributor"}
  ],
  "name_typ": "...",
  "role_typ": "..."
}

Peran terkandung dalam claims array.

Tentang headerAPI-ROLE X-MS

Peran dan Perilaku: Header X-MS-API-ROLE digunakan untuk menentukan peran mana yang ingin diasumsikan pengguna untuk permintaan saat ini. Nilai header ini harus cocok dengan salah satu nilai peran yang ditemukan dalam claims array X-MS-CLIENT-PRINCIPAL objek.
Apakah diperlukan?: Tidak. X-MS-API-ROLE Jika header tidak ada, permintaan diproses dalam konteks authenticated peran sistem. Ini berarti pengguna diakui sebagai masuk, tetapi tidak sebagai peran spesifik yang ditentukan aplikasi dari token.
Perilaku pada Kecocokan: Jika X-MS-API-ROLE header disediakan dan nilainya cocok dengan peran di prinsipal claimsklien , pengguna mengasumsikan peran tersebut untuk permintaan tersebut.
Perilaku pada Ketidakcocokan: Jika X-MS-API-ROLE header disediakan tetapi nilainya tidak cocok dengan peran apa pun di prinsipal klien, permintaan ditolak dengan 403 Forbidden kode status. Ini memastikan pengguna tidak dapat mengklaim peran yang belum ditetapkan.

EntraId (penyedia autentikasi)

{
 "host": {
  "authentication": {
   "provider": "EntraId", // previously AzureAd
   "jwt": {
    "audience": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "issuer": "https://login.microsoftonline.com/98765f43-21ba-400c-a5de-1f2a3d4e5f6a/v2.0"
   }
  }
 }
}

Penyedia ini mengamankan titik akhir dengan identitas pengguna dan aplikasi di Microsoft Entra. Ini ideal untuk layanan apa pun di mana pengguna atau layanan lain memerlukan akses aman dalam penyewa Entra.

[! CATATAN] Penyedia EntraId sebelumnya bernama AzureAd. Nama lama masih berfungsi, tetapi pengembang didorong untuk memigrasikan konfigurasi mereka dari AzureAd ke EntraId.

Penyedia ini mengharapkan token Pembawa JWT standar di Authorization header, yang dikeluarkan oleh Microsoft Entra. Token harus dikonfigurasi untuk aplikasi tertentu (menggunakan audience klaim). Peran untuk pengguna atau perwakilan layanan diharapkan berada dalam klaim dalam token. Kode mencari roles klaim secara default.

Anonim: Jika penyedia dikonfigurasi EntraId tetapi permintaan tiba tanpa Authorization header, permintaan ditetapkan ke peran anonymoussistem .

Payload JWT yang didekode mungkin terlihat seperti ini:

{
  "aud": "...", // Audience - your API
  "iss": "https://login.microsoftonline.com/{tenant-id}/v2.0", // Issuer
  "oid": "...", // User or principal object ID
  "roles": [
    "reader",
    "writer"
  ],
  // ... other claims
}

Tentang headerAPI-ROLE X-MS

Peran dan Perilaku: Header X-MS-API-ROLE digunakan untuk menentukan peran yang ingin diasumsikan pengguna untuk permintaan tersebut. Nilai header ini harus cocok dengan salah satu nilai peran yang ditemukan dalam roles klaim token JWT.
Apakah diperlukan?: Tidak. X-MS-API-ROLE Jika header tidak ada, permintaan diproses dalam konteks authenticated peran sistem. Ini berarti pengguna diakui sebagai masuk, tetapi tidak sebagai peran spesifik yang ditentukan aplikasi dari token.
Perilaku pada Kecocokan: Jika X-MS-API-ROLE header disediakan dan cocok dengan peran dalam roles klaim, konteks pengguna diatur ke peran tersebut.
Perilaku pada Ketidakcocokan: Jika X-MS-API-ROLE header disediakan tetapi nilainya tidak cocok dengan peran apa pun dalam roles klaim, permintaan ditolak dengan 403 Forbidden kode status. Ini memastikan pengguna tidak dapat mengklaim peran yang belum ditetapkan.

Kustom (penyedia autentikasi)

{
 "host": {
  "authentication": {
   "provider": "Custom",
   "jwt": {
    "audience": "<client-id-or-api-audience>",
    "issuer": "https://<your-domain>/oauth2/default"
   }
  }
 }
}

Penyedia ini ditujukan untuk pengembang yang ingin mengintegrasikan pembuat API Data dengan penyedia identitas pihak ketiga (seperti Auth0, Okta, atau server identitas kustom) yang mengeluarkan JWT. Ini memberikan fleksibilitas untuk mengonfigurasi token dan audience yang diharapkanissuer.

Penyedia Custom mengharapkan token Pembawa JWT standar di Authorization header. Perbedaan utama dari EntraId penyedia adalah Anda mengonfigurasi file konfigurasi penyusun Api Data yang valid issuer dan audience dalam. Penyedia memvalidasi token dengan memeriksa apakah otoritas tepercaya mengeluarkannya. Peran pengguna diharapkan berada dalam klaim dalam roles payload JWT.

[! CATATAN] Dalam beberapa kasus, tergantung pada penyedia identitas pihak ketiga, pengembang perlu memaksa struktur JWT mereka agar sesuai dengan struktur yang diharapkan oleh pembuat API Data (ditunjukkan di bawah).

Anonim: Jika penyedia dikonfigurasi Custom tetapi permintaan tiba tanpa Authorization header, permintaan ditetapkan ke peran anonymoussistem .

Payload JWT yang didekodekan untuk custom penyedia mungkin terlihat seperti ini:

{
  "aud": "my-api-audience", // Must match configuration
  "iss": "https://my-custom-issuer.com/", // Must match configuration
  "sub": "user-id",
  "roles": [
    "editor",
    "viewer"
  ],
  // ... other claims
}

Tentang headerAPI-ROLE X-MS

Peran dan Perilaku: Header X-MS-API-ROLE berfungsi persis seperti yang dilakukannya EntraId dengan penyedia. Ini memungkinkan pengguna untuk memilih salah satu peran yang ditetapkan. Nilai header ini harus cocok dengan salah satu peran dari roles klaim dalam token JWT kustom.
Apakah diperlukan?: Tidak. X-MS-API-ROLE Jika header tidak ada, pengguna diperlakukan sebagai berada dalam authenticated peran sistem.
Perilaku pada Kecocokan: Jika X-MS-API-ROLE nilai header cocok dengan peran dalam klaim JWT roles , konteks pengguna diatur ke peran tersebut untuk tujuan otorisasi.
Perilaku pada Ketidakcocokan: Jika X-MS-API-ROLE nilai header tidak cocok dengan peran apa pun dalam roles klaim, permintaan ditolak dengan 403 Forbidden kode status. Ini memastikan pengguna tidak dapat mengklaim peran yang belum ditetapkan.

Simulator (penyedia autentikasi)

Penyedia ini dirancang untuk memudahkan pengembang menguji konfigurasi mereka, terutama authorization kebijakan, tanpa perlu menyiapkan penyedia autentikasi lengkap seperti Entra Identity atau EasyAuth. Ini mensimulasikan authenticated pengguna.

Penyedia Simulator tidak menggunakan token JWT. Autentikasi disimulasikan. Saat menggunakan penyedia ini, semua permintaan diperlakukan seolah-olah mereka berasal dari pengguna yang diautentikasi.

Tentang headerAPI-ROLE X-MS

Peran dan Perilaku: Header X-MS-API-ROLE adalah satu-satunya cara untuk menentukan peran saat menggunakan Simulator. Karena tidak ada token dengan daftar peran, sistem secara implisit mempercayai peran yang dikirim di header ini.
Apakah diperlukan?: Tidak.
Perilaku saat Tidak Ada: Jika X-MS-API-ROLE header tidak ada, permintaan diproses dalam konteks authenticated peran sistem.
Perilaku pada Kehadiran: Jika X-MS-API-ROLE header ada, permintaan diproses dalam konteks peran yang ditentukan dalam nilai header. Tidak ada validasi terhadap daftar klaim, sehingga pengembang dapat mensimulasikan peran apa pun yang mereka butuhkan untuk menguji kebijakan mereka.

Simulator dalam Produksi

authentication.provider Jika diatur ke Simulator saat runtime.host.mode adalah production, penyusun API Data akan gagal dimulai.

"host": {
  "mode": "production", // or "development"
  "authentication": {
    "provider": "Simulator" 
  }
}

JWT (Runtime host autentikasi)

Parent	Property	Type	Required	Default
`runtime.host.authentication`	`jwt`	objek	❌ Tidak	-

Konfigurasi Global JSON Web Token (JWT).

Diagram dukungan token web JSON di penyusun API Data.

Properti berlapis

Parent	Property	Type	Required	Default
`runtime.host.authentication.jwt`	`audience`	string	❌ Tidak	None
`runtime.host.authentication.jwt`	`issuer`	string	❌ Tidak	None

Format

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

Penomoran halaman (Runtime)

Parent	Property	Type	Required	Default
`runtime`	`pagination`	objek	❌ Tidak	-

Batas penomoran halaman global untuk titik akhir REST dan GraphQL.

Properti berlapis

Parent	Property	Type	Required	Default
`runtime.pagination`	`max-page-size`	int	❌ Tidak	100,000
`runtime.pagination`	`default-page-size`	int	❌ Tidak	100
`runtime.pagination`	`next-link-relative`	boolean	❌ Tidak	`false`

Nilai yang didukung ukuran halaman maks

Value	Result
`integer`	Bilangan bulat 32-bit positif didukung.
`0`	Tidak didukung.
`-1`	Default ke nilai maksimum yang didukung.
`< -1`	Tidak didukung.

Nilai yang didukung ukuran halaman default

Value	Result
`integer`	Bilangan bulat positif apa pun yang kurang dari `max-page-size`saat ini.
`0`	Tidak didukung.
`-1`	Default ke pengaturan `max-page-size` saat ini.
`< -1`	Tidak didukung.

Perilaku relatif tautan berikutnya

Ketika next-link-relative adalah true, nilai penomoran nextLink halaman menggunakan URL relatif alih-alih URL absolut.

Value	Example
`false` (standar)	`"nextLink": "https://localhost:5001/api/users?$after=..."`
`true`	`"nextLink": "/api/users?$after=..."`

Format

{
  "runtime": {
    "pagination": {
      "max-page-size": <integer; default: 100000>,
      "default-page-size": <integer; default: 100>,
      "next-link-relative": <boolean; default: false>
    }
  }
}

Note

Ketika nilai lebih besar dari max-page-size, hasilnya dibatasi pada max-page-size.

Contoh: Halaman di REST

Request

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

Isi Muatan Respons

{
  "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=="
}

Minta Halaman Berikutnya

GET https://localhost:5001/api/users?$after=W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI==

Contoh: Penomoran halaman di GraphQL

Payload permintaan (Kueri)

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

Isi Muatan Respons

{
  "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=="
    }
  }
}

Minta Halaman Berikutnya

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

Contoh: Mengakses `max-page-size` dalam Permintaan

max-page-size Gunakan nilai menurut pengaturan $limit (REST) atau first (GraphQL) ke -1.

REST

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

GraphQL

query {
  users(first: -1) {
    items {
      ...
    }
  }
}

Cache (runtime)

Parent	Property	Type	Required	Default
`runtime`	`cache`	objek	❌ Tidak	-

Konfigurasi Cache Global.

Properti berlapis

Parent	Property	Type	Required	Default
`runtime.cache`	`enabled`	boolean	❌ Tidak	False
`runtime.cache`	`ttl-seconds`	integer	❌ Tidak	5

Tip

Properti tingkat cache.ttl-seconds entitas default ke nilai global ini.

Format

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

Important

Jika global enabled adalah false, tingkat enabled entitas individu tidak masalah.

Telemetri (runtime)

Parent	Property	Type	Required	Default
`runtime`	`telemetry`	objek	❌ Tidak	-

Konfigurasi telemetri global.

Properti berlapis

Parent	Property	Type	Required	Default
`runtime.telemetry`	`log-level`	dictionary	❌ Tidak	None
`runtime.telemetry`	`application-insights`	objek	❌ Tidak	-
`runtime.telemetry`	`open-telemetry`	objek	❌ Tidak	-

Mengonfigurasi verbositas pengelogan per namespace. Ini mengikuti konvensi pengelogan .NET standar dan memungkinkan kontrol terperinci, meskipun mengasumsikan beberapa keakraban dengan internal pembuat API Data. Penyusun API Data adalah sumber terbuka: https://aka.ms/dab

Format

{
  "runtime": {
    "telemetry": {
      "log-level": {
        "namespace": "log-level",
        "namespace": "log-level"
      }
    }
  }
}

Tip

log-level dapat dimuat ulang dalam pengembangan dan produksi. Saat ini adalah satu-satunya properti yang mendukung hot reload dalam produksi.

Example

{
  "runtime": {
    "telemetry": {
      "log-level": {
        "Azure.DataApiBuilder.Core.Configurations.RuntimeConfigValidator": "debug",
        "Azure.DataApiBuilder.Core": "information",
        "default": "warning"
      }
    }
  }
}

Application Insights (telemetri)

Parent	Property	Type	Required	Default
`runtime.telemetry`	`application-insights`	objek	❌ Tidak	-

Mengonfigurasi pengelogan ke Application Insights.

Properti berlapis

Parent	Property	Type	Required	Default
`runtime.telemetry.application-insights`	`enabled`	boolean	❌ Tidak	False
`runtime.telemetry.application-insights`	`connection-string`	string	✔️ Ya	None

Format

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

OpenTelemetry (telemetri)

Parent	Property	Type	Required	Default
`runtime.telemetry`	`open-telemetry`	objek	❌ Tidak	-

Mengonfigurasi pengelogan ke Open Telemetry.

Properti berlapis

Parent	Property	Type	Required	Default
`runtime.telemetry.open-telemetry`	`enabled`	boolean	❌ Tidak	true
`runtime.telemetry.open-telemetry`	`endpoint`	string	✔️ Ya	None
`runtime.telemetry.open-telemetry`	`headers`	string	❌ Tidak	None
`runtime.telemetry.open-telemetry`	`service-name`	string	❌ Tidak	"dab"
`runtime.telemetry.open-telemetry`	`exporter-protocol`	enum (`grpc` \| `httpprotobuf`)	❌ Tidak	`grpc`

Beberapa header dipisahkan , (koma).

Format

{
  "runtime": {
    "telemetry": {
      "open-telemetry": {
        "enabled": <true> (default) | <false>,
        "endpoint": <string>,
        "headers": <string>,
        "service-name": <string> (default: "dab"),
        "exporter-protocol": <"grpc" (default) | "httpprotobuf">
      }
    }
  }
}

Example

{
  "runtime": {
    "telemetry": {
      "open-telemetry": {
        "enabled": true,
        // a gRPC endpoint example
        "endpoint": "http://localhost:4317",
        // an HTTP/protobuf endpoint example
        "endpoint": "http://localhost:4318/v1/metrics",
        "headers": "api-key=key,other-config-value=value",
        "service-name": "dab",
      }
    }
  }
}

Pelajari selengkapnya tentang OTEL_EXPORTER_OTLP_HEADERS.

Note

gRPC (4317) lebih cepat dan mendukung streaming tetapi memerlukan lebih banyak penyiapan. HTTP/protobuf (4318) lebih sederhana dan lebih mudah di-debug tetapi kurang efisien.

Kesehatan (runtime)

Parent	Property	Type	Required	Default
`runtime`	`health`	objek	❌ Tidak	-

Konfigurasi titik akhir pemeriksaan kesehatan global (/health).

Properti berlapis

Parent	Property	Type	Required	Default	Rentang/Catatan
`runtime.health`	`enabled`	boolean	❌ Tidak	`true`
`runtime.health`	`roles`	larik string	✔️ Ya*	`null`	*Diperlukan dalam mode produksi
`runtime.health`	`cache-ttl-seconds`	integer	❌ Tidak	`5`	Min: 0
`runtime.health`	`max-query-parallelism`	integer	❌ Tidak	`4`	Min: 1, Maks: 8 (dijepit)

Perilaku dalam pengembangan vs. produksi

Condition	Perilaku Pengembangan	Perilaku Produksi
`health.enabled` = salah	`403` keadaan	`403` keadaan
`health.enabled` = benar	Tergantung pada peran	Tergantung pada peran
`roles` dihilangkan atau `null`	Kesehatan ditampilkan	`403` keadaan
peran saat ini tidak ada di `roles`	`403` keadaan	`403` keadaan
peran saat ini dalam `roles`	Kesehatan ditampilkan	Kesehatan ditampilkan
`roles` Termasuk `anonymous`	Kesehatan ditampilkan	Kesehatan ditampilkan

Format

{
  "health": {
    "enabled": <true> (default) | <false>,
    "roles": [ <string> ], // required in production
    "cache-ttl-seconds": <integer; default: 5>,
    "max-query-parallelism": <integer; default: 4>
  }
}

Note

Jika global enabled adalah false, tingkat enabled entitas individu tidak masalah.

Example

{
  "health": {
    "enabled": true,
    "roles": ["admin", "support"],
    "cache-ttl-seconds": 10,
    "max-query-parallelism": 6
  }
}

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-09-24

Bagikan melalui

Runtime

Pengaturan pagination

Pengaturan REST

Pengaturan GraphQL

Pengaturan host

Pengaturan CORS

Pengaturan autentikasi

Pengaturan cache

Pengaturan telemetri

Gambaran umum format

Mode (Runtime host)

Perilaku pengembangan

Format

Ukuran respons maksimum (Runtime host)

Format

GraphQL (runtime)

Properti berlapis

Catatan properti

Format

Contoh: beberapa mutasi

REST (runtime)

Properti berlapis

Catatan properti

Format

Contoh: request-body-strict

Sisipkan perilaku saat request-body-strict = false

Memperbarui perilaku saat request-body-strict = false

CORS (runtime host)

Properti berlapis

Format

Penyedia (Runtime host autentikasi)

Khusus anonim (penyedia autentikasi)

StaticWebApps (penyedia auth) [tidak digunakan lagi]

AppService (penyedia autentikasi)

Tentang headerAPI-ROLE X-MS

EntraId (penyedia autentikasi)

Tentang headerAPI-ROLE X-MS

Kustom (penyedia autentikasi)

Tentang headerAPI-ROLE X-MS

Simulator (penyedia autentikasi)

Tentang headerAPI-ROLE X-MS

Simulator dalam Produksi

JWT (Runtime host autentikasi)

Properti berlapis

Format

Penomoran halaman (Runtime)

Properti berlapis

Nilai yang didukung ukuran halaman maks

Nilai yang didukung ukuran halaman default

Perilaku relatif tautan berikutnya

Format

Contoh: Halaman di REST

Contoh: Penomoran halaman di GraphQL

Contoh: Mengakses max-page-size dalam Permintaan

Cache (runtime)

Properti berlapis

Format

Telemetri (runtime)

Properti berlapis

Format

Example

Application Insights (telemetri)

Properti berlapis

Format

OpenTelemetry (telemetri)

Properti berlapis

Format

Example

Kesehatan (runtime)

Properti berlapis

Perilaku dalam pengembangan vs. produksi

Format

Example

Saran dan Komentar

Sumber Daya Tambahan:

Sisipkan perilaku saat `request-body-strict = false`

Memperbarui perilaku saat `request-body-strict = false`

Contoh: Mengakses `max-page-size` dalam Permintaan