Runtime

Paramètres de configuration qui déterminent le comportement d’exécution.

Paramètres de pagination

Paramètres REST

Paramètres GraphQL

Paramètres de l’hôte

Paramètres CORS

Paramètres d’authentification

Paramètres du cache

Paramètres de compression

Paramètres de télémétrie

Paramètres MCP

Vue d’ensemble du 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: "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`)
        }
      }
    }
  }
}

Mode (runtime d’hôte)

Comportement de développement

• Enabled Nitro (anciennement Banana Cake Pop) pour les tests GraphQL
• Activation de l’interface utilisateur Swagger pour les tests REST
• Vérifications d’intégrité anonymes activées
• Augmentation du détail de journalisation (débogage)

Format

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

Taille de réponse maximale (runtime de l’hôte)

Définit la taille maximale (en mégaoctets) pour un résultat donné. Comme les réponses volumineuses peuvent forcer le système, max-response-size-mb limite la taille totale (différente du nombre de lignes) pour empêcher la surcharge, ce qui est particulièrement avec de grandes colonnes telles que du texte ou JSON.

Format

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

GraphQL (runtime)

Configuration globale de GraphQL.

Propriétés imbriquées

Notes de propriété

• Les sous-chemins ne sont pas autorisés pour la path propriété.
• Permet depth-limit de limiter les requêtes imbriquées.
• Définissez cette option allow-introspection pour false masquer le schéma GraphQL.
• Permet multiple-mutations d’insérer plusieurs entités dans une seule 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> | <false> (default)
        }
      }
    }
  }
}

Exemple : mutations multiples

Configuration

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

Mutation 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 (temps d'exécution)

Configuration REST globale.

Propriétés imbriquées

Notes de propriété

• Si global enabled est false, le niveau enabled d’entité individuel n’a pas d’importance.
• La path propriété ne prend pas en charge les valeurs de sous-chemin comme /api/data.
• request-body-strict a été introduit pour simplifier les objets .NET POCO.

Format

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

Exemple : request-body-strict

• Les colonnes avec une default() valeur sont ignorées uniquement INSERT lorsque leur valeur dans la charge utile est null. Par conséquent, INSERT les opérations en default() colonnes, quand c’est request-body-strictle castrue, ne peuvent pas entraîner de valeurs explicitesnull. Pour accomplir ce comportement, une UPDATE opération est requise.
• Les colonnes avec un default() ne sont pas ignorées pendant UPDATE quelle que soit la valeur de la charge utile.
• Les colonnes calculées sont toujours ignorées.
• Les colonnes générées automatiquement sont toujours ignorées.

Exemple de table

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

Charge utile de la demande

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

Comportement d’insertion lorsque 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.

Charge utile de la réponse

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

Mettre à jour le comportement quand request-body-strict = false

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

Charge utile de la réponse

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

CORS (runtime d’hôte)

Configuration CORS globale.

Propriétés imbriquées

Format

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

Fournisseur (runtime d’hôte d’authentification)

Sélectionne la méthode d’authentification. Chaque fournisseur valide l’identité différemment. Pour connaître la configuration pas à pas, consultez les guides pratiques du tableau suivant.

Résumé du fournisseur

Non authentifié (valeur par défaut)

Quand Unauthenticated est défini (ou qu’aucun fournisseur n’est spécifié), DAB n’inspecte ni ne valide aucun JWT. Toutes les requêtes s’exécutent anonymous en tant que rôle. Un service frontal tel que Gestion des API Azure ou une passerelle d’application peut toujours gérer l’authentification ou la stratégie d’accès avant que les requêtes atteignent DAB, mais DAB continue d’autoriser uniquement en tant que anonymous.

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

AppService

Approuve les en-têtes d’identité injectés par Azure App Service EasyAuth.

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

EntraID

Valide les jetons JWT émis par l’ID Microsoft Entra.

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

Coutume

Valide les jetons JWT des fournisseurs d’identité tiers.

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

Simulateur

Simule l’authentification pour le développement et les tests locaux.

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

Sélection de rôle

Pour tous les fournisseurs, à l’exception du simulateur, l’en-tête X-MS-API-ROLE sélectionne le rôle à utiliser à partir des revendications de l’utilisateur authentifié. Si elle est omise, la requête utilise le Authenticated rôle système. Pour plus d’informations sur l’évaluation des rôles, consultez vue d’ensemble de l’autorisation.

JWT (runtime d’hôte d’authentification)

Configuration JWT (Global JSON Web Token).

Propriétés imbriquées

* Les deux audience et issuer sont obligatoires lorsque l’objet jwt est présent. L’objet jwt lui-même est requis lorsque le fournisseur est EntraID, AzureADou Custom.

Format

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

Pagination (runtime)

Limites de pagination globales pour les points de terminaison REST et GraphQL.

Propriétés imbriquées

Valeurs prises en charge par la taille maximale de page

Valeurs prises en charge par défaut de la taille de page

Comportement relatif au lien suivant

Quand next-link-relative c’est truele cas, les valeurs de pagination nextLink utilisent des URL relatives au lieu d’URL absolues.

Format

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

Exemple : Pagination dans REST

Request

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

Charge utile de la réponse

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

Page Suivante de la demande

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

Exemple : Pagination dans GraphQL

Charge utile de la requête (requête)

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

Charge utile de la réponse

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

Page Suivante de la demande

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

Exemple : accès max-page-size aux demandes

Utilisez la max-page-size valeur en définissant $limit (REST) ou first (GraphQL) sur -1.

REST

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

GraphQL

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

Compression (runtime)

Configuration de la compression de réponse HTTP. Lorsqu’il est activé, DAB compresse les corps de réponse pour réduire les tailles de charge utile et améliorer les vitesses de transfert.

Propriétés imbriquées

Valeurs prises en charge pour level

En-têtes HTTP du client

La compression est appelée par l’en-tête du Accept-Encoding client. Les algorithmes pris en charge sont Gzip et Brotli. Le level paramètre configure la stratégie de compression lorsque le client et le serveur prennent en charge plusieurs algorithmes.

En-têtes pris en charge

Format

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

Example

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

Cache (runtime)

Configuration globale du cache.

Propriétés imbriquées

Format

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

Quand level-2.enabled c’est truele cas, DAB utilise le fournisseur de cache distribué configuré en plus du cache local en mémoire. Une entité configurée avec le niveau L1L2 du cache vérifie d’abord le cache local, puis le cache distribué, avant d’accéder à la base de données.

Télémétrie (runtime)

Configuration globale de la télémétrie.

Propriétés imbriquées

Configure la journalisation détaillée par espace de noms. Cette configuration suit les conventions de journalisation .NET standard et permet un contrôle granulaire, bien qu’elle suppose une certaine familiarité avec les internes du générateur d’API de données. Le générateur d’API de données est 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 (télémétrie)

Configure la journalisation dans Application Insights.

Propriétés imbriquées

Format

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

OpenTelemetry (télémétrie)

Configure la journalisation sur Open Telemetry.

Propriétés imbriquées

Plusieurs en-têtes sont , séparés par des virgules.

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

En savoir plus sur OTEL_EXPORTER_OTLP_HEADERS.

Azure Log Analytics (télémétrie)

Configure la journalisation sur Azure Log Analytics via un point de terminaison de collecte de données. En cas d’activation, DAB envoie des données de télémétrie par lots à un intervalle configurable.

Propriétés imbriquées

* auth est requis lorsque enabled c’est true.

* Obligatoire quand est enabledtrue.

• dab-identifier: étiquette transmise à Log Analytics pour vous aider à différencier les journaux provenant du générateur d’API de données.
• flush-interval-seconds— intervalle de temps (en secondes) entre l’envoi de lots de données de télémétrie.
• custom-table-name— nom de la table personnalisée dans Azure Log Analytics où les données sont stockées.
• dcr-immutable-id: ID immuable de la règle de collecte de données qui définit la façon dont les données sont collectées.
• dce-endpoint: URL du point de terminaison de collecte de données utilisée pour envoyer des données de télémétrie.

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

Fichier (télémétrie)

Configure l’écriture de journaux de télémétrie dans un fichier local. Lorsque cette option est activée, DAB écrit la sortie du journal structuré dans le chemin d’accès de fichier spécifié avec des intervalles de roulement et des limites de taille configurables.

Propriétés imbriquées

* path est requis lorsque enabled c’est true.

Valeurs d’intervalle propagé

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)

Configure le serveur MCP (SQL Model Context Protocol), qui expose les entités de base de données en tant qu’outils MCP pour les agents IA.

Propriétés imbriquées

La dml-tools propriété accepte une valeur booléenne pour activer ou désactiver tous les outils, ou un objet pour contrôler les outils individuels :

L’outil aggregate-records accepte une valeur booléenne ou un objet avec plus de paramètres :

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

Pour activer ou désactiver tous les outils DML à la fois, définis "dml-tools" sur true ou false.

Lorsque vous désactivez un outil au niveau du runtime, l’outil n’apparaît jamais dans la réponse MCP tools/list et ne peut pas être appelé, quelles que soient les autorisations au niveau de l’entité. Pour plus d’informations sur les outils DML individuels, consultez les outils DML (Data Manipulation Language).

Avec l’aide de l’interface CLI

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

Intégrité (runtime)

Configuration du point de terminaison de contrôle d’intégrité global (/health).

Propriétés imbriquées

Comportement dans le développement et la production

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