Freigeben über

Runtime

Konfigurationseinstellungen, die das Laufzeitverhalten bestimmen.

Paginierungseinstellungen

Property Default Description
runtime.pagination.max-Seitengröße Definiert maximale Datensätze pro Seite
runtime.pagination.default-page-size Legt Standarddatensätze pro Antwort fest

REST-Einstellungen

Property Default Description
runtime.rest.path "/api" Basispfad für REST-Endpunkte
runtime.rest.enabled true Ermöglicht das Aktivieren oder Deaktivieren von REST-Anforderungen für alle Entitäten.
runtime.rest.request-body-strict true Unzulässige zusätzliche Felder im Anforderungstext, wenn "true" ist

GraphQL-Einstellungen

Property Default Description
runtime.graphql.allow-introspection true Ermöglicht abfragen des zugrunde liegenden GraphQL-Schemas
runtime.graphql.path "/graphql" Basispfad für den GraphQL-Endpunkt
runtime.graphql.enabled true Ermöglicht das Aktivieren oder Deaktivieren von GraphQL-Anforderungen für alle Entitäten
runtime.graphql.depth-limit null Maximale zulässige Tiefe einer GraphQL-Abfrage
runtime.graphql.multiple-mutations.create.enabled false Ermöglicht mehrfach erstellte Mutationen für alle Entitäten.

Hosteinstellungen

Property Default Description
runtime.host.max-response-size-mb 158 Maximale Größe (MB) der Datenbankantwort, die in einem einzigen Ergebnis zulässig ist
runtime.host.mode "production" Ausführungsmodus; "production" oder "development"

CORS-Einstellungen

Property Default Description
runtime.host.cors.origins [] Zulässige CORS-Ursprünge
runtime.host.cors.allow-credentials false Legt den Wert für den Access-Control-Allow-Credentials-Header fest.

Authentifizierungseinstellungen

Property Default Description
runtime.host.authentication.provider null Authentifizierungsanbieter
runtime.host.authentication.jwt.audience null JWT-Zielgruppe
runtime.host.authentication.jwt.issuer null JWT-Aussteller

Cacheeinstellungen

Property Default Description
runtime.cache.enabled false Ermöglicht das zwischenspeichern von Antworten global
runtime.cache.ttl-seconds 5 Zeit für live (Sekunden) für den globalen Cache

Telemetrie-Einstellungen

Property Default Description
runtime.telemetry.application-insights.connection-string null Application Insights-Verbindungszeichenfolge
runtime.telemetry.application-insights.enabled false Aktiviert oder deaktiviert Die Telemetrie von Application Insights
runtime.telemetry.open-telemetry.endpoint null OpenTelemetry-Sammel-URL
runtime.telemetry.open-telemetry.headers {} OpenTelemetry-Exportheader
runtime.telemetry.open-telemetry.service-name "dab" Name des OpenTelemetry-Diensts
runtime.telemetry.open-telemetry.exporter-protocol "grpc" OpenTelemetry-Protokoll ("grpc" oder "httpprotobuf")
runtime.telemetry.open-telemetry.enabled true Aktiviert oder deaktiviert OpenTelemetry
runtime.telemetry.log-level.namespace null Außerkraftsetzung auf namespacespezifischer Protokollebene
runtime.health.enabled true Aktiviert oder deaktiviert den Integritätsprüfungsendpunkt global
runtime.health.roles null Zulässige Rollen für den umfassenden Integritätsendpunkt
runtime.health.cache-ttl-seconds 5 Zeit für den Cacheeintrag für die Integritätsprüfung (Sekunden)
runtime.health.max-Abfrage-Parallelität 4 Maximale Anzahl gleichzeitiger Integritätsprüfungsabfragen (Bereich: 1-8)

Formatübersicht

{
  "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`)
  }
}

Modus (Hostlaufzeit)

Parent Property Type Required Default
runtime host Enumeration (production | development) ❌ Nein production

Entwicklungsverhalten

  • Enabled Nitro (ehemals Banana Cake Pop) für GraphQL-Tests
  • Aktivierte Swagger-UI für REST-Tests
  • Anonyme Integritätsprüfungen aktiviert
  • Erweiterte Protokollierungsverknündlichkeit (Debug)

Format

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

Maximale Antwortgröße (Hostlaufzeit)

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

Legt die maximale Größe (in Megabyte) für ein bestimmtes Ergebnis fest. Da große Antworten das System belasten können, max-response-size-mb wird die Gesamtgröße (anders als die Zeilenanzahl) begrenzt, um eine Überladung zu verhindern, insbesondere bei großen Spalten wie Text oder JSON.

Value Result
nicht festgelegt Standard verwenden
null Standard verwenden
integer Beliebige positive 32-Bit-Ganzzahl
<= 0 Nicht unterstützt

Format

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

GraphQL (Laufzeit)

Parent Property Type Required Default
runtime graphql object ❌ Nein -

Globale GraphQL-Konfiguration.

Verschachtelte Eigenschaften

Parent Property Type Required Default
runtime.graphql enabled boolean ❌ Nein None
runtime.graphql path string ❌ Nein "/graphql"
runtime.graphql depth-limit integer ❌ Nein Keine (unbegrenzt)
runtime.graphql allow-introspection boolean ❌ Nein True
runtime.graphql multiple-mutations.create.enabled boolean ❌ Nein False

Eigenschaftsnotizen

  • Unterpfade sind für die path Eigenschaft nicht zulässig.
  • Wird verwendet depth-limit , um geschachtelte Abfragen einzuschränken.
  • Legen Sie fest allow-introspection , false dass das GraphQL-Schema ausgeblendet wird.
  • Wird verwendet multiple-mutations , um mehrere Entitäten in eine einzelne Mutation einzufügen.

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>
        }
    }
  }
}

Beispiel: Mehrere Mutationen

Configuration

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

GraphQL-Mutation

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 (Laufzeit)

Parent Property Type Required Default
runtime rest object ❌ Nein -

Globale REST-Konfiguration.

Verschachtelte Eigenschaften

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

Eigenschaftsnotizen

  • Wenn global enabled ist false, spielt die einzelne Entitätsebene enabled keine Rolle.
  • Die path Eigenschaft unterstützt keine Unterpfadwerte wie /api/data.
  • request-body-strict wurde eingeführt, um .NET POCO-Objekte zu vereinfachen.
request-body-strict Behavior
true Zusätzliche Felder im Anforderungstext verursachen eine BadRequest Ausnahme.
false Zusätzliche Felder im Anforderungstext werden ignoriert.

Format

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

Note

Beim Bereitstellen des Daten-API-Generators mit statischen Web Apps (Vorschau) fügt der Azure-Dienst automatisch einen anderen Unterpfad /data-api zur URL ein. Dieses Verhalten stellt die Kompatibilität mit vorhandenen Statischen Web App-Features sicher. Der resultierende Endpunkt wäre /data-api/api/<entity>. Diese Notiz ist nur für statische Web-Apps relevant.

Beispiel: anforderungstext-strict

  • Spalten mit einem default() Wert werden nur ignoriert INSERT , wenn ihr Wert in der Nutzlast ist null. INSERT Daher können Vorgänge in default() Spalten, wenn request-body-strict dies der Wert isttrue, nicht zu expliziten null Werten führen. Dazu ist ein UPDATE Vorgang erforderlich.
  • Spalten mit einer default() werden unabhängig vom Nutzlastwert nicht ignoriert UPDATE .
  • Berechnete Spalten werden immer ignoriert.
  • Automatisch generierte Spalten werden immer ignoriert.

Beispieltabelle

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
);

Anforderungsnutzlast

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

Einfügeverhalten bei 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.

Antwortnutzlast

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

Verhalten aktualisieren, wenn request-body-strict = false

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

Antwortnutzlast

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

CORS (Hostlaufzeit)

Parent Property Type Required Default
runtime.host cors object ❌ Nein -

Globale CORS-Konfiguration.

Tip

CORS steht für "Cross-Origin Resource Sharing". Es handelt sich um ein Browsersicherheitsfeature, das steuert, ob Webseiten Anforderungen an eine andere Domäne stellen können als die, die sie bereitgestellt hat.

Verschachtelte Eigenschaften

Parent Property Type Required Default
runtime.host.cors allow-credentials boolean ❌ Nein False
runtime.host.cors origins Zeichenfolgenarray ❌ Nein None

Note

Die allow-credentials Eigenschaft legt den Access-Control-Allow-Credentials CORS-Header fest.

Format

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

Note

Der Wildcard * ist als Wert gültig für origins.

Anbieter (Authentifizierungshostlaufzeit)

Parent Property Type Required Default
runtime.host.authentication provider Enumeration (AppService | EntraId | Custom | Simulator) ❌ Nein AppService

Definiert die Vom Daten-API-Generator verwendete Authentifizierungsmethode.

Nur anonym (Authentifizierungsanbieter)

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

Wenn der gesamte authentication Abschnitt aus der dab-config.json-Datei weggelassen wird, wird kein Authentifizierungsanbieter verwendet. In diesem Fall wird der Daten-API-Generator im Modus "Keine Authentifizierung" ausgeführt. In diesem Modus sucht DAB keine Token oder Authorization Header. Der X-MS-API-ROLE Header wird auch in dieser Konfiguration ignoriert.

[! Hinweis] Jede Anforderung, die in das Modul kommt, wird automatisch und sofort der Systemrolle anonymouszugewiesen. Die Zugriffssteuerung wird dann ausschließlich von den Berechtigungen behandelt, die Sie für jede Entität definieren.

Ein Beispiel für Entitätsberechtigungen.

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

Da in diesem Beispiel kein authentication Anbieter konfiguriert ist, werden alle eingehenden Anforderungen automatisch als von einem anonymous Benutzer betrachtet. Das permissions Array für die Book Entität gewährt der anonymous Rolle explizit die Möglichkeit, Vorgänge auszuführen read . Jeder Versuch, andere Aktionen (z create. B. , update, delete) auszuführen oder auf andere Entitäten zuzugreifen, die nicht für anonymous den Zugriff konfiguriert sind, wird verweigert.

StaticWebApps (Authentifizierungsanbieter) [veraltet]

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

Dieser Anbieter ist veraltet, da das Vorschaufeature Data Connections für statische Web Apps im November 2025 eingestellt wurde. Während es funktionsfähig bleibt, wurde es für eine ältere Implementierung der Authentifizierung in Azure Static Web Apps entwickelt. Entwickler sollten zum AppService Anbieter migrieren, um eine bessere langfristige Unterstützung und Konsistenz mit der umfassenderen "Easy Auth"-Plattform von Azure zu gewährleisten.

[! Hinweis] Die Migration ist nicht so einfach wie das Ändern des Anbieternamens in der Konfigurationsdatei. Die StaticWebApps Anbieter AppService erwarten unterschiedliche JSON-Strukturen innerhalb des Headers für die x-ms-client-principal Verarbeitung von Rollen.

AppService (Authentifizierungsanbieter)

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

Dieser Anbieter richtet sich an Anwendungen, die auf Azure App Service gehostet werden, z. B. Azure-Container-Apps. Die Azure-Hostingumgebung verarbeitet die Authentifizierung und übergibt dann die Identitätsinformationen des Benutzers über Anforderungsheader an die Anwendung. Es ist für Entwickler vorgesehen, die eine einfache, sofort einsatzbereite Authentifizierungslösung benötigen, die von der Azure-Plattform verwaltet wird.

Dieser Anbieter verwendet kein JWT-Token aus dem Authorization Header. Sie basiert auf einem speziellen Header, X-MS-CLIENT-PRINCIPALder von der App Service-Plattform eingefügt wird. Dieser Header enthält ein base64-codiertes JSON-Objekt mit den Identitätsdetails des Benutzers.

Anonym: Wenn der AppService Anbieter konfiguriert ist, aber eine Anforderung ohne den X-MS-CLIENT-PRINCIPAL Header eingeht, wird die Anforderung der Systemrolle zugewiesen anonymous.

Der decodierte JSON-Code aus dem Header sieht in der X-MS-CLIENT-PRINCIPAL Regel wie folgt aus:

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

Die Rollen sind im claims Array enthalten.

Informationen zum X-MS-API-ROLE-Header

  • Rolle und Verhalten: Der X-MS-API-ROLE Header wird verwendet, um anzugeben, welche Rolle der Benutzer für die aktuelle Anforderung annehmen möchte. Der Wert dieses Headers muss mit einem der Rollenwerte übereinstimmen, die claims im Array des X-MS-CLIENT-PRINCIPAL Objekts gefunden wurden.
  • Ist dies erforderlich?: Nein. Wenn der X-MS-API-ROLE Header nicht vorhanden ist, wird die Anforderung im Kontext der authenticated Systemrolle verarbeitet. Dies bedeutet, dass der Benutzer als angemeldet erkannt wird, aber nicht als bestimmte anwendungsdefinierte Rolle aus dem Token.
  • Verhalten bei Übereinstimmung: Wenn der X-MS-API-ROLE Header bereitgestellt wird und sein Wert einer Rolle im Clientprinzipal claimsentspricht, geht der Benutzer von dieser Rolle für die Anforderung aus.
  • Verhalten bei Nichtübereinstimmung: Wenn der X-MS-API-ROLE Header bereitgestellt wird, der Wert aber keiner Rolle im Clientprinzipal entspricht, wird die Anforderung mit einem 403 Forbidden Statuscode abgelehnt. Dadurch wird sichergestellt, dass ein Benutzer keine Rolle beanspruchen kann, denen er nicht zugewiesen wurde.

EntraId (Authentifizierungsanbieter)

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

Dieser Anbieter sichert Endpunkte mit Benutzer- und Anwendungsidentitäten in Microsoft Entra. Es ist ideal für jeden Dienst, bei dem Benutzer oder andere Dienste sicheren Zugriff innerhalb des Entra-Mandanten benötigen.

[! HINWEIS] Der EntraId Anbieter wurde zuvor benannt AzureAd. Der alte Name funktioniert weiterhin, aber Entwickler werden ermutigt, ihre Konfigurationen von AzureAd zu migrieren EntraId.

Dieser Anbieter erwartet ein standardmäßiges JWT Bearer-Token in der Authorization Kopfzeile, die von Microsoft Entra ausgestellt wurde. Das Token muss für die spezifische Anwendung (unter Verwendung des audience Anspruchs) konfiguriert werden. Die Rollen für den Benutzer- oder Dienstprinzipal werden in einem Anspruch innerhalb des Tokens erwartet. Der Code sucht standardmäßig nach einem roles Anspruch.

Anonym: Wenn der EntraId Anbieter konfiguriert ist, aber eine Anforderung ohne den Authorization Header eingeht, wird die Anforderung der Systemrolle zugewiesen anonymous.

Eine decodierte JWT-Nutzlast könnte wie folgt aussehen:

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

Informationen zum X-MS-API-ROLE-Header

  • Rolle und Verhalten: Der X-MS-API-ROLE Header wird verwendet, um eine Rolle anzugeben, die der Benutzer für die Anforderung annehmen möchte. Der Wert dieses Headers muss mit einem der Rollenwerte übereinstimmen, die roles im Anspruch des JWT-Tokens gefunden wurden.
  • Ist dies erforderlich?: Nein. Wenn der X-MS-API-ROLE Header nicht vorhanden ist, wird die Anforderung im Kontext der authenticated Systemrolle verarbeitet. Dies bedeutet, dass der Benutzer als angemeldet erkannt wird, aber nicht als bestimmte anwendungsdefinierte Rolle aus dem Token.
  • Verhalten bei Übereinstimmung: Wenn der X-MS-API-ROLE Header bereitgestellt wird und er einer Rolle im roles Anspruch entspricht, wird der Kontext des Benutzers auf diese Rolle festgelegt.
  • Verhalten bei Nichtübereinstimmung: Wenn der X-MS-API-ROLE Header bereitgestellt wird, der Wert aber keiner Rolle im roles Anspruch entspricht, wird die Anforderung mit einem 403 Forbidden Statuscode abgelehnt. Dadurch wird sichergestellt, dass ein Benutzer keine Rolle beanspruchen kann, denen er nicht zugewiesen wurde.

Benutzerdefiniert (Authentifizierungsanbieter)

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

Dieser Anbieter richtet sich an Entwickler, die den Daten-API-Generator in einen Drittanbieteridentitätsanbieter (z. B. Auth0, Okta oder einen benutzerdefinierten Identitätsserver) integrieren möchten, der JWTs ausgibt. Sie bietet die Flexibilität, die erwarteten audience und issuer die Token zu konfigurieren.

Der Custom Anbieter erwartet ein standardmäßiges JWT Bearer-Token im Authorization Header. Der Hauptunterschied zum EntraId Anbieter besteht darin, dass Sie die gültige issuer und audience in der Konfigurationsdatei des Daten-API-Generators konfigurieren. Der Anbieter überprüft das Token, indem überprüft wird, ob die vertrauenswürdige Autorität es ausgestellt hat. Die Rollen des Benutzers werden in einem roles Anspruch innerhalb der JWT-Nutzlast erwartet.

[! HINWEIS] In einigen Fällen müssen Entwickler je nach Identitätsanbieter des Drittanbieters die Struktur ihres JWT entsprechend der struktur des Daten-API-Generators (siehe unten) mit der struktur übereinstimmen, die vom Daten-API-Generator erwartet wird.

Anonym: Wenn der Custom Anbieter konfiguriert ist, aber eine Anforderung ohne den Authorization Header eingeht, wird die Anforderung der Systemrolle zugewiesen anonymous.

Eine decodierte JWT-Nutzlast für einen custom Anbieter könnte wie folgt aussehen:

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

Informationen zum X-MS-API-ROLE-Header

  • Rolle und Verhalten: Der X-MS-API-ROLE Header funktioniert genau wie bei dem EntraId Anbieter. Er ermöglicht es dem Benutzer, eine seiner zugewiesenen Rollen auszuwählen. Der Wert dieses Headers muss mit einer der Rollen aus dem roles Anspruch im benutzerdefinierten JWT-Token übereinstimmen.
  • Ist dies erforderlich?: Nein. Wenn der X-MS-API-ROLE Header nicht vorhanden ist, wird der Benutzer in der authenticated Systemrolle behandelt.
  • Verhalten bei Übereinstimmung: Wenn der Wert des X-MS-API-ROLE Headers einer Rolle im JWT-Anspruch roles entspricht, wird der Kontext des Benutzers für Autorisierungszwecke auf diese Rolle festgelegt.
  • Verhalten bei Nichtübereinstimmung: Wenn der Wert des X-MS-API-ROLE Headers keiner Rolle im roles Anspruch entspricht, wird die Anforderung mit einem 403 Forbidden Statuscode abgelehnt. Dadurch wird sichergestellt, dass ein Benutzer keine Rolle beanspruchen kann, denen er nicht zugewiesen wurde.

Simulator (Authentifizierungsanbieter)

Dieser Anbieter ist so konzipiert, dass Entwickler ihre Konfiguration, insbesondere authorization Richtlinien, einfach testen können, ohne einen vollständigen Authentifizierungsanbieter wie Entra Identity oder EasyAuth einrichten zu müssen. Er simuliert einen authenticated Benutzer.

Der Simulator Anbieter verwendet keine JWT-Token. Die Authentifizierung wird simuliert. Bei Verwendung dieses Anbieters werden alle Anforderungen behandelt, als ob sie von einem authentifizierten Benutzer stammen.

Informationen zum X-MS-API-ROLE-Header

  • Rolle und Verhalten: Die X-MS-API-ROLE Kopfzeile ist die einzige Möglichkeit, eine Rolle bei Verwendung der Simulator. Da es kein Token mit einer Liste von Rollen gibt, vertraut das System implizit der in diesem Header gesendeten Rolle.
  • Ist dies erforderlich?: Nein.
  • Verhalten bei Abwesenheit: Wenn der X-MS-API-ROLE Header nicht vorhanden ist, wird die Anforderung im Kontext der authenticated Systemrolle verarbeitet.
  • Verhalten bei Anwesenheit: Wenn der X-MS-API-ROLE Header vorhanden ist, wird die Anforderung im Kontext der rolle verarbeitet, die im Wert des Headers angegeben ist. Es gibt keine Überprüfung für eine Anspruchsliste, sodass der Entwickler jede Rolle simulieren kann, die sie zum Testen ihrer Richtlinien benötigen.

Simulator in Produktion

Wenn der authentication.provider Daten-API-Generator während des Simulator Vorgangs auf "runtime.host.modefestgelegt" festgelegt productionist, kann der Daten-API-Generator nicht gestartet werden.

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

JWT (Authentifizierungshostlaufzeit)

Parent Property Type Required Default
runtime.host.authentication jwt object ❌ Nein -

Konfiguration des globalen JSON-Webtokens (JWT).

Diagramm von JSON-Webtoken, die im Daten-API-Generator unterstützt werden.

Verschachtelte Eigenschaften

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

Format

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

Paginierung (Runtime)

Parent Property Type Required Default
runtime pagination object ❌ Nein -

Globale Paginierungsgrenzwerte für REST- und GraphQL-Endpunkte.

Verschachtelte Eigenschaften

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

Unterstützte Max-Page-Size-Werte

Value Result
integer Jede positive 32-Bit-Ganzzahl wird unterstützt.
0 Nicht unterstützt.
-1 Standardmäßig wird der maximal unterstützte Wert verwendet.
< -1 Nicht unterstützt.

Unterstützte Standardseitenwerte

Value Result
integer Eine positive ganze Zahl kleiner als die aktuelle max-page-size.
0 Nicht unterstützt.
-1 Standardmäßig wird die aktuelle max-page-size Einstellung festgelegt.
< -1 Nicht unterstützt.

Ist next-link-relative dies trueder Grund, verwenden Paginierungswerte nextLink relative URLs anstelle absoluter URLs.

Value Example
false (Standardwert) "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

Wenn der Wert größer als max-page-sizeist, werden die Ergebnisse auf max-page-size.

Beispiel: Paging in REST

Request

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

Antwortnutzlast

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

Nächste Seite anfordern

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

Beispiel: Paging in GraphQL

Anforderungsnutzlast (Abfrage)

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

Antwortnutzlast

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

Nächste Seite anfordern

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

Beispiel: Zugreifen auf max-page-size Anforderungen

Verwenden Sie den max-page-size Wert durch Festlegen $limit (REST) oder first (GraphQL) auf -1.

REST

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

GraphQL

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

Cache (Laufzeit)

Parent Property Type Required Default
runtime cache object ❌ Nein -

Globale Cachekonfiguration.

Verschachtelte Eigenschaften

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

Tip

Die Eigenschaft auf Entitätsebene cache.ttl-seconds wird standardmäßig auf diesen globalen Wert festgelegt.

Format

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

Important

Wenn global enabled ist false, spielt die einzelne Entitätsebene enabled keine Rolle.

Telemetrie (Laufzeit)

Parent Property Type Required Default
runtime telemetry object ❌ Nein -

Globale Telemetriekonfiguration.

Verschachtelte Eigenschaften

Parent Property Type Required Default
runtime.telemetry log-level dictionary ❌ Nein None
runtime.telemetry application-insights object ❌ Nein -
runtime.telemetry open-telemetry object ❌ Nein -

Konfiguriert die Ausführlichkeit der Protokollierung pro Namespace. Dies folgt standardmäßigen .NET-Protokollierungskonventionen und ermöglicht eine granulare Steuerung, obwohl davon ausgegangen wird, dass sie mit internen Daten-API-Generatoren vertraut ist. Der Daten-API-Generator ist Open Source: https://aka.ms/dab

Format

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

Tip

log-level kann sowohl in der Entwicklung als auch in der Produktion heiß neu geladen werden. Es ist derzeit die einzige Eigenschaft, die hot reload in der Produktion unterstützt.

Example

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

Application Insights (Telemetrie)

Parent Property Type Required Default
runtime.telemetry application-insights object ❌ Nein -

Konfiguriert die Protokollierung für Application Insights.

Verschachtelte Eigenschaften

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

Format

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

OpenTelemetry (Telemetrie)

Parent Property Type Required Default
runtime.telemetry open-telemetry object ❌ Nein -

Konfiguriert die Protokollierung für "Telemetrie öffnen".

Verschachtelte Eigenschaften

Parent Property Type Required Default
runtime.telemetry.open-telemetry enabled boolean ❌ Nein true
runtime.telemetry.open-telemetry endpoint string ✔️ Ja None
runtime.telemetry.open-telemetry headers string ❌ Nein None
runtime.telemetry.open-telemetry service-name string ❌ Nein "dab"
runtime.telemetry.open-telemetry exporter-protocol Enumeration (grpc | httpprotobuf) ❌ Nein grpc

Mehrere Kopfzeilen sind , (Komma) getrennt.

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",
      }
    }
  }
}

Erfahren Sie mehr über OTEL_EXPORTER_OTLP_HEADERS.

Note

gRPC (4317) ist schneller und unterstützt Streaming, erfordert jedoch mehr Setup. HTTP/protobuf (4318) ist einfacher und einfacher zu debuggen, aber weniger effizient.

Integrität (Laufzeit)

Parent Property Type Required Default
runtime health object ❌ Nein -

Konfiguration des globalen Integritätsprüfungsendpunkts (/health)

Verschachtelte Eigenschaften

Parent Property Type Required Default Bereich/Notizen
runtime.health enabled boolean ❌ Nein true
runtime.health roles Zeichenfolgenarray ✔️ Ja* null *Erforderlich im Produktionsmodus
runtime.health cache-ttl-seconds integer ❌ Nein 5 Min: 0
runtime.health max-query-parallelism integer ❌ Nein 4 Min: 1, Max: 8 (klemmt)

Verhalten bei der Entwicklung im Vergleich zur Produktion

Condition Entwicklungsverhalten Produktionsverhalten
health.enabled = falsch 403 Status 403 Status
health.enabled = wahr Hängt von der Rolle ab Hängt von der Rolle ab
roles nicht angegeben oder null Angezeigte Integrität 403 Status
Aktuelle Rolle nicht in roles 403 Status 403 Status
aktuelle Rolle in roles Angezeigte Integrität Angezeigte Integrität
roles Enthält anonymous Angezeigte Integrität Angezeigte Integrität

Format

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

Note

Wenn global enabled ist false, spielt die einzelne Entitätsebene enabled keine Rolle.

Example

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