Entities

Definições de configuração para entidades de banco de dados.

Health

Property	Description
`entities.entity-name.health.enabled`	Permite verificações de saúde para a entidade (tanto os endpoints REST como GraphQL)
`entities.entity-name.health.first`	Número de linhas devolvidas na consulta de verificação de saúde (intervalo: 1-500)
`entities.entity-name.health.threshold-ms`	Duração máxima em milissegundos para consulta de verificação de saúde (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 armazenados ou funções
`entities.entity-name.source.key-fields`	Lista de campos de chave primária para modos de exibição
`entities.entity-name.mappings`	Mapeia nomes de campos da API para colunas de banco de dados

REST

Property	Description
`entities.entity-name.rest.enabled`	Habilita REST para esta entidade
`entities.entity-name.rest.path`	Rota personalizada para 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`	Digite o nome 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 esta entidade

Permissions

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

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 desta entidade utilizados na relação
`entities.entity-name.relationships.relationship-name.target.fields`	Campos da entidade alvo
`entities.entity-name.relationships.relationship-name.linking.object`	Objeto de junção usado para relacionamentos 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`	Cache time-to-live 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`	objecto	✔️ 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 (de caracteres)	✔️ Sim	None
`entities.{entity-name}.source`	`type`	enum (`table`, `view`, `stored-procedure`)	✔️ Sim	None
`entities.{entity-name}.source`	`key-fields`	array de strings	✔️ Sim*	None
`entities.{entity-name}.source`	`parameters`	objecto	✔️ 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 dado do parâmetro é inferido. Parâmetros sem padrão podem ser omitidos.

Tip

Se o objeto pertencer ao esquema dbo, especificar o esquema é opcional. Além disso, colchetes em torno de nomes de objetos (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 (de caracteres)	✔️ 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 apenas com read permissões na User entidade.

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

Exemplos de utilização

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 (string-array Permissions, entidades-nome, entidades)

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

Uma matriz de cadeia de caracteres detalhando 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

* Atualmente, várias operações são suportadas apenas no GraphQL.

Note

Para procedimentos armazenados, a ação curinga (*) se expande para apenas 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 string, quando `type=stored-procedure`)

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

Example

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

Ações (objeto-matriz, Permissões, entidades-nome, entidades)

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

Uma matriz de objetos detalhando 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 (de caracteres)	✔️ Sim	None
`entities.{entity-name}.permissions.actions[]`	`fields`	objecto	❌ Não	None
`entities.{entity-name}.permissions.actions[]`	`policy`	objecto	❌ Não	None
`entities.{entity-name}.permissions.actions[].policy`	`database`	cadeia (de caracteres)	✔️ 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 suportam operadores OData como eq.
As políticas suportam predicados compostos usando and e or.
Suportado apenas para ações: create, read, updatee delete. (Não execute)
As políticas filtram os resultados, mas não impedem a execução de consultas no banco de dados.
O campo deve usar o alias de campo, se mapeado.

Tipo (entidades de nome de entidade GraphQL)

Parent	Property	Tipo	Required	Default
`entities.{entity-name}.graphql`	`type`	objecto	❌ 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 (de caracteres)	None
`entities.{entity-name}.graphql.type`	`plural`	❌ Não	cadeia (de caracteres)	N/D (padrão para o valor singular)

Example

Configuration

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

Consulta GraphQL

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

Resposta 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 GraphQL)

Parent	Property	Tipo	Required	Default
`entities.{entity-name}.graphql`	`operation`	string de enum	❌ Não	mutation

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

Note

Quando {entity-name}.type é definido como stored-procedure, uma nova executeXXX tipo GraphQL é criada automaticamente. Esta operation propriedade controla onde esse tipo é colocado no esquema GraphQL. Não há impacto funcional, apenas higiene do esquema.

Format

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

Exemplo: operação

Quando operation está definido como query

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

Quando operation está definido como mutation

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

Ativado (entidades de nome de entidade 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 (de caracteres)	❌ Não	`/{entity-name}`
`entities.{entity-name}.rest`	`methods`	array de strings	❌ Não*	`POST`

* A methods propriedade é apenas para stored-procedure endpoints.

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`	objecto	❌ Não	None

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

Important

Para entidades com o 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`	objecto	❌ 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`	número 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`	objecto	❌ Não	None

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

Note

A relationship-name propriedade de cada relacionamento deve ser exclusiva em todos os relacionamentos dessa entidade.

Propriedades aninhadas

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

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

Exemplo: cardinalidade um-para-um

Cada Profile um está relacionado a exatamente um User, e 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 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

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

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

Esquema GraphQL

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

Linha de comandos

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 entrada 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 GraphQL

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

Linha de comandos

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 ligaçã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 GraphQL

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

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

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

Saúde (entidades de nome de entidade)

Parent	Property	Tipo	Required	Default
`entities.{entity-name}`	`health`	objecto	❌ 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`	número inteiro	❌ Não	`100`
`entities.{entity-name}.health`	`threshold-ms`	número inteiro	❌ Não	`1000`

Example

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

Note

O first valor deve ser inferior ou igual à runtime.pagination.max-page-size definição. Valores mais pequenos ajudam as verificações de saúde a serem concluídas mais rapidamente.

Important

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

Comentários

Esta página foi útil?

Last updated on 2025-09-24

Partilhar 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 utilização

Ações (string-array Permissions, entidades-nome, entidades)

Format

Example

Formato alternativo (somente string, quando type=stored-procedure)

Example

Ações (objeto-matriz, Permissões, entidades-nome, entidades)

Propriedades aninhadas

Format

Example

Notas de política

Tipo (entidades de nome de entidade GraphQL)

Format

Propriedades aninhadas

Example

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

Format

Exemplo: operação

Ativado (entidades de nome de entidade 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

Saúde (entidades de nome de entidade)

Propriedades aninhadas

Example

Comentários

Recursos adicionais

Formato alternativo (somente string, quando `type=stored-procedure`)