Entities

Configurações para entidades de banco de dados.

Health

Property	Description
`entities.entity-name.health.enabled`	Habilita verificações de integridade para a entidade (pontos de extremidade REST e GraphQL)
`entities.entity-name.health.first`	Número de linhas retornadas na consulta de verificação de integridade (intervalo: 1 a 500)
`entities.entity-name.health.threshold-ms`	Duração máxima em milissegundos para consulta de verificação de integridade (min: 1)

Source

Property	Description
`entities.entity-name.source.type`	Tipo de objeto: `table`, `view`ou `stored-procedure`
`entities.entity-name.source.object`	Nome do objeto de banco de dados
`entities.entity-name.source.parameters`	Parâmetros para procedimentos ou funções armazenados
`entities.entity-name.source.key-fields`	Lista de campos de chave primária para exibições
`entities.entity-name.mappings`	Mapeia nomes de campo de API para colunas de banco de dados

REST

Property	Description
`entities.entity-name.rest.enabled`	Habilita o REST para essa entidade
`entities.entity-name.rest.path`	Rota personalizada para o ponto de extremidade REST
`entities.entity-name.rest.methods`	Métodos REST permitidos: `get`, , `post`, `put`, `patch`, `delete`

GraphQL

Property	Description
`entities.entity-name.graphql.type`	Nome do tipo ou objeto com `singular` e `plural`
`entities.entity-name.graphql.operation`	Tipo de operação: `query` ou `mutation`
`entities.entity-name.graphql.enabled`	Habilita o GraphQL para essa entidade

Permissions

Property	Description
`entities.entity-name.permissions[].role`	Cadeia de caracteres de nome de função
`entities.entity-name.permissions[].actions`	Um ou mais de: `create`, , `read`, `update`, `deleteexecute`

Relationships

Property	Description
`entities.entity-name.relationships.relationship-name.cardinality`	`one` ou `many`
`entities.entity-name.relationships.relationship-name.target.entity`	Nome da entidade de destino
`entities.entity-name.relationships.relationship-name.source.fields`	Campos dessa entidade usados na relação
`entities.entity-name.relationships.relationship-name.target.fields`	Campos da entidade de destino
`entities.entity-name.relationships.relationship-name.linking.object`	Objeto join usado para relações muitos para muitos
`entities.entity-name.relationships.relationship-name.linking.source.fields`	Campos da entidade de origem usados na junção
`entities.entity-name.relationships.relationship-name.linking.target.fields`	Campos da entidade de destino usados na junção

Cache

Property	Description
`entities.entity-name.cache.enabled`	Habilita o cache de resposta para a entidade
`entities.entity-name.cache.ttl-seconds`	Tempo de vida útil em cache em segundos

Visão geral do 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>
          }
        }
      ]
    }
  }
}

Origem (entidades de nome de entidade)

Parent	Property	Tipo	Required	Default
`entities.{entity-name}`	`source`	objeto	✔️ Sim	None

Os detalhes da fonte do banco de dados da entidade.

Propriedades aninhadas

Parent	Property	Tipo	Required	Default
`entities.{entity-name}.source`	`object`	cadeia	✔️ Sim	None
`entities.{entity-name}.source`	`type`	enumeração (`table`, `view`, `stored-procedure`)	✔️ Sim	None
`entities.{entity-name}.source`	`key-fields`	Matriz de cadeia de caracteres	✔️ Sim*	None
`entities.{entity-name}.source`	`parameters`	objeto	✔️ Sim**	None

key-fields só é necessário quando type é view. O valor representa as chaves primárias.

** parameters só é necessário quando type é stored-procedure e somente para parâmetros com valores padrão. O tipo de dados do parâmetro é inferido. Parâmetros sem um padrão podem ser omitidos.

Tip

Se o objeto pertencer ao esquema dbo, especificar o esquema será opcional. Além disso, colchetes em torno de nomes de objeto (por exemplo, dbo.Users vs. [dbo].[Users]) podem ser usados quando necessário.

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

Permissões (entidades de nome de entidade)

Parent	Property	Tipo	Required	Default
`entities.permissions`	`role`	cadeia	✔️ Sim	None

Uma cadeia de caracteres que especifica o nome da função à qual as permissões se aplicam.

Format

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

Example

Este exemplo define a função custom-role com apenas read permissões na User entidade.

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

Exemplos 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())

Ações (entidades de nome de entidade de permissões de matriz de cadeia de caracteres)

Parent	Property	Tipo	Required	Default
`entities.permissions`	`actions`	oneOf [cadeia de caracteres, matriz]	✔️ Sim	None

Uma matriz de cadeia de caracteres que detalha quais operações são permitidas para a função associada.

Action	Operação SQL
`*`	Todas as ações
`create`	Inserir uma ou mais linhas*
`read`	Selecionar uma ou mais linhas
`update`	Modificar uma ou mais linhas*
`delete`	Excluir uma ou mais linhas*
`execute`	Executa um procedimento armazenado

* No momento, há suporte para várias operações apenas no GraphQL.

Note

Para procedimentos armazenados, a ação curinga (*) expande-se apenas para a ação execute. Para tabelas e exibições, ele se expande para create, read, updatee delete.

Format

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

Example

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

Formato alternativo (somente cadeia de caracteres, quando `type=stored-procedure`)

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

Example

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

Ações (entidades de nome de entidade de permissões de matriz de objeto)

Parent	Property	Tipo	Required	Default
`entities.{entity-name}.permissions`	`actions`	Matriz de cadeia de caracteres	✔️ Sim	None

Uma matriz de objetos que detalha quais operações são permitidas para a função associada.

Note

Para procedimentos armazenados, a ação curinga (*) se expande para apenas execute. Para tabelas/exibições, ele se expande para create, read, updatee delete.

Propriedades aninhadas

Parent	Property	Tipo	Required	Default
`entities.{entity-name}.permissions.actions[]`	`action`	cadeia	✔️ Sim	None
`entities.{entity-name}.permissions.actions[]`	`fields`	objeto	❌ Não	None
`entities.{entity-name}.permissions.actions[]`	`policy`	objeto	❌ Não	None
`entities.{entity-name}.permissions.actions[].policy`	`database`	cadeia	✔️ Sim	None

Format

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

Example

Isso concede read permissão à auditorUser entidade, com restrições de campo e política.

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

Notas de política

As políticas dão suporte a operadores OData como eq.
As políticas dão suporte a predicados compostos usando and e or.
Só há suporte para ações: create, read, updatee delete. (Não execute)
As políticas filtram os resultados, mas não impedem a execução da consulta no banco de dados.
O campo deve usar o alias de campo, se mapeado.

Tipo (entidades de nome de entidade do GraphQL)

Parent	Property	Tipo	Required	Default
`entities.{entity-name}.graphql`	`type`	objeto	❌ Não	{entity-name}

Define a convenção de nomenclatura para uma entidade dentro do esquema GraphQL.

Format

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

Propriedades aninhadas

Parent	Property	Required	Tipo	Default
`entities.{entity-name}.graphql.type`	`singular`	❌ Não	cadeia	None
`entities.{entity-name}.graphql.type`	`plural`	❌ Não	cadeia	N/A (padrão para valor singular)

Example

Configuration

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

Consulta GraphQL

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

Resposta do GraphQL

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

Operação (entidades de nome de entidade do GraphQL)

Parent	Property	Tipo	Required	Default
`entities.{entity-name}.graphql`	`operation`	cadeia de caracteres de enumeração	❌ Não	mutation

Designa se a stored-procedure operação é exibida sob o Query ou Mutation.

Note

Quando {entity-name}.type é definido como stored-procedure, um novo tipo graphQL executeXXX é criado automaticamente. Essa operation propriedade controla onde esse tipo é colocado no esquema GraphQL. Não há impacto funcional, apenas higiene de esquema.

Format

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

Exemplo: operação

Quando operation é definido como query

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

Quando operation é definido como mutation

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

Habilitado (entidades de nome de entidade do GraphQL)

Parent	Property	Tipo	Required	Default
`entities.{entity-name}.graphql`	`enabled`	boolean	❌ Não	True

Permite que os desenvolvedores incluam seletivamente entidades no esquema GraphQL.

Format

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

REST (entidades de nome de entidade)

Parent	Property	Tipo	Required	Default
`entities.{entity-name}.rest`	`enabled`	boolean	❌ Não	True
`entities.rest`	`path`	cadeia	❌ Não	`/{entity-name}`
`entities.{entity-name}.rest`	`methods`	Matriz de cadeia de caracteres	❌ Não*	`POST`

* A methods propriedade é apenas para stored-procedure pontos de extremidade.

Format

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

Mapeamentos (entidades de nome de entidade)

Parent	Property	Tipo	Required	Default
`entities.{entity-name}`	`mappings`	objeto	❌ Não	None

Habilita aliases personalizados ou nomes expostos para campos de objeto de banco de dados.

Important

Para entidades com GraphQL habilitado, o nome exposto configurado deve atender aos requisitos de nome do 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

Tabela de banco de dados

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

Configuration

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

Cache (entidades de nome de entidade)

Parent	Property	Tipo	Required	Default
`entities.{entity-name}`	`cache`	objeto	❌ Não	None

Habilita e configura o cache para a entidade.

Propriedades aninhadas

Parent	Property	Tipo	Required	Default
`entities.{entity-name}.cache`	`enabled`	boolean	❌ Não	False
`entities.{entity-name}.cache`	`ttl-seconds`	inteiro	❌ Não	-

Format

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

Note

Quando não especificado, ttl-seconds herda o valor global definido em runtime.cache.

Example

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

Relações (entidades de nome de entidade)

Parent	Property	Tipo	Required	Default
`entities.{entity-name}`	`relationships`	objeto	❌ Não	None

Configura como as entidades do GraphQL estão relacionadas a outras entidades expostas. Para obter mais informações, consulte divisão de relações do construtor de API de Dados.

Note

A relationship-name propriedade de cada relação deve ser exclusiva em todas as relações dessa entidade.

Propriedades aninhadas

Essas propriedades são usadas em combinações diferentes dependendo da cardinalidade da relação.

Parent	Property	Tipo	Required	Default
`entities.{entity-name}.relationships`	`cardinality`	cadeia	✔️ Sim	None
`entities.{entity-name}.relationships`	`target.entity`	cadeia	✔️ Sim	None
`entities.{entity-name}.relationships`	`target.fields`	Matriz de cadeia de caracteres	❌ Não	None
`entities.{entity-name}.relationships`	`source.fields`	Matriz de cadeia de caracteres	❌ Não	None
`entities.{entity-name}.relationships`	`linking.object`	cadeia	❌ Não	None
`entities.{entity-name}.relationships`	`linking.source.fields`	Matriz de cadeia de caracteres	❌ Não	None
`entities.{entity-name}.relationships`	`linking.target.fields`	Matriz de cadeia de caracteres	❌ Não	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`	Uma entidade de categoria pode se relacionar com muitas entidades de todo
many-to-one	`one`	Muitas entidades de todo podem se relacionar com uma entidade de categoria
many-to-many	`many`	Uma entidade todo pode se relacionar com muitas entidades de usuário e uma entidade de usuário pode se relacionar com várias entidades de todo

Exemplo: cardinalidade um-para-um

Cada Profile um está relacionado a exatamente um Usere cada User um tem exatamente um relacionado Profile.

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

Esquema do GraphQL

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

Command-line

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

Exemplo: cardinalidade um-para-muitos

Uma Category pode ter uma ou mais entidades relacionadas Book , enquanto cada Book uma pode ter uma relacionada Category.

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

Esquema do GraphQL

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

Linha de comando

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

Exemplo: cardinalidade muitos para um

Muitas Book entidades podem ter uma relacionada Category, enquanto uma Category pode ter uma ou mais entradas relacionadas Book .

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

Esquema do GraphQL

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

Linha de comando

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

Exemplo: cardinalidade muitos para muitos

Muitas Book entidades podem ter muitas entidades relacionadas Author , enquanto muitas Author entidades podem ter muitas entradas relacionadas Book .

Note

Essa relação é possível com uma terceira tabela, dbo.books_authorsque chamamos de objeto de vinculação.

{
  "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 do GraphQL

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

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

Linha de comando

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"

Integridade (entidades de nome de entidade)

Parent	Property	Tipo	Required	Default
`entities.{entity-name}`	`health`	objeto	❌ Não	None

Habilita e configura verificações de integridade para a entidade.

Propriedades aninhadas

Parent	Property	Tipo	Required	Default
`entities.{entity-name}.health`	`enabled`	boolean	❌ Não	`true`
`entities.{entity-name}.health`	`first`	inteiro	❌ Não	`100`
`entities.{entity-name}.health`	`threshold-ms`	inteiro	❌ Não	`1000`

Example

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

Note

O first valor deve ser menor ou igual à configuração runtime.pagination.max-page-size . Valores menores ajudam as verificações de integridade a serem concluídas mais rapidamente.

Important

Os procedimentos armazenados são automaticamente excluídos das verificações de integridade da entidade porque exigem parâmetros e podem não ser determinísticos.

Comentários

Esta página foi útil?

Last updated on 2025-09-24

Compartilhar via

Entities

Health

Source

REST

GraphQL

Permissions

Relationships

Cache

Visão geral do formato

Origem (entidades de nome de entidade)

Propriedades aninhadas

Format

Permissões (entidades de nome de entidade)

Format

Example

Exemplos de uso

Ações (entidades de nome de entidade de permissões de matriz de cadeia de caracteres)

Format

Example

Formato alternativo (somente cadeia de caracteres, quando type=stored-procedure)

Example

Ações (entidades de nome de entidade de permissões de matriz de objeto)

Propriedades aninhadas

Format

Example

Notas de política

Tipo (entidades de nome de entidade do GraphQL)

Format

Propriedades aninhadas

Example

Operação (entidades de nome de entidade do GraphQL)

Format

Exemplo: operação

Habilitado (entidades de nome de entidade do GraphQL)

Format

REST (entidades de nome de entidade)

Format

Mapeamentos (entidades de nome de entidade)

Format

Examples

Cache (entidades de nome de entidade)

Propriedades aninhadas

Format

Example

Relações (entidades de nome de entidade)

Propriedades aninhadas

Format

Exemplo: cardinalidade um-para-um

Exemplo: cardinalidade um-para-muitos

Exemplo: cardinalidade muitos para um

Exemplo: cardinalidade muitos para muitos

Integridade (entidades de nome de entidade)

Propriedades aninhadas

Example

Comentários

Recursos adicionais

Formato alternativo (somente cadeia de caracteres, quando `type=stored-procedure`)