Referencia del esquema de configuración de Data API Builder

Artículo
10/04/2024

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": {
    "Book": {
      "source": "dbo.books",
      "permissions": [{
          "actions": ["*"],
          "role": "anonymous"
      }]
    }
  }
}

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	Ninguno
`mssql`	Azure SQL MI	Ninguno
`mssql`	SQL Server	SQL 2016
`sqldw`	Azure SQL Data Warehouse	Ninguno
`postgresql`	PostgreSQL	v11
`mysql`	MySQL	v8
`cosmosdb_nosql`	Azure Cosmos DB para NoSQL	Ninguno
`cosmosdb_postgresql`	Azure Cosmos DB para PostgreSQL	Ninguno

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.

	Sobras
primera	`2`
Second	`4`
tercera	`8`
cuarto	`16`
Quinto	`32`

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('database-connection-string')`	Acceda a una variable de entorno desde el equipo local. En este ejemplo, se hace referencia a la variable de entorno `database-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
  }
}
```
- formato de cadena de conexión típico: "Server=tcp:myserver.database.windows.net,1433;Initial Catalog=myDataBase;Persist Security Info=False;User ID=mylogin;Password=myPassword;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"
postgresql
```
"data-source": {
  "database-type": "postgresql",
  "connection-string": "$env('my-connection-string')"
}
```
- formato de cadena de conexión típico: "Host=myserver.postgres.database.azure.com;Database=myDataBase;Username=mylogin@myserver;Password=myPassword;"
mysql
```
"data-source": {
  "database-type": "mysql",
  "connection-string": "$env('my-connection-string')"
}
```
- formato de cadena de conexión típico: "Server=myserver.mysql.database.azure.com;Database=myDataBase;Uid=mylogin@myserver;Pwd=myPassword;"

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

formato de cadena de conexión típico: "AccountEndpoint=https://mycosmosdb.documents.azure.com:443/;AccountKey=myAccountKey;"

cosmosdb_postgresql
```
"data-source": {
  "database-type": "cosmosdb_postgresql",
  "connection-string": "$env('my-connection-string')"
}
```
- formato de cadena de conexión típico: "Host=mycosmosdb.postgres.database.azure.com;Database=myDataBase;Username=mylogin@mycosmosdb;Password=myPassword;Port=5432;SSL Mode=Require;"

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.

Formato

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

Ejemplos

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

	Valor	Descripción
Habilitar `SESSION_CONTEXT` en Azure SQL o SQL Server	`"set-session-context": false`	Para Azure SQL y SQL Server, data API Builder puede aprovechar `SESSION_CONTEXT` para 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.

{
  "data-source"{
    "options": {
        "set-session-context": false
    }
  }
}

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

En este ejemplo, se habilitan varias mutaciones para el entorno de ejecución de GraphQL. En concreto, la operación de creación múltiple está habilitada especificando un valor de true para la propiedad runtime.graphql.multiple-mutations.create.enabled.

{
  "runtime": {
    "graphql": {
      "multiple-mutations": {
        "create": {
          "enabled": true
        }
      }
    }
  }
}

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.

Cuerpo de solicitud estricto (tiempo de ejecución de REST)

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

Esta marca booleana determina si el cuerpo de la solicitud para una operación de mutación rest puede contener campos extraños. De forma predeterminada, el valor es true, lo que significa que los campos adicionales del cuerpo de la solicitud producen una excepción de BadRequest. Sin embargo, establecer esta marca en false permite a los usuarios incluir campos adicionales en el cuerpo de la solicitud, que se omiten. Es importante tener en cuenta que esta marca no afecta a las solicitudes de consulta REST (GET), ya que el cuerpo de la solicitud siempre se omite para las operaciones GET.

Nota

Esta marca no afecta a las solicitudes HTTP GET al punto de conexión de la API REST. El cuerpo de la solicitud siempre se omite para las operaciones GET.

Formato

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

Ejemplos

En este ejemplo, la validación estricta del cuerpo de la solicitud está deshabilitada.

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

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

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 encabezado CORS de Access-Control-Allow-Credentials, consulte 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.

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

Ejemplo

{
  "runtime": {
    "pagination": {
      "max-page-size": 100000,
      "default-page-size": 1
    }
  }
}

Ejemplo de paginación REST

En este ejemplo, la emisión del https://localhost:5001/api/books GET rest devolvería un registro en la matriz de value porque el default-page-size se estableció en 1. Si existen más resultados, Data API Builder anexa un nextLink en la respuesta. El nextLink contiene un parámetro $after para recuperar la página siguiente de datos.

{
  "value": [
    {
      "id": 1000,
      "title": "Prelude to Foundation",
      "year": 1988,
      "pages": 403,
      "series_id": 10000
    }
  ],
  "nextLink": "https://localhost:5001/api/books?$after=W3siRW50aXR5TmFtZSI6ImJvb2tzIiwiRmllbGROYW1lI=="
}

El uso del nextLink garantiza que se devuelva el siguiente conjunto de resultados, incluso si los datos han cambiado entre consultas.

Ejemplo de paginación de GraphQL

En GraphQL, use los campos hasNextPage y endCursor para la paginación. Estos son necesarios para capturar el siguiente conjunto de resultados. Sin ellos, la consulta todavía está limitada al tamaño de página predeterminado.

query {
  books {
    items {
      id,
      title,
      year,
      pages,
      series_id
    }
    hasNextPage
    endCursor
  }
}

La respuesta incluye los campos hasNextPage y endCursor:

{
  "data": {
    "books": {
      "items": [
        {
          "id": 1000,
          "title": "Prelude to Foundation",
          "year": 1988,
          "pages": 403,
          "series_id": 10000
        }
      ],
      "hasNextPage": true,
      "endCursor": "W3siRW50aXR5TmFtZSI6ImJvb2tzIiwiRmllbGROYW1lI=="
    }
  }
}

Para capturar la página siguiente, incluya el valor del cursor en la consulta siguiente:

query {
  books(after: "W3siRW50aXR5TmFtZSI6ImJvb2tzIiwiRmllbGROYW1lI==") {
    items {
      id
      title
      year
      pages
      series_id
    }
    hasNextPage
    endCursor
  }
}

Usar $limit o first para cambiar el tamaño de página:

REST y GraphQL admiten un parámetro $limit o first para ajustar el número de resultados por consulta. Por ejemplo, https://{server}/api/books?$limit=10 limita el resultado a 10 registros, reemplazando el default-page-size. Si $limit supera max-page-size, el resultado se limita a max-page-size.

Primer valor	Resultado
`-1`	El valor predeterminado es el valor de `max-page-size` actual.
`< max-page-size`	Limita el resultado al valor proporcionado.
`0`	No se admite.
`< -1`	No se admite.
`> max-page-size`	No se admite.

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 Author y un punto de conexión REST accesible a través de la ruta de acceso de /Author. La tabla de base de datos dbo.authors respalda la entidad y la configuración permite a cualquier persona acceder al punto de conexión de forma anónima.

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

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": {
    "Book": {
      "rest": {
        "enabled": true,
        "path": "/books",
        "methods": ["GET", "POST", "PUT"]
      },
      "graphql": {
        "enabled": true,
        "type": {
          "singular": "Book",
          "plural": "Books"
        },
        "operation": "query"
      },
      "source": {
        "object": "BooksTable",
        "type": "table",
        "key-fields": ["Id"],
        "parameters": {}
      },
      "mappings": {
        "id": "Id",
        "title": "Title",
        "authorId": "AuthorId"
      },
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"],
          "fields": {
            "include": ["id", "title"],
            "exclude": []
          },
          "policy": {
            "database": "@claims.userId eq @item.authorId"
          }
        },
        {
          "role": "admin",
          "actions": ["create", "read", "update", "delete"],
          "fields": {
            "include": ["*"],
            "exclude": []
          },
          "policy": {
            "database": "@claims.userRoles has 'BookAdmin'"
          }
        }
      ]
    }
  }
}

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.

En escenarios sencillos, donde la entidad se asigna directamente a una sola tabla o colección 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.

Formato

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

Propiedades

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

Ejemplos

En este ejemplo se muestra la estructura más sencilla para asociar una entidad a una tabla de origen.

{
  "entities": {
    "Author": {
      "source": {
        "object": "dbo.authors",
        "type": "table"
      }
    }
  }
}

Este es un exmaple de una relación de varios a varios.

Diagrama de una relación de varios a varios entre varias tablas de base de datos

{
  "entities": {
    "Todo": {
      "type": "stored-procedure",
      "source": {
        "type": "stored-procedure",
        "object": "GetUserTodos"
      },
      "parameters": {
        "UserId": 0, 
        "Completed": null,
        "CategoryName": null
      },
      "mapping": {
        "Id": "todo_id",
        "Title": "todo_title",
        "Description": "todo_description",
        "Completed": "todo_completed"
      }
    }
  }
}

Entidad Todo respaldada por un procedimiento almacenado.
La propiedad type dentro del origen se establece en stored-procedure, lo que indica el tipo de objeto de origen al que se asigna la entidad.
La propiedad object dentro del origen es el nombre del procedimiento almacenado en la base de datos.

También en este ejemplo, la propiedad mapping (opcional) se agrega a la configuración de la entidad "Todo". Especifica cómo los campos de la entidad (Id, Title, Descriptiony Completed) se asignan a los campos correspondientes en los parámetros del origen de datos subyacente o del procedimiento almacenado (todo_id, todo_title, todo_descriptiony todo_completed, respectivamente). Esta asignación garantiza que los datos correctos se pasan entre la entidad y el procedimiento almacenado durante las operaciones de creación y actualización.

En el ejemplo anterior se usaría el siguiente procedimiento SQL.

CREATE PROCEDURE GetUserTodos
    @UserId INT,
    @Completed BIT = NULL,
    @CategoryName NVARCHAR(100) = NULL
AS
BEGIN
    SELECT t.*
    FROM Todo t
    INNER JOIN users_todos ut ON t.id = ut.todo_id
    INNER JOIN Category c ON t.category_id = c.id
    WHERE ut.user_id = @UserId
    AND ISNULL(@Completed, t.completed)
    AND ISNULL(@CategoryName, c.name)
END

@UserId: parámetro obligatorio sin un valor predeterminado.
@Completed: parámetro opcional. Si se proporciona, filtra todos por su estado de finalización.
@CategoryName: parámetro opcional. Si se proporciona, filtra los todos por nombre de categoría.

Este es un ejemplo de actualizaciones mediante un procedimiento almacenado.

{
  "entities": {
    "Todo": {
      "type": "stored-procedure",
      "source": {
        "object": "UpsertTodo"
      },
      "method": "POST", // Specify the HTTP method as POST
      "parameters": {
        "Id": 0,
        "Title": null,
        "Description": null,
        "Completed": null
      }
    }
  }
}

En este ejemplo se establece explícitamente el método HTTP para interactuar con esta entidad para POST mediante la propiedad method.

CREATE PROCEDURE UpsertTodo
    @Id INT,
    @Title NVARCHAR(100),
    @Description NVARCHAR(255),
    @Completed BIT
AS
BEGIN
    SET NOCOUNT ON;

    MERGE INTO Todo AS target
    USING (VALUES (@Id, @Title, @Description, @Completed)) AS source (Id, Title, Description, Completed)
    ON target.Id = source.Id
    WHEN MATCHED THEN
        UPDATE SET
            Title = source.Title,
            Description = source.Description,
            Completed = source.Completed
    WHEN NOT MATCHED THEN
        INSERT (Id, Title, Description, Completed)
        VALUES (source.Id, source.Title, source.Description, source.Completed);
END;

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.

Ejemplos

En este ejemplo, object hace referencia al objeto dbo.books de la base de datos.

{
  "entities": {
    "Book": {
      "source": {
        "object": "dbo.books",
        "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, que incluyen view, tabley stored-procedure. La propiedad type es necesaria y no hay ningún valor predeterminado.

Formato

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

Valores

Esta es una lista de valores permitidos para esta propiedad:

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

Ejemplos

En este ejemplo, type indica que este origen es una vista de la base de datos. Este valor influye en si se requieren otros valores (por ejemplo, key-fields).

{
  "entities": {
    "Category": {
      "source": {
        "object": "dbo.vw_category_details",
        "type": "view",
        "key-fields": [
          "category_id"
        ]
      }
    }
  }
}

Campos clave

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

La configuración de {entity}.key-fields es necesaria para las entidades respaldadas por vistas, por lo que Data API Builder sabe cómo puede identificar y devolver un solo elemento, si es necesario. Si type se establece en view sin key-fields, el motor del generador de DATA API se niega a iniciarse.

Importante

Esta propiedad es necesaria si el tipo de objeto es un view. Además, esta propiedad es necesaria es el tipo de objeto un table sin ninguna clave principal definida.

Formato

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

Ejemplos

En este ejemplo se usa la vista dbo.vw_category_details con category_id indicado como campo de clave.

{
  "entities": {
    "Category": {
      "source": {
        "object": "dbo.vw_category_details",
        "type": "view",
        "key-fields": [
          "category_id"
        ]
      }
    }
  }
}

Parámetros

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

La configuración de {entity}.source.parameters es importante para las entidades respaldadas por procedimientos almacenados, lo que permite a los desarrolladores especificar parámetros y sus valores predeterminados. Los parámetros garantizan que si ciertos parámetros no se proporcionan dentro de una solicitud HTTP, el sistema puede revertir a estos valores predefinidos.

Importante

Esta propiedad es necesaria si el tipo de objeto es un stored-procedure.

Formato

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

Ejemplos

En este ejemplo se invoca el dbo.stp_get_bestselling_books procedimiento almacenado que pasa estos dos parámetros:

	Valor
`depth`	25
`list`	contoso-best-seller

{
  "entities": {
    "BestsellingBooks": {
      "source": {
        "object": "dbo.stp_get_bestselling_books",
        "type": "stored-procedure",
        "parameters": {
          "depth": 25,
          "list": "contoso-best-sellers"
        }
      }
    }
  }
}

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 esta sección en los términos de roles. Las acciones se definen como operaciones CRUD típicas, como: create, read, updatey delete. La sección permissions define quién (en términos de roles) puede acceder a la entidad relacionada y usar qué acciones. Las acciones son las operaciones CRUD habituales: create, read, update, delete.

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 relacionados con la entidad.
`*`	Concede todas las operaciones CRUD aplicables

Ejemplos

En este ejemplo, se define un rol anónimo con acceso a todas las acciones posibles.

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

También puede combinar y hacer coincidir acciones de cadena y matriz de objetos.

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

rol anónimo Permitir que los usuarios anónimos lean todos los campos excepto el secret-field. El uso de "include": ["*"] con "exclude": ["secret-field"] oculta eficazmente secret-field de usuarios anónimos al tiempo que permite el acceso a todos los demás campos.

rol autenticado Permitir que los usuarios autenticados lean y actualicen campos específicos, incluidos explícitamente id, titley secret-field, pero excluyendo secret-field. Muestra la inclusión explícita y la exclusión posterior de secret-field, que muestra la prioridad de exclude. Dado que secret-field se incluye y excluye, termina siendo inaccesible, que coincide con la regla prevista de exclude teniendo prioridad.

rol de autor autores pueden realizar todas las operaciones * en todos los campos sin exclusiones. El archivo indica "include": ["*"] con una matriz "exclude": [] vacía concede acceso a todos los campos, ya que no se excluye explícitamente ningún campo.

Esta configuración representa el valor predeterminado si no se especifica nada.

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

Es eficazmente idéntico a:

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

Tenga en cuenta también la siguiente configuración:

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

La configuración anterior especifica eficazmente que no se incluye ningún campo explícitamente ("include": [] está vacío, lo que indica que no se permiten campos) y que todos los campos se excluyen ("exclude": ["*"] usa el carácter comodín * para indicar todos los campos).

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 podría realizar 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", "Title"],
  "exclude": ["*"]
}

La configuración anterior intenta especificar que solo se deben incluir los campos Id y Title, al tiempo que se indica que todos los campos deben excluirse con el comodín * en la sección exclude. Otra manera de expresar la misma lógica sería:

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

Dada la regla general que la lista de exclude tiene prioridad sobre la lista de include, especificar exclude: ["*"] normalmente significaría que todos los campos se excluyen, incluso los campos enumerados en la sección include. Por lo tanto, a primera vista, esta configuración puede parecer impedir que se pueda acceder a los campos, ya que la regla de exclusión es dominante.

The Reverse: si la intención es conceder, el acceso solo a los campos Id y Title, es más claro y confiable especificar solo los campos de la sección include y no usar exclude con un carácter comodín. Como alternativa, puede ajustar la lógica de permisos del sistema para adaptarse explícitamente a estos casos, suponiendo que esté bajo el control de su diseño. Por ejemplo:

"fields": {
  "include": ["Id", "Title"],
  "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. La cadena role 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 en los puntos de conexión REST y GraphQL. Los roles no son aditivos. Para obtener más información sobre los roles, consulte autorización.

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 encabezado HTTP de `X-MS-API-ROLE` se incluye especificando un rol de usuario que también se incluye en la notificación de roles del token de acceso.

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 read en el punto de conexión.

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

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 se pueden configurar para 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. La matriz actions detalla qué acciones se permiten en el rol asociado. Cuando la entidad es una tabla o vista, los roles se pueden configurar con una combinación de las acciones: create, read, update, delete.

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 a una lista que solo incluye la acción execute. Para tablas y vistas, la acción comodín se expande a una lista que incluye acciones de create, read, updatey delete.

Ejemplos

En este ejemplo se proporcionan permisos create y read al primer rol denominado contributor. El segundo rol denominado auditor solo tiene permisos delete.

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

Este es otro ejemplo.

{
  ...
  "entities": {
    "<entity-name>": {
      ...
      "permissions": [
        {
          "role": "contributor",
          "actions": ["read", "create"]
        }
      ]
    }
  }
}

Acciones (matriz de objetos)

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

Nota

Formato

{
  "entities": {
    <string>: {
      "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

Ejemplos

En este ejemplo solo se concede read permiso al rol de auditor. El rol auditor solo puede leer datos específicos mediante el predicado definido en policy.database. El rol de auditor también está limitado en qué campos puede o no puede leer mediante la propiedad fields.

{
  "entities": {
    "CheckoutLogs": {
      "permissions": [
        {
          "role": "auditor",
          "actions": [
            {
              "action": "read",
              "fields": {
                "include": ["*"],
                "exclude": ["last_updated"]
              },
              "policy": {
                "database": "@item.LogDepth lt 3"
              }
            }
          ]
        }
      ]
    }
  }
}

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

Esta es una lista de valores permitidos para esta propiedad:

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

Formato

{
  "entities": {
    <string>: {
      "permissions": [
        {
          "role": <string>,
          "actions": [
            {
              "action": <string>,
              "fields": <object>,
              "policy": <object>
            }
          ]
        }
      ]
    }
  }
}

Ejemplos

Este es un ejemplo en el que los usuarios de anonymous pueden execute un procedimiento almacenado específico y read una tabla específica.

{
  "entities": {
    "Author": {
      "source": {
        "object": "dbo.authors",
        "type": "table"
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read"
            }
          ]
        }
      ]
    },
    "BestSellingAuthor": {
      "source": {
        "object": "dbo.stp_get_bestselling_authors",
        "type": "stored-procedure",
        "parameters": {
          "depth": 10
        }
      },
      "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. La configuración de roles es un tipo de objeto con dos propiedades internas, include y exclude. Estos valores admiten la definición pormenorizado del acceso a las columnas de base de datos (campos) en la sección fields.

Formato

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

Ejemplos

En este ejemplo, el rol anonymous puede leer desde todos los campos excepto id, pero puede usar todos los campos al crear un elemento.

{
  "entities": {
    "Author": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "fields": {
                "include": [ "*" ],
                "exclude": [ "id" ]
              }
            },
            { "action": "create" }
          ]
        }
      ]
    }
  }
}

Incluir y excluir trabajar juntos. El * comodín de la sección include indica todos los campos. Los campos indicados en la sección exclude tienen prioridad sobre los campos indicados en la sección include. La definición se traduce en incluir todos los campos excepto el campo "last_updated"."

"Book": {
    "source": "books",
    "permissions": [
        {
            "role": "anonymous",
            "actions": [ "read" ],
            // Include All Except Specific Fields
            "fields": {
              "include": [ "*" ],
              "exclude": [ "secret-field" ]
            }
        },
        {
            "role": "authenticated",
            "actions": [ "read", "update" ],
            // Explicit Include and Exclude
            "fields": {
              "include": [ "id", "title", "secret-field" ],
              "exclude": [ "secret-field" ]
            }
        },
        {
            "role": "author",
            "actions": [ "*" ],
            // Include All With No Exclusions (default)
            "fields": {
              "include": ["*"],
              "exclude": []
            }
        }
    ]
}

Política

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

La sección policy, definida por action, define reglas de seguridad de nivel de elemento (directivas de base de datos) que limitan los resultados devueltos desde una solicitud. La subsección database denota la expresión de directiva de base de datos que se evalúa durante la ejecución de la solicitud.

Formato

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

Propiedades

Propiedad	Obligatorio	Tipo	Predeterminado
`database`	✔️ Sí	cuerda	Ninguno

Descripción

La directiva de database: una expresión similar a OData que se traduce en un predicado de consulta que evalúa la base de datos, incluidos operadores como eq, lty gt. Para que los resultados se devuelvan para una solicitud, el predicado de consulta de la solicitud resuelto desde una directiva de base de datos debe evaluarse para true al ejecutarse en la base de datos.

Directiva de elemento de ejemplo	Predicado
`@item.OwnerId eq 2000`	`WHERE Table.OwnerId = 2000`
`@item.OwnerId gt 2000`	`WHERE Table.OwnerId > 2000`
`@item.OwnerId lt 2000`	`WHERE Table.OwnerId < 2000`

Un predicate es una expresión que se evalúa como TRUE o FALSE. Los predicados se usan en la condición de búsqueda de cláusulas WHERE y HAVING, las condiciones de combinación de cláusulas FROM y otras construcciones donde se requiere un valor booleano. (Microsoft Learn Docs)

Directiva de base de datos

Se pueden usar dos tipos de directivas para administrar la directiva de base de datos al crear una expresión de directiva de base de datos:

Directiva	Descripción
`@claims`	Acceso a una notificación dentro del token de acceso validado proporcionado en la solicitud
`@item`	Representa un campo de la entidad para la que se define la directiva de base de datos.

Nota

Cuando se configura autenticación de Azure Static Web Apps (EasyAuth), hay disponible un número limitado de tipos de notificaciones para su uso en las directivas de base de datos: identityProvider, userId, userDetailsy userRoles. Para más información, consulte la documentación de datos de entidad de seguridad de cliente de Azure Static Web App.

Estas son algunas directivas de base de datos de ejemplo:

@claims.userId eq @item.OwnerId
@claims.userId gt @item.OwnerId
@claims.userId lt @item.OwnerId

Data API Builder compara el valor de la notificación UserId con el valor del campo de base de datos OwnerId. La carga de resultados solo incluye registros que cumplen los metadatos de solicitud y la expresión de directiva de base de datos.

Limitaciones

Las directivas de base de datos se admiten para tablas y vistas. Los procedimientos almacenados no se pueden configurar con directivas.

Las directivas de base de datos no impiden que las solicitudes se ejecuten dentro de la base de datos. Este comportamiento se debe a que se resuelven como predicados en las consultas generadas que se pasan al motor de base de datos.

Las directivas de base de datos solo se admiten para actionscrear, leer, actualizary eliminar. Puesto que no hay ningún predicado en una llamada a procedimiento almacenado, no se pueden anexar.

Operadores de tipo OData admitidos

Operador	Descripción	Sintaxis de ejemplo
`and`	AND lógico	`"@item.status eq 'active' and @item.age gt 18"`
`or`	OR lógico	`"@item.region eq 'US' or @item.region eq 'EU'"`
`eq`	Iguales	`"@item.type eq 'employee'"`
`gt`	Mayor que	`"@item.salary gt 50000"`
`lt`	Menos que	`"@item.experience lt 5"`

Para obtener más información, consulte operadores binarios.

Operador	Descripción	Sintaxis de ejemplo
`-`	Negate (numérico)	`"@item.balance lt -100"`
`not`	Negación lógica (NOT)	`"not @item.status eq 'inactive'"`

Para obtener más información, consulte operadores unarios.

Restricciones de nombre de campo de entidad

Reglas: debe comenzar con una letra o un carácter de subrayado (_), seguido de hasta 127 letras, caracteres de subrayado (_) o dígitos (0-9).
Impacto: los campos que no se adhieren a estas reglas no se pueden usar directamente en las directivas de base de datos.
solución: use la sección mappings para crear alias para campos que no cumplan estas convenciones de nomenclatura; Las asignaciones garantizan que todos los campos se pueden incluir en expresiones de directiva.

Uso de `mappings` para campos no compatibles

Si los nombres de campo de entidad no cumplen las reglas de sintaxis de OData o simplemente desea alias por otros motivos, puede definir alias en la sección mappings de la configuración.

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

En este ejemplo, field-1-name es el nombre del campo de base de datos original que no cumple las convenciones de nomenclatura de OData. Crear un mapa para field-1-name y field-1-alias permite hacer referencia a este campo en expresiones de directiva de base de datos sin problema. Este enfoque no solo ayuda a cumplir las convenciones de nomenclatura de OData, sino que también mejora la claridad y accesibilidad del modelo de datos en los puntos de conexión de GraphQL y RESTful.

Ejemplos

Considere una entidad denominada Employee dentro de una configuración de Data API que use directivas de notificaciones y elementos. Garantiza que el acceso a los datos se administre de forma segura en función de los roles de usuario y la propiedad de la entidad:

{
  "entities": {
    "Employee": {
      "source": {
        "object": "HRUNITS",
        "type": "table",
        "key-fields": ["employee NUM"],
        "parameters": {}
      },
      "mappings": {
        "employee NUM": "EmployeeId",
        "employee Name": "EmployeeName",
        "department COID": "DepartmentId"
      },
      "policy": {
        "database": "@claims.role eq 'HR' or @claims.userId eq @item.EmployeeId"
      }
    }
  }
}

definición de entidad: la entidad Employee está configurada para interfaces REST y GraphQL, lo que indica que sus datos se pueden consultar o manipular a través de estos puntos de conexión.

de configuración de origen: identifica el HRUNITS de la base de datos, con employee NUM como campo de clave.

Asignaciones: los alias se usan para asignar employee NUM, employee Namey department COID a EmployeeId, EmployeeNamey DepartmentId, respectivamente, simplificando los nombres de campo y potencialmente ofuscando los detalles del esquema de base de datos confidenciales.

aplicación de directiva: la sección policy aplica una directiva de base de datos mediante una expresión similar a OData. Esta directiva restringe el acceso de datos a los usuarios con el rol de RR. HH. (@claims.role eq 'HR') o a los usuarios cuya notificación de UserId coincide con EmployeeId ( el alias de campo) de la base de datos (@claims.userId eq @item.EmployeeId). Garantiza que los empleados solo puedan acceder a sus propios registros a menos que pertenezcan al departamento de RR. HH. Las directivas pueden aplicar la seguridad de nivel de fila en función de las condiciones dinámicas.

Base de datos

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

Formato

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

Esta propiedad denota la expresión de directiva de base de datos que se evalúa durante la ejecución de la solicitud. La cadena de directiva es una expresión de OData que se traduce en una consulta que se evalúa previamente por la base de datos. Por ejemplo, la expresión de directiva @item.OwnerId eq 2000 se traduce al predicado de consulta WHERE <schema>.<object-name>.OwnerId = 2000.

Nota

Un predicado de es una expresión que evaluta a TRUE, FALSEo UNKNOWN. Los predicados se usan en:

Condición de búsqueda de cláusulas de WHERE
Condición de búsqueda de cláusulas de FROM
Condiciones de combinación de cláusulas de FROM
Otras construcciones en las que se requiere un valor booleano.

Para obtener más información, vea predicados.

Para que los resultados se devuelvan para una solicitud, el predicado de consulta de la solicitud resuelto desde una directiva de base de datos debe evaluarse para true al ejecutarse en la base de datos.

Se pueden usar dos tipos de directivas para administrar la directiva de base de datos al crear una expresión de directiva de base de datos:

	Descripción
`@claims`	Obtiene acceso a una notificación dentro del token de acceso validado proporcionado en la solicitud.
`@item`	Representa un campo de la entidad para la que se define la directiva de base de datos.

Nota

Hay disponible un número limitado de tipos de notificaciones para su uso en las directivas de base de datos cuando se configura la autenticación de Azure Static Web Apps (EasyAuth). Estos tipos de notificaciones incluyen: identityProvider, userId, userDetailsy userRoles. Para más información, consulte datos de entidad de seguridad de cliente de Azure Static Web Apps.

Ejemplos

Por ejemplo, una expresión de directiva básica puede evaluar si un campo específico es true dentro de la tabla. En este ejemplo se evalúa si el campo soft_delete es false.

{
  "entities": {
    "Manuscripts": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "@item.soft_delete eq false"
              }
            }
          ]
        }
      ]
    }
  }
}

Los predicados también pueden evaluar los tipos de directiva claims y item. En este ejemplo se extrae el campo UserId del token de acceso y se compara con el campo owner_id de la tabla de base de datos de destino.

{
  "entities": {
    "Manuscript": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "@claims.userId eq @item.owner_id"
              }
            }
          ]
        }
      ]
    }
  }
}

Limitaciones

Las directivas de base de datos se admiten para tablas y vistas. Los procedimientos almacenados no se pueden configurar con directivas.
Las directivas de base de datos no se pueden usar para evitar que una solicitud se ejecute dentro de una base de datos. Esta limitación se debe a que las directivas de base de datos se resuelven como predicados de consulta en las consultas de base de datos generadas. En última instancia, el motor de base de datos evalúa estas consultas.
Las directivas de base de datos solo se admiten para los actionscreate, read, updatey delete.
La sintaxis de la expresión de OData de la directiva de base de datos solo admite estos escenarios.
- Operadores binarios, entre los que se incluyen, entre otros; and, or, eq, gty lt. Para obtener más información, vea BinaryOperatorKind.
- Operadores unarios, como los operadores - (negación) y not. Para obtener más información, vea UnaryOperatorKind.
Las directivas de base de datos también tienen restricciones relacionadas con los nombres de campo.
- Nombres de campo de entidad que comienzan por una letra o un carácter de subrayado, seguidos de como máximo 127 letras, caracteres de subrayado o dígitos.
- Este requisito es por especificación de OData. Para obtener más información, vea lenguaje de definición de esquema común de OData.

Propina

Los campos que no se ajustan a las restricciones mencionadas no se pueden hacer referencia en las directivas de base de datos. Como solución alternativa, configure la entidad con una sección de asignaciones para asignar alias conformes a los campos.

GraphQL (entidades)

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

Este segmento proporciona la integración de una entidad en el esquema de GraphQL. Permite a los desarrolladores especificar o modificar valores predeterminados para la entidad en GraphQL. Esta configuración garantiza que el esquema refleje con precisión la estructura prevista y las convenciones de nomenclatura.

Formato

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

{
  "entities": {
    "<entity-name>": {
      "graphql": {
        "enabled": <boolean>,
        "type": <string-or-object>,
        "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.

{
  "entities": {
    "Author": {
      "graphql": true
    }
  }
}

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

En este ejemplo, la entidad definida es Book, lo que indica que estamos tratando con un conjunto de datos relacionados con libros de la base de datos. La configuración de la entidad Book dentro del segmento GraphQL ofrece una estructura clara sobre cómo se debe representar e interactuar con en un esquema GraphQL.

propiedad Enabled: la entidad Book está disponible a través de GraphQL ("enabled": true), lo que significa que los desarrolladores y usuarios pueden consultar o mutar datos de libros a través de operaciones de GraphQL.

propiedad Type: la entidad se representa con el nombre singular "Book" y el nombre plural "Books" en el esquema GraphQL. Esta distinción garantiza que al consultar un único libro o varios libros, el esquema ofrece tipos con nombre intuitivo (Book para una sola entrada, Books para una lista), lo que mejora la facilidad de uso de la API.

propiedad Operation: la operación se establece en "query", lo que indica que la interacción principal con la entidad Book a través de GraphQL está pensada para consultar (recuperar) datos en lugar de mutarlos (crear, actualizar o eliminar). Esta configuración se alinea con los patrones de uso típicos en los que los datos del libro se leen con más frecuencia que los modificados.

{
  "entities": {
    "Book": {
      ...
      "graphql": {
        "enabled": true,
        "type": {
          "singular": "Book",
          "plural": "Books"
        },
        "operation": "query"
      },
      ...
    }
  }
}

Tipo (entidad GraphQL)

Padre	Propiedad	Tipo	Obligatorio	Predeterminado
`entities.{entity}.graphql`	`type`	oneOf [string, object]	❌ No	{entity-name}

Esta propiedad dicta la convención de nomenclatura de una entidad dentro del esquema graphQL. Admite valores de cadena escalares y tipos de objeto. El valor del objeto especifica los formatos singulares y plurales. Esta propiedad proporciona un control pormenorizado sobre la legibilidad del esquema y la experiencia del usuario.

Formato

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

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

Propiedades

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

Ejemplos

Para un mayor control sobre el tipo GraphQL, puede configurar cómo se representa el nombre singular y plural de forma independiente.

Si falta o se omite plural (como el valor escalar) El generador de Data API intenta pluralizar el nombre automáticamente, siguiendo las reglas en inglés para la pluralización (por ejemplo: https://engdic.org/singular-and-plural-noun-rules-definitions-examples)

{
  "entities" {
    "<entity-name>": {
      ...
      "graphql": {
        ...
        "type": {
          "singular": "User",
          "plural": "Users"
        }
      }
    }
  }
}

Se puede especificar un nombre de entidad personalizado mediante el parámetro type con un valor de cadena. En este ejemplo, el motor diferencia automáticamente entre las variantes singulares y plurales de este nombre mediante reglas comunes en inglés para pluralización.

{
  "entities": {
    "Author": {
      "graphql": {
        "type": "bookauthor"
      }
    }
  }
}

Si decide especificar los nombres explícitamente, use las propiedades type.singular y type.plural. En este ejemplo se establecen explícitamente ambos nombres.

{
  "entities": {
    "Author": {
      "graphql": {
        "type": {
          "singular": "bookauthor",
          "plural": "bookauthors"
        }
      }
    }
  }
}

Ambos ejemplos son funcionalmente equivalentes. Ambos devuelven la misma salida JSON para una consulta graphQL que usa el nombre de entidad bookauthors.

{
  bookauthors {
    items {
      first_name
      last_name
    }
  }
}

{
  "data": {
    "bookauthors": {
      "items": [
        {
          "first_name": "Henry",
          "last_name": "Ross"
        },
        {
          "first_name": "Jacob",
          "last_name": "Hancock"
        },
        ...
      ]
    }
  }
}

Operación (entidad GraphQL)

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

En el caso de las entidades asignadas a procedimientos almacenados, la propiedad operation designa el tipo de operación GraphQL (consulta o mutación) donde se puede acceder al procedimiento almacenado. Esta configuración permite la organización lógica del esquema y el cumplimiento de los procedimientos recomendados de GraphQL, sin afectar a la funcionalidad.

Nota

Se especifica una entidad para que sea un procedimiento almacenado estableciendo el valor de propiedad {entity}.type en stored-procedure. En el caso de un procedimiento almacenado, se crea automáticamente un nuevo tipo de GraphQL executeXXX. Sin embargo, la propiedad operation permite al desarrollador coerse la ubicación de ese tipo en las partes mutation o query del esquema. Esta propiedad permite la hygene del esquema y no hay ningún impacto funcional independientemente de operation valor.

Si falta, el valor predeterminado del operation es mutation.

Formato

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

Valores

Esta es una lista de valores permitidos para esta propiedad:

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

Ejemplos

Cuando operation es mutation, el esquema de GraphQL sería similar al siguiente:

type Mutation {
  executeGetCowrittenBooksByAuthor(
    searchType: String = "S"
  ): [GetCowrittenBooksByAuthor!]!
}

Cuando operation es query, el esquema de GraphQL sería similar al siguiente:

El esquema de GraphQL sería similar al siguiente:

type Query {
  executeGetCowrittenBooksByAuthor(
    searchType: String = "S"
  ): [GetCowrittenBooksByAuthor!]!
}

Nota

La propiedad operation solo se refiere a la colocación de la operación en el esquema graphQL, 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": 10
        }
      },
      "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

You're right; the formatting doesn't match your style. Here’s the corrected version following your preferred documentation format:

```json
{
  "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

Opciones

Formato

Ejemplos

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

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

Cuerpo de solicitud estricto (tiempo de ejecución de REST)

Formato

Ejemplos

Host (tiempo de ejecución)

Formato

Propiedades

Ejemplos

Modo (tiempo de ejecución del host)

Formato

Valores

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

Valores permitidos

Formato

CORS (tiempo de ejecución de host)

Formato

Propiedades

Permitir credenciales (tiempo de ejecución de host)

Formato