Runtime

Opciones de configuración que determinan el comportamiento en tiempo de ejecución.

Configuración de paginación

Configuración de REST

Configuración de GraphQL

Configuración del host

Configuración de CORS

Configuración de autenticación

Configuración de caché

Configuración de compresión

Configuración de telemetría

Configuración de MCP

Introducción al formato

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

Modo (tiempo de ejecución del host)

Comportamiento de desarrollo

• Nitro habilitado (anteriormente Banana Cake Pop) para las pruebas de GraphQL
• Interfaz de usuario de Swagger habilitada para pruebas REST
• Comprobaciones de estado anónimas habilitadas
• Mayor detalle de registro (depuración)

Format

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

Tamaño máximo de respuesta (tiempo de ejecución del host)

Establece el tamaño máximo (en megabytes) para cualquier resultado determinado. Como las respuestas grandes pueden tensar el sistema, max-response-size-mb limita el tamaño total (diferente del recuento de filas) para evitar la sobrecarga, que es especialmente con columnas grandes como texto o JSON.

Format

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

GraphQL (runtime)

Configuración global de GraphQL.

Propiedades anidadas

Notas de la propiedad

• No se permiten subrutas para la path propiedad .
• Use depth-limit para restringir las consultas anidadas.
• Establézcalo allow-introspection en false para ocultar el esquema de GraphQL.
• Se usa multiple-mutations para insertar varias entidades en una sola mutación.

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

Ejemplo: varias mutaciones

Configuration

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

Mutación de 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 (tiempo de ejecución)

Configuración de REST global.

Propiedades anidadas

Notas de la propiedad

• Si global enabled es false, el nivel enabled de entidad individual no importa.
• La path propiedad no admite valores de subruta como /api/data.
• request-body-strict se introdujo para ayudar a simplificar los objetos POCO de .NET.

Format

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

Ejemplo: request-body-strict

• Las columnas con un default() valor se omiten solo cuando INSERT su valor en la carga es null. Como consecuencia, INSERT las operaciones en default() columnas, cuando request-body-strict es true, no pueden dar lugar a valores explícitos null . Para lograr este comportamiento, se requiere una UPDATE operación.
• Las columnas con un default() no se omiten durante independientemente UPDATE del valor de carga.
• Las columnas calculadas siempre se omiten.
• Las columnas generadas automáticamente siempre se omiten.

Tabla de ejemplo

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

Carga de solicitud

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

Insertar comportamiento cuando 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.

Carga de respuesta

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

Comportamiento de actualización cuando request-body-strict = false

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

Carga de respuesta

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

CORS (tiempo de ejecución de host)

Configuración de CORS global.

Propiedades anidadas

Format

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

Proveedor (entorno de ejecución del host de autenticación)

Selecciona el método de autenticación. Cada proveedor valida la identidad de forma diferente. Para la configuración paso a paso, consulte las guías paso a paso de la tabla siguiente.

Resumen del proveedor

Sin autenticar (valor predeterminado)

Cuando Unauthenticated se establece (o no se especifica ningún proveedor), DAB no inspecciona ni valida ningún JWT. Todas las solicitudes se ejecutan como rol anonymous . Un servicio front-end, como Azure API Management o una puerta de enlace de aplicaciones, todavía puede controlar la autenticación o la directiva de acceso antes de que las solicitudes lleguen a DAB, pero DAB sigue autorizando solo como anonymous.

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

AppService

Confía en los encabezados de identidad insertados por EasyAuth de Azure App Service.

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

EntraID

Valida los tokens JWT emitidos por microsoft Entra ID.

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

Custom

Valida tokens JWT de proveedores de identidades de terceros.

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

Simulador

Simula la autenticación para el desarrollo y las pruebas locales.

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

Selección de roles

Para todos los proveedores excepto Simulador, el X-MS-API-ROLE encabezado selecciona qué rol se va a usar en las notificaciones del usuario autenticado. Si se omite, la solicitud usa el rol del Authenticated sistema. Para más información sobre la evaluación de roles, consulte Introducción a la autorización.

JWT (entorno de ejecución del host de autenticación)

Configuración global de JSON Web Token (JWT).

Propiedades anidadas

* Ambos audience y issuer son necesarios cuando el jwt objeto está presente. El jwt propio objeto es necesario cuando el proveedor es EntraID, AzureADo Custom.

Format

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

Paginación (tiempo de ejecución)

Límites de paginación global para puntos de conexión REST y GraphQL.

Propiedades anidadas

Valores admitidos de tamaño máximo de página

Valores admitidos de tamaño de página predeterminado

Comportamiento relativo al vínculo siguiente

Cuando next-link-relative es true, los valores de paginación nextLink usan direcciones URL relativas en lugar de direcciones URL absolutas.

Format

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

Ejemplo: Paginación en REST

Request

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

Carga de respuesta

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

Página Siguiente de solicitud

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

Ejemplo: Paginación en GraphQL

Carga de solicitud (consulta)

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

Carga de respuesta

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

Página Siguiente de solicitud

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

Ejemplo: Acceso max-page-size en solicitudes

Use el max-page-size valor estableciendo $limit (REST) o first (GraphQL) en -1.

REST

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

GraphQL

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

Compresión (tiempo de ejecución)

Configuración de compresión de respuesta HTTP. Cuando se habilita, DAB comprime los cuerpos de respuesta para reducir los tamaños de carga y mejorar las velocidades de transferencia.

Propiedades anidadas

Valores admitidos para level

Encabezados HTTP de cliente

El encabezado del Accept-Encoding cliente invoca la compresión. Los algoritmos admitidos son Gzip y Brotli. La level configuración configura la estrategia de compresión cuando el cliente y el servidor admiten varios algoritmos.

Encabezados admitidos

Format

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

Example

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

Caché (tiempo de ejecución)

Configuración de caché global.

Propiedades anidadas

Format

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

Cuando level-2.enabled es true, DAB usa el proveedor de caché distribuida configurado además de la memoria caché local en memoria. Una entidad configurada con el nivel L1L2 de caché comprueba primero la caché local y, después, la caché distribuida, antes de ir a la base de datos.

Telemetría (tiempo de ejecución)

Configuración de telemetría global.

Propiedades anidadas

Configura el nivel de detalle del registro por espacio de nombres. Esta configuración sigue las convenciones de registro estándar de .NET y permite un control pormenorizado, aunque supone cierta familiaridad con los internos del Generador de API de datos. Data API Builder es de código abierto: 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 (telemetría)

Configura el registro en Application Insights.

Propiedades anidadas

Format

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

OpenTelemetry (telemetría)

Configura el registro en Abrir telemetría.

Propiedades anidadas

Hay varios encabezados separados (comas , ).

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

Obtenga más información sobre OTEL_EXPORTER_OTLP_HEADERS.

Azure Log Analytics (telemetría)

Configura el registro en Azure Log Analytics a través de un punto de conexión de recopilación de datos. Cuando está habilitada, DAB envía datos de telemetría en lotes a un intervalo configurable.

Propiedades anidadas

* auth es necesario cuando enabled es true.

* Obligatorio cuando enabled es true.

• dab-identifier: una etiqueta que se pasa a Log Analytics para ayudar a diferenciar qué registros proceden del generador de Data API.
• flush-interval-seconds: intervalo de tiempo (en segundos) entre el envío de lotes de datos de telemetría.
• custom-table-name: el nombre de la tabla personalizada en Azure Log Analytics donde se almacenan los datos.
• dcr-immutable-id: el identificador inmutable de la regla de recopilación de datos que define cómo se recopilan los datos.
• dce-endpoint: la dirección URL del punto de conexión de recopilación de datos que se usa para enviar datos de telemetría.

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

Archivo (telemetría)

Configura la escritura de registros de telemetría en un archivo local. Cuando se habilita, DAB escribe la salida del registro estructurado en la ruta de acceso del archivo especificada con intervalos graduales y límites de tamaño configurables.

Propiedades anidadas

* path es necesario cuando enabled es true.

Valores de intervalo gradual

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 (tiempo de ejecución)

Configura el servidor del Protocolo de contexto de modelo de SQL (MCP), que expone entidades de base de datos como herramientas de MCP para agentes de IA.

Propiedades anidadas

La dml-tools propiedad acepta un valor booleano para habilitar o deshabilitar todas las herramientas, o un objeto para controlar herramientas individuales:

La aggregate-records herramienta acepta un valor booleano o un objeto con más opciones de configuración:

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

Para habilitar o deshabilitar todas las herramientas DML a la vez, establezca en "dml-tools"true o false.

Al deshabilitar una herramienta en el nivel de tiempo de ejecución, la herramienta nunca aparece en la respuesta mcP tools/list y no se puede invocar, independientemente de los permisos de nivel de entidad. Para obtener más información sobre las herramientas de DML individuales, consulte Herramientas de lenguaje de manipulación de datos (DML).

Uso de la 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

Estado (tiempo de ejecución)

Configuración del punto de conexión de comprobación de estado global ()./health

Propiedades anidadas

Comportamiento en desarrollo frente a producción

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