Runtime

Konfigurationsinställningar som avgör körningsbeteende.

Sidnumreringsinställningar

REST-inställningar

GraphQL-inställningar

Värdinställningar

CORS-inställningar

Autentiseringsinställningar

Cacheinställningar

Inställningar för telemetri

Formatöversikt

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

Läge (värdkörning)

Utvecklingsbeteende

• Aktiverad Nitro (tidigare Banana Cake Pop) för GraphQL-testning
• Aktiverat Swagger-användargränssnitt för REST-testning
• Aktiverade anonyma hälsokontroller
• Ökad loggningsveroalitet (felsökning)

Format

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

Maximal svarsstorlek (värdkörning)

Anger den maximala storleken (i megabyte) för ett givet resultat. Eftersom stora svar kan belasta systemet begränsar max-response-size-mb du den totala storleken (skiljer sig från radantal) för att förhindra överbelastning, vilket är särskilt med stora kolumner som text eller JSON.

Format

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

GraphQL (körning)

Global GraphQL-konfiguration.

Kapslade egenskaper

Egenskapsanteckningar

• Undersökvägar tillåts inte för egenskapen path .
• Använd depth-limit för att begränsa kapslade frågor.
• Ange allow-introspection till false för att dölja GraphQL-schemat.
• Använd multiple-mutations för att infoga flera entiteter i en enda mutation.

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

Exempel: flera mutationer

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

Global REST-konfiguration.

Kapslade egenskaper

Egenskapsanteckningar

• Om global enabled är falsespelar den enskilda entitetsnivån enabled ingen roll.
• Egenskapen path stöder inte undersökvägsvärden som /api/data.
• request-body-strict introducerades för att förenkla .NET POCO-objekt.

Format

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

Exempel: request-body-strict

• Kolumner med ett default() värde ignoreras endast när INSERT deras värde i nyttolasten är null. Därför INSERT kan åtgärder i default() kolumner, när request-body-strict är true, inte resultera i explicita null värden. För att åstadkomma detta krävs en UPDATE åtgärd.
• Kolumner med en default() ignoreras inte under UPDATE oavsett nyttolastvärde.
• Beräknade kolumner ignoreras alltid.
• Autogenererade kolumner ignoreras alltid.

Exempeltabell

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

Begär nyttolast

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

Infoga beteende när 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.

Svarslast

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

Uppdatera beteende när request-body-strict = false

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

Svarslast

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

CORS (värdkörning)

Global CORS-konfiguration.

Kapslade egenskaper

Format

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

Provider (Autentiseringsvärdkörning)

Definierar den autentiseringsmetod som används av data-API-byggaren.

Endast anonym (autentiseringsprovider)

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

När hela authentication avsnittet utelämnas från filen dab-config.json används ingen autentiseringsprovider. I det här fallet fungerar Data API Builder i läget "no-auth". I det här läget letar DAB inte efter några token eller Authorization rubriker. Huvudet X-MS-API-ROLE ignoreras också i den här konfigurationen.

[! Obs! Varje begäran som kommer in i motorn tilldelas automatiskt och tilldelas omedelbart systemrollen anonymous. Åtkomstkontroll hanteras sedan exklusivt av de behörigheter som du definierar för varje entitet.

Ett exempel på entitetsbehörigheter.

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

I det här exemplet, eftersom ingen authentication provider har konfigurerats, anses alla inkommande begäranden automatiskt vara från en anonymous användare. Matrisen permissions för entiteten Book ger anonymous uttryckligen rollen möjlighet att utföra read åtgärder. Alla försök att utföra andra åtgärder (till exempel , update, delete) eller åtkomst till andra entiteter som createinte har konfigurerats för anonymous åtkomst nekas.

StaticWebApps (autentiseringsprovider) [inaktuell]

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

Den här providern är inaktuell eftersom förhandsversionen Data Connections av Static Web Apps drogs tillbaka i november 2025. Även om den fortfarande fungerar har den utformats för en äldre implementering av autentisering i Azure Static Web Apps. Utvecklare bör migrera till providern AppService för bättre långsiktig support och konsekvens med Azures bredare "Easy Auth"-plattform.

[! Obs! Migrering är inte lika enkelt som att ändra providernamnet i konfigurationsfilen. Leverantörerna StaticWebApps och AppService förväntar sig olika JSON-strukturer i x-ms-client-principal huvudet för bearbetning av roller.

AppService (autentiseringsprovider)

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

Den här providern är avsedd för program som finns i Azure App Service, till exempel Azure Container Apps. Azure-värdmiljön hanterar autentisering och skickar sedan användarens identitetsinformation till programmet via begärandehuvuden. Den är avsedd för utvecklare som vill ha en enkel, out-of-the-box-autentiseringslösning som hanteras av Azure-plattformen.

Den här providern använder inte en JWT-token från Authorization huvudet. Den förlitar sig på en särskild rubrik, X-MS-CLIENT-PRINCIPAL, som matas in av App Service-plattformen. Det här huvudet innehåller ett base64-kodat JSON-objekt med användarens identitetsinformation.

Anonym: Om providern AppService är konfigurerad men en begäran kommer utan X-MS-CLIENT-PRINCIPAL huvudet tilldelas begäran till systemrollen anonymous.

Den avkodade JSON:en X-MS-CLIENT-PRINCIPAL från rubriken ser vanligtvis ut så här:

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

Rollerna finns i matrisen claims .

Om rubriken X-MS-API-ROLE

• Roll och beteende: Rubriken X-MS-API-ROLE används för att ange vilken roll användaren vill ta för den aktuella begäran. Värdet för det här huvudet måste matcha ett av rollvärdena som finns i claims objektets X-MS-CLIENT-PRINCIPAL matris.
• Krävs det?: Nej. X-MS-API-ROLE Om huvudet saknas bearbetas begäran i kontexten för systemrollenauthenticated. Det innebär att användaren identifieras som inloggad, men inte som någon specifik programdefinierad roll från token.
• Beteende vid matchning: Om X-MS-API-ROLE huvudet anges och dess värde matchar en roll i klientens claimshuvudnamn, antar användaren den rollen för begäran.
• Beteende vid matchningsfel: Om X-MS-API-ROLE huvudet anges men värdet inte matchar någon roll i klientobjektet avvisas begäran med en 403 Forbidden statuskod. Detta säkerställer att en användare inte kan göra anspråk på en roll som de inte har tilldelats.

EntraId (autentiseringsprovider)

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

Den här providern skyddar slutpunkter med användar- och programidentiteter i Microsoft Entra. Det är idealiskt för alla tjänster där användare eller andra tjänster behöver säker åtkomst i Entra-klientorganisationen.

[! OBS! Providern EntraId hette AzureAdtidigare . Det gamla namnet fungerar fortfarande, men utvecklare uppmanas att migrera sina konfigurationer från AzureAd till EntraId.

Den här providern förväntar sig en JWT Bearer-standardtoken i Authorization rubriken som utfärdats av Microsoft Entra. Token måste konfigureras för det specifika programmet (med anspråket audience ). Rollerna för användaren eller tjänstens huvudnamn förväntas finnas i ett anspråk i token. Koden söker efter ett roles anspråk som standard.

Anonym: Om providern EntraId är konfigurerad men en begäran kommer utan Authorization huvudet tilldelas begäran till systemrollen anonymous.

En avkodad JWT-nyttolast kan se ut så här:

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

Om rubriken X-MS-API-ROLE

• Roll och beteende: Rubriken X-MS-API-ROLE används för att ange en roll som användaren vill anta för begäran. Värdet för det här huvudet måste matcha ett av rollvärdena som finns i anspråket roles för JWT-token.
• Krävs det?: Nej. X-MS-API-ROLE Om huvudet saknas bearbetas begäran i kontexten för systemrollenauthenticated. Det innebär att användaren identifieras som inloggad, men inte som någon specifik programdefinierad roll från token.
• Beteende vid matchning: Om X-MS-API-ROLE rubriken tillhandahålls och den matchar en roll i anspråket roles är användarens kontext inställd på den rollen.
• Beteende vid matchningsfel: Om X-MS-API-ROLE rubriken anges men dess värde inte matchar någon roll i anspråket roles avvisas begäran med en 403 Forbidden statuskod. Detta säkerställer att en användare inte kan göra anspråk på en roll som de inte har tilldelats.

Anpassad (autentiseringsprovider)

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

Den här providern är avsedd för utvecklare som vill integrera Data API Builder med en identitetsprovider från tredje part (till exempel Auth0, Okta eller en anpassad identitetsserver) som utfärdar JWTs. Det ger flexibiliteten att konfigurera de förväntade audience token och issuer token.

Providern Custom förväntar sig en JWT Bearer-standardtoken i Authorization rubriken. Den viktigaste skillnaden från providern EntraId är att du konfigurerar den giltiga issuer och audience i data-API-byggarens konfigurationsfil. Providern validerar token genom att kontrollera att den betrodda utfärdaren har utfärdat den. Användarens roller förväntas finnas i ett roles anspråk inom JWT-nyttolasten.

[! OBS! I vissa fall måste utvecklare, beroende på identitetsprovidern från tredje part, tvinga strukturen för sin JWT att matcha den struktur som förväntas av Data API-byggare (visas nedan).

Anonym: Om providern Custom är konfigurerad men en begäran kommer utan Authorization huvudet tilldelas begäran till systemrollen anonymous.

En avkodad JWT-nyttolast för en custom provider kan se ut så här:

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

Om rubriken X-MS-API-ROLE

• Roll och beteende: Rubriken X-MS-API-ROLE fungerar precis som med providern EntraId . Det gör att användaren kan välja en av sina tilldelade roller. Värdet för den här rubriken måste matcha en av rollerna från anspråket roles i den anpassade JWT-token.
• Krävs det?: Nej. X-MS-API-ROLE Om rubriken saknas behandlas användaren som i systemrollenauthenticated.
• Beteende vid matchning: Om X-MS-API-ROLE huvudets värde matchar en roll i JWT-anspråket roles anges användarens kontext till den rollen i auktoriseringssyfte.
• Beteende vid matchningsfel: Om X-MS-API-ROLE huvudets värde inte matchar någon roll i anspråket roles avvisas begäran med en 403 Forbidden statuskod. Detta säkerställer att en användare inte kan göra anspråk på en roll som de inte har tilldelats.

Simulator (autentiseringsprovider)

Den här providern är utformad för att göra det enkelt för utvecklare att testa sin konfiguration, särskilt authorization principer, utan att behöva konfigurera en fullständig autentiseringsprovider som Entra Identity eller EasyAuth. Den simulerar en authenticated användare.

Providern Simulator använder inte JWT-token. Autentisering simuleras. När du använder den här providern behandlas alla begäranden som om de kommer från en autentiserad användare.

Om rubriken X-MS-API-ROLE

• Roll och beteende: Rubriken X-MS-API-ROLE är det enda sättet att ange en roll när du använder Simulator. Eftersom det inte finns någon token med en lista över roller litar systemet implicit på rollen som skickas i det här huvudet.
• Krävs det?: Nej.
• Beteende vid frånvaro: Om X-MS-API-ROLE huvudet saknas bearbetas begäran i kontexten för systemrollen authenticated .
• Beteende vid närvaro: Om X-MS-API-ROLE rubriken finns bearbetas begäran i kontexten för den roll som anges i huvudets värde. Det finns ingen validering mot en anspråkslista, så utvecklaren kan simulera vilken roll de behöver för att testa sina principer.

Simulator i produktion

authentication.provider Om är inställt på Simulatorruntime.host.mode medan är production, kommer Data API Builder inte att starta.

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

JWT (autentiseringsvärdkörning)

Global JSON-webbtokenkonfiguration (JWT).

Kapslade egenskaper

Format

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

Sidnumrering (Runtime)

Globala sidnumreringsgränser för REST- och GraphQL-slutpunkter.

Kapslade egenskaper

Värden med maximal sidstorlek som stöds

Standardvärden för sidstorlek som stöds

Format

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

Exempel: Växling i REST

Request

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

Svarslast

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

Begär nästa sida

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

Exempel: Växling i GraphQL

Begär nyttolast (fråga)

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

Svarslast

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

Begär nästa sida

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

Exempel: Åtkomst i max-page-size begäranden

max-page-size Använd värdet genom att ange $limit (REST) eller first (GraphQL) till -1.

REST

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

GraphQL

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

Cache (körning)

Global cachekonfiguration.

Kapslade egenskaper

Format

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

Telemetri (körning)

Global telemetrikonfiguration.

Kapslade egenskaper

Konfigurerar loggning av verbositet per namnområde. Detta följer standardkonventionerna för .NET-loggning och tillåter detaljerad kontroll, även om det förutsätter viss förtrogenhet med interna Data API-byggare. Data-API-byggare är öppen källkod: https://aka.ms/dab

Format

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

Example

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

Application Insights (telemetri)

Konfigurerar loggning till Application Insights.

Kapslade egenskaper

Format

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

OpenTelemetry (telemetri)

Konfigurerar loggning till Öppna telemetri.

Kapslade egenskaper

Flera rubriker är , avgränsade (kommatecken).

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

Läs mer om OTEL_EXPORTER_OTLP_HEADERS.

Hälsa (körning)

Konfiguration av slutpunkt för global hälsokontroll (/health).

Kapslade egenskaper

Beteende i utveckling jämfört med produktion

Format

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

Example

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