Referencia del esquema de configuración de Data API Builder

2025-06-11

El motor del generador de Data API requiere un archivo de configuración. El archivo de configuración de Data API Builder proporciona un enfoque estructurado y completo para configurar la API, detallando todo, desde variables de entorno hasta configuraciones específicas de la entidad. Este documento con formato JSON comienza con una propiedad $schema. Esta configuración valida el documento.

Las propiedades database-type y connection-string garantizar una integración sin problemas con los sistemas de base de datos, desde Azure SQL Database a La API NoSQL de Cosmos DB.

El archivo de configuración puede incluir opciones como:

Información de conexión y servicio de base de datos
Opciones de configuración global y en tiempo de ejecución
Conjunto de entidades expuestas
Método de autenticación
Reglas de seguridad necesarias para acceder a identidades
Reglas de asignación de nombres entre la API y la base de datos
Relaciones entre entidades que no se pueden deducir
Características únicas para servicios de base de datos específicos

Introducción a la sintaxis

Este es un desglose rápido de las "secciones" principales de un archivo de configuración.

{
  "$schema": "...",
  "data-source": { ... },
  "data-source-files": [ ... ],
  "runtime": {
    "rest": { ... },
    "graphql": { .. },
    "host": { ... },
    "cache": { ... },
    "telemetry": { ... },
    "pagination": { ... }
  }
  "entities": [ ... ]
}

Propiedades de nivel superior

Esta es la descripción de las propiedades de nivel superior en formato de tabla:

Propiedad	Descripción
$schema	Especifica el esquema JSON para la validación, lo que garantiza que la configuración cumple el formato necesario.
de origen de datos	Contiene los detalles sobre el tipo de base de datos de y la cadena de conexión , necesario para establecer la conexión de base de datos.
archivos de origen de datos	Matriz opcional que especifica otros archivos de configuración que podrían definir otros orígenes de datos.
en tiempo de ejecución de	Configura los comportamientos y las opciones de tiempo de ejecución, incluidas las subpropiedades para REST, GraphQL, host, cachéy telemetría.
entidades	Define el conjunto de entidades (tablas de base de datos, vistas, etc.) que se exponen a través de la API, incluidas sus asignaciones de , permisosy relaciones .

Configuraciones de ejemplo

Este es un archivo de configuración de ejemplo que solo incluye las propiedades necesarias para una sola entidad simple. Este ejemplo está pensado para ilustrar un escenario mínimo.

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')"
  },
  "entities": {
    "User": {
      "source": "dbo.Users",
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["*"]
        }
      ]
    }
  }
}

Para obtener un ejemplo de un escenario más complejo, consulte la configuración de ejemplo de un extremo a otro.

Entornos

El archivo de configuración de Data API Builder puede admitir escenarios en los que necesite admitir varios entornos, de forma similar al archivo de appSettings.json en ASP.NET Core. El marco proporciona tres valores de entorno comunes; Development, Stagingy Production; pero puede optar por usar cualquier valor de entorno que elija. El entorno que usa Data API Builder debe configurarse mediante la variable de entorno DAB_ENVIRONMENT.

Considere un ejemplo en el que desea una configuración de línea base y una configuración específica del desarrollo. En este ejemplo se requieren dos archivos de configuración:

	Medio ambiente
dab-config.json	Base
dab-config.Development.json	Desarrollo

Para usar la configuración específica del desarrollo, debe establecer la variable de entorno DAB_ENVIRONMENT en Development.

Los archivos de configuración específicos del entorno invalidan los valores de propiedad en el archivo de configuración base. En este ejemplo, si el valor de connection-string se establece en ambos archivos, se usa el valor del archivo *.Development.json.

Consulte esta matriz para comprender mejor qué valor se usa en función de dónde se especifique ese valor (o no se especifique) en cualquiera de los archivos.

	Especificado en la configuración base	No se especifica en la configuración base
Especificado en la configuración actual del entorno	Entorno actual	Entorno actual
No especificado en la configuración actual del entorno	Base	Ninguno

Para obtener un ejemplo de uso de varios archivos de configuración, consulte uso de Data API Builder con entornos.

Propiedades de configuración

En esta sección se incluyen todas las propiedades de configuración posibles que están disponibles para un archivo de configuración.

Esquema

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`$root`	`$schema`	cuerda	✔️ Sí	Ninguno

Cada archivo de configuración comienza con una propiedad , especificando el de esquema JSON de para la validación.

Formato

{
  "$schema": <string>
}

Ejemplos

Los archivos de esquema están disponibles para las versiones 0.3.7-alpha en adelante en direcciones URL específicas, lo que garantiza que usa la versión correcta o el esquema disponible más reciente.

https://github.com/Azure/data-api-builder/releases/download/<VERSION>-<suffix>/dab.draft.schema.json

Reemplace VERSION-suffix por la versión que desee.

https://github.com/Azure/data-api-builder/releases/download/v0.3.7-alpha/dab.draft.schema.json

La versión más reciente del esquema siempre está disponible en https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json.

Estos son algunos ejemplos de valores de esquema válidos.

Versión	URI	Descripción
0.3.7-alpha	`https://github.com/Azure/data-api-builder/releases/download/v0.3.7-alpha/dab.draft.schema.json`	Usa el esquema de configuración de una versión alfa de la herramienta.
0.10.23	`https://github.com/Azure/data-api-builder/releases/download/v0.10.23/dab.draft.schema.json`	Usa el esquema de configuración para una versión estable de la herramienta.
Último	`https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json`	Usa la versión más reciente del esquema de configuración.

Nota

Las versiones del generador de Data API antes de 0.3.7-alpha pueden tener un URI de esquema diferente.

Origen de datos

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`$root`	`data-source`	cuerda	✔️ Sí	Ninguno

La sección data-source define la base de datos y el acceso a la base de datos a través de la cadena de conexión. También define las opciones de la base de datos. La propiedad data-source configura las credenciales necesarias para conectarse a la base de datos de respaldo. En la sección data-source se describe la conectividad de la base de datos de back-end, especificando tanto el database-type como el connection-string.

Formato

{
  "data-source": {
    "database-type": <string>,
    "connection-string": <string>,
    
    // mssql-only
    "options": {
      "set-session-context": <true> (default) | <false>
    },
    
    // cosmosdb_nosql-only
    "options": {
      "database": <string>,
      "container": <string>,
      "schema": <string>
    }
  }
}

Propiedades

	Obligatorio	Tipo
`database-type`	✔️ Sí	enum string
`connection-string`	✔️ Sí	cuerda
`options`	❌ No	objeto

Tipo de base de datos

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`data-source`	`database-type`	enum-string	✔️ Sí	Ninguno

Cadena de enumeración utilizada para especificar el tipo de base de datos que se va a usar como origen de datos.

Formato

{
  "data-source": {
    "database-type": <string>
  }
}

Valores de tipo

La propiedad type indica el tipo de base de datos back-end.

Tipo	Descripción	Versión mínima
`mssql`	Azure SQL Database	-
`mssql`	Azure SQL MI	-
`mssql`	SQL Server	2016
`dwsql`	Azure Synapse Analytics	-
`dwsql`	Fabric Warehouse	-
`dwsql`	Punto de conexión de SQL Analytics de Fabric	-
`postgresql`	PostgreSQL	ver. 11
`mysql`	MySQL	ver. 8
`cosmosdb_nosql`	Azure Cosmos DB para NoSQL	-
`cosmosdb_postgresql`	Azure Cosmos DB para PostgreSQL	-

Cadena de conexión

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`data-source`	`connection-string`	cuerda	✔️ Sí	Ninguno

Cadena valor que contiene una cadena de conexión válida para conectarse al servicio de base de datos de destino. Cadena de conexión ADO.NET para conectarse a la base de datos de back-end. Para obtener más información, consulte ADO.NET cadenas de conexión.

Formato

{
  "data-source": {
    "connection-string": <string>
  }
}

Resistencia de conexión

El generador de API de datos vuelve a intentar automáticamente las solicitudes de base de datos después de detectar errores transitorios. La lógica de reintento sigue una estrategia de retroceso exponencial donde el número máximo de reintentos es cinco. La duración de retroceso del reintento después de calcular las solicitudes posteriores mediante esta fórmula (suponiendo que el intento de reintento actual es r): $r^2$

Con esta fórmula, puede calcular el tiempo de cada reintento en segundos.

Intentos	First	Segundo	Tercero	Cuarto	Quinto
Sobras	2s	4s	8s	16s	32s

Azure SQL y SQL Server

Data API Builder usa la biblioteca de SqlClient para conectarse a Azure SQL o SQL Server mediante la cadena de conexión que proporcione en el archivo de configuración. Hay disponible una lista de todas las opciones de cadena de conexión admitidas aquí: propiedad SqlConnection.ConnectionString.

El generador de API de datos también puede conectarse a la base de datos de destino mediante Managed Service Identities (MSI) cuando data API Builder se hospeda en Azure. El DefaultAzureCredential definido en Azure.Identity biblioteca se usa para conectarse mediante identidades conocidas cuando no se especifica un nombre de usuario o una contraseña en la cadena de conexión. Para obtener más información, vea ejemplos de DefaultAzureCredential.

de identidad administrada asignada por el usuario (UMI): anexe los de autenticación de y id. de usuario a la cadena de conexión al sustituir el identificador de cliente de la identidad administrada asignada por el usuario: .
de identidad administrada asignada por el sistema (SMI): anexe la propiedad Authentication de y excluya los argumentos UserId de y Password de la cadena de conexión: . La ausencia del userId y las propiedades de cadena de conexión contraseña indicará a DAB que se autentique mediante una identidad administrada asignada por el sistema.

Para obtener más información sobre cómo configurar una identidad de servicio administrada con Azure SQL o SQL Server, consulte identidades administradas en Microsoft Entra para Azure SQL.

Ejemplos

El valor utilizado para la cadena de conexión depende en gran medida del servicio de base de datos usado en el escenario. Siempre puede elegir almacenar la cadena de conexión en una variable de entorno y acceder a ella mediante la función @env().

	Valor	Descripción
Uso del valor de cadena de Azure SQL Database	`Server=<server-address>;Database=<name-of-database>;User ID=<username>;Password=<password>;`	Cadena de conexión a una cuenta de Azure SQL Database. Para más información, consulte cadenas de conexión de Azure SQL Database.
Uso del valor de cadena de Azure Database for PostgreSQL	`Server=<server-address>;Database=<name-of-database>;Port=5432;User Id=<username>;Password=<password>;Ssl Mode=Require;`	Cadena de conexión a una cuenta de Azure Database for PostgreSQL. Para más información, consulte cadenas de conexión de Azure Database for PostgreSQL.
Uso de azure Cosmos DB para el valor de cadena NoSQL	`AccountEndpoint=<endpoint>;AccountKey=<key>;`	Cadena de conexión a una cuenta de Azure Cosmos DB para NoSQL. Para más información, consulte cadenas de conexión de Azure Cosmos DB para NoSQL.
Uso del valor de cadena de Azure Database for MySQL	`Server=<server-address>;Database=<name-of-database>;User ID=<username>;Password=<password>;Sslmode=Required;SslCa=<path-to-certificate>;`	Cadena de conexión a una cuenta de Azure Database for MySQL. Para más información, consulte cadenas de conexión de Azure Database for MySQL.
de variables de entorno de Access	`@env('SQL_CONNECTION_STRING')`	Acceda a una variable de entorno desde el equipo local. En este ejemplo, se hace referencia a la variable de entorno `SQL_CONNECTION_STRING`.

Propina

Como procedimiento recomendado, evite almacenar información confidencial en el archivo de configuración. Cuando sea posible, use @env() para hacer referencia a variables de entorno. Para obtener más información, vea @env() función.

Estos ejemplos solo muestran cómo se puede configurar cada tipo de base de datos. El escenario podría ser único, pero este ejemplo es un buen punto de partida. Reemplace los marcadores de posición, como myserver, myDataBase, myloginy myPassword por los valores reales específicos de su entorno.

`mssql`

"data-source": {
  "database-type": "mssql",
  "connection-string": "$env('my-connection-string')",
  "options": {
    "set-session-context": true
  }
}

`postgresql`

"data-source": {
  "database-type": "postgresql",
  "connection-string": "$env('my-connection-string')"
}

`mysql`

"data-source": {
  "database-type": "mysql",
  "connection-string": "$env('my-connection-string')"
}

`cosmosdb_nosql`

"data-source": {
  "database-type": "cosmosdb_nosql",
  "connection-string": "$env('my-connection-string')",
  "options": {
    "database": "Your_CosmosDB_Database_Name",
    "container": "Your_CosmosDB_Container_Name",
    "schema": "Path_to_Your_GraphQL_Schema_File"
  }
}

`cosmosdb_postgresql`

"data-source": {
  "database-type": "cosmosdb_postgresql",
  "connection-string": "$env('my-connection-string')"
}

Nota

Las "opciones" especificadas como database, containery schema son específicas de la API NoSQL de Azure Cosmos DB en lugar de la API de PostgreSQL. Para Azure Cosmos DB mediante la API de PostgreSQL, las "opciones" no incluirían database, containero schema como en la configuración de NoSQL.

Opciones

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`data-source`	`options`	objeto	❌ No	Ninguno

Sección opcional de parámetros de clave-valor adicionales para conexiones de base de datos específicas.

Si la sección options es necesaria o no depende en gran medida del servicio de base de datos que se está usando.

Formato

{
  "data-source": {
    "options": {
      "<key-name>": <string>
    }
  }
}

opciones: { set-session-context: boolean }

Para Azure SQL y SQL Server, Data API Builder puede aprovechar las ventajas de SESSION_CONTEXT enviar metadatos especificados por el usuario a la base de datos subyacente. Estos metadatos están disponibles para data API Builder en virtud de las notificaciones presentes en el token de acceso. Los datos SESSION_CONTEXT están disponibles para la base de datos durante la conexión de la base de datos hasta que se cierre esa conexión. Para obtener más información, consulte contexto de sesión.

Ejemplo de procedimiento almacenado de SQL:

CREATE PROC GetUser @userId INT AS
BEGIN
    -- Check if the current user has access to the requested userId
    IF SESSION_CONTEXT(N'user_role') = 'admin' 
        OR SESSION_CONTEXT(N'user_id') = @userId
    BEGIN
        SELECT Id, Name, Age, IsAdmin
        FROM Users
        WHERE Id = @userId;
    END
    ELSE
    BEGIN
        RAISERROR('Unauthorized access', 16, 1);
    END
END;

Ejemplo de configuración de JSON:

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')",
    "options": {
      "set-session-context": true
    }
  },
  "entities": {
    "User": {
      "source": {
        "object": "dbo.GetUser",
        "type": "stored-procedure",
        "parameters": {
          "userId": "number"
        }
      },
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["execute"]
        }
      ]
    }
  }
}

Explicación:

procedimiento almacenado (GetUser):
- El procedimiento comprueba el SESSION_CONTEXT para validar si el autor de la llamada tiene el rol admin o coincide con el userId proporcionado.
- El acceso no autorizado produce un error.
de configuración JSON :
- set-session-context está habilitado para pasar metadatos de usuario desde el token de acceso a la base de datos.
- La propiedad parameters asigna el parámetro userId requerido por el procedimiento almacenado.
- El bloque permissions garantiza que solo los usuarios autenticados puedan ejecutar el procedimiento almacenado.

Archivos de origen de datos

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`$root`	`data-source-files`	matriz de cadenas	❌ No	Ninguno

Data API Builder admite varios archivos de configuración para distintos orígenes de datos, con uno designado como archivo de nivel superior que administra runtime configuración. Todas las configuraciones comparten el mismo esquema, lo que permite runtime valores en cualquier archivo sin errores. Las configuraciones secundarias se combinan automáticamente, pero se deben evitar las referencias circulares. Las entidades se pueden dividir en archivos independientes para una mejor administración, pero las relaciones entre entidades deben estar en el mismo archivo.

Diagrama de varios archivos de configuración a los que se hace referencia como una matriz dentro de un único archivo de configuración.

Formato

{
  "data-source-files": [ <string> ]
}

Consideraciones sobre archivos de configuración

Cada archivo de configuración debe incluir la propiedad data-source.
Cada archivo de configuración debe incluir la propiedad entities.
La configuración de runtime solo se usa desde el archivo de configuración de nivel superior, incluso si se incluye en otros archivos.
Los archivos de configuración secundarios también pueden incluir sus propios archivos secundarios.
Los archivos de configuración se pueden organizar en subcarpetas según sea necesario.
Los nombres de entidad deben ser únicos en todos los archivos de configuración.
No se admiten las relaciones entre entidades en archivos de configuración diferentes.

Ejemplos

{
  "data-source-files": [
    "dab-config-2.json"
  ]
}

{
  "data-source-files": [
    "dab-config-2.json", 
    "dab-config-3.json"
  ]
}

También se admite la sintaxis de subcarpeta:

{
  "data-source-files": [
    "dab-config-2.json",
    "my-folder/dab-config-3.json",
    "my-folder/my-other-folder/dab-config-4.json"
  ]
}

Ejecución

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`$root`	`runtime`	objeto	✔️ Sí	Ninguno

En la sección runtime se describen las opciones que influyen en el comportamiento y la configuración del entorno de ejecución para todas las entidades expuestas.

Formato

{
  "runtime": {
    "rest": {
      "path": <string> (default: /api),
      "enabled": <true> (default) | <false>,
      "request-body-strict": <true> (default) | <false>
    },
    "graphql": {
      "path": <string> (default: /graphql),
      "enabled": <true> (default) | <false>,
      "allow-introspection": <true> (default) | <false>
    },
    "host": {
      "mode": "production" (default) | "development",
      "cors": {
        "origins": ["<array-of-strings>"],
        "allow-credentials": <true> | <false> (default)
      },
      "authentication": {
        "provider": "StaticWebApps" (default) | ...,
        "jwt": {
          "audience": "<client-id>",
          "issuer": "<issuer-url>"
        }
      }
    }
  },
  "cache": {
    "enabled": <true> | <false> (default),
    "ttl-seconds": <integer; default: 5>
  },
  "pagination": {
    "max-page-size": <integer; default: 100000>,
    "default-page-size": <integer; default: 100>,
    "max-response-size-mb": <integer; default: 158>
  },
  "telemetry": {
    "application-insights": {
      "connection-string": <string>,
      "enabled": <true> | <false> (default)
    }
  }
}

Propiedades

	Obligatorio	Tipo
`rest`	❌ No	objeto
`graphql`	❌ No	objeto
`host`	❌ No	objeto
`cache`	❌ No	objeto

Ejemplos

Este es un ejemplo de una sección en tiempo de ejecución con varios parámetros predeterminados comunes especificados.

{
  "runtime": {
    "rest": {
      "enabled": true,
      "path": "/api",
      "request-body-strict": true
    },
    "graphql": {
      "enabled": true,
      "path": "/graphql",
      "allow-introspection": true
    },
    "host": {
      "mode": "development",
      "cors": {
        "allow-credentials": false,
        "origins": [
          "*"
        ]
      },
      "authentication": {
        "provider": "StaticWebApps",
        "jwt": {
          "audience": "<client-id>",
          "issuer": "<identity-provider-issuer-uri>"
        }
      }
    },
    "cache": {
      "enabled": true,
      "ttl-seconds": 5
    },
    "pagination": {
      "max-page-size": -1 | <integer; default: 100000>,
      "default-page-size": -1 | <integer; default: 100>,
      "max-response-size-mb": <integer; default: 158>
    },
    "telemetry": {
      "application-insights": {
        "connection-string": "<connection-string>",
        "enabled": true
      }
    }
  }
}

GraphQL (runtime)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`runtime`	`graphql`	objeto	❌ No	Ninguno

Este objeto define si GraphQL está habilitado y el nombre que se usa para exponer la entidad como un tipo GraphQL. Este objeto es opcional y solo se usa si el nombre o la configuración predeterminados no son suficientes. En esta sección se describe la configuración global del punto de conexión de GraphQL.

Formato

{
  "runtime": {
    "graphql": {
      "path": <string> (default: /graphql),
      "enabled": <true> (default) | <false>,
      "depth-limit": <integer; default: none>,
      "allow-introspection": <true> (default) | <false>,
      "multiple-mutations": <object>
    }
  }
}

Propiedades

Propiedad	Obligatorio	Tipo	Predeterminado
`enabled`	❌ No	booleano	Verdadero
`path`	❌ No	cuerda	/graphql (valor predeterminado)
`allow-introspection`	❌ No	booleano	Verdadero
`multiple-mutations`	❌ No	objeto	{ create: { enabled: false } }

Habilitado (tiempo de ejecución de GraphQL)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`runtime.graphql`	`enabled`	booleano	❌ No	Ninguno

Define si se habilitan o deshabilitan los puntos de conexión de GraphQL globalmente. Si se deshabilita globalmente, no se puede acceder a ninguna entidad a través de solicitudes graphQL independientemente de la configuración de entidad individual.

Formato

{
  "runtime": {
    "graphql": {
      "enabled": <true> (default) | <false>
    }
  }
}

Ejemplos

En este ejemplo, el punto de conexión de GraphQL está deshabilitado para todas las entidades.

{
  "runtime": {
    "graphql": {
      "enabled": false
    }
  }
}

Límite de profundidad (tiempo de ejecución de GraphQL)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`runtime.graphql`	`depth-limit`	entero	❌ No	Ninguno

Profundidad máxima de consulta permitida de una consulta.

La capacidad de GraphQL para controlar consultas anidadas basadas en definiciones de relación es una característica increíble, lo que permite a los usuarios capturar datos complejos relacionados en una sola consulta. Sin embargo, a medida que los usuarios siguen agregando consultas anidadas, aumenta la complejidad de la consulta, lo que puede poner en peligro el rendimiento y la confiabilidad de la base de datos y el punto de conexión de API. Para administrar esta situación, la propiedad runtime/graphql/depth-limit establece la profundidad máxima permitida de una consulta GraphQL (y mutación). Esta propiedad permite a los desarrolladores alcanzar un equilibrio, lo que permite a los usuarios disfrutar de las ventajas de las consultas anidadas mientras se colocan límites para evitar escenarios que podrían poner en peligro el rendimiento y la calidad del sistema.

Ejemplos

{
  "runtime": {
    "graphql": {
      "depth-limit": 2
    }
  }
}

Ruta de acceso (tiempo de ejecución de GraphQL)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`runtime.graphql`	`path`	cuerda	❌ No	"/graphql"

Define la ruta de acceso de dirección URL en la que está disponible el punto de conexión de GraphQL. Por ejemplo, si este parámetro se establece en /graphql, el punto de conexión de GraphQL se expone como /graphql. De forma predeterminada, la ruta de acceso es /graphql.

Importante

No se permiten rutas de acceso secundarias para esta propiedad. Un valor de ruta de acceso personalizado para el punto de conexión de GraphQL no está disponible actualmente.

Formato

{
  "runtime": {
    "graphql": {
      "path": <string> (default: /graphql)
    }
  }
}

Ejemplos

En este ejemplo, el URI raíz de GraphQL es /query.

{
  "runtime": {
    "graphql": {
      "path": "/query"
    }
  }
}

Permitir introspección (runtime de GraphQL)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`runtime.graphql`	`allow-introspection`	booleano	❌ No	Verdadero

Esta marca booleana controla la capacidad de realizar consultas de introspección de esquema en el punto de conexión de GraphQL. Habilitar la introspección permite a los clientes consultar el esquema para obtener información sobre los tipos de datos disponibles, los tipos de consultas que pueden realizar y las mutaciones disponibles.

Esta característica es útil durante el desarrollo para comprender la estructura de GraphQL API y para las herramientas que generan automáticamente consultas. Sin embargo, para entornos de producción, podría deshabilitarse para ocultar los detalles del esquema de la API y mejorar la seguridad. De forma predeterminada, la introspección está habilitada, lo que permite una exploración inmediata y completa del esquema GraphQL.

Formato

{
  "runtime": {
    "graphql": {
      "allow-introspection": <true> (default) | <false>
    }
  }
}

Ejemplos

En este ejemplo, la introspección está deshabilitada.

{
  "runtime": {
    "graphql": {
      "allow-introspection": false
    }
  }
}

Varias mutaciones (runtime de GraphQL)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`runtime.graphql`	`multiple-mutations`	objeto	❌ No	Ninguno

Configura todas las operaciones de mutación múltiples para el entorno de ejecución de GraphQL.

Nota

De forma predeterminada, no se habilitan varias mutaciones y se deben configurar explícitamente para habilitarse.

Formato

{
  "runtime": {
    "graphql": {
      "multiple-mutations": {
        "create": {
          "enabled": <true> (default) | <false>
        }
      }
    }
  }
}

Propiedades

	Obligatorio	Tipo
`create`	❌ No	objeto

Varias mutaciones: creación (runtime de GraphQL)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`runtime.graphql.multiple-mutations`	`create`	booleano	❌ No	Falso

Configura varias operaciones de creación para el entorno de ejecución de GraphQL.

Formato

{
  "runtime": {
    "graphql": {
      "multiple-mutations": {
        "create": {
          "enabled": <true> (default) | <false>
        }
      }
    }
  }
}

Propiedades

Propiedad	Obligatorio	Tipo	Predeterminado
`enabled`	✔️ Sí	booleano	Verdadero

Ejemplos

A continuación se muestra cómo habilitar y usar varias mutaciones en el entorno de ejecución de GraphQL. En este caso, la operación create está configurada para permitir la creación de varios registros en una sola solicitud estableciendo la propiedad runtime.graphql.multiple-mutations.create.enabled en true.

Ejemplo de configuración

Esta configuración habilita varias mutaciones create:

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

Ejemplo de mutación de GraphQL

Con la configuración anterior, la siguiente mutación crea varios registros de User en una sola operación:

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)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`runtime`	`rest`	objeto	❌ No	Ninguno

En esta sección se describe la configuración global de los puntos de conexión REST. Estas opciones de configuración sirven como valores predeterminados para todas las entidades, pero se pueden invalidar por entidad en sus respectivas configuraciones.

Formato

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

Propiedades

Propiedad	Obligatorio	Tipo	Predeterminado
`enabled`	❌ No	booleano	Verdadero
`path`	❌ No	cuerda	/API
`request-body-strict`	❌ No	booleano	Verdadero

Habilitado (tiempo de ejecución de REST)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`runtime.rest`	`enabled`	booleano	❌ No	Ninguno

Marca booleana que determina la disponibilidad global de los puntos de conexión REST. Si está deshabilitado, no se puede acceder a las entidades a través de REST, independientemente de la configuración de entidad individual.

Formato

{
  "runtime": {
    "rest": {
      "enabled": <true> (default) | <false>,
    }
  }
}

Ejemplos

En este ejemplo, el punto de conexión de la API REST está deshabilitado para todas las entidades.

{
  "runtime": {
    "rest": {
      "enabled": false
    }
  }
}

Ruta de acceso (tiempo de ejecución de REST)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`runtime.rest`	`path`	cuerda	❌ No	"/api"

Establece la ruta de acceso url para acceder a todos los puntos de conexión REST expuestos. Por ejemplo, establecer path en /api hace que el punto de conexión REST sea accesible en /api/<entity>. No se permiten subrutas. Este campo es opcional, con /api como valor predeterminado.

Nota

Al implementar data API Builder mediante Static Web Apps (versión preliminar), el servicio de Azure inserta automáticamente la subruta adicional /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>. Esto solo es relevante para Static Web Apps.

Formato

{
  "runtime": {
    "rest": {
      "path": <string> (default: /api)
    }
  }
}

Importante

Las sub rutas de acceso proporcionadas por el usuario no están permitidas para esta propiedad.

Ejemplos

En este ejemplo, el URI de la API REST raíz es /data.

{
  "runtime": {
    "rest": {
      "path": "/data"
    }
  }
}

Propina

Si define una entidad Author, el punto de conexión de esta entidad sería /data/Author.

Request Body Strict (tiempo de ejecución rest)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`runtime.rest`	`request-body-strict`	booleano	❌ No	Verdadero

Esta configuración controla cómo se valida el cuerpo de la solicitud para las operaciones de mutación rest (por ejemplo, POST, PUT, PATCH).

true (valor predeterminado): los campos adicionales del cuerpo de la solicitud que no se asignan a columnas de tabla provocan una excepción de BadRequest.
false: se omiten los campos adicionales y solo se procesan las columnas válidas.

Esta configuración no se aplica a las solicitudes de GET, ya que su cuerpo de solicitud siempre se omite.

Comportamiento con configuraciones de columna específicas

Las columnas con un valor default() se omiten durante INSERT solo cuando su valor en la carga es null. Las columnas con un valor default() no se omiten durante UPDATE independientemente del valor de carga.
Las columnas calculadas siempre se omiten.
Las columnas generadas automáticamente siempre se omiten.

Formato

{
  "runtime": {
    "rest": {
      "request-body-strict": <true> (default) | <false>
    }
  }
}

Ejemplos

CREATE TABLE Users (
    Id INT PRIMARY KEY IDENTITY,
    Name NVARCHAR(50) NOT NULL,
    Age INT DEFAULT 18,
    IsAdmin BIT DEFAULT 0,
    IsMinor AS IIF(Age <= 18, 1, 0)
);

Configuración de ejemplo

{
  "runtime": {
    "rest": {
      "request-body-strict": false
    }
  }
}

Comportamiento INSERT con `request-body-strict: false`

de carga de solicitud :

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

instrucción insert resultante:

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 con `request-body-strict: false`

de carga de solicitud :

{
  "Id": 1,
  "Name": "Alice Updated",
  "Age": null,     // explicitely set to 'null'
  "IsMinor": true, // ignored because computed
  "ExtraField": "ignored"
}

instrucción update resultante:

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

Host (tiempo de ejecución)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`runtime`	`host`	objeto	❌ No	Ninguno

La sección host de la configuración en tiempo de ejecución proporciona la configuración fundamental para el entorno operativo del generador de DATA API. Estas opciones incluyen modos operativos, configuración de CORS y detalles de autenticación.

Formato

{
  "runtime": {
    "host": {
      "mode": "production" (default) | "development",
      "max-response-size-mb": <integer; default: 158>,
      "cors": {
        "origins": ["<array-of-strings>"],
        "allow-credentials": <true> | <false> (default)
      },
      "authentication": {
        "provider": "StaticWebApps" (default) | ...,
        "jwt": {
          "audience": "<client-id>",
          "issuer": "<issuer-url>"
        }
      }
    }
  }
}

Propiedades

Propiedad	Obligatorio	Tipo	Predeterminado
`mode`	❌ No	enum string	producción
`cors`	❌ No	objeto	Ninguno
`authentication`	❌ No	objeto	Ninguno

Ejemplos

Este es un ejemplo de un entorno de ejecución configurado para el hospedaje de desarrollo.

{
  "runtime": {
    "host": {
      "mode": "development",
      "cors": {
        "allow-credentials": false,
        "origins": ["*"]
      },
      "authentication": {
        "provider": "Simulator"
      }
    }
  }
}

Modo (tiempo de ejecución del host)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`runtime.host`	`mode`	cuerda	❌ No	"producción"

Define si el motor del generador de API de datos debe ejecutarse en modo development o production. El valor predeterminado es production.

Normalmente, los errores de base de datos subyacentes se exponen en detalle estableciendo el nivel de detalle predeterminado para los registros en Debug cuando se ejecuta en desarrollo. En producción, el nivel de detalle de los registros se establece en Error.

Propina

El nivel de registro predeterminado se puede invalidar aún más mediante dab start --LogLevel <level-of-detail>. Para obtener más información, consulte referencia de la interfaz de línea de comandos (CLI).

Formato

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

Valores

Esta es una lista de valores permitidos para esta propiedad:

	Descripción
`production`	Uso al hospedar en producción en Azure
`development`	Uso en el desarrollo en la máquina local

Comportamientos

Solo en modo development está disponible Swagger.
Solo en development modo está disponible Banana Cake Pop.

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

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`runtime.host`	`max-response-size-mb`	entero	❌ No	158

Establece el tamaño máximo (en megabytes) para cualquier resultado determinado. Esta configuración permite a los usuarios configurar la cantidad de datos que la memoria de su plataforma host puede controlar al transmitir datos desde los orígenes de datos subyacentes.

Cuando los usuarios solicitan grandes conjuntos de resultados, puede forzar la base de datos y el generador de Data API. Para solucionar esto, max-response-size-mb permite a los desarrolladores limitar el tamaño máximo de respuesta, medido en megabytes, a medida que los flujos de datos del origen de datos. Este límite se basa en el tamaño general de los datos, no en el número de filas. Dado que las columnas pueden variar de tamaño, algunas columnas (como texto, binario, XML o JSON) pueden contener hasta 2 GB cada una, lo que hace que las filas individuales sean potencialmente muy grandes. Esta configuración ayuda a los desarrolladores a proteger sus puntos de conexión limitando los tamaños de respuesta y evitando sobrecargas del sistema, a la vez que mantiene la flexibilidad de los distintos tipos de datos.

Valores permitidos

Valor	Resultado
`null`	El valor predeterminado es 158 megabytes si no se establece o establece explícitamente en `null`.
`integer`	Se admite cualquier entero positivo de 32 bits.
`< 0`	No se admite. Los errores de validación se producen si se establece en menos de 1 MB.

Formato

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

CORS (tiempo de ejecución de host)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`runtime.host`	`cors`	objeto	❌ No	Ninguno

Configuración de uso compartido de recursos entre orígenes (CORS) para el host del motor del generador de datos.

Formato

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

Propiedades

	Obligatorio	Tipo
`allow-credentials`	❌ No	booleano
`origins`	❌ No	matriz de cadenas

Permitir credenciales (tiempo de ejecución de host)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`runtime.host.cors`	`allow-credentials`	booleano	❌ No	Falso

Si es true, establece el encabezado CORS de Access-Control-Allow-Credentials.

Nota

Para obtener más información sobre el Access-Control-Allow-Credentials encabezado CORS, vea Referencia de CORS de documentos web de MDN.

Formato

{
  "runtime": {
    "host": {
      "cors": {
        "allow-credentials": <true> (default) | <false>
      }
    }
  }
}

Orígenes (tiempo de ejecución de host)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`runtime.host.cors`	`origins`	matriz de cadenas	❌ No	Ninguno

Establece una matriz con una lista de orígenes permitidos para CORS. Esta configuración permite el * comodín para todos los orígenes.

Formato

{
  "runtime": {
    "host": {
      "cors": {
        "origins": ["<array-of-strings>"]
      }
    }
  }
}

Ejemplos

Este es un ejemplo de un host que permite CORS sin credenciales de todos los orígenes.

{
  "runtime": {
    "host": {
      "cors": {
        "allow-credentials": false,
        "origins": ["*"]
      }
    }
  }
}

Autenticación (entorno de ejecución de host)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`runtime.host`	`authentication`	objeto	❌ No	Ninguno

Configura la autenticación para el host de Data API Builder.

Formato

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "StaticWebApps" (default) | ...,
        "jwt": {
          "audience": "<string>",
          "issuer": "<string>"
        }
      }
    }
  }
}

Propiedades

Propiedad	Obligatorio	Tipo	Predeterminado
`provider`	❌ No	enum string	StaticWebApps
`jwt`	❌ No	objeto	Ninguno

la autenticación y las responsabilidades del cliente

Data API Builder está diseñado para funcionar dentro de una canalización de seguridad más amplia y hay pasos importantes para configurar antes de procesar las solicitudes. Es importante comprender que Data API Builder no autentica al autor de la llamada directa (como la aplicación web), sino al usuario final, en función de un token JWT válido proporcionado por un proveedor de identidades de confianza (por ejemplo, Id. de Entra). Cuando una solicitud llega a Data API Builder, supone que el token JWT es válido y lo comprueba con los requisitos previos configurados, como notificaciones específicas. A continuación, se aplican reglas de autorización para determinar a qué puede acceder o modificar el usuario.

Una vez superada la autorización, Data API Builder ejecuta la solicitud mediante la cuenta especificada en la cadena de conexión. Dado que esta cuenta a menudo requiere permisos elevados para controlar varias solicitudes de usuario, es esencial minimizar sus derechos de acceso para reducir el riesgo. Se recomienda proteger la arquitectura mediante la configuración de Un vínculo privado entre la aplicación web de front-end y el punto de conexión de API, y al proteger la máquina que hospeda data API Builder. Estas medidas ayudan a garantizar que el entorno permanezca seguro, protegiendo los datos y minimizando las vulnerabilidades que podrían aprovecharse para acceder, modificar o filtrar información confidencial.

Proveedor (tiempo de ejecución de host)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`runtime.host.authentication`	`provider`	cuerda	❌ No	"StaticWebApps"

La configuración de authentication.provider dentro de la configuración de host define el método de autenticación que usa el generador de Data API. Determina cómo valida la API la identidad de los usuarios o servicios que intentan acceder a sus recursos. Esta configuración permite flexibilidad en la implementación e integración, ya que admite varios mecanismos de autenticación adaptados a distintos entornos y requisitos de seguridad.

Proveedor	Descripción
`StaticWebApps`	Indica al generador de Data API que busque un conjunto de encabezados HTTP que solo estén presentes al ejecutarse dentro de un entorno de Static Web Apps.
`AppService`	Cuando el entorno de ejecución se hospeda en Azure AppService con la autenticación de AppService habilitada y configurada (EasyAuth).
`AzureAd`	Microsoft Entra Identity debe configurarse para que pueda autenticar una solicitud enviada a Data API Builder (la "aplicación de servidor"). Para obtener más información, consulte autenticación de Id. de Entra de Microsoft.
`Simulator`	Proveedor de autenticación configurable que indica al motor del generador de DATA API que trate todas las solicitudes como autenticadas. Para obtener más información, consulte autenticación local.

Formato

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "StaticWebApps" (default) | ...
      }
    }
  }
}

Valores

Esta es una lista de valores permitidos para esta propiedad:

	Descripción
`StaticWebApps`	Azure Static Web Apps
`AppService`	Azure App Service
`AzureAD`	Microsoft Entra ID
`Simulator`	Simulador

JSON Web Tokens (tiempo de ejecución de host)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`runtime.host.authentication`	`jwt`	objeto	❌ No	Ninguno

Si el proveedor de autenticación está establecido en AzureAD (Id. de Entra de Microsoft), esta sección es necesaria para especificar la audiencia y los emisores para el token JSOn Web Tokens (JWT). Estos datos se usan para validar los tokens en el inquilino de Microsoft Entra.

Obligatorio si el proveedor de autenticación es AzureAD para el identificador de Microsoft Entra. Esta sección debe especificar el audience y el issuer para validar el token JWT recibido en el inquilino de AzureAD previsto para la autenticación.

Ajuste	Descripción
audiencia	Identifica el destinatario previsto del token; Normalmente, el identificador de la aplicación registrado en Microsoft Entra Identity (o su proveedor de identidades), lo que garantiza que el token se emitió realmente para la aplicación.
Emisor	Especifica la dirección URL de la entidad emisora, que es el servicio de token que emitió el JWT. Esta dirección URL debe coincidir con la dirección URL del emisor del proveedor de identidades desde la que se obtuvo el JWT, validando el origen del token.

Formato

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "StaticWebApps" (default) | ...,
        "jwt": {
          "audience": "<client-id>",
          "issuer": "<issuer-url>"
        }
      }
    }
  }
}

Propiedades

Propiedad	Obligatorio	Tipo	Predeterminado
`audience`	❌ No	cuerda	Ninguno
`issuer`	❌ No	cuerda	Ninguno

Ejemplos

Data API Builder (DAB) ofrece compatibilidad de autenticación flexible, integración con microsoft Entra Identity y servidores JSON Web Token (JWT) personalizados. En esta imagen, el servidor JWT de representa el servicio de autenticación que emite tokens JWT a los clientes tras iniciar sesión correctamente. A continuación, el cliente pasa el token a DAB, que puede interrogar sus notificaciones y propiedades.

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

A continuación se muestran ejemplos de la propiedad host dadas varias opciones arquitectónicas que podría tomar en la solución.

Azure Static Web Apps

{
 "host": {
  "mode": "development",
  "cors": {
   "origins": ["https://dev.example.com"],
   "credentials": true
  },
  "authentication": {
   "provider": "StaticWebApps"
  }
 }
}

Con StaticWebApps, Data API Builder espera que Azure Static Web Apps autentique la solicitud y el encabezado HTTP de X-MS-CLIENT-PRINCIPAL esté presente.

Azure App Service

{
 "host": {
  "mode": "production",
  "cors": {
   "origins": [ "https://api.example.com" ],
   "credentials": false
  },
  "authentication": {
   "provider": "AppService",
   "jwt": {
    "audience": "9e7d452b-7e23-4300-8053-55fbf243b673",
    "issuer": "https://example-appservice-auth.com"
   }
  }
 }
}

La autenticación se delega en un proveedor de identidades compatible en el que se puede emitir el token de acceso. Un token de acceso adquirido debe incluirse con las solicitudes entrantes a Data API Builder. Después, data API Builder valida los tokens de acceso presentados, lo que garantiza que Data API Builder era la audiencia prevista del token.

Microsoft Entra ID

{
 "host": {
  "mode": "production",
  "cors": {
   "origins": [ "https://api.example.com" ],
   "credentials": true
  },
  "authentication": {
   "provider": "AzureAD",
   "jwt": {
    "audience": "c123d456-a789-0abc-a12b-3c4d56e78f90",
    "issuer": "https://login.microsoftonline.com/98765f43-21ba-400c-a5de-1f2a3d4e5f6a/v2.0"
   }
  }
 }
}

Simulador (solo desarrollo)

{
 "host": {
  "mode": "development",
  "authentication": {
   "provider": "Simulator"
  }
 }
}

Audiencia (tiempo de ejecución de host)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`runtime.host.authentication.jwt`	`audience`	cuerda	❌ No	Ninguno

Audiencia del token JWT.

Formato

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

Emisor (tiempo de ejecución de host)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`runtime.host.authentication.jwt`	`issuer`	cuerda	❌ No	Ninguno

Emisor del token JWT.

Formato

{
  "runtime": {
    "host": {
      "authentication": {
        "jwt": {
          "issuer": "<issuer-url>"
        }
      }
    }
  }
}

Paginación (tiempo de ejecución)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`runtime`	`pagination`	objeto	❌ No	Ninguno

Configura los límites de paginación para los puntos de conexión REST y GraphQL.

Formato

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

Propiedades

Propiedad	Obligatorio	Tipo	Predeterminado
`max-page-size`	❌ No	entero	100,000
`default-page-size`	❌ No	entero	100

Configuración de ejemplo

{
  "runtime": {
    "pagination": {
      "max-page-size": 1000,
      "default-page-size": 2
    }
  },
  "entities": {
    "Users": {
      "source": "dbo.Users",
      "permissions": [
        {
          "actions": ["read"],
          "role": "anonymous"
        }
      ]
    }
  }
}

Ejemplo de paginación rest

En este ejemplo, la emisión de la solicitud REST GET https://localhost:5001/api/users devolvería dos registros en la matriz value porque el default-page-size está establecido en 2. Si existen más resultados, Data API Builder incluye un nextLink en la respuesta. El nextLink contiene un parámetro $after para recuperar la página siguiente de datos.

Pedir:

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

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

Con el nextLink, el cliente puede capturar el siguiente conjunto de resultados.

Ejemplo de paginación de GraphQL

En GraphQL, use los campos hasNextPage y endCursor para la paginación. Estos campos indican si hay más resultados disponibles y proporcionan un cursor para capturar la página siguiente.

Consulta:

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

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

Para capturar la página siguiente, incluya el valor de endCursor en la siguiente consulta:

Consulta con cursor:

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

Ajustar el tamaño de página

REST y GraphQL permiten ajustar el número de resultados por consulta mediante $limit (REST) o first (GraphQL).

valor de `$limit`/`first`	Comportamiento
`-1`	Su valor predeterminado es `max-page-size`.
`< max-page-size`	Limita los resultados al valor especificado.
`0` o `< -1`	No se admite.
`> max-page-size`	Limitado en `max-page-size`.

Consulta REST de ejemplo:

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

Consulta graphQL de ejemplo:

query {
  users(first: 5) {
    items {
      Id
      Name
      Age
      IsAdmin
      IsMinor
    }
  }
}

Tamaño máximo de página (tiempo de ejecución de paginación)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`runtime.pagination`	`max-page-size`	Int	❌ No	100,000

Establece el número máximo de registros de nivel superior devueltos por REST o GraphQL. Si un usuario solicita más de max-page-size, los resultados se limitan a max-page-size.

Valores permitidos

Valor	Resultado
`-1`	El valor predeterminado es el valor máximo admitido.
`integer`	Se admite cualquier entero positivo de 32 bits.
`< -1`	No se admite.
`0`	No se admite.

Formato

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

Tamaño de página predeterminado (tiempo de ejecución de paginación)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`runtime.pagination`	`default-page-size`	Int	❌ No	100

Establece el número predeterminado de registros de nivel superior devueltos cuando la paginación está habilitada, pero no se proporciona ningún tamaño de página explícito.

Valores permitidos

Valor	Resultado
`-1`	El valor predeterminado es el valor de `max-page-size` actual.
`integer`	Cualquier entero positivo menor que el `max-page-size`actual.
`< -1`	No se admite.
`0`	No se admite.

Caché (tiempo de ejecución)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`runtime`	`cache`	objeto	❌ No	Ninguno

Habilita y configura el almacenamiento en caché para todo el tiempo de ejecución.

Formato

{
  "runtime": {
    "cache": <object>
  }
}

Propiedades

Propiedad	Obligatorio	Tipo	Predeterminado
`enabled`	❌ No	booleano	Ninguno
`ttl-seconds`	❌ No	entero	5

Ejemplos

En este ejemplo, la memoria caché está habilitada y los elementos expiran después de 30 segundos.

{
  "runtime": {
    "cache": {
      "enabled": true,
      "ttl-seconds": 30
    }
  }
}

Habilitado (tiempo de ejecución de caché)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`runtime.cache`	`enabled`	booleano	❌ No	Falso

Habilita el almacenamiento en caché globalmente para todas las entidades. Su valor predeterminado es false.

Formato

{
  "runtime": {
    "cache":  {
      "enabled": <boolean>
    }
  }
}

Ejemplos

En este ejemplo, la memoria caché está deshabilitada.

{
  "runtime": {
    "cache": {
      "enabled": false
    }
  }
}

TTL en segundos (tiempo de ejecución de caché)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`runtime.cache`	`ttl-seconds`	entero	❌ No	5

Configura el valor de período de vida (TTL) en segundos para los elementos almacenados en caché. Una vez transcurrido este tiempo, los elementos se eliminan automáticamente de la memoria caché. El valor predeterminado es 5 segundos.

Formato

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

Ejemplos

En este ejemplo, la memoria caché está habilitada globalmente y todos los elementos expiran después de 15 segundos.

{
  "runtime": {
    "cache": {
      "enabled": true,
      "ttl-seconds": 15
    }
  }
}

Telemetría (tiempo de ejecución)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`runtime`	`telemetry`	objeto	❌ No	Ninguno

Esta propiedad configura Application Insights para centralizar los registros de API. Obtenga información más.

Formato

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

Application Insights (tiempo de ejecución de telemetría)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`runtime.telemetry`	`application-insights`	objeto	✔️ Sí	Ninguno

Habilitado (telemetría de Application Insights)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`runtime.telemetry.application-insights`	`enabled`	booleano	❌ No	Verdadero

Cadena de conexión (telemetría de Application Insights)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`runtime.telemetry.application-insights`	`connection-string`	cuerda	✔️ Sí	Ninguno

Entidades

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`$root`	`entities`	objeto	✔️ Sí	Ninguno

La sección entities actúa como el núcleo del archivo de configuración, estableciendo un puente entre los objetos de base de datos y sus puntos de conexión de API correspondientes. En esta sección se asignan objetos de base de datos a puntos de conexión expuestos. En esta sección también se incluyen la asignación de propiedades y la definición de permisos. Cada entidad expuesta se define en un objeto dedicado. El nombre de propiedad del objeto se usa como nombre de la entidad que se va a exponer.

En esta sección se define cómo se representa cada entidad de la base de datos en la API, incluidas las asignaciones de propiedades y los permisos. Cada entidad se encapsula dentro de su propia subsección, con el nombre de la entidad que actúa como clave de referencia en toda la configuración.

Formato

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "enabled": <true; default: true> | <false>,
        "path": <string; default: "<entity-name>">,
        "methods": <array of strings; default: ["GET", "POST"]>
      },
      "graphql": {
        "enabled": <true; default: true> | <false>,
        "type": {
          "singular": <string>,
          "plural": <string>
        },
        "operation": <"query" | "mutation"; default: "query">
      },
      "source": {
        "object": <string>,
        "type": <"view" | "stored-procedure" | "table">,
        "key-fields": <array of strings>,
        "parameters": {
          "<parameter-name>": <string | number | boolean>
        }
      },
      "mappings": {
        "<database-field-name>": <string>
      },
      "relationships": {
        "<relationship-name>": {
          "cardinality": <"one" | "many">,
          "target.entity": <string>,
          "source.fields": <array of strings>,
          "target.fields": <array of strings>,
          "linking.object": <string>,
          "linking.source.fields": <array of strings>,
          "linking.target.fields": <array of strings>
        }
      },
      "permissions": [
        {
          "role": <"anonymous" | "authenticated" | "custom-role-name">,
          "actions": <array of strings>,
          "fields": {
            "include": <array of strings>,
            "exclude": <array of strings>
          },
          "policy": {
            "database": <string>
          }
        }
      ]
    }
  }
}

Propiedades

	Obligatorio	Tipo
`source`	✔️ Sí	objeto
`permissions`	✔️ Sí	arreglo
`rest`	❌ No	objeto
`graphql`	❌ No	objeto
`mappings`	❌ No	objeto
`relationships`	❌ No	objeto
`cache`	❌ No	objeto

Ejemplos

Por ejemplo, este objeto JSON indica al generador de Data API que exponga una entidad GraphQL denominada User y un punto de conexión REST accesible a través de la ruta de acceso de /User. La tabla de base de datos dbo.User respalda la entidad y la configuración permite a cualquier persona acceder al punto de conexión de forma anónima.

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["*"]
        }
      ]
    }
  }
}

En este ejemplo se declara la entidad User. Este nombre User se usa en cualquier lugar del archivo de configuración en el que se hace referencia a las entidades. De lo contrario, el nombre de la entidad no es relevante para los puntos de conexión.

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table",
        "key-fields": ["Id"],
        "parameters": {} // only when source.type = stored-procedure
      },
      "rest": {
        "enabled": true,
        "path": "/users",
        "methods": [] // only when source.type = stored-procedure
      },
      "graphql": {
        "enabled": true,
        "type": {
          "singular": "User",
          "plural": "Users"
        },
        "operation": "query"
      },
      "mappings": {
        "id": "Id",
        "name": "Name",
        "age": "Age",
        "isAdmin": "IsAdmin"
      },
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"],  // "execute" only when source.type = stored-procedure
          "fields": {
            "include": ["id", "name", "age", "isAdmin"],
            "exclude": []
          },
          "policy": {
            "database": "@claims.userId eq @item.id"
          }
        },
        {
          "role": "admin",
          "actions": ["create", "read", "update", "delete"],
          "fields": {
            "include": ["*"],
            "exclude": []
          },
          "policy": {
            "database": "@claims.userRole eq 'UserAdmin'"
          }
        }
      ]
    }
  }
}

Fuente

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.{entity}`	`source`	objeto	✔️ Sí	Ninguno

La configuración de {entity}.source conecta la entidad expuesta a la API y su objeto de base de datos subyacente. Esta propiedad especifica la tabla de base de datos, la vista o el procedimiento almacenado que representa la entidad, estableciendo un vínculo directo para la recuperación y manipulación de datos.

Para escenarios sencillos en los que la entidad se asigna directamente a una sola tabla de base de datos, la propiedad de origen solo necesita el nombre de ese objeto de base de datos. Esta simplicidad facilita la configuración rápida para casos de uso comunes: "source": "dbo.User".

Formato

{
  "entities": {
    "<entity-name>": {
      "source": {
        "object": <string>,
        "type": <"view" | "stored-procedure" | "table">, 
        "key-fields": <array of strings>,
        "parameters": {  // only when source.type = stored-procedure
          "<name>": <string | number | boolean>
        }
      }
    }
  }
}

Propiedades

	Obligatorio	Tipo
`object`	✔️ Sí	cuerda
`type`	✔️ Sí	enum string
`parameters`	❌ No	objeto
`key-fields`	❌ No	matriz de cadenas

Ejemplos

1. Asignación de tabla simple:

En este ejemplo se muestra cómo asociar una entidad de User con una tabla de origen dbo.Users.

SQL

CREATE TABLE dbo.Users (
  Id INT PRIMARY KEY,
  Name NVARCHAR(100),
  Age INT,
  IsAdmin BIT
);

configuración de

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      }
    }
  }
}

2. Ejemplo de procedimiento almacenado:

En este ejemplo se muestra cómo asociar una entidad de User con un proceso de origen dbo.GetUsers.

SQL

CREATE PROCEDURE GetUsers 
     @IsAdmin BIT 
AS
SELECT Id, Name, Age, IsAdmin
FROM dbo.Users
WHERE IsAdmin = @IsAdmin;

configuración de

{
  "entities": {
    "User": {
      "source": {
        "type": "stored-procedure",
        "object": "GetUsers",
        "parameters": {
          "IsAdmin": "boolean"
        }
      },
      "mappings": {
        "Id": "id",
        "Name": "name",
        "Age": "age",
        "IsAdmin": "isAdmin"
      }
    }
  }
}

La propiedad mappings es opcional para los procedimientos almacenados.

Objeto

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.{entity}.source`	`object`	cuerda	✔️ Sí	Ninguno

Nombre del objeto de base de datos que se va a usar. Si el objeto pertenece al esquema de dbo, especificar el esquema es opcional. Además, los corchetes alrededor de los nombres de objeto (por ejemplo, [dbo].[Users] frente a dbo.Users) se pueden usar o omitir.

Ejemplos

SQL

CREATE TABLE dbo.Users (
  Id INT PRIMARY KEY,
  Name NVARCHAR(100),
  Age INT,
  IsAdmin BIT
);

configuración de

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      }
    }
  }
}

notación alternativa sin esquema y corchetes:

Si la tabla está en el esquema de dbo, puede omitir el esquema o corchetes:

{
  "entities": {
    "User": {
      "source": {
        "object": "Users",
        "type": "table"
      }
    }
  }
}

Tipo (entidades)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.{entity}.source`	`type`	cuerda	✔️ Sí	Ninguno

La propiedad type identifica el tipo de objeto de base de datos detrás de la entidad, incluidos view, tabley stored-procedure. Esta propiedad es necesaria y no tiene ningún valor predeterminado.

Formato

{
  "entities": {
    "<entity-name>": {
      "type": <"view" | "stored-procedure" | "table">
    }
  }
}

Valores

Valor	Descripción
`table`	Representa una tabla.
`stored-procedure`	Representa un procedimiento almacenado.
`view`	Representa una vista.

Ejemplos

1. Ejemplo de tabla:

SQL

CREATE TABLE dbo.Users (
  Id INT PRIMARY KEY,
  Name NVARCHAR(100),
  Age INT,
  IsAdmin BIT
);

configuración de

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      }
    }
  }
}

2. Ejemplo de vista:

SQL

CREATE VIEW dbo.AdminUsers AS
SELECT Id, Name, Age
FROM dbo.Users
WHERE IsAdmin = 1;

configuración de

{
  "entities": {
    "AdminUsers": {
      "source": {
        "object": "dbo.AdminUsers",
        "type": "view",
        "key-fields": ["Id"]
      },
      "mappings": {
        "Id": "id",
        "Name": "name",
        "Age": "age"
      }
    }
  }
}

Nota: Especificar key-fields es importante para las vistas porque carecen de claves principales inherentes.

3. Ejemplo de procedimiento almacenado:

SQL

CREATE PROCEDURE dbo.GetUsers (@IsAdmin BIT)
AS
SELECT Id, Name, Age, IsAdmin
FROM dbo.Users
WHERE IsAdmin = @IsAdmin;

configuración de

{
  "entities": {
    "User": {
      "source": {
        "type": "stored-procedure",
        "object": "GetUsers",
        "parameters": {
          "IsAdmin": "boolean"
        }
      }
    }
  }
}

Campos clave

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.{entity}.source`	`key-fields`	matriz de cadenas	❌ No	Ninguno

La propiedad {entity}.key-fields es especialmente necesaria para las entidades respaldadas por vistas, por lo que Data API Builder sabe cómo identificar y devolver un solo elemento. Si type se establece en view sin especificar key-fields, el motor se niega a iniciarse. Esta propiedad se permite con tablas y procedimientos almacenados, pero no se usa en esos casos.

Importante

Esta propiedad es necesaria si el tipo de objeto es un view.

Formato

{
  "entities": {
    "<entity-name>": {
      "source": {
        "type": <"view" | "stored-procedure" | "table">,
        "key-fields": <array of strings>
      }
    }
  }
}

Ejemplo: Ver con campos de clave

En este ejemplo se usa la vista dbo.AdminUsers con Id indicado como campo de clave.

SQL

CREATE VIEW dbo.AdminUsers AS
SELECT Id, Name, Age
FROM dbo.Users
WHERE IsAdmin = 1;

configuración de

{
  "entities": {
    "AdminUsers": {
      "source": {
        "object": "dbo.AdminUsers",
        "type": "view",
        "key-fields": ["Id"]
      }
    }
  }
}

Parámetros

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.{entity}.source`	`parameters`	objeto	❌ No	Ninguno

La propiedad parameters dentro de entities.{entity}.source se usa para las entidades respaldadas por procedimientos almacenados. Garantiza la asignación adecuada de los nombres de parámetros y los tipos de datos requeridos por el procedimiento almacenado.

Importante

La propiedad parameters es necesaria si se type el stored-procedure del objeto y se requiere el parámetro .

Formato

{
  "entities": {
    "<entity-name>": {
      "source": {
        "type": "stored-procedure",
        "parameters": {
          "<parameter-name-1>": <string | number | boolean>,
          "<parameter-name-2>": <string | number | boolean>
        }
      }
    }
  }
}

Ejemplo 1: Procedimiento almacenado sin parámetros

SQL

CREATE PROCEDURE dbo.GetUsers AS
SELECT Id, Name, Age, IsAdmin FROM dbo.Users;

configuración de

{
  "entities": {
    "Users": {
      "source": {
        "object": "dbo.GetUsers",
        "type": "stored-procedure"
      }
    }
  }
}

Ejemplo 2: Procedimiento almacenado con parámetros

SQL

CREATE PROCEDURE dbo.GetUser (@userId INT) AS
SELECT Id, Name, Age, IsAdmin FROM dbo.Users
WHERE Id = @userId;

configuración de

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.GetUser",
        "type": "stored-procedure",
        "parameters": {
          "userId": "number"
        }
      }
    }
  }
}

Permisos

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.{entity}`	`permissions`	objeto	✔️ Sí	Ninguno

En esta sección se define quién puede acceder a la entidad relacionada y qué acciones se permiten. Los permisos se definen en términos de roles y operaciones CRUD: create, read, updatey delete. La sección permissions especifica qué roles pueden tener acceso a la entidad relacionada y usar qué acciones.

Formato

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "actions": ["create", "read", "update", "delete", "execute", "*"]
        }
      ]
    }
  }
}

Acción	Descripción
`create`	Permite crear un nuevo registro en la entidad.
`read`	Permite leer o recuperar registros de la entidad.
`update`	Permite actualizar los registros existentes en la entidad.
`delete`	Permite eliminar registros de la entidad.
`execute`	Permite ejecutar un procedimiento almacenado o una operación.
`*`	Concede todas las operaciones CRUD aplicables.

Ejemplos

ejemplo 1: Rol anónimo en la entidad de usuario

En este ejemplo, el rol anonymous se define con acceso a todas las acciones posibles en la entidad User.

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["*"]
        }
      ]
    }
  }
}

ejemplo 2: Acciones mixtas para el rol anónimo

En este ejemplo se muestra cómo combinar acciones de matriz de cadenas y objetos para la entidad User.

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            { "action": "read" },
            "create"
          ]        
        }
      ]
    }
  }
}

rol anónimo: permite a los usuarios anónimos leer todos los campos excepto un campo hipotético confidencial (por ejemplo, secret-field). El uso de "include": ["*"] con "exclude": ["secret-field"] oculta secret-field al tiempo que permite el acceso a todos los demás campos.

rol autenticado: permite a los usuarios autenticados leer y actualizar campos específicos. Por ejemplo, incluir explícitamente id, namey age, pero excluir isAdmin puede demostrar cómo las exclusiones invalidan las inclusiones.

rol de administrador: los administradores pueden realizar todas las operaciones (*) en todos los campos sin exclusiones. Especificar "include": ["*"] con una matriz "exclude": [] vacía concede acceso a todos los campos.

Esta configuración:

"fields": {
  "include": [],
  "exclude": []
}

es eficazmente idéntico a:

"fields": {
  "include": ["*"],
  "exclude": []
}

Tenga en cuenta también esta configuración:

"fields": {
  "include": [],
  "exclude": ["*"]
}

Esto especifica que no se incluyen explícitamente campos y se excluyen todos los campos, que normalmente restringen el acceso por completo.

uso práctico: esta configuración puede parecer contraintuitiva, ya que restringe el acceso a todos los campos. Sin embargo, podría usarse en escenarios en los que un rol realiza determinadas acciones (como crear una entidad) sin tener acceso a ninguno de sus datos.

El mismo comportamiento, pero con una sintaxis diferente, sería:

"fields": {
  "include": ["Id", "Name"],
  "exclude": ["*"]
}

Esta configuración intenta incluir solo campos Id y Name, pero excluye todos los campos debido al carácter comodín de exclude.

Otra manera de expresar la misma lógica sería:

"fields": {
  "include": ["Id", "Name"],
  "exclude": ["Id", "Name"]
}

Dado que exclude tiene prioridad sobre include, especificar exclude: ["*"] significa que se excluyen todos los campos, incluso los de include. Por lo tanto, a primera vista, esta configuración puede parecer impedir que se pueda acceder a los campos.

The Reverse: si la intención es conceder acceso solo a los campos Id y Name, es más claro y confiable especificar solo los campos de la sección include sin usar un carácter comodín de exclusión:

"fields": {
  "include": ["Id", "Name"],
  "exclude": []
}

Propiedades

	Obligatorio	Tipo
`role`	✔️ Sí	cuerda
`actions` (matriz de cadenas) o `actions` (matriz de objetos)	✔️ Sí	matriz de objetos o cadenas

Rol

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.permissions`	`role`	cuerda	✔️ Sí	Ninguno

Cadena que contiene el nombre del rol al que se aplica el permiso definido. Los roles establecen el contexto de permisos en el que se debe ejecutar una solicitud. Para cada entidad definida en la configuración en tiempo de ejecución, puede definir un conjunto de roles y permisos asociados que determinen cómo se puede acceder a la entidad a través de puntos de conexión REST y GraphQL. Los roles no son aditivos.

Data API Builder evalúa las solicitudes en el contexto de un único rol:

Rol	Descripción
`anonymous`	No se presenta ningún token de acceso
`authenticated`	Se presenta un token de acceso válido
`<custom-role>`	Se presenta un token de acceso válido y el `X-MS-API-ROLE` encabezado HTTP especifica un rol presente en el token.

Formato

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "role": <"anonymous" | "authenticated" | "custom-role">,
          "actions": ["create", "read", "update", "delete", "execute", "*"],
          "fields": {
            "include": <array of strings>,
            "exclude": <array of strings>
          }
        }
      ]
    }
  }
}

Ejemplos

En este ejemplo se define un rol denominado reader solo con permisos de read en la entidad User.

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "reader",
          "actions": ["read"]
        }
      ]
    }
  }
}

Puede usar <custom-role> cuando se presenta un token de acceso válido y se incluye el encabezado HTTP de X-MS-API-ROLE, especificando un rol de usuario que también se incluye en la notificación de roles del token de acceso. A continuación se muestran ejemplos de solicitudes GET a la entidad User, incluido el token de portador de autorización y el encabezado X-MS-API-ROLE, en la base del punto de conexión DE REST /api en localhost mediante distintos idiomas.

HTTP
de C#
JavaScript/TypeScript
python

GET https://localhost:5001/api/User
Authorization: Bearer <your_access_token>
X-MS-API-ROLE: custom-role

using System.Net.Http;
using System.Net.Http.Headers;

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<your_access_token>");
client.DefaultRequestHeaders.Add("X-MS-API-ROLE", "custom-role");
var response = await client.GetAsync("https://localhost:5001/api/User");

const response = await fetch('https://localhost:5001/api/User', {
  headers: { 
    "Authorization": "Bearer <your_access_token>",
    "X-MS-API-ROLE": "custom-role"
  }
});

import requests

headers = {
  "Authorization": "Bearer <your_access_token>",
  "X-MS-API-ROLE": "custom-role"
}
response = requests.get('https://localhost:5001/api/User', headers=headers)
print(response.json())

Acciones (matriz de cadenas)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.permissions`	`actions`	oneOf [string, array]	✔️ Sí	Ninguno

Matriz de valores de cadena que detalla qué operaciones se permiten para el rol asociado. Para los objetos de base de datos table y view, los roles pueden usar cualquier combinación de acciones de create, read, updateo delete. En el caso de los procedimientos almacenados, los roles solo pueden tener la acción execute.

Acción	Operación SQL
`*`	Comodín, incluida la ejecución
`create`	Insertar una o varias filas
`read`	Selección de una o varias filas
`update`	Modificar una o varias filas
`delete`	Eliminar una o varias filas
`execute`	Ejecuta un procedimiento almacenado

Nota

En el caso de los procedimientos almacenados, la acción comodín (*) se expande solo a la acción execute. Para tablas y vistas, se expande a create, read, updatey delete.

Ejemplos

En este ejemplo se proporcionan permisos de create y read a un rol denominado contributor y delete permisos a un rol denominado auditor en la entidad User.

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "auditor",
          "actions": ["delete"]
        },
        {
          "role": "contributor",
          "actions": ["read", "create"]
        }
      ]
    }
  }
}

Otro ejemplo:

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "contributor",
          "actions": ["read", "create"]
        }
      ]
    }
  }
}

Acciones (matriz de objetos)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.permissions`	`actions`	matriz de cadenas	✔️ Sí	Ninguno

Matriz de objetos de acción que detalla las operaciones permitidas para el rol asociado. Para los objetos table y view, los roles pueden usar cualquier combinación de create, read, updateo delete. En el caso de los procedimientos almacenados, solo se permite execute.

Nota

En el caso de los procedimientos almacenados, la acción comodín (*) se expande solo a execute. En el caso de las tablas o vistas, se expande a create, read, updatey delete.

Formato

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "role": <string>,
          "actions": [
            {
              "action": <string>,
              "fields": <array of strings>,
              "policy": <object>
            }
          ]
        }
      ]
    }
  }
}

Propiedades

Propiedad	Obligatorio	Tipo	Predeterminado
`action`	✔️ Sí	cuerda	Ninguno
`fields`	❌ No	matriz de cadenas	Ninguno
`policy`	❌ No	objeto	Ninguno

Ejemplo

En este ejemplo solo se concede permiso read al rol de auditor en la entidad User, con restricciones de campo y directiva.

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "auditor",
          "actions": [
            {
              "action": "read",
              "fields": {
                "include": ["*"],
                "exclude": ["last_login"]
              },
              "policy": {
                "database": "@item.IsAdmin eq false"
              }
            }
          ]
        }
      ]
    }
  }
}

Acción

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.permissions.actions[]`	`action`	cuerda	✔️ Sí	Ninguno

Especifica la operación específica permitida en el objeto de base de datos.

Valores

	Mesas	Vistas	Procedimientos almacenados	Descripción
`create`	✔️ Sí	✔️ Sí	❌ No	Crear nuevos elementos
`read`	✔️ Sí	✔️ Sí	❌ No	Leer elementos existentes
`update`	✔️ Sí	✔️ Sí	❌ No	Actualizar o reemplazar elementos
`delete`	✔️ Sí	✔️ Sí	❌ No	Eliminar elementos
`execute`	❌ No	❌ No	✔️ Sí	Ejecución de operaciones mediante programación

Formato

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "role": "<role>",
          "actions": [
            {
              "action": "<string>",
              "fields": {
                "include": [/* fields */],
                "exclude": [/* fields */]
              },
              "policy": {
                "database": "<predicate>"
              }
            }
          ]
        }
      ]
    }
  }
}

Ejemplo

Este es un ejemplo en el que los usuarios de anonymous pueden execute un procedimiento almacenado y read de la tabla User.

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read"
            }
          ]
        }
      ]
    },
    "GetUser": {
      "source": {
        "object": "dbo.GetUser",
        "type": "stored-procedure",
        "parameters": {
          "userId": "number"
        }
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "execute"
            }
          ]
        }
      ]
    }
  }
}

Campos

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.permissions.actions[]`	`fields`	objeto	❌ No	Ninguno

Especificaciones granulares en las que se permite el acceso a campos específicos para el objeto de base de datos. El fields objeto contiene dos propiedades, include y exclude, para definir qué columnas de base de datos se permiten o restringen para una acción determinada.

Formato

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "role": "<role>",
          "actions": [
            {
              "action": "<string>",
              "fields": {
                "include": [/* array of strings */],
                "exclude": [/* array of strings */]
              },
              "policy": { /* object */ }
            }
          ]
        }
      ]
    }
  }
}

Ejemplos

SQL

CREATE TABLE dbo.Users (
  Id INT PRIMARY KEY,
  Name NVARCHAR(100),
  Age INT,
  IsAdmin BIT
);

configuración de

Esta configuración permite que el anonymous rol lea todos los campos de la User entidad, excepto IsAdmin, a la vez que permite la creación de nuevos User registros.

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "fields": {
                "include": ["*"],
                "exclude": ["IsAdmin"]
              }
            },
            {
              "action": "create"
            }
          ]
        }
      ]
    }
  }
}

Política

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.{entity}.permissions.actions[]`	`policy`	objeto	❌ No	Ninguno

La policy sección, definida por acción, establece reglas de seguridad de nivel de elemento que limitan los resultados devueltos de una solicitud. La database subsección denota una expresión similar a OData evaluada durante la ejecución de la consulta, que Data API Builder se traduce en un predicado de consulta.

Formato

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "role": "<role>",
          "actions": [
            {
              "action": "<string>",
              "policy": {
                "database": "<predicate>"
              }
            }
          ]
        }
      ]
    }
  }
}

Ejemplo básico

En este ejemplo se restringe la read acción del adultReader rol para que solo se devuelvan los usuarios anteriores a 18:

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      },
      "permissions": [
        {
          "role": "adultReader",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "@item.Age gt 18"
              }
            }
          ]
        }
      ]
    }
  }
}

Base de datos

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.{entity}.permissions[].actions[].policy`	`database`	cuerda	✔️ Sí	Ninguno

Descripción

La database propiedad de una directiva define una expresión similar a OData que Data API Builder traduce en un predicado SQL para filtrar los resultados durante la ejecución de la consulta. Esta expresión debe evaluarse para true que se devuelvan filas. Por ejemplo:

@item.Age gt 18 puede traducirse a WHERE Users.Age > 18.
@claims.userId eq @item.Id restringe los resultados a las filas en las que el identificador del usuario de las notificaciones coincide con el Id campo.

Directivas

@claims: accede a una notificación desde el token de acceso validado.
@item: representa un campo de la entidad para la que se define la directiva.

Nota

Cuando se usa la autenticación de Azure Static Web Apps (EasyAuth), solo hay determinados tipos de notificación (identityProvider, userId, userDetails, userRoles) disponibles.

Operadores de tipo OData admitidos

La expresión admite operadores como:

Lógico: and, , ornot
Comparación: eq, , gtlt
Negación numérica unaria: -

Por ejemplo, "@item.Age gt 18 and @item.Age lt 65" restringe los resultados a los usuarios de entre 19 y 64 años.

Restricciones de nombre de campo de entidad

Los campos deben comenzar con una letra o un carácter de subrayado (_), seguidos de hasta 127 letras, caracteres de subrayado o dígitos. Los campos que no siguen estas reglas no se pueden usar directamente en las directivas. Use la mappings sección para establecer alias de nombres de campo no compatibles con las referencias de directiva.

`mappings` Usar para campos no compatibles

Si los nombres de campo de entidad no cumplen las convenciones de nomenclatura de OData, defina alias en la mappings sección:

{
  "entities": {
    "<entity-name>": {
      "mappings": {
        "<original-field-name>": "<alias>",
        "...": "..."
      }
    }
  }
}

Esto crea alias compatibles para su uso en directivas y mejora la claridad entre los puntos de conexión.

Limitaciones

Las directivas solo se aplican a tablas y vistas; los procedimientos almacenados no pueden usarlos.
Las directivas filtran los resultados, pero no impiden la ejecución de consultas en la base de datos.
Solo se admite para acciones: create, read, updatey delete.
Los nombres de campo deben cumplir las convenciones de nomenclatura de OData. Use asignaciones para los campos de alias si es necesario.

Ejemplos

Considere una entidad denominada User dentro de una configuración de Data API que use directivas para restringir el acceso en función de la edad y la identidad del usuario.

SQL

CREATE TABLE dbo.Users (
  Id INT PRIMARY KEY,
  Name NVARCHAR(100),
  Age INT,
  IsAdmin BIT
);

Ejemplo 1: Age-Based Access

Esta configuración restringe el adultReader rol para que la read acción solo devuelva usuarios donde Age > 18.

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      },
      "permissions": [
        {
          "role": "adultReader",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "@item.Age gt 18"
              }
            }
          ]
        }
      ]
    }
  }
}

Ejemplo 2: Acceso basado en notificaciones

Esta configuración usa una notificación para restringir el selfReader rol para que los usuarios solo puedan leer sus propios registros si su userId notificación coincide con el Id campo.

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      },
      "permissions": [
        {
          "role": "selfReader",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "@claims.userId eq @item.Id"
              }
            }
          ]
        }
      ]
    }
  }
}

GraphQL (entidades)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.{entity}`	`graphql`	objeto	❌ No	Ninguno

Este objeto define el comportamiento de GraphQL de la entidad.

Formato

{
  "entities": {
    "<entity-name>": {
      "graphql": {
        "enabled": <true> (default) | <false>,
        "type": {
          "singular": <string>,
          "plural": <string>
        },
        "operation": "query" (default) | "mutation"
      }
    }
  }
}

Propiedades

Propiedad	Obligatorio	Tipo	Predeterminado
`enabled`	❌ No	booleano	Ninguno
`type`	❌ No	string o object	Ninguno
`operation`	❌ No	enum string	Ninguno

Ejemplos

Estos dos ejemplos son funcionalmente equivalentes, lo que permite GraphQL para la User entidad con la configuración predeterminada:

{
  "entities": {
    "User": {
      "graphql": {
        "enabled": true
      }
    }
  }
}

En este ejemplo, la entidad definida es User, lo que indica que estamos tratando con datos de usuario. La configuración de la User entidad dentro del segmento GraphQL especifica cómo se debe representar e interactuar con en un esquema GraphQL.

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      },
      "graphql": {
        "enabled": true,
        "type": {
          "singular": "User",
          "plural": "Users"
        },
        "operation": "query"
      }
    }
  }
}

Tipo (entidad GraphQL)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.{entity}.graphql`	`type`	objeto	❌ No	{entity-name}

Esta propiedad dicta la convención de nomenclatura de una entidad dentro del esquema graphQL. Especifica los formularios singulares y plurales, lo que proporciona control pormenorizado sobre la legibilidad del esquema y la experiencia del usuario.

Formato

{
  "entities": {
    "<entity-name>": {
      "graphql": {
        "type": {
          "singular": "<string>",
          "plural": "<string>"
        }
      }
    }
  }
}

Propiedades

Propiedad	Obligatorio	Tipo	Predeterminado
`singular`	❌ No	cuerda	Ninguno
`plural`	❌ No	cuerda	N/A (el valor predeterminado es singular)

Ejemplos

Si plural falta o se omite (como un valor escalar), Data API Builder intentará pluralizar automáticamente el nombre mediante reglas en inglés para la pluralización.

Nombres singulares y plurales explícitos:

{
  "entities": {
    "User": {
      "graphql": {
        "type": {
          "singular": "User",
          "plural": "Users"
        }
      }
    }
  }
}

Ejemplo de consulta de GraphQL:

{
  Users {
    items {
      id
      name
      age
      isAdmin
    }
  }
}

Respuesta JSON de ejemplo:

{
  "data": {
    "Users": {
      "items": [
        {
          "id": 1,
          "name": "Alice",
          "age": 30,
          "isAdmin": true
        },
        {
          "id": 2,
          "name": "Bob",
          "age": 25,
          "isAdmin": false
        }
        // ...
      ]
    }
  }
}

Operación (entidad GraphQL)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.{entity}.graphql`	`operation`	enum string	❌ No	mutación

Para las entidades asignadas a procedimientos almacenados, la operation propiedad designa si la operación GraphQL aparece bajo el Query tipo o Mutation . Esta configuración organiza el esquema lógicamente sin afectar a la funcionalidad.

Nota

Cuando {entity}.type se establece en stored-procedure, se crea automáticamente un nuevo tipo executeXXX GraphQL. La operation propiedad controla si este tipo se coloca en Query o Mutation. No hay ningún impacto funcional en función del valor elegido.

Formato

{
  "entities": {
    "<entity-name>": {
      "graphql": {
        "operation": "query" | "mutation"
      }
    }
  }
}

Valores

Valor	Descripción
`query`	El procedimiento almacenado se expone como una consulta
`mutation`	El procedimiento almacenado se expone como una mutación

Ejemplos

configuración de

{
  "entities": {
    "UserProcedure": {
      "graphql": {
        "operation": "query" // schema location
      },
      "source": {
        "object": "dbo.GetUser",
        "type": "stored-procedure",
        "parameters": {
          "userId": "number"
        }
      }
    }
  }
}

Resultado del esquema de GraphQL

Si operation se establece queryen , el esquema de GraphQL coloca el procedimiento en el Query tipo :

type Query {
  executeGetUserDetails(userId: Int!): GetUserDetailsResponse
}

Si se hubiera establecido en mutation, aparecería bajo el Mutation tipo :

type Mutation {
  executeGetUserDetails(userId: Int!): GetUserDetailsResponse
}

Nota

La operation propiedad afecta solo a la ubicación de la operación GraphQL en el esquema; no cambia el comportamiento de la operación.

Habilitado (entidad GraphQL)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.{entity}.graphql`	`enabled`	booleano	❌ No	Verdadero

Habilita o deshabilita el punto de conexión de GraphQL. Controla si una entidad está disponible a través de puntos de conexión de GraphQL. Alternar la propiedad enabled permite a los desarrolladores exponer de forma selectiva entidades desde el esquema GraphQL.

Formato

{
  "entities": {
    "<entity-name>": {
      "graphql": {
        "enabled": <true> (default) | <false>
      }
    }
  }
}

REST (entidades)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.{entity}`	`rest`	objeto	❌ No	Ninguno

La sección rest del archivo de configuración se dedica a ajustar los puntos de conexión RESTful para cada entidad de base de datos. Esta funcionalidad de personalización garantiza que la API REST expuesta coincida con requisitos específicos, lo que mejora sus funcionalidades de utilidad e integración. Aborda posibles discrepancias entre la configuración deducida predeterminada y los comportamientos de punto de conexión deseados.

Formato

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "enabled": <true> (default) | <false>,
        "path": <string; default: "<entity-name>">,
        "methods": <array of strings; default: ["GET", "POST"]>
      }
    }
  }
}

Propiedades

Propiedad	Obligatorio	Tipo	Predeterminado
`enabled`	✔️ Sí	booleano	Verdadero
`path`	❌ No	cuerda	`/<entity-name>`
`methods`	❌ No	matriz de cadenas	OBTENER

Ejemplos

Estos dos ejemplos son funcionalmente equivalentes.

{
  "entities": {
    "Author": {
      "source": {
        "object": "dbo.authors",
        "type": "table"
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["*"]
        }
      ],
      "rest": true
    }
  }
}

{
  "entities": {
    "Author": {
      ...
      "rest": {
        "enabled": true
      }
    }
  }
}

Este es otro ejemplo de una configuración de REST para una entidad.

{
  "entities" {
    "User": {
      "rest": {
        "enabled": true,
        "path": "/User"
      },
      ...
    }
  }
}

Habilitado (entidad REST)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.{entity}.rest`	`enabled`	booleano	❌ No	Verdadero

Esta propiedad actúa como alternancia para la visibilidad de las entidades dentro de la API REST. Al establecer la propiedad enabled en true o false, los desarrolladores pueden controlar el acceso a entidades específicas, lo que permite una superficie de API adaptada que se alinea con los requisitos de seguridad y funcionalidad de la aplicación.

Formato

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "enabled": <true> (default) | <false>
      }
    }
  }
}

Ruta de acceso (entidad REST)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.rest`	`path`	cuerda	❌ No	Ninguno

La propiedad path especifica el segmento de URI que se usa para acceder a una entidad a través de la API REST. Esta personalización permite rutas de conexión más descriptivas o simplificadas más allá del nombre de entidad predeterminado, lo que mejora la navegabilidad de api y la integración del lado cliente. De forma predeterminada, la ruta de acceso es /<entity-name>.

Formato

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "path": <string; default: "<entity-name>">
      }
    }
  }
}

Ejemplos

En este ejemplo se expone la entidad Author mediante el punto de conexión de /auth.

{
  "entities": {
    "Author": {
      "rest": {
        "path": "/auth"
      }
    }
  }
}

Métodos (entidad REST)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.{entity}.rest`	`methods`	matriz de cadenas	❌ No	Ninguno

Aplicable específicamente a los procedimientos almacenados, la propiedad methods define a qué verbos HTTP (por ejemplo, GET, POST) el procedimiento puede responder. Los métodos permiten un control preciso sobre cómo se exponen los procedimientos almacenados a través de la API REST, lo que garantiza la compatibilidad con los estándares RESTful y las expectativas del cliente. En esta sección se subraya el compromiso de la plataforma con la flexibilidad y el control del desarrollador, lo que permite un diseño de API preciso e intuitivo adaptado a las necesidades específicas de cada aplicación.

Si se omite o falta, el valor predeterminado del methods es POST.

Formato

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "methods": ["GET" (default), "POST"]
      }
    }
  }
}

Valores

Esta es una lista de valores permitidos para esta propiedad:

	Descripción
`get`	Expone solicitudes HTTP GET
`post`	Expone solicitudes HTTP POST

Ejemplos

En este ejemplo se indica al motor que el stp_get_bestselling_authors procedimiento almacenado solo admite acciones de HTTP GET.

{
  "entities": {
    "BestSellingAuthor": {
      "source": {
        "object": "dbo.stp_get_bestselling_authors",
        "type": "stored-procedure",
        "parameters": {
          "depth": "number"
        }
      },
      "rest": {
        "path": "/best-selling-authors",
        "methods": [ "get" ]
      }
    }
  }
}

Asignaciones (entidades)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.{entity}`	`mappings`	objeto	❌ No	Ninguno

la sección mappings habilita la configuración de alias o nombres expuestos para campos de objeto de base de datos. Los nombres expuestos configurados se aplican a los puntos de conexión de GraphQL y REST.

Importante

Para las entidades con GraphQL habilitado, el nombre expuesto configurado debe cumplir los requisitos de nomenclatura de GraphQL. Para obtener más información, consulte especificación de nombres graphQL.

Formato

{
  "entities": {
    "<entity-name>": {
      "mappings": {
        "<field-1-name>": "<field-1-alias>",
        "<field-2-name>": "<field-2-alias>",
        "<field-3-name>": "<field-3-alias>"
      }
    }
  }
}

Ejemplos

En este ejemplo, el campo sku_title del objeto de base de datos dbo.magazines se expone mediante el nombre title. Del mismo modo, el campo sku_status se expone como status en los puntos de conexión REST y GraphQL.

{
  "entities": {
    "Magazine": {
      ...
      "mappings": {
        "sku_title": "title",
        "sku_status": "status"
      }
    }
  }
}

Este es otro ejemplo de asignaciones.

{
  "entities": {
    "Book": {
      ...
      "mappings": {
        "id": "BookID",
        "title": "BookTitle",
        "author": "AuthorName"
      }
    }
  }
}

Asignaciones: el objeto mappings vincula los campos de base de datos (BookID, BookTitle, AuthorName) a nombres más intuitivos o estandarizados (id, title, author) que se usan externamente. Este alias sirve para varios propósitos:

claridad y coherencia: permite el uso de nombres claros y coherentes en la API, independientemente del esquema de base de datos subyacente. Por ejemplo, BookID de la base de datos se representa como id en la API, lo que hace que sea más intuitivo para los desarrolladores que interactúan con el punto de conexión.
GraphQL Compliance: al proporcionar un mecanismo para alias de nombres de campo, garantiza que los nombres expuestos a través de la interfaz graphQL cumplan los requisitos de nomenclatura de GraphQL. La atención a los nombres es importante porque GraphQL tiene reglas estrictas sobre los nombres (por ejemplo, sin espacios, debe comenzar con una letra o un carácter de subrayado, etc.). Por ejemplo, si un nombre de campo de base de datos no cumple estos criterios, se puede establecer un alias en un nombre compatible mediante asignaciones.
Flexibilidad: este alias agrega una capa de abstracción entre el esquema de base de datos y la API, lo que permite cambios en uno sin necesidad de cambios en el otro. Por ejemplo, un cambio de nombre de campo en la base de datos no requiere una actualización de la documentación de la API ni del código del lado cliente si la asignación sigue siendo coherente.
ofuscación de nombre de campo: la asignación permite ofuscar los nombres de campo, lo que puede ayudar a evitar que los usuarios no autorizados infieran información confidencial sobre el esquema de la base de datos o la naturaleza de los datos almacenados.
proteger la información de propiedad: al cambiar el nombre de los campos, también puede proteger los nombres de propiedad o la lógica de negocios que se pueden sugerir a través de los nombres de campo originales de la base de datos.

Relaciones (entidades)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.{entity}`	`relationships`	objeto	❌ No	Ninguno

En esta sección se incluye un conjunto de definiciones de relación que asignan cómo se relacionan las entidades con otras entidades expuestas. Estas definiciones de relación también pueden incluir detalles sobre los objetos de base de datos subyacentes que se usan para admitir y aplicar las relaciones. Los objetos definidos en esta sección se exponen como campos GraphQL en la entidad relacionada. Para obtener más información, consulte desglose de las relaciones del generador de datos.

Nota

Las relaciones solo son relevantes para las consultas de GraphQL. Los puntos de conexión REST acceden solo a una entidad cada vez y no pueden devolver tipos anidados.

En la sección relationships se describe cómo interactúan las entidades dentro del generador de Data API, detallando las asociaciones y la compatibilidad potencial de la base de datos para estas relaciones. La propiedad relationship-name para cada relación es necesaria y debe ser única en todas las relaciones de una entidad determinada. Los nombres personalizados garantizan conexiones claras e identificables y mantienen la integridad del esquema graphQL generado a partir de estas configuraciones.

Relación	Cardinalidad	Ejemplo
uno a varios	`many`	Una entidad de categoría puede relacionarse con muchas entidades de tareas pendientes
varios a uno	`one`	Muchas entidades de tareas pendientes pueden relacionarse con una entidad de categoría
varios a varios	`many`	Una entidad de tareas pendientes puede relacionarse con muchas entidades de usuario y una entidad de usuario puede relacionarse con muchas entidades de tareas pendientes.

Formato

{
  "entities": {
    "<entity-name>": {
      "relationships": {
        "<relationship-name>": {
          "cardinality": "one" | "many",
          "target.entity": "<string>",
          "source.fields": ["<string>"],
          "target.fields": ["<string>"],
          "linking.object": "<string>",
          "linking.source.fields": ["<string>"],
          "linking.target.fields": ["<string>"]
        }
      }
    }
  }
}

Propiedades

Propiedad	Obligatorio	Tipo	Predeterminado
`cardinality`	✔️ Sí	enum string	Ninguno
`target.entity`	✔️ Sí	cuerda	Ninguno
`source.fields`	❌ No	matriz de cadenas	Ninguno
`target.fields`	❌ No	matriz de cadenas	Ninguno
`linking.<object-or-entity>`	❌ No	cuerda	Ninguno
`linking.source.fields`	❌ No	matriz de cadenas	Ninguno
`linking.target.fields`	❌ No	matriz de cadenas	Ninguno

Ejemplos

Al considerar las relaciones, es mejor comparar las diferencias entre , varios a uno y relaciones de varios a varios.

Uno a varios

En primer lugar, consideremos un ejemplo de una relación con la entidad expuesta Category tiene una relación de uno a varios con la entidad Book. Aquí, la cardinalidad se establece en many. Cada Category puede tener varias entidades Book relacionadas, mientras que cada entidad Book solo está asociada a una sola entidad Category.

{
  "entities": {
    "Book": {
      ...
    },
    "Category": {
      "relationships": {
        "category_books": {
          "cardinality": "many",
          "target.entity": "Book",
          "source.fields": [ "id" ],
          "target.fields": [ "category_id" ]
        }
      }
    }
  }
}

En este ejemplo, la lista de source.fields especifica el campo id de la entidad de origen (Category). Este campo se usa para conectarse al elemento relacionado de la entidad target. Por el contrario, la lista de target.fields especifica el campo category_id de la entidad de destino (Book). Este campo se usa para conectarse al elemento relacionado de la entidad source.

Con esta relación definida, el esquema GraphQL expuesto resultante debe ser similar a este ejemplo.

type Category
{
  id: Int!
  ...
  books: [BookConnection]!
}

Varios a uno

A continuación, considere de varios a uno, que establece la cardinalidad en one. La entidad Book expuesta puede tener una sola entidad Category relacionada. La entidad Category puede tener varias entidades Book relacionadas.

{
  "entities": {
    "Book": {
      "relationships": {
        "books_category": {
          "cardinality": "one",
          "target.entity": "Category",
          "source.fields": [ "category_id" ],
          "target.fields": [ "id" ]
        }
      },
      "Category": {
        ...
      }
    }
  }
}

Aquí, la lista de source.fields especifica que el campo category_id de la entidad de origen (Book) hace referencia al campo id de la entidad de destino relacionada (Category). Inversamente, la lista de target.fields especifica la relación inversa. Con esta relación, el esquema de GraphQL resultante ahora incluye una asignación de libros a categorías.

type Book
{
  id: Int!
  ...
  category: Category
}

Varios a varios

Por último, se define una relación de de varios a varios con una cardinalidad de y más metadatos para definir qué objetos de base de datos se usan para crear la relación en la base de datos de respaldo. Aquí, la entidad Book puede tener varias entidades Author y, por el contrario, la entidad Author puede tener varias entidades Book.

{
  "entities": {
    "Book": {
      "relationships": {
        ...,
        "books_authors": {
          "cardinality": "many",
          "target.entity": "Author",
          "source.fields": [ "id" ],
          "target.fields": [ "id" ],
          "linking.object": "dbo.books_authors",
          "linking.source.fields": [ "book_id" ],
          "linking.target.fields": [ "author_id" ]
        }
      },
      "Category": {
        ...
      },
      "Author": {
        ...
      }
    }
  }
}

En este ejemplo, el source.fields y el target.fields indican que la tabla de relaciones usa el identificador principal (id) de las entidades source (Book) y target (Author). El campo linking.object especifica que la relación se define en el objeto de base de datos dbo.books_authors. Además, linking.source.fields especifica que el campo book_id del objeto de vinculación hace referencia al campo id de la entidad Book y linking.target.fields especifica que el campo author_id del objeto de vinculación hace referencia al campo id de la entidad Author.

Este ejemplo se puede describir mediante un esquema graphQL similar a este ejemplo.

type Book
{
  id: Int!
  ...
  authors: [AuthorConnection]!
}

type Author
{
  id: Int!
  ...
  books: [BookConnection]!
}

Cardinalidad

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.{entity}.relationships`	`cardinality`	cuerda	✔️ Sí	Ninguno

Especifica si la entidad de origen actual está relacionada con una sola instancia de la entidad de destino o varias.

Valores

Esta es una lista de valores permitidos para esta propiedad:

	Descripción
`one`	El origen solo se relaciona con un registro del destino.
`many`	El origen puede relacionarse con registros de cero a varios del destino.

Entidad de destino

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.{entity}.relationships`	`target.entity`	cuerda	✔️ Sí	Ninguno

Nombre de la entidad definida en otra parte de la configuración que es el destino de la relación.

Campos de origen

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.{entity}.relationships`	`source.fields`	arreglo	❌ No	Ninguno

Parámetro opcional para definir el campo utilizado para la asignación en la entidad de origen de que se usa para conectarse al elemento relacionado de la entidad de destino.

Propina

Este campo no es necesario si hay una clave externa restricción en la base de datos entre los dos objetos de base de datos que se pueden usar para deducir la relación automáticamente.

Campos de destino

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.{entity}.relationships`	`target.fields`	arreglo	❌ No	Ninguno

Parámetro opcional para definir el campo utilizado para la asignación en el destino entidad que se usa para conectarse al elemento relacionado de la entidad de origen.

Propina

Este campo no es necesario si hay una clave externa restricción en la base de datos entre los dos objetos de base de datos que se pueden usar para deducir la relación automáticamente.

Vincular objeto o entidad

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.{entity}.relationships`	`linking.object`	cuerda	❌ No	Ninguno

Para las relaciones de varios a varios, el nombre del objeto de base de datos o la entidad que contiene los datos necesarios para definir una relación entre otras dos entidades.

Vinculación de campos de origen

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.{entity}.relationships`	`linking.source.fields`	arreglo	❌ No	Ninguno

Nombre del objeto de base de datos o campo de entidad que está relacionado con la entidad de origen.

Vincular campos de destino

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.{entity}.relationships`	`linking.target.fields`	arreglo	❌ No	Ninguno

Nombre del objeto de base de datos o campo de entidad que está relacionado con la entidad de destino.

Caché (entidades)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.{entity}.cache`	`enabled`	booleano	❌ No	Falso

Habilita y configura el almacenamiento en caché de la entidad.

Formato

{
  "entities": {
    "<entity-name>": {
      "cache": {
        "enabled": <true> (default) | <false>,
        "ttl-seconds": <integer; default: 5>
      }
    }
  }
}

Propiedades

Propiedad	Obligatorio	Tipo	Predeterminado
`enabled`	❌ No	booleano	Falso
`ttl-seconds`	❌ No	entero	5

Ejemplos

En este ejemplo, la memoria caché está habilitada y los elementos expiran después de 30 segundos.

{
  "entities": {
    "Author": {
      "cache": {
        "enabled": true,
        "ttl-seconds": 30
      }
    }
  }
}

Habilitado (entidad de caché)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.{entity}.cache`	`enabled`	booleano	❌ No	Falso

Habilita el almacenamiento en caché para la entidad.

Compatibilidad con objetos de base de datos

Tipo de objeto	Compatibilidad con caché
Mesa	✅ Sí
Vista	✅ Sí
Procedimiento almacenado	✖️ No
Contenedor	✖️ No

Compatibilidad con encabezados HTTP

Encabezado de solicitud	Compatibilidad con caché
`no-cache`	✖️ No
`no-store`	✖️ No
`max-age`	✖️ No
`public`	✖️ No
`private`	✖️ No
`etag`	✖️ No

Formato

{
  "entities": {
    "<entity-name>": {
      "cache": {
        "enabled": <boolean> (default: false)
      }
    }
  }
}

Ejemplos

En este ejemplo, la memoria caché está deshabilitada.

{
  "entities": {
    "Author": {
      "cache": {
        "enabled": false
      }
    }
  }
}

TTL en segundos (entidad de caché)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.cache`	`ttl-seconds`	entero	❌ No	5

Formato

{
  "entities": {
    "<entity-name>": {
      "cache": {
        "ttl-seconds": <integer; inherited>
      }
    }
  }
}

Ejemplos

En este ejemplo, la memoria caché está habilitada y los elementos expiran después de 15 segundos. Cuando se omite, esta configuración hereda la configuración global o el valor predeterminado.

{
  "entities": {
    "Author": {
      "cache": {
        "enabled": true,
        "ttl-seconds": 15
      }
    }
  }
}

de referencia de Functions
referencia de la interfaz de línea de comandos (CLI)

Compartir a través de

Referencia del esquema de configuración de Data API Builder

Introducción a la sintaxis

Propiedades de nivel superior

Configuraciones de ejemplo

Entornos

Propiedades de configuración

Esquema

Formato

Ejemplos

Origen de datos

Formato

Propiedades

Tipo de base de datos

Formato

Valores de tipo

Cadena de conexión

Formato

Resistencia de conexión

Azure SQL y SQL Server

Ejemplos

mssql

postgresql

mysql

cosmosdb_nosql

cosmosdb_postgresql

Opciones

Formato

opciones: { set-session-context: boolean }

Ejemplo de procedimiento almacenado de SQL:

Ejemplo de configuración de JSON:

Explicación:

Archivos de origen de datos

Formato

Consideraciones sobre archivos de configuración

Ejemplos

Ejecución

Formato

Propiedades

Ejemplos

GraphQL (runtime)

Formato

Propiedades

Habilitado (tiempo de ejecución de GraphQL)

Formato

Ejemplos

Límite de profundidad (tiempo de ejecución de GraphQL)

Ejemplos

Ruta de acceso (tiempo de ejecución de GraphQL)

Formato

Ejemplos

Permitir introspección (runtime de GraphQL)

Formato

Ejemplos

Varias mutaciones (runtime de GraphQL)

Formato

Propiedades

Varias mutaciones: creación (runtime de GraphQL)

Formato

Propiedades

Ejemplos

Ejemplo de configuración

Ejemplo de mutación de GraphQL

REST (tiempo de ejecución)

Formato

Propiedades

Habilitado (tiempo de ejecución de REST)

Formato

Ejemplos

Ruta de acceso (tiempo de ejecución de REST)

Formato

Ejemplos

Request Body Strict (tiempo de ejecución rest)

Comportamiento con configuraciones de columna específicas

Formato

Ejemplos

Configuración de ejemplo

Comportamiento INSERT con request-body-strict: false

Comportamiento DE ACTUALIZACIÓN con request-body-strict: false

Host (tiempo de ejecución)

`mssql`

`postgresql`

`mysql`

`cosmosdb_nosql`

`cosmosdb_postgresql`

Comportamiento INSERT con `request-body-strict: false`

Comportamiento DE ACTUALIZACIÓN con `request-body-strict: false`