Runtime

Configuratie-instellingen die het runtimegedrag bepalen.

Instellingen voor paginering

REST-instellingen

GraphQL-instellingen

Hostinstellingen

CORS-instellingen

Verificatie-instellingen

Cache-instellingen

Compressie-instellingen

Telemetrie-instellingen

MCP-instellingen

Overzicht van opmaak

{
  "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: "Unauthenticated"),
        "jwt": {
          "audience": "<string>",
          "issuer": "<string>"
        }
      }
    }
  },
    "compression": {
      "level": <"optimal"> (default) | <"fastest"> | <"none">
    },
    "cache": {
      "enabled": <true>|<false> (default: `false`),
      "ttl-seconds": <integer> (default: `5`),
      "level-2": {
        "enabled": <true>|<false> (default: `false`),
        "provider": <"redis">,
        "connection-string": <string>,
        "partition": <string>
      }
    },
    "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`)
      },
      "azure-log-analytics": {
        "enabled": <true>|<false> (default: `false`),
        "dab-identifier": <string> (default: "DabLogs"),
        "flush-interval-seconds": <integer> (default: `5`),
        "auth": {
          "custom-table-name": <string>,
          "dcr-immutable-id": <string>,
          "dce-endpoint": <string>
        }
      },
      "file": {
        "enabled": <true>|<false> (default: `false`),
        "path": <string> (default: "/logs/dab-log.txt"),
        "rolling-interval": <string> (default: "Day"),
        "retained-file-count-limit": <integer> (default: `1`),
        "file-size-limit-bytes": <integer> (default: `1048576`)
      },
      "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`)
    },
    "mcp": {
      "enabled": <true>|<false> (default: `true`),
      "path": <string> (default: `"/mcp"`),
      "description": <string>,
      "dml-tools": <true>|<false> | {
        "describe-entities": <true>|<false> (default: `true`),
        "create-record": <true>|<false> (default: `true`),
        "read-records": <true>|<false> (default: `true`),
        "update-record": <true>|<false> (default: `true`),
        "delete-record": <true>|<false> (default: `true`),
        "execute-entity": <true>|<false> (default: `true`),
        "aggregate-records": <true>|<false> | {
          "enabled": <true>|<false> (default: `true`),
          "query-timeout": <integer> (default: `30`)
        }
      }
    }
  }
}

Modus (hostruntime)

Ontwikkelingsgedrag

• Nitro (voorheen Banana Cake Pop) ingeschakeld voor GraphQL-tests
• Swagger UI ingeschakeld voor REST-tests
• Anonieme statuscontroles ingeschakeld
• Uitgebreide logboekregistratie (foutopsporing)

Format

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

Maximale antwoordgrootte (hostruntime)

Hiermee stelt u de maximale grootte (in megabytes) in voor elk gegeven resultaat. Omdat grote reacties het systeem kunnen belasten, max-response-size-mb wordt de totale grootte (afgezien van het aantal rijen) om overbelasting te voorkomen, wat vooral geldt voor grote kolommen, zoals tekst of JSON.

Format

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

GraphQL (runtime)

Globale GraphQL-configuratie.

Geneste eigenschappen

Opmerkingen bij eigenschappen

• Subpaden zijn niet toegestaan voor de path eigenschap.
• Gebruik depth-limit dit om geneste query's te beperken.
• Ingesteld allow-introspection om false het GraphQL-schema te verbergen.
• Gebruik multiple-mutations dit om meerdere entiteiten in één mutatie in te voegen.

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> | <false> (default)
        }
      }
    }
  }
}

Voorbeeld: meerdere mutaties

Configuration

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

GraphQL mutatie

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

Globale REST-configuratie.

Geneste eigenschappen

Opmerkingen bij eigenschappen

• Als globaal enabled het geval is false, maakt het niet uit op het niveau van enabled afzonderlijke entiteiten.
• De path eigenschap biedt geen ondersteuning voor subpadwaarden zoals /api/data.
• request-body-strict is geïntroduceerd om .NET POCO-objecten te vereenvoudigen.

Format

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

Voorbeeld: aanvraag-body-strict

• Kolommen met een default() waarde worden alleen genegeerd INSERT wanneer hun waarde in de nettolading is null. Als gevolg hiervan INSERT kunnen bewerkingen in default() kolommen, wanneer request-body-strict dat wel is true, niet resulteren in expliciete null waarden. Om dit gedrag te bereiken, is een UPDATE bewerking vereist.
• Kolommen met een default() kolom worden niet genegeerd, UPDATE ongeacht de nettoladingwaarde.
• Berekende kolommen worden altijd genegeerd.
• Automatisch gegenereerde kolommen worden altijd genegeerd.

Voorbeeldtabel

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

Nettolading aanvragen

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

Gedrag invoegen wanneer 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.

Antwoordlading

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

Gedrag bijwerken wanneer request-body-strict = false

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

Antwoordlading

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

CORS (hostruntime)

Globale CORS-configuratie.

Geneste eigenschappen

Format

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

Provider (verificatiehostruntime)

Selecteert de verificatiemethode. Elke provider valideert de identiteit anders. Zie de instructiegidsen in de volgende tabel voor stapsgewijze instellingen.

Providersamenvatting

Niet-geverifieerd (standaard)

Wanneer Unauthenticated is ingesteld (of er geen provider is opgegeven), inspecteert of valideert DAB geen JWT. Alle aanvragen worden uitgevoerd als de anonymous rol. Een front-endservice zoals Azure API Management of een toepassingsgateway kan nog steeds verificatie- of toegangsbeleid verwerken voordat aanvragen DAB bereiken, maar DAB blijft alleen autoriseren als anonymous.

{
  "host": {
    "authentication": {
      "provider": "Unauthenticated"
    }
  }
}

AppService

Vertrouwt identiteitsheaders die zijn geïnjecteerd door Azure App Service EasyAuth.

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

EntraID

Valideert JWT-tokens die zijn uitgegeven door Microsoft Entra ID.

{
  "host": {
    "authentication": {
      "provider": "EntraId",
      "jwt": {
        "audience": "<application-id>",
        "issuer": "https://login.microsoftonline.com/<tenant-id>/v2.0"
      }
    }
  }
}

Op maat gemaakt

Valideert JWT-tokens van externe id-providers.

{
  "host": {
    "authentication": {
      "provider": "Custom",
      "jwt": {
        "audience": "<api-audience>",
        "issuer": "https://<your-idp-domain>/"
      }
    }
  }
}

Simulator

Simuleert verificatie voor lokale ontwikkeling en testen.

{
  "host": {
    "authentication": {
      "provider": "Simulator"
    }
  }
}

Rolselectie

Voor alle providers behalve Simulator selecteert de X-MS-API-ROLE header welke rol moet worden gebruikt van de claims van de geverifieerde gebruiker. Als u dit weglaat, gebruikt de aanvraag de Authenticated systeemrol. Zie Het overzicht van autorisatie voor meer informatie over rolevaluatie.

JWT (Runtime van verificatiehost)

Algemene JSON-webtokenconfiguratie (JWT).

Geneste eigenschappen

* Beide audience en issuer zijn vereist wanneer het jwt object aanwezig is. Het jwt object zelf is vereist wanneer de provider , EntraIDAzureADof Custom.

Format

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

Paginering (runtime)

Globale pagineringslimieten voor REST- en GraphQL-eindpunten.

Geneste eigenschappen

Ondersteunde waarden voor maximale paginagrootte

Ondersteunde waarden voor standaardpaginagrootte

Next-link-relative behavior

Wanneer next-link-relative gebruiken truepagineringswaarden nextLink relatieve URL's in plaats van absolute URL's.

Format

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

Voorbeeld: Paging in REST

Request

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

Antwoordlading

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

Volgende pagina aanvragen

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

Voorbeeld: Paging in GraphQL

Nettolading aanvragen (query)

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

Antwoordlading

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

Volgende pagina aanvragen

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

Voorbeeld: Toegang max-page-size tot aanvragen

Gebruik de max-page-size waarde door (REST) of $limit (GraphQL) in te stellen first op -1.

REST

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

GraphQL

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

Compressie (runtime)

Configuratie van HTTP-antwoordcompressie. Wanneer deze functie is ingeschakeld, comprimeert DAB antwoordteksten om nettoladinggrootten te verminderen en de overdrachtssnelheden te verbeteren.

Geneste eigenschappen

Ondersteunde waarden voor level

HTTP-headers van client

Compressie wordt aangeroepen door de header van Accept-Encoding de client. Ondersteunde algoritmen zijn Gzip en Brotli. De level instelling configureert de compressiestrategie wanneer zowel de client als de server meerdere algoritmen ondersteunen.

Ondersteunde headers

Format

{
  "runtime": {
    "compression": {
      "level": <"optimal"> (default) | <"fastest"> | <"none">
    }
  }
}

Example

{
  "runtime": {
    "compression": {
      "level": "optimal"
    }
  }
}

Cache (runtime)

Globale cacheconfiguratie.

Geneste eigenschappen

Format

{
  "runtime": {
    "cache":  {
      "enabled": <boolean>,
      "ttl-seconds": <integer>,
      "level-2": {
        "enabled": <boolean>,
        "provider": "redis",
        "connection-string": <string>,
        "partition": <string>
      }
    }
  }
}

Wanneer level-2.enabled is true, gebruikt DAB de geconfigureerde gedistribueerde cacheprovider naast de lokale cache in het geheugen. Een entiteit die is geconfigureerd met cacheniveau L1L2 controleert eerst de lokale cache en vervolgens gedistribueerde cache voordat u naar de database gaat.

Telemetrie (runtime)

Globale telemetrieconfiguratie.

Geneste eigenschappen

Hiermee configureert u de uitgebreide logboekregistratie per naamruimte. Deze configuratie volgt standaard .NET-logboekregistratieconventies en maakt gedetailleerde controle mogelijk, hoewel er wordt uitgegaan van enige bekendheid met interne gegevens van Data API Builder. Data API Builder is open source: 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 (telemetrie)

Hiermee configureert u logboekregistratie voor Application Insights.

Geneste eigenschappen

Format

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

OpenTelemetry (telemetrie)

Hiermee configureert u logboekregistratie voor het openen van telemetrie.

Geneste eigenschappen

Meerdere kopteksten worden , gescheiden (komma's).

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

Meer informatie over OTEL_EXPORTER_OTLP_HEADERS.

Azure Log Analytics (telemetrie)

Hiermee configureert u logboekregistratie naar Azure Log Analytics via een eindpunt voor gegevensverzameling. Indien ingeschakeld, verzendt DAB telemetriegegevens in batches met een configureerbaar interval.

Geneste eigenschappen

* authis vereist wanneer enabled .true

* Vereist wanneer enabled is true.

• dab-identifier— een label dat is doorgegeven aan Log Analytics om te helpen onderscheiden welke logboeken afkomstig zijn van data-API builder.
• flush-interval-seconds— het tijdsinterval (in seconden) tussen het verzenden van batches telemetriegegevens.
• custom-table-name— de naam van de aangepaste tabel in Azure Log Analytics waar gegevens worden opgeslagen.
• dcr-immutable-id— de onveranderbare id van de regel voor gegevensverzameling die definieert hoe gegevens worden verzameld.
• dce-endpoint— de eindpunt-URL voor gegevensverzameling die wordt gebruikt voor het verzenden van telemetriegegevens.

Format

{
  "runtime": {
    "telemetry": {
      "azure-log-analytics": {
        "enabled": <true> | <false> (default),
        "dab-identifier": <string> (default: "DabLogs"),
        "flush-interval-seconds": <integer> (default: 5),
        "auth": {
          "custom-table-name": "<string>",
          "dcr-immutable-id": "<string>",
          "dce-endpoint": "<string>"
        }
      }
    }
  }
}

Example

{
  "runtime": {
    "telemetry": {
      "azure-log-analytics": {
        "enabled": true,
        "dab-identifier": "MyDabInstance",
        "flush-interval-seconds": 10,
        "auth": {
          "custom-table-name": "DabTelemetry_CL",
          "dcr-immutable-id": "dcr-abc123def456",
          "dce-endpoint": "https://my-dce.eastus-1.ingest.monitor.azure.com"
        }
      }
    }
  }
}

Bestand (telemetrie)

Hiermee configureert u het schrijven van telemetrielogboeken naar een lokaal bestand. Indien ingeschakeld, schrijft DAB gestructureerde logboekuitvoer naar het opgegeven bestandspad met configureerbare rolling intervallen en groottelimieten.

Geneste eigenschappen

* pathis vereist wanneer enabled .true

Waarden voor rollend interval

Format

{
  "runtime": {
    "telemetry": {
      "file": {
        "enabled": <true> | <false> (default),
        "path": <string> (default: "/logs/dab-log.txt"),
        "rolling-interval": <"Day"> (default) | <"Minute"> | <"Hour"> | <"Month"> | <"Year"> | <"Infinite">,
        "retained-file-count-limit": <integer> (default: 1),
        "file-size-limit-bytes": <integer> (default: 1048576)
      }
    }
  }
}

Example

{
  "runtime": {
    "telemetry": {
      "file": {
        "enabled": true,
        "path": "/var/log/dab/dab-telemetry.txt",
        "rolling-interval": "Hour",
        "retained-file-count-limit": 24,
        "file-size-limit-bytes": 5242880
      }
    }
  }
}

MCP (runtime)

Hiermee configureert u de MCP-server (SQL Model Context Protocol), die database-entiteiten beschikbaar maakt als MCP-hulpprogramma's voor AI-agents.

Geneste eigenschappen

De dml-tools eigenschap accepteert een Booleaanse waarde om alle hulpprogramma's in of uit te schakelen, of een object om afzonderlijke hulpprogramma's te beheren:

Het aggregate-records hulpprogramma accepteert een Booleaanse waarde of een object met meer instellingen:

Format

{
  "runtime": {
    "mcp": {
      "enabled": <true> (default) | <false>,
      "path": <string> (default: "/mcp"),
      "description": <string>,
      "dml-tools": {
        "describe-entities": <true> | <false>,
        "create-record": <true> | <false>,
        "read-records": <true> | <false>,
        "update-record": <true> | <false>,
        "delete-record": <true> | <false>,
        "execute-entity": <true> | <false>,
        "aggregate-records": {
          "enabled": <true> | <false>,
          "query-timeout": <integer; default: 30>
        }
      }
    }
  }
}

Example

{
  "runtime": {
    "mcp": {
      "enabled": true,
      "dml-tools": {
        "describe-entities": true,
        "create-record": true,
        "read-records": true,
        "update-record": true,
        "delete-record": true,
        "execute-entity": true,
        "aggregate-records": {
          "enabled": true,
          "query-timeout": 30
        }
      }
    }
  }
}

Als u alle DML-hulpprogramma's tegelijk wilt in- of uitschakelen, stelt u dit in "dml-tools" op true of false.

Wanneer u een hulpprogramma uitschakelt op runtimeniveau, wordt het hulpprogramma nooit weergegeven in het MCP-antwoord tools/list en kan het niet worden aangeroepen, ongeacht machtigingen op entiteitsniveau. Zie DML-hulpprogramma's (Data Manipulat Language) voor meer informatie over afzonderlijke DML-hulpprogramma's.

De CLI gebruiken

dab configure --runtime.mcp.enabled true
dab configure --runtime.mcp.path "/mcp"
dab configure --runtime.mcp.dml-tools.describe-entities true
dab configure --runtime.mcp.dml-tools.create-record true
dab configure --runtime.mcp.dml-tools.read-records true
dab configure --runtime.mcp.dml-tools.update-record true
dab configure --runtime.mcp.dml-tools.delete-record true
dab configure --runtime.mcp.dml-tools.execute-entity true
dab configure --runtime.mcp.dml-tools.aggregate-records.enabled true

Status (runtime)

Globale configuratie van statuscontrole-eindpunt (/health).

Geneste eigenschappen

Gedrag in ontwikkeling versus productie

Format

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

Example

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