Entities

Opciones de configuración para entidades de base de datos.

Health

Property	Description
`entities.entity-name.health.enabled`	Habilita las comprobaciones de estado de la entidad (puntos de conexión REST y GraphQL)
`entities.entity-name.health.first`	Número de filas devueltas en la consulta de comprobación de estado (intervalo: 1-500)
`entities.entity-name.health.threshold-ms`	Duración máxima en milisegundos para la consulta de comprobación de estado (min: 1)

Source

Property	Description
`entities.entity-name.source.type`	Tipo de objeto: `table`, `view`o `stored-procedure`
`entities.entity-name.source.object`	Nombre del objeto de base de datos
`entities.entity-name.source.parameters`	Parámetros para procedimientos almacenados o funciones
`entities.entity-name.source.key-fields`	Lista de campos de clave principal para vistas
`entities.entity-name.mappings`	Asigna nombres de campo de API a columnas de base de datos

REST

Property	Description
`entities.entity-name.rest.enabled`	Habilita REST para esta entidad
`entities.entity-name.rest.path`	Ruta personalizada para el punto de conexión REST
`entities.entity-name.rest.methods`	Métodos REST permitidos: `get`, `post`, `put`, `patch`, , `delete`

GraphQL

Property	Description
`entities.entity-name.graphql.type`	Nombre de tipo u objeto con `singular` y `plural`
`entities.entity-name.graphql.operation`	Tipo de operación: `query` o `mutation`
`entities.entity-name.graphql.enabled`	Habilita GraphQL para esta entidad

Permissions

Property	Description
`entities.entity-name.permissions[].role`	Cadena de nombre de rol
`entities.entity-name.permissions[].actions`	Uno o varios de: `create`, `read`, `update`, , `delete`, `execute`

Relationships

Property	Description
`entities.entity-name.relationships.relationship-name.cardinality`	`one` o `many`
`entities.entity-name.relationships.relationship-name.target.entity`	Nombre de la entidad de destino
`entities.entity-name.relationships.relationship-name.source.fields`	Campos de esta entidad usadas en la relación
`entities.entity-name.relationships.relationship-name.target.fields`	Campos de la entidad de destino
`entities.entity-name.relationships.relationship-name.linking.object`	Objeto join usado para relaciones de varios a varios
`entities.entity-name.relationships.relationship-name.linking.source.fields`	Campos de la entidad de origen usada en combinación
`entities.entity-name.relationships.relationship-name.linking.target.fields`	Campos de la entidad de destino usada en combinación

Cache

Property	Description
`entities.entity-name.cache.enabled`	Habilita el almacenamiento en caché de respuestas para la entidad
`entities.entity-name.cache.ttl-seconds`	Tiempo de vida de caché en segundos

Introducción al formato

{
  "entities": {
    "{entity-name}": {
      "rest": {
        "enabled": <boolean> // default: true
        "path": <string> // default: "{entity-name}"
        "methods": ["GET", "POST"] // default: ["GET", "POST"]
      },
      "graphql": {
        "enabled": <boolean> // default: true
        "type": {
          "singular": <string>,
          "plural": <string>
        },
        "operation": "query" | "mutation" // default: "query"
      },
      "source": {
        "object": <string>,
        "type": "view" | "stored-procedure" | "table",
        "key-fields": [<string>], // primary keys for the view
        "parameters": { // only for stored-procedure
          "<parameter-name>": <default-value>,
          "<parameter-name>": <default-value>
        }
      },
      "mappings": {
        "<database-field-name>": <string>
      },
      "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>]
        }
      },
      "permissions": [
        {
          "role": "anonymous" | "authenticated" | <custom-role>,
          "actions": ["create", "read", "update", "delete", "execute", "*"],
          "fields": {
            "include": [<string>],
            "exclude": [<string>]
          },
          "policy": {
            "database": <string>
          }
        }
      ]
    }
  }
}

Origen (entidades de nombre de entidad)

Parent	Property	Type	Required	Default
`entities.{entity-name}`	`source`	object	✔️ Sí	None

Detalles del origen de la base de datos de la entidad.

Propiedades anidadas

Parent	Property	Type	Required	Default
`entities.{entity-name}.source`	`object`	string	✔️ Sí	None
`entities.{entity-name}.source`	`type`	enum (`table`, `view`, `stored-procedure`)	✔️ Sí	None
`entities.{entity-name}.source`	`key-fields`	matriz de cadena	✔️ Sí*	None
`entities.{entity-name}.source`	`parameters`	object	✔️ Sí**	None

key-fields solo es necesario cuando type es view. El valor representa las claves principales.

** parameters solo es necesario cuando type es stored-procedure y solo para parámetros con valores predeterminados. El tipo de datos del parámetro se deduce. Los parámetros sin un valor predeterminado se pueden omitir.

Tip

Si el objeto pertenece al esquema de dbo, especificar el esquema es opcional. Además, los corchetes alrededor de los nombres de objeto (por ejemplo, dbo.Users frente [dbo].[Users]a ) se pueden usar cuando sea necesario.

Format

{
  "entities": {
    "{entity-name}": {
      "source": {
        "object": <string>,
        "type": <"view" | "stored-procedure" | "table">,
        "key-fields": [ <string> ], // primary keys of the view
        "parameters": { // only for option stored-procedure parameters
          "<parameter-name-1>": <default-value>
          "<parameter-name-2>": <default-value>
        }
      }
    }
  }
}

Permisos (entidades de nombre de entidad)

Parent	Property	Type	Required	Default
`entities.permissions`	`role`	string	✔️ Sí	None

Cadena que especifica el nombre del rol al que se aplican los permisos.

Format

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "role": <"anonymous" | "authenticated" | "custom-role">
        }
      ]
    }
  }
}

Example

En este ejemplo se define el rol custom-role solo read con permisos en la User entidad.

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

Ejemplos de uso

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

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

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

const response = await fetch('https://localhost:5001/api/User', {
  headers: {
    "Authorization": "Bearer <your_access_token>",
    "X-MS-API-ROLE": "custom-role"
  }
});
// To read the response body as JSON:
// const data = await response.json();

import requests

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

Acciones (entidades de nombre de entidad de permisos de matriz de cadenas)

Parent	Property	Type	Required	Default
`entities.permissions`	`actions`	oneOf [string, array]	✔️ Sí	None

Matriz de cadenas que detalla qué operaciones se permiten para el rol asociado.

Action	Operación SQL
`*`	Todas las acciones
`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

* Actualmente solo se admiten varias operaciones en GraphQL.

Note

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

Format

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "actions": [ <string> ]
        }
      ]
    }
  }
}

Example

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "actions": [ "*" ] // equivalent to create, read, update, delete
        }
      ]
    }
  }
}

Formato alternativo (solo cadena, cuando `type=stored-procedure`)

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "actions": <string>
        }
      ]
    }
  }
}

Example

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "actions": "*" // equivalent to execute
        }
      ]
    }
  }
}

Acciones (entidades de nombre de entidad permisos de matriz de objetos)

Parent	Property	Type	Required	Default
`entities.{entity-name}.permissions`	`actions`	matriz de cadena	✔️ Sí	None

Matriz de objetos que detalla qué operaciones se permiten para el rol asociado.

Note

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

Propiedades anidadas

Parent	Property	Type	Required	Default
`entities.{entity-name}.permissions.actions[]`	`action`	string	✔️ Sí	None
`entities.{entity-name}.permissions.actions[]`	`fields`	object	❌ No	None
`entities.{entity-name}.permissions.actions[]`	`policy`	object	❌ No	None
`entities.{entity-name}.permissions.actions[].policy`	`database`	string	✔️ Sí	None

Format

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

Example

Esto concede read permiso para auditor en la User entidad, con restricciones de campo y directiva.

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

Notas de la directiva

Las directivas admiten operadores de OData como eq.
Las directivas admiten predicados compuestos mediante and y or.
Solo se admite para acciones: create, read, updatey delete. (No execute)
Las directivas filtran los resultados, pero no impiden la ejecución de consultas en la base de datos.
Field debe usar el alias de campo, si se asigna.

Tipo (entidades de nombre de entidad de GraphQL)

Parent	Property	Type	Required	Default
`entities.{entity-name}.graphql`	`type`	object	❌ No	{entity-name}

Establece la convención de nomenclatura de una entidad dentro del esquema de GraphQL.

Format

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

Propiedades anidadas

Parent	Property	Required	Type	Default
`entities.{entity-name}.graphql.type`	`singular`	❌ No	string	None
`entities.{entity-name}.graphql.type`	`plural`	❌ No	string	N/A (el valor predeterminado es singular)

Example

Configuration

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

Consulta de GraphQL

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

Respuesta de GraphQL

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

Operación (entidades de nombre de entidad de GraphQL)

Parent	Property	Type	Required	Default
`entities.{entity-name}.graphql`	`operation`	enum string	❌ No	mutation

Designa si la stored-procedure operación aparece en o QueryMutation.

Note

Cuando {entity-name}.type se establece en stored-procedure, se crea automáticamente un nuevo tipo executeXXX GraphQL. Esta operation propiedad controla dónde se coloca este tipo en el esquema GraphQL. No hay ningún impacto funcional, solo la higiene del esquema.

Format

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

Ejemplo: operación

Cuando operation se establece en query

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

Cuando operation se establece en mutation

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

Habilitado (entidades de nombre de entidad de GraphQL)

Parent	Property	Type	Required	Default
`entities.{entity-name}.graphql`	`enabled`	boolean	❌ No	True

Permite a los desarrolladores incluir de forma selectiva entidades en el esquema graphQL.

Format

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

REST (entidades de nombre de entidad)

Parent	Property	Type	Required	Default
`entities.{entity-name}.rest`	`enabled`	boolean	❌ No	True
`entities.rest`	`path`	string	❌ No	`/{entity-name}`
`entities.{entity-name}.rest`	`methods`	matriz de cadena	❌ No*	`POST`

* La methods propiedad es solo para stored-procedure los puntos de conexión.

Format

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

Asignaciones (entidades de nombre de entidad)

Parent	Property	Type	Required	Default
`entities.{entity-name}`	`mappings`	object	❌ No	None

Habilita alias personalizados o nombres expuestos para campos de objeto de base de datos.

Important

En el caso de las entidades con GraphQL habilitado, el nombre expuesto configurado debe cumplir los requisitos de nombre de GraphQL.

Format

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

Examples

Tabla de base de datos

CREATE TABLE Books
(
  id INT,
  sku_title VARCHAR(50),
  sku_status VARCHAR(50),
)

Configuration

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

Caché (entidades de nombre de entidad)

Parent	Property	Type	Required	Default
`entities.{entity-name}`	`cache`	object	❌ No	None

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

Propiedades anidadas

Parent	Property	Type	Required	Default
`entities.{entity-name}.cache`	`enabled`	boolean	❌ No	False
`entities.{entity-name}.cache`	`ttl-seconds`	integer	❌ No	-

Format

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

Note

Cuando no se especifica, ttl-seconds hereda el valor global establecido en runtime.cache.

Example

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

Relaciones (entidades de nombre de entidad)

Parent	Property	Type	Required	Default
`entities.{entity-name}`	`relationships`	object	❌ No	None

Configura cómo se relacionan las entidades de GraphQL con otras entidades expuestas. Para obtener más información, consulte desglose de las relaciones del generador de datos.

Note

La relationship-name propiedad de cada relación debe ser única en todas las relaciones de esa entidad.

Propiedades anidadas

Estas propiedades se usan en combinaciones diferentes en función de la cardinalidad de la relación.

Parent	Property	Type	Required	Default
`entities.{entity-name}.relationships`	`cardinality`	string	✔️ Sí	None
`entities.{entity-name}.relationships`	`target.entity`	string	✔️ Sí	None
`entities.{entity-name}.relationships`	`target.fields`	matriz de cadena	❌ No	None
`entities.{entity-name}.relationships`	`source.fields`	matriz de cadena	❌ No	None
`entities.{entity-name}.relationships`	`linking.object`	string	❌ No	None
`entities.{entity-name}.relationships`	`linking.source.fields`	matriz de cadena	❌ No	None
`entities.{entity-name}.relationships`	`linking.target.fields`	matriz de cadena	❌ No	None

Format

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

Relationship	Cardinality	Example
one-to-many	`many`	Una entidad de categoría puede relacionarse con muchas entidades de tareas pendientes
many-to-one	`one`	Muchas entidades de tareas pendientes pueden relacionarse con una entidad de categoría
many-to-many	`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.

Ejemplo: Cardinalidad uno a uno

Cada Profile uno está relacionado exactamente con un Usery cada uno User tiene exactamente uno relacionado Profile.

{
  "entities": {
    "User": {
      "relationships": {
        "user_profile": {
          "cardinality": "one",
          "target.entity": "Profile",
          "source.fields": [ "id" ],
          "target.fields": [ "user_id" ]
        }
      }
    },
    "Profile": {
      ...
    }
  }
}

Esquema de GraphQL

type User
{
  id: Int!
  ...
  profile: Profile
}

Command-line

dab update User \
  --relationship profile \
  --target.entity Profile \
  --cardinality one \
  --relationship.fields "id:user_id"

Ejemplo: cardinalidad uno a varios

Un Category puede tener una o varias entidades relacionadas Book , mientras que cada Book una puede tener una relacionada Category.

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

Esquema de GraphQL

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

Línea de comandos

dab update Category \
  --relationship category_books \
  --target.entity Book \
  --cardinality many \
  --relationship.fields "id:category_id"

Ejemplo: Cardinalidad de varios a uno

Muchas Book entidades pueden tener una relacionada Category, mientras que una Category puede tener una o varias entradas relacionadas Book .

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

Esquema de GraphQL

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

Línea de comandos

dab update Book \
  --relationship books_category \
  --target.entity "Category" \
  --cardinality one \
  --relationship.fields "category_id:id"

Ejemplo: Cardinalidad de varios a varios

Muchas Book entidades pueden tener muchas entidades relacionadas Author , mientras que muchas entidades pueden tener muchas Author entradas relacionadas Book .

Note

Esta relación es posible con una tercera tabla, , dbo.books_authorsque hacemos referencia a como el objeto de vinculación.

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

Esquema de GraphQL

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

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

Línea de comandos

dab update Book \
  --relationship books_authors \
  --target.entity "Author" \
  --cardinality many \
  --relationship.fields "id:id" \
  --linking.object "dbo.books_authors" \
  --linking.source.fields "book_id" \
  --linking.target.fields "author_id"

Estado (entidades de nombre de entidad)

Parent	Property	Type	Required	Default
`entities.{entity-name}`	`health`	object	❌ No	None

Habilita y configura las comprobaciones de estado de la entidad.

Propiedades anidadas

Parent	Property	Type	Required	Default
`entities.{entity-name}.health`	`enabled`	boolean	❌ No	`true`
`entities.{entity-name}.health`	`first`	integer	❌ No	`100`
`entities.{entity-name}.health`	`threshold-ms`	integer	❌ No	`1000`

Example

{
  "entities": {
    "Book": {
      "health": {
        "enabled": true,
        "first": 3,
        "threshold-ms": 500
      }
    }
  }
}

Note

El first valor debe ser menor o igual que la runtime.pagination.max-page-size configuración. Los valores más pequeños ayudan a que las comprobaciones de estado se completen más rápido.

Important

Los procedimientos almacenados se excluyen automáticamente de las comprobaciones de estado de entidad porque requieren parámetros y pueden no ser deterministas.

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2025-09-24

Compartir a través de

Entities

Health

Source

REST

GraphQL

Permissions

Relationships

Cache

Introducción al formato

Origen (entidades de nombre de entidad)

Propiedades anidadas

Format

Permisos (entidades de nombre de entidad)

Format

Example

Ejemplos de uso

Acciones (entidades de nombre de entidad de permisos de matriz de cadenas)

Format

Example

Formato alternativo (solo cadena, cuando type=stored-procedure)

Example

Acciones (entidades de nombre de entidad permisos de matriz de objetos)

Propiedades anidadas

Format

Example

Notas de la directiva

Tipo (entidades de nombre de entidad de GraphQL)

Format

Propiedades anidadas

Example

Operación (entidades de nombre de entidad de GraphQL)

Format

Ejemplo: operación

Habilitado (entidades de nombre de entidad de GraphQL)

Format

REST (entidades de nombre de entidad)

Format

Asignaciones (entidades de nombre de entidad)

Format

Examples

Caché (entidades de nombre de entidad)

Propiedades anidadas

Format

Example

Relaciones (entidades de nombre de entidad)

Propiedades anidadas

Format

Ejemplo: Cardinalidad uno a uno

Ejemplo: cardinalidad uno a varios

Ejemplo: Cardinalidad de varios a uno

Ejemplo: Cardinalidad de varios a varios

Estado (entidades de nombre de entidad)

Propiedades anidadas

Example

Comentarios

Recursos adicionales

Formato alternativo (solo cadena, cuando `type=stored-procedure`)