Runtime

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

Configuración de paginación

Property	Default	Description
runtime.pagination.max-page-size	Define el máximo de registros por página
runtime.pagination.default-page-size	Establece registros predeterminados por respuesta

Configuración de REST

Property	Default	Description
runtime.rest.path	`"/api"`	Ruta de acceso base para puntos de conexión REST
runtime.rest.enabled	`true`	Permite habilitar o deshabilitar solicitudes REST para todas las entidades
runtime.rest.request-body-strict	`true`	No permite campos extraños en el cuerpo de la solicitud cuando es true

Configuración de GraphQL

Property	Default	Description
runtime.graphql.allow-introspection	`true`	Permite consultar el esquema de GraphQL subyacente.
runtime.graphql.path	`"/graphql"`	Ruta de acceso base para el punto de conexión de GraphQL
runtime.graphql.enabled	`true`	Permite habilitar o deshabilitar solicitudes de GraphQL para todas las entidades
runtime.graphql.depth-limit	`null`	Profundidad máxima permitida de una consulta GraphQL
runtime.graphql.multiple-mutations.create.enabled	`false`	Permite mutaciones de creación múltiple para todas las entidades

Configuración del host

Property	Default	Description
runtime.host.max-response-size-mb	`158`	Tamaño máximo (MB) de la respuesta de base de datos permitida en un único resultado
runtime.host.mode	`"production"`	Modo de ejecución; `"production"` o `"development"`

Configuración de CORS

Property	Default	Description
runtime.host.cors.origins	`[]`	Orígenes de CORS permitidos
runtime.host.cors.allow-credentials	`false`	Establece el valor del encabezado Access-Control-Allow-Credentials

Configuración de autenticación

Property	Default	Description
runtime.host.authentication.provider	`null`	Proveedor de autenticación
runtime.host.authentication.jwt.audience	`null`	Audiencia de JWT
runtime.host.authentication.jwt.issuer	`null`	Emisor de JWT

Configuración de caché

Property	Default	Description
runtime.cache.enabled	`false`	Habilita el almacenamiento en caché de respuestas globalmente
runtime.cache.ttl-seconds	`5`	Período de vida (segundos) para la caché global

Configuración de telemetría

Property	Default	Description
runtime.telemetry.application-insights.connection-string	`null`	Cadena de conexión de Application Insights
runtime.telemetry.application-insights.enabled	`false`	Habilita o deshabilita la telemetría de Application Insights
runtime.telemetry.open-telemetry.endpoint	`null`	Dirección URL del recopilador de OpenTelemetry
runtime.telemetry.open-telemetry.headers	`{}`	Encabezados de exportación de OpenTelemetry
runtime.telemetry.open-telemetry.service-name	`"dab"`	Nombre del servicio OpenTelemetry
runtime.telemetry.open-telemetry.exporter-protocol	`"grpc"`	Protocolo OpenTelemetry ("grpc" o "httpprotobuf")
runtime.telemetry.open-telemetry.enabled	`true`	Habilita o deshabilita OpenTelemetry
runtime.telemetry.log-level.namespace	`null`	Invalidación del nivel de registro específico del espacio de nombres
runtime.health.enabled	`true`	Habilita o deshabilita el punto de conexión de comprobación de estado globalmente.
runtime.health.roles	`null`	Roles permitidos para el punto de conexión de mantenimiento completo
runtime.health.cache-ttl-seconds	`5`	Período de vida (segundos) para la entrada de caché del informe de comprobación de estado
runtime.health.max-query-parallelism	`4`	Número máximo de consultas de comprobación de estado simultáneas (intervalo: 1-8)

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

Modo (tiempo de ejecución del host)

Parent	Property	Type	Required	Default
`runtime`	`host`	enumeración (`production` \| `development`)	❌ No	`production`

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)

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

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.

Value	Result
no establecido	Usar el valor predeterminado
`null`	Usar el valor predeterminado
`integer`	Entero positivo de 32 bits
`<= 0`	No está soportado

Format

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

GraphQL (runtime)

Parent	Property	Type	Required	Default
`runtime`	`graphql`	object	❌ No	-

Configuración global de GraphQL.

Propiedades anidadas

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

Notas de la propiedad

No se permiten rutas de acceso secundarias 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> (default) | <false>
        }
    }
  }
}

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)

Parent	Property	Type	Required	Default
`runtime`	`rest`	object	❌ No	-

Configuración de REST global.

Propiedades anidadas

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

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.

`request-body-strict`	Behavior
`true`	Los campos adicionales del cuerpo de la solicitud provocan una `BadRequest` excepción.
`false`	Se omiten los campos adicionales del cuerpo de la solicitud.

Format

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

Note

Al implementar data API Builder mediante Static Web Apps (versión preliminar), el servicio de Azure inserta automáticamente otra subruta /data-api en la dirección URL. Este comportamiento garantiza la compatibilidad con las características existentes de Static Web App. El punto de conexión resultante sería /data-api/api/<entity>. Esta nota solo es relevante para Static Web Apps.

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 ello, 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)

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

Configuración de CORS global.

Tip

CORS significa "Uso compartido de recursos entre orígenes". Es una característica de seguridad del explorador que controla si las páginas web pueden realizar solicitudes a un dominio diferente al que les ha servido.

Propiedades anidadas

Parent	Property	Type	Required	Default
`runtime.host.cors`	`allow-credentials`	boolean	❌ No	False
`runtime.host.cors`	`origins`	matriz de cadena	❌ No	None

Note

La allow-credentials propiedad establece el Access-Control-Allow-Credentials encabezado CORS.

Format

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

Note

El carácter comodín * es válido como un valor para origins.

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

Parent	Property	Type	Required	Default
`runtime.host.authentication`	`provider`	enumeración (`AppService` \| `EntraId` \| `Custom` \| `Simulator`)	❌ No	`AppService`

Define el método de autenticación que usa el generador de Data API.

Solo anónimo (proveedor de autenticación)

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

Cuando se omite toda authentication la sección del archivo dab-config.json, no se usa ningún proveedor de autenticación. En este caso, data API builder funciona en modo "sin autenticación". En este modo, DAB no busca ningún token ni Authorization encabezado. El X-MS-API-ROLE encabezado también se omite en esta configuración.

[! Nota] Todas las solicitudes que entran en el motor se asignan automáticamente e inmediatamente al rol de sistema de anonymous. A continuación, el control de acceso se controla exclusivamente mediante los permisos que defina en cada entidad.

Ejemplo de permisos de entidad.

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

En este ejemplo, dado que no hay ningún authentication proveedor configurado, todas las solicitudes entrantes se consideran automáticamente de un anonymous usuario. La permissions matriz de la Book entidad concede explícitamente al anonymous rol la capacidad de realizar read operaciones. Cualquier intento de realizar otras acciones (como create, update, delete) o acceder a otras entidades no configuradas para anonymous el acceso se deniega.

StaticWebApps (proveedor de autenticación) [en desuso]

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

Este proveedor está en desuso porque la característica Data Connections de versión preliminar de Static Web Apps se retiró en noviembre de 2025. Aunque sigue siendo funcional, se diseñó para una implementación heredada de la autenticación en Azure Static Web Apps. Los desarrolladores deben migrar al proveedor para mejorar la AppService compatibilidad a largo plazo y la coherencia con la plataforma "Easy Auth" más amplia de Azure.

[! Nota] La migración no es tan simple como cambiar el nombre del proveedor en el archivo de configuración. Los StaticWebApps proveedores y AppService esperan estructuras JSON diferentes dentro del x-ms-client-principal encabezado para procesar roles.

AppService (proveedor de autenticación)

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

Este proveedor es para aplicaciones hospedadas en Azure App Service, como Azure Container Apps. El entorno de hospedaje de Azure controla la autenticación y, a continuación, pasa la información de identidad del usuario a la aplicación a través de encabezados de solicitud. Está diseñado para desarrolladores que desean una solución de autenticación sencilla y integrada administrada por la plataforma Azure.

Este proveedor no usa un token JWT desde el Authorization encabezado. Se basa en un encabezado especial, X-MS-CLIENT-PRINCIPAL, insertado por la plataforma de App Service. Este encabezado contiene un objeto JSON codificado en base64 con los detalles de identidad del usuario.

Anónimo: si el AppService proveedor está configurado pero una solicitud llega sin el X-MS-CLIENT-PRINCIPAL encabezado , la solicitud se asigna al rol del sistema de anonymous.

El JSON descodificado del X-MS-CLIENT-PRINCIPAL encabezado suele tener este aspecto:

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

Los roles están incluidos en la claims matriz.

Acerca del encabezado X-MS-API-ROLE

Rol y comportamiento: el X-MS-API-ROLE encabezado se usa para especificar qué rol quiere asumir el usuario para la solicitud actual. El valor de este encabezado debe coincidir con uno de los valores de rol que se encuentran en la claims matriz del X-MS-CLIENT-PRINCIPAL objeto .
¿Es necesario?: No. Si el X-MS-API-ROLE encabezado no está presente, la solicitud se procesa en el contexto del rol del authenticated sistema. Esto significa que el usuario se reconoce como iniciado sesión, pero no como ningún rol específico definido por la aplicación del token.
Comportamiento en coincidencia: si se proporciona el X-MS-API-ROLE encabezado y su valor coincide con un rol en la entidad de seguridad de claimscliente, el usuario asume ese rol para la solicitud.
Comportamiento en error de coincidencia: si se proporciona el X-MS-API-ROLE encabezado, pero el valor no coincide con ningún rol en la entidad de seguridad de cliente, la solicitud se rechaza con un 403 Forbidden código de estado. Esto garantiza que un usuario no pueda reclamar un rol al que no se le haya asignado.

EntraId (proveedor de autenticación)

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

Este proveedor protege los puntos de conexión con identidades de usuario y aplicación en Microsoft Entra. Es ideal para cualquier servicio en el que los usuarios u otros servicios necesiten acceso seguro dentro del inquilino de Entra.

[! NOTA] El EntraId proveedor se denominaba AzureAdanteriormente . El nombre anterior sigue funcionando, pero se recomienda a los desarrolladores migrar sus configuraciones de AzureAd a EntraId.

Este proveedor espera un token de portador JWT estándar en el Authorization encabezado emitido por Microsoft Entra. El token debe configurarse para la aplicación específica (mediante la audience notificación). Se espera que los roles para el usuario o la entidad de servicio estén en una notificación dentro del token. El código busca una roles notificación de forma predeterminada.

Anónimo: si el EntraId proveedor está configurado pero una solicitud llega sin el Authorization encabezado , la solicitud se asigna al rol del sistema de anonymous.

Una carga JWT descodificada podría tener este aspecto:

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

Acerca del encabezado X-MS-API-ROLE

Rol y comportamiento: el X-MS-API-ROLE encabezado se usa para especificar un rol que el usuario desea asumir para la solicitud. El valor de este encabezado debe coincidir con uno de los valores de rol encontrados en la roles notificación del token JWT.
¿Es necesario?: No. Si el X-MS-API-ROLE encabezado no está presente, la solicitud se procesa en el contexto del rol del authenticated sistema. Esto significa que el usuario se reconoce como iniciado sesión, pero no como ningún rol específico definido por la aplicación del token.
Comportamiento en coincidencia: si se proporciona el X-MS-API-ROLE encabezado y coincide con un rol en la roles notificación, el contexto del usuario se establece en ese rol.
Comportamiento en error de coincidencia: si se proporciona el X-MS-API-ROLE encabezado pero su valor no coincide con ningún rol de la roles notificación, la solicitud se rechaza con un 403 Forbidden código de estado. Esto garantiza que un usuario no pueda reclamar un rol al que no se le haya asignado.

Personalizado (proveedor de autenticación)

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

Este proveedor es para desarrolladores que quieren integrar Data API Builder con un proveedor de identidades de terceros (como Auth0, Okta o un servidor de identidades personalizado) que emite JWT. Proporciona la flexibilidad para configurar los tokens esperados audience y issuer .

El Custom proveedor espera un token de portador JWT estándar en el Authorization encabezado. La diferencia clave del EntraId proveedor es que se configuran los valores válidos issuer y audience en el archivo de configuración del generador de DATA API. El proveedor valida el token comprobando que la autoridad de confianza la emitió. Se espera que los roles del usuario estén en una roles notificación dentro de la carga de JWT.

[! NOTA] En algunos casos, en función del proveedor de identidades de terceros, los desarrolladores deben coertar la estructura de su JWT para que coincida con la estructura esperada por data API Builder (que se muestra a continuación).

Anónimo: si el Custom proveedor está configurado pero una solicitud llega sin el Authorization encabezado , la solicitud se asigna al rol del sistema de anonymous.

Una carga JWT descodificada para un custom proveedor podría tener este aspecto:

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

Acerca del encabezado X-MS-API-ROLE

Rol y comportamiento: el X-MS-API-ROLE encabezado funciona exactamente igual que con el EntraId proveedor. Permite al usuario seleccionar uno de sus roles asignados. El valor de este encabezado debe coincidir con uno de los roles de la roles notificación en el token JWT personalizado.
¿Es necesario?: No. Si el X-MS-API-ROLE encabezado no está presente, el usuario se trata como en el rol del authenticated sistema.
Comportamiento en coincidencia: si el X-MS-API-ROLE valor del encabezado coincide con un rol en la notificación de roles JWT, el contexto del usuario se establece en ese rol con fines de autorización.
Comportamiento en error de coincidencia: si el X-MS-API-ROLE valor del encabezado no coincide con ningún rol de la roles notificación, la solicitud se rechaza con un 403 Forbidden código de estado. Esto garantiza que un usuario no pueda reclamar un rol al que no se le haya asignado.

Simulador (proveedor de autenticación)

Este proveedor está diseñado para facilitar a los desarrolladores probar su configuración, especialmente authorization las directivas, sin necesidad de configurar un proveedor de autenticación completo, como Entra Identity o EasyAuth. Simula un authenticated usuario.

El Simulator proveedor no usa tokens JWT. La autenticación se simula. Al usar este proveedor, todas las solicitudes se tratan como si provenían de un usuario autenticado.

Acerca del encabezado X-MS-API-ROLE

Rol y comportamiento: el X-MS-API-ROLE encabezado es la única manera de especificar un rol al usar .Simulator Puesto que no hay ningún token con una lista de roles, el sistema confía implícitamente en el rol enviado en este encabezado.
¿Es necesario?: No.
Comportamiento en ausencia: si el X-MS-API-ROLE encabezado está ausente, la solicitud se procesa en el contexto del rol del authenticated sistema.
Comportamiento en presencia: si el X-MS-API-ROLE encabezado está presente, la solicitud se procesa en el contexto del rol especificado en el valor del encabezado. No hay ninguna validación en una lista de notificaciones, por lo que el desarrollador puede simular cualquier rol que necesite para probar sus directivas.

Simulador en producción

Si se establece authentication.provider en Simulator mientras runtime.host.mode es production, Data API Builder no se iniciará.

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

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

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

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

Diagrama de compatibilidad con tokens web JSON en Data API Builder.

Propiedades anidadas

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

Format

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

Paginación (tiempo de ejecución)

Parent	Property	Type	Required	Default
`runtime`	`pagination`	object	❌ No	-

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

Propiedades anidadas

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

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

Value	Result
`integer`	Se admite cualquier entero positivo de 32 bits.
`0`	No está soportado.
`-1`	El valor predeterminado es el valor máximo admitido.
`< -1`	No está soportado.

Valores admitidos de tamaño de página predeterminado

Value	Result
`integer`	Cualquier entero positivo menor que el `max-page-size`actual.
`0`	No está soportado.
`-1`	El valor predeterminado es el valor de `max-page-size` actual.
`< -1`	No está soportado.

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.

Value	Example
`false` (valor predeterminado)	`"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

Cuando el valor es mayor que max-page-size, los resultados se limitan a max-page-size.

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

Caché (tiempo de ejecución)

Parent	Property	Type	Required	Default
`runtime`	`cache`	object	❌ No	-

Configuración de caché global.

Propiedades anidadas

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

Tip

La propiedad de nivel cache.ttl-seconds de entidad tiene como valor predeterminado este valor global.

Format

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

Important

Si global enabled es false, el nivel enabled de entidad individual no importa.

Telemetría (tiempo de ejecución)

Parent	Property	Type	Required	Default
`runtime`	`telemetry`	object	❌ No	-

Configuración de telemetría global.

Propiedades anidadas

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

Configura el nivel de detalle del registro por espacio de nombres. Esto sigue las convenciones de registro de .NET estándar 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"
      }
    }
  }
}

Tip

log-level se puede volver a cargar en caliente tanto en desarrollo como en producción. Actualmente es la única propiedad que admite la recarga activa en producción.

Example

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

Application Insights (telemetría)

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

Configura el registro en Application Insights.

Propiedades anidadas

Parent	Property	Type	Required	Default
`runtime.telemetry.application-insights`	`enabled`	boolean	❌ No	False
`runtime.telemetry.application-insights`	`connection-string`	string	✔️ Sí	None

Format

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

OpenTelemetry (telemetría)

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

Configura el registro en Abrir telemetría.

Propiedades anidadas

Parent	Property	Type	Required	Default
`runtime.telemetry.open-telemetry`	`enabled`	boolean	❌ No	true
`runtime.telemetry.open-telemetry`	`endpoint`	string	✔️ Sí	None
`runtime.telemetry.open-telemetry`	`headers`	string	❌ No	None
`runtime.telemetry.open-telemetry`	`service-name`	string	❌ No	"dab"
`runtime.telemetry.open-telemetry`	`exporter-protocol`	enumeración (`grpc` \| `httpprotobuf`)	❌ No	`grpc`

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.

Note

gRPC (4317) es más rápido y admite el streaming, pero requiere más configuración. HTTP/protobuf (4318) es más sencillo y fácil de depurar, pero menos eficaz.

Estado (tiempo de ejecución)

Parent	Property	Type	Required	Default
`runtime`	`health`	object	❌ No	-

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

Propiedades anidadas

Parent	Property	Type	Required	Default	Rango/Notas
`runtime.health`	`enabled`	boolean	❌ No	`true`
`runtime.health`	`roles`	matriz de cadena	✔️ Sí*	`null`	*Obligatorio en modo de producción
`runtime.health`	`cache-ttl-seconds`	integer	❌ No	`5`	Min: 0
`runtime.health`	`max-query-parallelism`	integer	❌ No	`4`	Min: 1, Max: 8 (abrazado)

Comportamiento en desarrollo frente a producción

Condition	Comportamiento de desarrollo	Comportamiento de producción
`health.enabled` = falso	`403` estado	`403` estado
`health.enabled` = verdadero	Depende del rol	Depende del rol
`roles` omitido o `null`	Estado mostrado	`403` estado
rol actual no en `roles`	`403` estado	`403` estado
rol actual en `roles`	Estado mostrado	Estado mostrado
`roles` Incluye `anonymous`	Estado mostrado	Estado mostrado

Format

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

Note

Si global enabled es false, el nivel enabled de entidad individual no importa.

Example

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

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2025-09-24

Compartir a través de

Runtime

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 telemetría

Introducción al formato

Modo (tiempo de ejecución del host)

Comportamiento de desarrollo

Format

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

Format

GraphQL (runtime)

Propiedades anidadas

Notas de la propiedad

Format

Ejemplo: varias mutaciones

REST (tiempo de ejecución)

Propiedades anidadas

Notas de la propiedad

Format

Ejemplo: request-body-strict

Insertar comportamiento cuando request-body-strict = false

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

CORS (tiempo de ejecución de host)

Propiedades anidadas

Format

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

Solo anónimo (proveedor de autenticación)

StaticWebApps (proveedor de autenticación) [en desuso]

AppService (proveedor de autenticación)

Acerca del encabezado X-MS-API-ROLE

EntraId (proveedor de autenticación)

Acerca del encabezado X-MS-API-ROLE

Personalizado (proveedor de autenticación)

Acerca del encabezado X-MS-API-ROLE

Simulador (proveedor de autenticación)

Acerca del encabezado X-MS-API-ROLE

Simulador en producción

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

Propiedades anidadas

Format

Paginación (tiempo de ejecución)

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

Format

Ejemplo: Paginación en REST

Ejemplo: Paginación en GraphQL

Ejemplo: Acceso max-page-size en solicitudes

Caché (tiempo de ejecución)

Propiedades anidadas

Format

Telemetría (tiempo de ejecución)

Propiedades anidadas

Format

Example

Application Insights (telemetría)

Propiedades anidadas

Format

OpenTelemetry (telemetría)

Propiedades anidadas

Format

Example

Estado (tiempo de ejecución)

Propiedades anidadas

Comportamiento en desarrollo frente a producción

Format

Example

Comentarios

Recursos adicionales

Insertar comportamiento cuando `request-body-strict = false`

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

Ejemplo: Acceso `max-page-size` en solicitudes