Referência do esquema de configuração do construtor de API de dados

O mecanismo do construtor da API de dados requer um arquivo de configuração. O arquivo de configuração do Data API Builder fornece uma abordagem estruturada e abrangente para configurar sua API, detalhando tudo, desde variáveis ambientais até configurações específicas da entidade. Este documento formatado em JSON começa com uma propriedade $schema. Esta configuração valida o documento.

As propriedades database-type e connection-string garantem uma integração perfeita com sistemas de banco de dados, do Banco de Dados SQL do Azure à API NoSQL do Cosmos DB.

O arquivo de configuração pode incluir opções como:

• Serviço de banco de dados e informações de conexão
• Opções de configuração global e de tempo de execução
• Conjunto de entidades expostas
• Método de autenticação
• Regras de segurança necessárias para acessar identidades
• Regras de mapeamento de nomes entre API e banco de dados
• Relações entre entidades que não podem ser inferidas
• Recursos exclusivos para serviços de banco de dados específicos

Visão geral da sintaxe

Aqui está um detalhamento rápido das "seções" primárias em um arquivo de configuração.

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

Propriedades de nível superior

Aqui está a descrição das propriedades de nível superior em um formato de tabela:

Propriedade	Descrição
$schema	Especifica o esquema JSON para validação, garantindo que a configuração siga o formato necessário.
fonte de dados	Contém os detalhes sobre o tipo de banco de dados e a cadeia de conexão , necessários para estabelecer a conexão do banco de dados.
arquivos de fonte de dados	Uma matriz opcional que especifica outros arquivos de configuração que podem definir outras fontes de dados.
tempo de execução	Define comportamentos e configurações de tempo de execução, incluindo subpropriedades para REST , GraphQL, host, cachee telemetria.
entidades	Define o conjunto de entidades (tabelas de banco de dados, exibições, etc.) que são expostas por meio da API, incluindo seus mapeamentos de , permissõese relacionamentos.

Configurações de exemplo

Aqui está um arquivo de configuração de exemplo que inclui apenas as propriedades necessárias para uma única entidade simples. Este exemplo destina-se a ilustrar um cenário 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 obter um exemplo de um cenário mais complexo, consulte o de exemplo de configuração de ponta a ponta .

Ambientes

O arquivo de configuração do construtor de API de dados pode oferecer suporte a cenários em que você precisa oferecer suporte a vários ambientes, semelhante ao arquivo appSettings.json no ASP.NET Core. O quadro fornece três valores ambientais comuns; Development, Staginge Production; Mas você pode optar por usar qualquer valor de ambiente que escolher. O ambiente que o construtor de API de dados usa deve ser configurado usando a variável de ambiente DAB_ENVIRONMENT.

Considere um exemplo em que você deseja uma configuração de linha de base e uma configuração específica de desenvolvimento. Este exemplo requer dois arquivos de configuração:

	Meio Ambiente
dab-config.json	Base
dab-config.Development.json	Desenvolvimento

Para usar a configuração específica do desenvolvimento, você deve definir a variável de ambiente DAB_ENVIRONMENT como Development.

Os arquivos de configuração específicos do ambiente substituem os valores de propriedade no arquivo de configuração base. Neste exemplo, se o valor connection-string estiver definido em ambos os arquivos, o valor do arquivo *.Development.json será usado.

Consulte esta matriz para entender melhor qual valor é usado dependendo de onde esse valor é especificado (ou não especificado) em qualquer arquivo.

	Especificado no de configuração base	Não especificado no de configuração base
Especificado no de configuração do ambiente atual	Ambiente atual	Ambiente atual
Não especificado no de configuração do ambiente atual	Base	Nenhum

Para obter um exemplo de uso de vários arquivos de configuração, consulte usar o Data API builder com ambientes.

Propriedades de configuração

Esta seção inclui todas as propriedades de configuração possíveis que estão disponíveis para um arquivo de configuração.

Esquema

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
$root	$schema	string	✔️ Sim	Nenhum

Cada arquivo de configuração começa com uma propriedade $schema, especificando o esquema JSON para validação.

Formato

{
  "$schema": <string>
}

Exemplos

Os arquivos de esquema estão disponíveis para versões 0.3.7-alpha em diante em URLs específicas, garantindo que você use a versão correta ou o esquema mais recente disponível.

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

Substitua VERSION-suffix pela versão desejada.

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

A versão mais recente do esquema está sempre disponível em https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json.

Aqui estão alguns exemplos de valores de esquema válidos.

Versão	URI	Descrição
0.3.7-alfa	https://github.com/Azure/data-api-builder/releases/download/v0.3.7-alpha/dab.draft.schema.json	Usa o esquema de configuração de uma versão alfa da ferramenta.
0.10.23	https://github.com/Azure/data-api-builder/releases/download/v0.10.23/dab.draft.schema.json	Usa o esquema de configuração para uma versão estável da ferramenta.
Últimas notícias	https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json	Usa a versão mais recente do esquema de configuração.

Fonte de dados

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
$root	data-source	string	✔️ Sim	Nenhum

A seção data-source define o banco de dados e o acesso ao banco de dados por meio da cadeia de conexão. Ele também define opções de banco de dados. A propriedade data-source configura as credenciais necessárias para se conectar ao banco de dados de backup. A seção data-source descreve a conectividade do banco de dados de back-end, especificando o database-type e o 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>
    }
  }
}

Propriedades

	Necessário	Tipo
database-type	✔️ Sim	string de enum
connection-string	✔️ Sim	string
options	❌ Não	objeto

Tipo de base de dados

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
data-source	database-type	enum-string	✔️ Sim	Nenhum

Uma cadeia de caracteres enum usada para especificar o tipo de banco de dados a ser usado como fonte de dados.

Formato

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

Valores de tipo

A propriedade type indica o tipo de banco de dados de back-end.

Tipo	Descrição	Versão Min
mssql	Banco de Dados SQL do Azure	Nenhum
mssql	Azure SQL MI	Nenhum
mssql	Servidor SQL	SQL 2016
sqldw	Azure SQL Data Warehouse	Nenhum
postgresql	PostgreSQL	v11
mysql	MySQL	v8
cosmosdb_nosql	Azure Cosmos DB para NoSQL	Nenhum
cosmosdb_postgresql	Azure Cosmos DB para PostgreSQL	Nenhum

Cadeia de conexão

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
data-source	connection-string	string	✔️ Sim	Nenhum

Uma cadeia de caracteres valor contendo uma cadeia de conexão válida para se conectar ao serviço de banco de dados de destino. A cadeia de conexão ADO.NET para se conectar ao banco de dados de back-end. Para obter mais informações, consulte ADO.NET cadeias de conexão.

Formato

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

Resiliência da conexão

O construtor de API de dados tenta novamente automaticamente as solicitações de banco de dados depois de detetar erros transitórios. A lógica de repetição segue uma estratégia de de Backoff Exponencial , onde o número máximo de tentativas é de cinco. A duração do recuo de repetição após solicitações subsequentes é calculada usando esta fórmula (supondo que a tentativa de repetição atual seja r): $r^2$

Usando essa fórmula, você pode calcular o tempo para cada tentativa de repetição em segundos.

	Segundos
Primeira	2
Second	4
Terceiro	8
Quarta	16
Quinta	32

Azure SQL e SQL Server

O construtor de API de dados usa a biblioteca de SqlClient para se conectar ao SQL ou SQL Server do Azure usando a cadeia de conexão fornecida no arquivo de configuração. Uma lista de todas as opções de cadeia de conexão suportadas está disponível aqui: Propriedade SqlConnection.ConnectionString.

O construtor de API de dados também pode se conectar ao banco de dados de destino usando Identidades de Serviço Gerenciado (MSI) quando o Construtor de API de Dados está hospedado no Azure. O DefaultAzureCredential definido em Azure.Identity biblioteca é usado para se conectar usando identidades conhecidas quando você não especifica um nome de usuário ou senha na cadeia de conexão. Para obter mais informações, consulte DefaultAzureCredential exemplos.

• de Identidade Gerenciada Atribuída pelo Usuário (UMI): Anexe as propriedades de Autenticação e ID de Usuário à sua cadeia de conexão enquanto substitui a ID do cliente da Identidade Gerenciada Atribuída pelo Usuário: Authentication=Active Directory Managed Identity; User Id=<UMI_CLIENT_ID>;.
• System Assigned Managed Identity (SMI): Anexe a propriedade de Autenticação e exclua os argumentos UserId e Password da cadeia de conexão: . A ausência do UserId e propriedades da cadeia de conexão Password sinalizará DAB para autenticação usando uma identidade gerenciada atribuída ao sistema.

Para obter mais informações sobre como configurar uma Identidade de Serviço Gerenciado com o SQL ou SQL Server do Azure, consulte identidades gerenciadas no Microsoft Entra para o SQLdo Azure .

Exemplos

O valor usado para a cadeia de conexão depende em grande parte do serviço de banco de dados usado em seu cenário. Você sempre pode optar por armazenar a cadeia de conexão em uma variável de ambiente e acessá-la usando a função @env().

	Valor	Descrição
Usar o valor da cadeia de caracteres do Banco de Dados SQL do Azure	Server=<server-address>;Database=<name-of-database>;User ID=<username>;Password=<password>;	Cadeia de conexão para uma conta do Banco de Dados SQL do Azure. Para obter mais informações, consulte cadeias de conexão do Banco de Dados SQL do Azure.
Usar o Banco de Dados do Azure para o valor da cadeia de caracteres PostgreSQL	Server=<server-address>;Database=<name-of-database>;Port=5432;User Id=<username>;Password=<password>;Ssl Mode=Require;	Cadeia de conexão para uma conta do Banco de Dados do Azure para PostgreSQL. Para obter mais informações, consulte Banco de Dados do Azure para cadeias de conexão PostgreSQL.
Usar o Azure Cosmos DB para o valor da cadeia de caracteres NoSQL	AccountEndpoint=<endpoint>;AccountKey=<key>;	Cadeia de conexão para uma conta do Azure Cosmos DB para NoSQL. Para obter mais informações, consulte Azure Cosmos DB para cadeias de conexão NoSQL.
Usar o Banco de Dados do Azure para o valor da cadeia de caracteres do MySQL	Server=<server-address>;Database=<name-of-database>;User ID=<username>;Password=<password>;Sslmode=Required;SslCa=<path-to-certificate>;	Cadeia de conexão para uma conta do Banco de Dados do Azure para MySQL. Para obter mais informações, consulte Banco de Dados do Azure para cadeias de conexão MySQL.
Variável de ambiente do Access	@env('database-connection-string')	Acesse uma variável de ambiente a partir da máquina local. Neste exemplo, a variável de ambiente database-connection-string é referenciada.

Esses exemplos apenas ilustram como cada tipo de banco de dados pode ser configurado. Seu cenário pode ser único, mas este exemplo é um bom ponto de partida. Substitua os espaços reservados, como myserver, myDataBase, mylogine myPassword, pelos valores reais específicos do seu ambiente.

• mssql

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

  • Formato típico de cadeia de conexão: "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 típico de cadeia de conexão: "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 típico de cadeia de conexão: "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 típico de cadeia de conexão: "AccountEndpoint=https://mycosmosdb.documents.azure.com:443/;AccountKey=myAccountKey;"

• cosmosdb_postgresql

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

  • Formato típico de cadeia de conexão: "Host=mycosmosdb.postgres.database.azure.com;Database=myDataBase;Username=mylogin@mycosmosdb;Password=myPassword;Port=5432;SSL Mode=Require;"

Opções

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
data-source	options	objeto	❌ Não	Nenhum

Uma seção opcional de parâmetros chave-valor extra para conexões de banco de dados específicas.

Formato

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

Exemplos

Se a seção options é necessária ou não, depende em grande parte do serviço de banco de dados que está sendo usado.

	Valor	Descrição
Habilitar SESSION_CONTEXT no SQL SQL do Azure ou no SQL Server	"set-session-context": false	Para o SQL do Azure e o SQL Server, o construtor de API de Dados pode aproveitar SESSION_CONTEXT para enviar metadados especificados pelo usuário para o banco de dados subjacente. Esses metadados estão disponíveis para o construtor de API de dados em virtude das declarações presentes no token de acesso. Os dados SESSION_CONTEXT ficam disponíveis para o banco de dados durante a conexão do banco de dados até que essa conexão seja fechada. Para obter mais informações, consulte contexto da sessão.

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

Arquivos de fonte de dados

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
$root	data-source-files	matriz de cadeia de caracteres	❌ Não	Nenhum

O construtor de API de dados suporta vários arquivos de configuração para diferentes fontes de dados, com um designado como o arquivo de nível superior gerenciando runtime configurações. Todas as configurações compartilham o mesmo esquema, permitindo runtime configurações em qualquer arquivo sem erros. As configurações filho são mescladas automaticamente, mas as referências circulares devem ser evitadas. As entidades podem ser divididas em arquivos separados para melhor gerenciamento, mas as relações entre entidades devem estar no mesmo arquivo.

Formato

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

Considerações sobre o arquivo de configuração

• Cada arquivo de configuração deve incluir a propriedade data-source.
• Cada arquivo de configuração deve incluir a propriedade entities.
• A configuração runtime só é usada a partir do arquivo de configuração de nível superior, mesmo se incluído em outros arquivos.
• Os arquivos de configuração filho também podem incluir seus próprios arquivos filho.
• Os arquivos de configuração podem ser organizados em subpastas, conforme desejado.
• Os nomes de entidade devem ser exclusivos em todos os arquivos de configuração.
• Não há suporte para relacionamentos entre entidades em diferentes arquivos de configuração.

Exemplos

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

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

A sintaxe da subpasta também é suportada:

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

Tempo de execução

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
$root	runtime	objeto	✔️ Sim	Nenhum

A seção runtime descreve as opções que influenciam o comportamento e as configurações de tempo de execução para todas as entidades expostas.

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

Propriedades

	Necessário	Tipo
rest	❌ Não	objeto
graphql	❌ Não	objeto
host	❌ Não	objeto
cache	❌ Não	objeto

Exemplos

Aqui está um exemplo de uma seção de tempo de execução com vários parâmetros padrão comuns 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 (tempo de execução)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
runtime	graphql	objeto	❌ Não	Nenhum

Este objeto define se o GraphQL está habilitado e o(s) nome(s) usado(s) para expor a entidade como um tipo GraphQL. Este objeto é opcional e só é usado se o nome ou as configurações padrão não forem suficientes. Esta seção descreve as configurações globais para o ponto de extremidade 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>
    }
  }
}

Propriedades

Propriedade	Necessário	Tipo	Inadimplência
enabled	❌ Não	Booleano	Verdadeiro
path	❌ Não	string	/graphql (padrão)
allow-introspection	❌ Não	Booleano	Verdadeiro
multiple-mutations	❌ Não	objeto	{ create: { enabled: false } }

Ativado (tempo de execução do GraphQL)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
runtime.graphql	enabled	Booleano	❌ Não	Nenhum

Define se os pontos de extremidade GraphQL devem ser habilitados ou desabilitados globalmente. Se desativado globalmente, nenhuma entidade será acessível por meio de solicitações GraphQL, independentemente das configurações individuais da entidade.

Formato

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

Exemplos

Neste exemplo, o ponto de extremidade GraphQL está desabilitado para todas as entidades.

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

Limite de profundidade (tempo de execução do GraphQL)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
runtime.graphql	depth-limit	inteiro	❌ Não	Nenhum

A profundidade máxima de consulta permitida de uma consulta.

A capacidade do GraphQL de lidar com consultas aninhadas com base em definições de relacionamento é um recurso incrível, permitindo que os usuários busquem dados complexos e relacionados em uma única consulta. No entanto, à medida que os usuários continuam a adicionar consultas aninhadas, a complexidade da consulta aumenta, o que pode, eventualmente, comprometer o desempenho e a confiabilidade do banco de dados e do ponto de extremidade da API. Para gerenciar essa situação, a propriedade runtime/graphql/depth-limit define a profundidade máxima permitida de uma consulta GraphQL (e mutação). Essa propriedade permite que os desenvolvedores encontrem um equilíbrio, permitindo que os usuários aproveitem os benefícios das consultas aninhadas enquanto colocam limites para evitar cenários que possam comprometer o desempenho e a qualidade do sistema.

Exemplos

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

Caminho (tempo de execução do GraphQL)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
runtime.graphql	path	string	❌ Não	"/graphql"

Define o caminho da URL onde o ponto de extremidade GraphQL é disponibilizado. Por exemplo, se esse parâmetro estiver definido como /graphql, o ponto de extremidade GraphQL será exposto como /graphql. Por padrão, o caminho é /graphql.

Formato

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

Exemplos

Neste exemplo, o URI raiz do GraphQL é /query.

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

Permitir introspeção (tempo de execução do GraphQL)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
runtime.graphql	allow-introspection	Booleano	❌ Não	Verdadeiro

Esse sinalizador booleano controla a capacidade de executar consultas de introspeção de esquema no ponto de extremidade GraphQL. Habilitar a introspeção permite que os clientes consultem o esquema para obter informações sobre os tipos de dados disponíveis, os tipos de consultas que podem executar e as mutações disponíveis.

Esse recurso é útil durante o desenvolvimento para entender a estrutura da API do GraphQL e para ferramentas que geram consultas automaticamente. No entanto, para ambientes de produção, ele pode ser desabilitado para obscurecer os detalhes do esquema da API e aumentar a segurança. Por padrão, a introspeção é ativada, permitindo a exploração imediata e abrangente do esquema GraphQL.

Formato

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

Exemplos

Neste exemplo, a introspeção está desativada.

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

Mutações múltiplas (tempo de execução do GraphQL)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
runtime.graphql	multiple-mutations	objeto	❌ Não	Nenhum

Configura todas as operações de mutação múltipla para o tempo de execução do GraphQL.

Formato

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

Propriedades

	Necessário	Tipo
create	❌ Não	objeto

Mutações múltiplas - criar (tempo de execução do GraphQL)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
runtime.graphql.multiple-mutations	create	Booleano	❌ Não	Falso

Configura várias operações de criação para o tempo de execução do GraphQL.

Formato

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

Propriedades

Propriedade	Necessário	Tipo	Inadimplência
enabled	✔️ Sim	Booleano	Verdadeiro

Exemplos

Neste exemplo, várias mutações são habilitadas para o tempo de execução do GraphQL. Especificamente, a operação de criação múltipla é habilitada especificando um valor de true para a propriedade runtime.graphql.multiple-mutations.create.enabled.

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

REST (tempo de execução)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
runtime	rest	objeto	❌ Não	Nenhum

Esta seção descreve as configurações globais para os pontos de extremidade REST. Essas configurações servem como padrões para todas as entidades, mas podem ser substituídas por entidade em suas respetivas configurações.

Formato

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

Propriedades

Propriedade	Necessário	Tipo	Inadimplência
enabled	❌ Não	Booleano	Verdadeiro
path	❌ Não	string	/api
request-body-strict	❌ Não	Booleano	Verdadeiro

Ativado (tempo de execução REST)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
runtime.rest	enabled	Booleano	❌ Não	Nenhum

Um sinalizador booleano que determina a disponibilidade global de pontos de extremidade REST. Se desabilitadas, as entidades não podem ser acessadas via REST, independentemente das configurações de entidades individuais.

Formato

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

Exemplos

Neste exemplo, o ponto de extremidade da API REST está desabilitado para todas as entidades.

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

Caminho (tempo de execução REST)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
runtime.rest	path	string	❌ Não	"/api"

Define o caminho da URL para acessar todos os pontos de extremidade REST expostos. Por exemplo, definir path como /api torna o ponto de extremidade REST acessível em /api/<entity>. Subcaminhos não são permitidos. Este campo é opcional, com /api como padrão.

Formato

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

Exemplos

Neste exemplo, a raiz REST API URI é /data.

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

Solicitar corpo estrito (tempo de execução REST)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
runtime.rest	request-body-strict	Booleano	❌ Não	Verdadeiro

Esse sinalizador booleano determina se o corpo da solicitação para uma operação de mutação REST pode conter campos estranhos. Por padrão, o valor é true, o que significa que campos extras no corpo da solicitação resultam em uma exceção BadRequest. No entanto, definir esse sinalizador como false permite que os usuários incluam campos extras no corpo da solicitação, que são ignorados. É importante observar que esse sinalizador não afeta as solicitações de consulta REST (GET), pois o corpo da solicitação é sempre ignorado para operações GET.

Formato

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

Exemplos

Neste exemplo, a validação do corpo da solicitação estrita está desabilitada.

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

Host (tempo de execução)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
runtime	host	objeto	❌ Não	Nenhum

A seção host dentro da configuração de tempo de execução fornece definições cruciais para o ambiente operacional do construtor de API de dados. Essas configurações incluem modos operacionais, configuração CORS e detalhes de autenticação.

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

Propriedades

Propriedade	Necessário	Tipo	Inadimplência
mode	❌ Não	string de enum	Produção
cors	❌ Não	objeto	Nenhum
authentication	❌ Não	objeto	Nenhum

Exemplos

Aqui está um exemplo de um tempo de execução configurado para hospedagem de desenvolvimento.

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

Modo (tempo de execução do host)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
runtime.host	mode	string	❌ Não	"produção"

Define se o mecanismo do construtor de API de dados deve ser executado no modo development ou production. O valor predefinido é production.

Normalmente, os erros do banco de dados subjacente são expostos em detalhes, definindo o nível padrão de detalhe para logs a Debug quando executados em desenvolvimento. Na produção, o nível de detalhe dos logs é definido como Error.

Formato

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

Valores

Aqui está uma lista de valores permitidos para esta propriedade:

	Descrição
production	Usar ao hospedar em produção no Azure
development	Uso em desenvolvimento em máquina local

Tamanho máximo da resposta (Runtime)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
runtime.host	max-response-size-mb	inteiro	❌ Não	158

Define o tamanho máximo (em megabytes) para qualquer resultado. Essa configuração permite que os usuários configurem a quantidade de dados que a memória da plataforma host pode manipular ao transmitir dados das fontes de dados subjacentes.

Quando os usuários solicitam grandes conjuntos de resultados, isso pode sobrecarregar o banco de dados e o construtor de API de dados. Para resolver isso, max-response-size-mb permite que os desenvolvedores limitem o tamanho máximo da resposta, medido em megabytes, conforme os fluxos de dados da fonte de dados. Esse limite é baseado no tamanho geral dos dados, não no número de linhas. Como as colunas podem variar em tamanho, algumas colunas (como texto, binário, XML ou JSON) podem conter até 2 GB cada, tornando as linhas individuais potencialmente muito grandes. Essa configuração ajuda os desenvolvedores a proteger seus endpoints limitando os tamanhos de resposta e evitando sobrecargas do sistema, mantendo a flexibilidade para diferentes tipos de dados.

Valores permitidos

Valor	Resultado
null	O padrão é 158 megabytes se não estiver definido ou explicitamente definido como null.
integer	Qualquer inteiro positivo de 32 bits é suportado.
< 0	Não suportado. Os erros de validação ocorrem se definidos como inferiores a 1 MB.

Formato

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

CORS (Tempo de execução do host)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
runtime.host	cors	objeto	❌ Não	Nenhum

Configurações de compartilhamento de recursos entre origens (CORS) para o host do mecanismo do construtor de API de dados.

Formato

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

Propriedades

	Necessário	Tipo
allow-credentials	❌ Não	Booleano
origins	❌ Não	matriz de cadeia de caracteres

Permitir credenciais (tempo de execução do host)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
runtime.host.cors	allow-credentials	Booleano	❌ Não	Falso

Se true, define o cabeçalho CORS Access-Control-Allow-Credentials.

Formato

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

Origens (tempo de execução do host)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
runtime.host.cors	origins	matriz de cadeia de caracteres	❌ Não	Nenhum

Define uma matriz com uma lista de origens permitidas para CORS. Essa configuração permite que o curinga * para todas as origens.

Formato

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

Exemplos

Aqui está um exemplo de um host que permite CORS sem credenciais de todas as origens.

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

Autenticação (tempo de execução do host)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
runtime.host	authentication	objeto	❌ Não	Nenhum

Configura a autenticação para o host do construtor de API de dados.

Formato

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

Propriedades

Propriedade	Necessário	Tipo	Inadimplência
provider	❌ Não	string de enum	StaticWebApps
jwt	❌ Não	objeto	Nenhum

Autenticação e responsabilidades do cliente

O construtor de API de dados foi projetado para operar dentro de um pipeline de segurança mais amplo, e há etapas importantes a serem configuradas antes de processar solicitações. É importante entender que o construtor de API de dados não autentica o chamador direto (como seu aplicativo Web), mas sim o usuário final, com base em um token JWT válido fornecido por um provedor de identidade confiável (por exemplo, Entra ID). Quando uma solicitação chega ao construtor de API de dados, ela assume que o token JWT é válido e o verifica em relação a quaisquer pré-requisitos que você tenha configurado, como declarações específicas. As regras de autorização são então aplicadas para determinar o que o usuário pode acessar ou modificar.

Depois que a autorização é aprovada, o construtor de API de dados executa a solicitação usando a conta especificada na cadeia de conexão. Como essa conta geralmente requer permissões elevadas para lidar com várias solicitações de usuário, é essencial minimizar seus direitos de acesso para reduzir o risco. Recomendamos proteger sua arquitetura configurando um Link Privado entre seu aplicativo Web front-end e o ponto de extremidade da API e protegendo a máquina que hospeda o construtor de API de dados. Essas medidas ajudam a garantir que seu ambiente permaneça seguro, protegendo seus dados e minimizando vulnerabilidades que podem ser exploradas para acessar, modificar ou exfiltrar informações confidenciais.

Provedor (tempo de execução do host)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
runtime.host.authentication	provider	string	❌ Não	"StaticWebApps"

A configuração authentication.provider na configuração host define o método de autenticação usado pelo construtor da API de dados. Ele determina como a API valida a identidade de usuários ou serviços que tentam acessar seus recursos. Essa configuração permite flexibilidade na implantação e integração, oferecendo suporte a vários mecanismos de autenticação adaptados a diferentes ambientes e requisitos de segurança.

Fornecedor	Descrição
StaticWebApps	Instrui o construtor de API de Dados a procurar um conjunto de cabeçalhos HTTP presentes apenas durante a execução em um ambiente de Aplicativos Web estáticos.
AppService	Quando o tempo de execução é hospedado no Azure AppService com a Autenticação do AppService habilitada e configurada (EasyAuth).
AzureAd	O Microsoft Entra Identity precisa ser configurado para que possa autenticar uma solicitação enviada ao construtor de API de dados (o "Aplicativo de Servidor"). Para obter mais informações, consulte de autenticação do Microsoft Entra ID .
Simulator	Um provedor de autenticação configurável que instrui o mecanismo do construtor de API de dados a tratar todas as solicitações como autenticadas. Para obter mais informações, consulte de autenticação local .

Formato

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

Valores

Aqui está uma lista de valores permitidos para esta propriedade:

	Descrição
StaticWebApps	Aplicativos Web estáticos do Azure
AppService	Serviço de Aplicativo do Azure
AzureAD	Microsoft Entra ID
Simulator	Simulador

Tokens Web JSON (tempo de execução do host)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
runtime.host.authentication	jwt	objeto	❌ Não	Nenhum

Se o provedor de autenticação estiver definido como AzureAD (ID do Microsoft Entra), esta seção será necessária para especificar a audiência e os emissores para o token JSOn Web Tokens (JWT). Esses dados são usados para validar os tokens em relação ao locatário do Microsoft Entra.

Necessário se o provedor de autenticação estiver AzureAD para o Microsoft Entra ID. Esta seção deve especificar os audience e issuer validar o token JWT recebido em relação ao locatário AzureAD pretendido para autenticação.

Cenário	Descrição
Público-alvo	Identifica o destinatário pretendido do token; normalmente o identificador do aplicativo registrado no Microsoft Entra Identity (ou seu provedor de identidade), garantindo que o token foi realmente emitido para seu aplicativo.
emitente	Especifica a URL da autoridade emissora, que é o serviço de token que emitiu o JWT. Esse URL deve corresponder ao URL do emissor do provedor de identidade do qual o JWT foi obtido, validando a origem do token.

Formato

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

Propriedades

Propriedade	Necessário	Tipo	Inadimplência
audience	❌ Não	string	Nenhum
issuer	❌ Não	string	Nenhum

Exemplos

O construtor de API de dados (DAB) oferece suporte flexível à autenticação, integrando-se com o Microsoft Entra Identity e servidores JWT (JSON Web Token) personalizados. Nesta imagem, o JWT Server representa o serviço de autenticação que emite tokens JWT para clientes após o login bem-sucedido. Em seguida, o cliente passa o token para o DAB, que pode interrogar suas declarações e propriedades.

A seguir estão exemplos da propriedade host dadas várias opções de arquitetura que você pode fazer em sua solução.

Aplicativos Web estáticos do Azure

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

Com StaticWebApps, o construtor de API de Dados espera que os Aplicativos Web Estáticos do Azure autentiquem a solicitação e o cabeçalho HTTP X-MS-CLIENT-PRINCIPAL esteja presente.

Serviço de Aplicativo do Azure

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

A autenticação é delegada a um provedor de identidade suportado onde o token de acesso pode ser emitido. Um token de acesso adquirido deve ser incluído nas solicitações de entrada para o Data API builder. Em seguida, o construtor de API de dados valida todos os tokens de acesso apresentados, garantindo que o construtor de API de dados seja o público-alvo do 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 (somente desenvolvimento)

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

Audiência (tempo de execução do host)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
runtime.host.authentication.jwt	audience	string	❌ Não	Nenhum

Audiência para o token JWT.

Formato

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

Emissor (tempo de execução do host)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
runtime.host.authentication.jwt	issuer	string	❌ Não	Nenhum

Emissor do token JWT.

Formato

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

Paginação (tempo de execução)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
runtime	pagination	objeto	❌ Não	Nenhum

Configura limites de paginação.

Formato

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

Propriedades

Propriedade	Necessário	Tipo	Inadimplência
max-page-size	❌ Não	inteiro	100,000
default-page-size	❌ Não	inteiro	100

Exemplo

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

Exemplo de paginação REST

Neste exemplo, emitir o https://localhost:5001/api/books REST GET retornaria um registro na matriz value porque o default-page-size foi definido como 1. Se existirem mais resultados, o construtor de API de dados acrescentará um nextLink na resposta. O nextLink contém um parâmetro $after para recuperar a próxima página de dados.

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

O uso do nextLink garante que o próximo conjunto de resultados seja retornado, mesmo que os dados tenham sido alterados entre consultas.

Exemplo de paginação do GraphQL

Para GraphQL, use os campos hasNextPage e endCursor para paginação. Estes são necessários para obter o próximo conjunto de resultados. Sem eles, a consulta ainda é limitada ao tamanho de página padrão.

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

A resposta inclui os campos hasNextPage e endCursor:

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

Para buscar a próxima página, inclua o valor do cursor na próxima consulta:

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

Usando $limit ou first para alterar o tamanho da página:

REST e GraphQL suportam um parâmetro $limit ou first para ajustar o número de resultados por consulta. Por exemplo, https://{server}/api/books?$limit=10 limita o resultado a 10 registros, substituindo o default-page-size. Se $limit exceder max-page-size, o resultado é limitado a max-page-size.

Primeiro valor	Resultado
-1	O padrão é a configuração max-page-size atual.
< max-page-size	Limita o resultado ao valor fornecido.
0	Não suportado.
< -1	Não suportado.
> max-page-size	Não suportado.

---

Tamanho máximo da página (tempo de execução da paginação)

Pai	Propriedade	Tipo	Necessário	Inadimplência
runtime.pagination	max-page-size	Int	❌ Não	100,000

Define o número máximo de registros de nível superior retornados por REST ou GraphQL. Se um usuário solicitar mais de max-page-size, os resultados serão limitados a max-page-size.

Valores permitidos

Valor	Resultado
-1	O padrão é o valor máximo suportado.
integer	Qualquer inteiro positivo de 32 bits é suportado.
< -1	Não suportado.
0	Não suportado.

Formato

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

---

Tamanho de página padrão (tempo de execução de paginação)

Pai	Propriedade	Tipo	Necessário	Inadimplência
runtime.pagination	default-page-size	Int	❌ Não	100

Define o número padrão de registros de nível superior retornados quando a paginação está habilitada, mas nenhum tamanho de página explícito é fornecido.

Valores permitidos

Valor	Resultado
-1	O padrão é a configuração max-page-size atual.
integer	Qualquer número inteiro positivo menor que o max-page-sizeatual.
< -1	Não suportado.
0	Não suportado.

Cache (tempo de execução)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
runtime	cache	objeto	❌ Não	Nenhum

Habilita e configura o cache para todo o tempo de execução.

Formato

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

Propriedades

Propriedade	Necessário	Tipo	Inadimplência
enabled	❌ Não	Booleano	Nenhum
ttl-seconds	❌ Não	inteiro	5

Exemplos

Neste exemplo, o cache é habilitado e os itens expiram após 30 segundos.

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

Ativado (tempo de execução do cache)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
runtime.cache	enabled	Booleano	❌ Não	Falso

Permite o armazenamento em cache globalmente para todas as entidades. O padrão é false.

Formato

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

Exemplos

Neste exemplo, o cache está desabilitado.

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

TTL em segundos (tempo de execução do cache)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
runtime.cache	ttl-seconds	inteiro	❌ Não	5

Configura o valor TTL (time-to-live) em segundos para itens armazenados em cache. Após esse tempo, os itens são removidos automaticamente do cache. O valor padrão é 5 segundos.

Formato

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

Exemplos

Neste exemplo, o cache é habilitado globalmente e todos os itens expiram após 15 segundos.

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

Telemetria (tempo de execução)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
runtime	telemetry	objeto	❌ Não	Nenhum

Esta propriedade configura o Application Insights para centralizar logs de API. Saiba mais.

Formato

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

Application Insights (tempo de execução de telemetria)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
runtime.telemetry	application-insights	objeto	✔️ Sim	Nenhum

Ativado (telemetria do Application Insights)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
runtime.telemetry.application-insights	enabled	Booleano	❌ Não	Verdadeiro

Cadeia de conexão (telemetria do Application Insights)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
runtime.telemetry.application-insights	connection-string	string	✔️ Sim	Nenhum

Entidades

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
$root	entities	objeto	✔️ Sim	Nenhum

A seção entities serve como o núcleo do arquivo de configuração, estabelecendo uma ponte entre os objetos de banco de dados e seus pontos de extremidade de API correspondentes. Esta seção mapeia objetos de banco de dados para pontos de extremidade expostos. Esta seção também inclui mapeamento de propriedades e definição de permissão. Cada entidade exposta é definida em um objeto dedicado. O nome da propriedade do objeto é usado como o nome da entidade a ser exposta.

Esta seção define como cada entidade no banco de dados é representada na API, incluindo mapeamentos de propriedade e permissões. Cada entidade é encapsulada em sua própria subseção, com o nome da entidade atuando como uma chave para referência em toda a configuração.

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

Propriedades

	Necessário	Tipo
source	✔️ Sim	objeto
permissions	✔️ Sim	matriz
rest	❌ Não	objeto
graphql	❌ Não	objeto
mappings	❌ Não	objeto
relationships	❌ Não	objeto
cache	❌ Não	objeto

Exemplos

Por exemplo, esse objeto JSON instrui o construtor de API de dados a expor uma entidade GraphQL chamada Author e um ponto de extremidade REST acessível através do caminho /Author. A tabela de banco de dados dbo.authors apoia a entidade e a configuração permite que qualquer pessoa acesse o ponto de extremidade anonimamente.

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

Este exemplo declara a entidade User. Esse nome User é usado em qualquer lugar no arquivo de configuração onde as entidades são referenciadas. Caso contrário, o nome da entidade não será relevante para os pontos de extremidade.

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

Fonte

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
entities.{entity}	source	objeto	✔️ Sim	Nenhum

A configuração {entity}.source conecta a entidade exposta à API e seu objeto de banco de dados subjacente. Essa propriedade especifica a tabela, a exibição ou o procedimento armazenado do banco de dados que a entidade representa, estabelecendo um link direto para recuperação e manipulação de dados.

Para cenários simples, em que a entidade mapeia diretamente para uma única tabela ou coleção de banco de dados, a propriedade source precisa apenas do nome desse objeto de banco de dados. Essa simplicidade facilita a configuração rápida para casos de uso comuns.

Formato

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

Propriedades

	Necessário	Tipo
object	✔️ Sim	string
type	✔️ Sim	string de enum
parameters	❌ Não	objeto
key-fields	❌ Não	matriz de cadeia de caracteres

Exemplos

Este exemplo mostra a estrutura mais simples para associar uma entidade a uma tabela de origem.

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

Aqui está um resumo de uma relação muitos-para-muitos.

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

• A entidade Todo apoiada por um procedimento armazenado.
• A propriedade type dentro do código-fonte é definida como stored-procedure, indicando o tipo de objeto de origem para o qual a entidade está mapeada.
• A propriedade object na origem é o nome do procedimento armazenado no banco de dados.

Também neste exemplo, a propriedade mapping (opcional) é adicionada à configuração da entidade "Todo". Ele especifica como os campos na entidade (Id, Title, Descriptione Completed) são mapeados para os campos correspondentes na fonte de dados subjacente ou parâmetros de procedimento armazenado (todo_id, todo_title, todo_descriptione todo_completed, respectivamente). Esse mapeamento garante que os dados corretos sejam passados entre a entidade e o procedimento armazenado durante as operações de criação/atualização.

O exemplo anterior usaria o seguinte procedimento 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 obrigatório sem um valor padrão.
• @Completed: Parâmetro opcional. Se fornecido, filtra todos pelo seu status de conclusão.
• @CategoryName: Parâmetro opcional. Se fornecido, filtra todos por nome de categoria.

Aqui está um exemplo de atualizações usando um procedimento armazenado.

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

Este exemplo define explicitamente o método HTTP para interagir com essa entidade como POST usando a propriedade de método.

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

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
entities.{entity}.source	object	string	✔️ Sim	Nenhum

Nome do objeto de banco de dados a ser usado.

Exemplos

Neste exemplo, object refere-se ao objeto dbo.books no banco de dados.

{
  "entities": {
    "Book": {
      "source": {
        "object": "dbo.books",
        "type": "table"
      }
    }
  }
}

Tipo (entidades)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
entities.{entity}.source	type	string	✔️ Sim	Nenhum

A propriedade type identifica o tipo de objeto de banco de dados por trás da entidade, eles incluem view, tablee stored-procedure. A propriedade type é necessária e não há valor padrão.

Formato

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

Valores

Aqui está uma lista de valores permitidos para esta propriedade:

	Descrição
table	Representa uma tabela.
stored-procedure	Representa um procedimento armazenado.
view	Representa um modo de exibição.

Exemplos

Neste exemplo, type indica que essa fonte é uma exibição no banco de dados. Este valor influencia se outros valores (ex: key-fields) são necessários.

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

Domínios-chave

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
entities.{entity}.source	key-fields	matriz de cadeia de caracteres	❌ Não	Nenhum

A configuração {entity}.key-fields é necessária para entidades apoiadas por exibições, para que o Data API builder saiba como pode identificar e retornar um único item, se necessário. Se type estiver definido como view sem key-fields, o mecanismo do construtor da API de dados se recusará a iniciar.

Formato

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

Exemplos

Este exemplo usa o modo de exibição dbo.vw_category_details com category_id indicado como campo chave.

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

Parâmetros

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
entities.{entity}.source	parameters	objeto	❌ Não	Nenhum

A configuração {entity}.source.parameters é importante para entidades apoiadas por procedimentos armazenados, permitindo que os desenvolvedores especifiquem parâmetros e seus valores padrão. Os parâmetros garantem que, se determinados parâmetros não forem fornecidos em uma solicitação HTTP, o sistema poderá retornar a esses valores predefinidos.

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

Exemplos

Este exemplo invoca o procedimento armazenado dbo.stp_get_bestselling_books passando estes dois parâmetros:

	Valor
depth	25
list	contoso-best-sellers

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

Permissões

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
entities.{entity}	permissions	objeto	✔️ Sim	Nenhum

Esta seção define quem pode acessar a entidade relacionada e quais ações são permitidas. As permissões são definidas nesta seção em termos de funções. As ações são definidas como operações CRUD típicas, incluindo: create, read, updatee delete. A seção permissions define quem (em termos de funções) pode acessar a entidade relacionada e usando quais ações. As ações são as operações CRUD usuais: create, read, update, delete.

Formato

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

Ação	Descrição
create	Permite criar um novo registo na entidade.
read	Permite ler ou recuperar registros da entidade.
update	Permite atualizar os registos existentes na entidade.
delete	Permite excluir registros da entidade.
execute	Permite executar um procedimento armazenado ou operação relacionada à entidade.
*	Subvenções a todas as operações CRUD aplicáveis

Exemplos

Neste exemplo, uma função anônima é definida com acesso a todas as ações possíveis.

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

Você também pode misturar e combinar ações de cadeia de caracteres e matriz de objetos.

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

Função Anônima Permitir que usuários anônimos leiam todos os campos, exceto o secret-field. O uso de "include": ["*"] com "exclude": ["secret-field"] efetivamente esconde secret-field de usuários anônimos, permitindo o acesso a todos os outros campos.

Função autenticada Permitir que usuários autenticados leiam e atualizem campos específicos, incluindo explicitamente id, titlee secret-field, mas excluindo secret-field. Demonstra a inclusão explícita e subsequente exclusão de secret-field, mostrando a precedência de exclude. Uma vez que secret-field está incluído e excluído, acaba por ser inacessível, o que corresponde à regra pretendida de exclude tendo precedência.

Função de Autor Autores podem fazer todas as operações * em todos os campos sem exclusões. O arquivo indica "include": ["*"] com uma matriz de "exclude": [] vazia concede acesso a todos os campos, pois nenhum campo é explicitamente excluído.

Essa configuração representa o padrão se nada for especificado.

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

É efetivamente idêntico a:

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

Considere também a seguinte configuração:

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

A configuração anterior especifica efetivamente que nenhum campo está explicitamente incluído ("include": [] está vazio, indicando que nenhum campo é permitido) e que todos os campos são excluídos ("exclude": ["*"] usa o * curinga para indicar todos os campos).

Uso prático: Tal configuração pode parecer contraintuitiva, uma vez que restringe o acesso a todos os campos. No entanto, ele pode ser utilizado em cenários em que uma função pode executar determinadas ações - como criar uma entidade - sem acessar nenhum de seus dados.

O mesmo comportamento, mas com sintaxe diferente, seria:

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

A configuração anterior tenta especificar que apenas os campos Id e Title devem ser incluídos, ao mesmo tempo em que indica que todos os campos devem ser excluídos com o * curinga na seção exclude. Outra forma de expressar a mesma lógica seria:

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

Dada a regra geral de que a lista exclude tem precedência sobre a lista include, especificar exclude: ["*"] normalmente significaria que todos os campos são excluídos, mesmo os campos listados na seção include. Assim, à primeira vista, esta configuração pode parecer impedir que quaisquer campos sejam acessíveis, uma vez que a regra de exclusão é dominante.

Oinverso: Se a intenção for conceder, acesso apenas aos campos Id e Title, é mais claro e confiável especificar apenas esses campos na seção include e não usar exclude com um curinga. Como alternativa, você pode ajustar a lógica de permissões do sistema para acomodar explicitamente esses casos, supondo que você esteja no controle de seu design. Por exemplo:

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

Propriedades

	Necessário	Tipo
role	✔️ Sim	string
actions (string-array) ou actions (object-array)	✔️ Sim	objeto ou matriz de cadeia de caracteres

Funções

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
entities.permissions	role	string	✔️ Sim	Nenhum

String que contém o nome da função à qual a permissão definida se aplica. A cadeia de caracteres role contém o nome da função à qual a permissão definida se aplica.

As funções definem o contexto de permissões no qual uma solicitação deve ser executada. Para cada entidade definida na configuração de tempo de execução, você pode definir um conjunto de funções e permissões associadas que determinam como a entidade pode ser acessada nos pontos de extremidade REST e GraphQL. As funções não são aditivas. Para obter mais informações sobre funções, consulte autorização.

O construtor de API de dados avalia as solicitações no contexto de uma única função:

Funções	Descrição
anonymous	Nenhum token de acesso é apresentado
authenticated	É apresentado um token de acesso válido
<custom-role>	Um token de acesso válido é apresentado e o cabeçalho HTTP X-MS-API-ROLE é incluído especificando uma função de usuário que também está incluída na declaração de funções do token de acesso

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

Exemplos

Este exemplo define uma função chamada reader com apenas read permissões no ponto de extremidade.

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

Ações (string-array)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
entities.permissions	actions	oneOf [string, matriz]	✔️ Sim	Nenhum

Uma matriz de valores de cadeia de caracteres detalhando quais operações são permitidas para a função associada. Para objetos de banco de dados table e view, as funções podem ser configuradas para usar qualquer combinação de ações create, read, updateou delete. Para procedimentos armazenados, as funções só podem ter a ação execute. A matriz actions detalha quais ações são permitidas na função associada. Quando a entidade é uma tabela ou exibição, as funções podem ser configuradas com uma combinação das ações: create, read, update, delete.

Ação	Operação SQL
*	Curinga, incluindo executar
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

Exemplos

Este exemplo dá permissões de create e read para a primeira função chamada contributor. A segunda função chamada auditor só tem delete permissões.

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

Aqui está outro exemplo.

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

Ações (matriz-objeto)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
entities.permissions	actions	matriz de cadeia de caracteres	✔️ Sim	Nenhum

Uma matriz de valores de cadeia de caracteres detalhando quais operações são permitidas para a função associada. Para objetos de banco de dados table e view, as funções podem ser configuradas para usar qualquer combinação de ações create, read, updateou delete. Para procedimentos armazenados, as funções só podem ter a ação execute.

Formato

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

Propriedades

Propriedade	Necessário	Tipo	Inadimplência
action	✔️ Sim	string	Nenhum
fields	❌ Não	matriz de cadeia de caracteres	Nenhum
policy	❌ Não	objeto	Nenhum

Exemplos

Este exemplo concede apenas read permissão para a função auditor. A função auditor só pode ler dados específicos usando o predicado definido em policy.database. A função auditor também é limitada em quais campos ela pode ou não ler usando a propriedade fields.

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

Ação

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
entities.permissions.actions[]	action	string	✔️ Sim	Nenhum

Especifica a operação específica permitida no objeto de banco de dados.

Valores

Aqui está uma lista de valores permitidos para esta propriedade:

	Tabelas	Modos de exibição	Procedimentos armazenados	Descrição
create	✔️ Sim	✔️ Sim	❌ Não	Criar novos itens
read	✔️ Sim	✔️ Sim	❌ Não	Ponto de leitura de itens existentes
update	✔️ Sim	✔️ Sim	❌ Não	Atualizar ou substituir itens existentes
delete	✔️ Sim	✔️ Sim	❌ Não	Remover itens existentes
execute	❌ Não	❌ Não	✔️ Sim	Executar operações programáticas

Formato

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

Exemplos

Veja um exemplo em que anonymous usuários têm permissão para execute um procedimento armazenado específico e read uma tabela 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

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
entities.permissions.actions[]	fields	objeto	❌ Não	Nenhum

Especificações granulares sobre as quais campos específicos têm permissão de acesso para o objeto de banco de dados. A configuração de função é um tipo de objeto com duas propriedades internas, include e exclude. Esses valores suportam a definição granular de quais colunas de banco de dados (campos) têm permissão de acesso na seção fields.

Formato

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

Exemplos

Neste exemplo, a função anonymous tem permissão para ler de todos os campos, exceto id, mas pode usar todos os campos ao criar um item.

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

Incluir e excluir o trabalho em conjunto. O * curinga na seção include indica todos os campos. Os campos indicados na secção exclude têm precedência sobre os campos indicados na secção include. A definição traduz-se por incluir todos os campos, exceto o 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

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
entities.{entity}.permissions.actions[]	policy	objeto	❌ Não	Nenhum

A seção policy, definida por action, define regras de segurança no nível do item (diretivas de banco de dados) que limitam os resultados retornados de uma solicitação. A subseção database indica a expressão de política de banco de dados avaliada durante a execução da solicitação.

Formato

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

Propriedades

Propriedade	Necessário	Tipo	Inadimplência
database	✔️ Sim	string	Nenhum

Descrição

A política de database: uma expressão semelhante a OData que é traduzida em um predicado de consulta que o banco de dados avalia, incluindo operadores como eq, lte gt. Para que os resultados sejam retornados para uma solicitação, o predicado de consulta da solicitação resolvido a partir de uma política de banco de dados deve ser avaliado para true ao executar no banco de dados.

Exemplo de política de item	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

Um predicate é uma expressão que é avaliada como VERDADEIRO ou FALSO. Os predicados são usados na condição de pesquisa de WHERE cláusulas e HAVING cláusulas, as condições de junção de FROM cláusulas e outras construções onde um valor booleano é necessário. (Microsoft Learn Docs)

Política de banco de dados

Dois tipos de diretivas podem ser usados para gerenciar a diretiva de banco de dados ao criar uma expressão de diretiva de banco de dados:

Diretiva	Descrição
@claims	Acessar uma declaração dentro do token de acesso validado fornecido na solicitação
@item	Representa um campo da entidade para a qual a política de banco de dados está definida

Aqui estão alguns exemplos de políticas de banco de dados:

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

O construtor de API de dados compara o valor da declaração de UserId com o valor do campo de banco de dados OwnerId. A carga útil resultante inclui apenas registros que cumprem tanto metadados de solicitação quanto a expressão de política de banco de dados.

Limitações

Há suporte para políticas de banco de dados para tabelas e exibições. Os procedimentos armazenados não podem ser configurados com políticas.

As políticas de banco de dados não impedem a execução de solicitações no banco de dados. Esse comportamento ocorre porque eles são resolvidos como predicados nas consultas geradas que são passadas para o mecanismo de banco de dados.

As políticas de banco de dados são suportadas apenas para o actionscriar, ler, atualizare excluir. Como não há predicado em uma chamada de procedimento armazenado, eles não podem ser acrescentados.

Operadores OData suportados

Operador	Descrição	Sintaxe de exemplo
and	Lógica E	"@item.status eq 'active' and @item.age gt 18"
or	Lógica OU	"@item.region eq 'US' or @item.region eq 'EU'"
eq	Igual	"@item.type eq 'employee'"
gt	Maior que	"@item.salary gt 50000"
lt	Menos de	"@item.experience lt 5"

Para obter mais informações, consulte operadores binários.

Operador	Descrição	Sintaxe de exemplo
-	Negate (numérico)	"@item.balance lt -100"
not	Negação lógica (NOT)	"not @item.status eq 'inactive'"

Para obter mais informações, consulte operadores unários.

Restrições de nome de campo de entidade

• Regras: Deve começar com uma letra ou sublinhado (_), seguido por até 127 letras, sublinhados (_) ou dígitos (0-9).
• Impacto: Os campos que não aderem a essas regras não podem ser usados diretamente em políticas de banco de dados.
• Solução: Utilize a seção mappings para criar aliases para campos que não atendem a essas convenções de nomenclatura; Os mapeamentos garantem que todos os campos possam ser incluídos em expressões de política.

Utilização de mappings para campos não conformes

Se os nomes de campo da entidade não atenderem às regras de sintaxe OData ou se você simplesmente quiser usá-los por outros motivos, poderá definir aliases na seção mappings da sua configuração.

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

Neste exemplo, field-1-name é o nome do campo de banco de dados original que não atende às convenções de nomenclatura OData. A criação de um mapa para field-1-name e field-1-alias permite que esse campo seja referenciado em expressões de política de banco de dados sem problemas. Essa abordagem não só ajuda a aderir às convenções de nomenclatura OData, mas também melhora a clareza e a acessibilidade do seu modelo de dados nos pontos de extremidade GraphQL e RESTful.

Exemplos

Considere uma entidade chamada Employee dentro de uma configuração de API de dados que utiliza declarações e diretivas de item. Ele garante que o acesso aos dados seja gerenciado com segurança com base nas funções do usuário e na propriedade da entidade:

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

Entity Definition: A entidade Employee é configurada para interfaces REST e GraphQL, indicando que seus dados podem ser consultados ou manipulados por meio desses endpoints.

Source Configuration: Identifica o HRUNITS no banco de dados, com employee NUM como campo chave.

Mapeamentos: Os aliases são usados para mapear employee NUM, employee Namee department COID para EmployeeId, EmployeeNamee DepartmentId, respectivamente, simplificando nomes de campo e potencialmente ofuscando detalhes confidenciais do esquema do banco de dados.

Policy Application: A seção policy aplica uma diretiva de banco de dados usando uma expressão semelhante a OData. Esta política restringe o acesso aos dados aos utilizadores com a função de RH (@claims.role eq 'HR') ou aos utilizadores cuja declaração de UserId corresponde EmployeeId - o alias de campo - na base de dados (@claims.userId eq @item.EmployeeId). Ele garante que os funcionários só possam acessar seus próprios registros, a menos que pertençam ao departamento de RH. As políticas podem impor segurança em nível de linha com base em condições dinâmicas.

Base de dados

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
entities.{entity}.permissions.actions.policy	database	objeto	✔️ Sim	Nenhum

A seção policy, definida por action, define regras de segurança no nível do item (diretivas de banco de dados) que limitam os resultados retornados de uma solicitação. A subseção database indica a expressão de política de banco de dados avaliada durante a execução da solicitação.

Formato

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

Essa propriedade indica a expressão de política de banco de dados que é avaliada durante a execução da solicitação. A cadeia de caracteres de política é uma expressão OData que é convertida em uma consulta predicada avaliada pelo banco de dados. Por exemplo, a expressão de política @item.OwnerId eq 2000 é traduzida para o predicado de consulta WHERE <schema>.<object-name>.OwnerId = 2000.

Para que os resultados sejam retornados para uma solicitação, o predicado de consulta da solicitação resolvido a partir de uma política de banco de dados deve ser avaliado para true ao executar no banco de dados.

Dois tipos de diretivas podem ser usados para gerenciar a diretiva de banco de dados ao criar uma expressão de diretiva de banco de dados:

	Descrição
@claims	Acessa uma declaração dentro do token de acesso validado fornecido na solicitação
@item	Representa um campo da entidade para a qual a política de banco de dados está definida

Exemplos

Por exemplo, uma expressão de política básica pode avaliar se um campo específico é verdadeiro na tabela. Este exemplo avalia se o campo soft_delete é false.

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

Os predicados também podem avaliar os tipos de diretiva claims e item. Este exemplo extrai o campo UserId do token de acesso e o compara com o campo owner_id na tabela do banco de dados de destino.

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

Limitações

• Há suporte para políticas de banco de dados para tabelas e exibições. Os procedimentos armazenados não podem ser configurados com políticas.
• As políticas de banco de dados não podem ser usadas para impedir que uma solicitação seja executada em um banco de dados. Essa limitação ocorre porque as diretivas de banco de dados são resolvidas como predicados de consulta nas consultas de banco de dados geradas. Em última análise, o mecanismo de banco de dados avalia essas consultas.
• As diretivas de banco de dados são suportadas apenas para os actionscreate, read, updatee delete.
• A sintaxe de expressão OData da política de banco de dados oferece suporte apenas a esses cenários.
  • Operadores binários incluindo, mas não limitado a; and, or, eq, gte lt. Para obter mais informações, veja BinaryOperatorKind.
  • Operadores unários, como os operadores - (negar) e not. Para obter mais informações, veja UnaryOperatorKind.
• As políticas de banco de dados também têm restrições relacionadas a nomes de campos.
  • Nomes de campos de entidade que começam com uma letra ou sublinhado, seguidos por no máximo 127 letras, sublinhados ou dígitos.
  • Este requisito é de acordo com a especificação OData. Para obter mais informações, consulte OData Common Schema Definition Language.

GraphQL (entidades)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
entities.{entity}	graphql	objeto	❌ Não	Nenhum

Este objeto define se o GraphQL está habilitado e o(s) nome(s) usado(s) para expor a entidade como um tipo GraphQL. Este objeto é opcional e só é usado se o nome ou as configurações padrão não forem suficientes.

Este segmento fornece a integração de uma entidade no esquema GraphQL. Ele permite que os desenvolvedores especifiquem ou modifiquem valores padrão para a entidade no GraphQL. Essa configuração garante que o esquema reflita com precisão a estrutura pretendida e as convenções 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"
      }
    }
  }
}

Propriedades

Propriedade	Necessário	Tipo	Inadimplência
enabled	❌ Não	Booleano	Nenhum
type	❌ Não	string ou objeto	Nenhum
operation	❌ Não	string de enum	Nenhum

Exemplos

Estes dois exemplos são funcionalmente equivalentes.

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

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

Neste exemplo, a entidade definida é Book, indicando que estamos lidando com um conjunto de dados relacionados a livros no banco de dados. A configuração para a entidade Book dentro do segmento GraphQL oferece uma estrutura clara sobre como ela deve ser representada e interagida em um esquema GraphQL.

Enabled property: A entidade Book é disponibilizada através do GraphQL ("enabled": true), o que significa que os desenvolvedores e usuários podem consultar ou mutar dados do livro por meio de operações GraphQL.

Propriedade Type: A entidade é representada com o nome singular "Book" e o nome plural "Books" no esquema GraphQL. Essa distinção garante que, ao consultar um único livro ou vários livros, o esquema ofereça tipos nomeados intuitivamente (Book para uma única entrada Books para uma lista), aprimorando a usabilidade da API.

propriedade Operation: A operação é definida como "query", indicando que a interação primária com a entidade Book por meio do GraphQL destina-se a consultar (recuperar) dados em vez de mutá-los (criá-los, atualizá-los ou excluí-los). Essa configuração se alinha aos padrões de uso típicos, nos quais os dados do livro são lidos com mais frequência do que modificados.

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

Tipo (entidade GraphQL)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
entities.{entity}.graphql	type	oneOf [string, objeto]	❌ Não	{nome-da-entidade}

Esta propriedade dita a convenção de nomenclatura para uma entidade dentro do esquema GraphQL. Ele suporta valores de cadeia de caracteres escalares e tipos de objeto. O valor do objeto especifica as formas singular e plural. Essa propriedade fornece controle granular sobre a legibilidade do esquema e a experiência do usuário.

Formato

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

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

Propriedades

Propriedade	Necessário	Tipo	Inadimplência
singular	❌ Não	string	Nenhum
plural	❌ Não	string	N/D (padrão: singular)

Exemplos

Para um controle ainda maior sobre o tipo GraphQL, você pode configurar como o nome singular e plural é representado independentemente.

Se plural estiver ausente ou omitido (como valor escalar), o construtor de API de dados tentará pluralizar o nome automaticamente, seguindo as regras em inglês para pluralização (por exemplo: https://engdic.org/singular-and-plural-noun-rules-definitions-examples)

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

Um nome de entidade personalizado pode ser especificado usando o parâmetro type com um valor de cadeia de caracteres. Neste exemplo, o mecanismo diferencia automaticamente entre as variantes singular e plural desse nome usando regras comuns em inglês para pluralização.

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

Se você optar por especificar os nomes explicitamente, use as propriedades type.singular e type.plural. Este exemplo define explicitamente os dois nomes.

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

Ambos os exemplos são funcionalmente equivalentes. Ambos retornam a mesma saída JSON para uma consulta GraphQL que usa o nome da entidade bookauthors.

{
  bookauthors {
    items {
      first_name
      last_name
    }
  }
}

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

Operação (entidade GraphQL)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
entities.{entity}.graphql	operation	string de enum	❌ Não	Nenhum

Para entidades mapeadas para procedimentos armazenados, a propriedade operation designa o tipo de operação GraphQL (consulta ou mutação) onde o procedimento armazenado está acessível. Essa configuração permite a organização lógica do esquema e a adesão às práticas recomendadas do GraphQL, sem afetar a funcionalidade.

Se faltar, o padrão operation é mutation.

Formato

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

Valores

Aqui está uma lista de valores permitidos para esta propriedade:

	Descrição
query	O procedimento armazenado subjacente é exposto como uma consulta
mutation	O procedimento armazenado subjacente é exposto como uma mutação

Exemplos

Quando operation é mutation, o esquema GraphQL seria semelhante:

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

Quando operation é query, o esquema GraphQL seria semelhante:

O esquema GraphQL seria semelhante:

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

Ativado (entidade GraphQL)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
entities.{entity}.graphql	enabled	Booleano	❌ Não	Verdadeiro

Habilita ou desabilita o ponto de extremidade GraphQL. Controla se uma entidade está disponível por meio de pontos de extremidade GraphQL. Alternar a propriedade enabled permite que os desenvolvedores exponham seletivamente entidades do esquema GraphQL.

Formato

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

REST (entidades)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
entities.{entity}	rest	objeto	❌ Não	Nenhum

A seção rest do arquivo de configuração é dedicada ao ajuste fino dos pontos de extremidade RESTful para cada entidade de banco de dados. Esse recurso de personalização garante que a API REST exposta atenda a requisitos específicos, melhorando seus recursos de utilidade e integração. Ele aborda possíveis incompatibilidades entre as configurações inferidas padrão e os comportamentos de ponto de extremidade desejados.

Formato

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

Propriedades

Propriedade	Necessário	Tipo	Inadimplência
enabled	✔️ Sim	Booleano	Verdadeiro
path	❌ Não	string	/<entity-name>
methods	❌ Não	matriz de cadeia de caracteres	OBTER

Exemplos

Estes dois exemplos são funcionalmente equivalentes.

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

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

Aqui está outro exemplo de uma configuração REST para uma entidade.

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

Ativado (entidade REST)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
entities.{entity}.rest	enabled	Booleano	❌ Não	Verdadeiro

Essa propriedade atua como uma alternância para a visibilidade de entidades dentro da API REST. Ao definir a propriedade enabled como true ou false, os desenvolvedores podem controlar o acesso a entidades específicas, permitindo uma superfície de API personalizada que se alinha aos requisitos de segurança e funcionalidade do aplicativo.

Formato

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

Caminho (entidade REST)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
entities.rest	path	string	❌ Não	Nenhum

A propriedade path especifica o segmento URI usado para acessar uma entidade por meio da API REST. Essa personalização permite caminhos de ponto de extremidade mais descritivos ou simplificados além do nome da entidade padrão, aprimorando a navegabilidade da API e a integração do lado do cliente. Por padrão, o caminho é /<entity-name>.

Formato

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

Exemplos

Este exemplo expõe a entidade Author usando o ponto de extremidade /auth.

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

Métodos (entidade REST)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
entities.{entity}.rest	methods	matriz de cadeia de caracteres	❌ Não	Nenhum

Aplicável especificamente a procedimentos armazenados, a propriedade methods define a quais verbos HTTP (por exemplo, GET, POST) o procedimento pode responder. Os métodos permitem um controle preciso sobre como os procedimentos armazenados são expostos por meio da API REST, garantindo a compatibilidade com os padrões RESTful e as expectativas do cliente. Esta seção destaca o compromisso da plataforma com a flexibilidade e o controle do desenvolvedor, permitindo um design de API preciso e intuitivo adaptado às necessidades específicas de cada aplicativo.

Se omitido ou ausente, o padrão methods é POST.

Formato

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

Valores

Aqui está uma lista de valores permitidos para esta propriedade:

	Descrição
get	Expõe solicitações HTTP GET
post	Expõe solicitações HTTP POST

Exemplos

Este exemplo instrui o mecanismo que o procedimento armazenado stp_get_bestselling_authors suporta apenas ações HTTP GET.

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

Mapeamentos (entidades)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
entities.{entity}	mappings	objeto	❌ Não	Nenhum

A seção mappings permite configurar aliases, ou nomes expostos, para campos de objeto de banco de dados. Os nomes expostos configurados aplicam-se aos pontos de extremidade GraphQL e REST.

Formato

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

Exemplos

Neste exemplo, o campo sku_title do objeto de banco de dados dbo.magazines é exposto usando o nome title. Da mesma forma, o campo sku_status é exposto como status em ambos os pontos de extremidade REST e GraphQL.

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

Aqui está outro exemplo de mapeamentos.

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

Mapeamentos: O objeto mappings vincula os campos do banco de dados (BookID, BookTitle, AuthorName) a nomes mais intuitivos ou padronizados (id, title, author) que é usado externamente. Este aliasing serve várias finalidades:

• Clareza e consistência: Permite o uso de nomenclatura clara e consistente em toda a API, independentemente do esquema de banco de dados subjacente. Por exemplo, o BookID no banco de dados é representado como id na API, tornando-o mais intuitivo para os desenvolvedores que interagem com o ponto de extremidade.

• de conformidade com o GraphQL: Ao fornecer um mecanismo para nomes de campos de alias, ele garante que os nomes expostos através da interface GraphQL estejam em conformidade com os requisitos de nomenclatura do GraphQL. A atenção aos nomes é importante porque o GraphQL tem regras rígidas sobre nomes (por exemplo, sem espaços, deve começar com uma letra ou sublinhado, etc.). Por exemplo, se um nome de campo de banco de dados não atender a esses critérios, ele poderá ser aliado para um nome compatível por meio de mapeamentos.

• Flexibilidade: Este aliasing adiciona uma camada de abstração entre o esquema do banco de dados e a API, permitindo alterações em um sem exigir alterações no outro. Por exemplo, uma alteração de nome de campo no banco de dados não requer uma atualização da documentação da API ou do código do lado do cliente se o mapeamento permanecer consistente.

• Ofuscação de Nome de Campo: O mapeamento permite a ofuscação de nomes de campos, o que pode ajudar a impedir que usuários não autorizados inferam informações confidenciais sobre o esquema do banco de dados ou a natureza dos dados armazenados.

• Proteção de informações proprietárias: Ao renomear campos, você também pode proteger nomes proprietários ou lógica de negócios que podem ser sugeridos através dos nomes de campo originais do banco de dados.

Relações (entidades)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
entities.{entity}	relationships	objeto	❌ Não	Nenhum

Esta seção mapeia um conjunto de definições de relacionamento que mapeiam como as entidades estão relacionadas a outras entidades expostas. Essas definições de relacionamento também podem, opcionalmente, incluir detalhes sobre os objetos de banco de dados subjacentes usados para dar suporte e impor as relações. Os objetos definidos nesta seção são expostos como campos GraphQL na entidade relacionada. Para obter mais informações, consulte detalhamento de relações do construtor de API de dados.

A seção relationships descreve como as entidades interagem dentro do construtor de API de dados, detalhando associações e suporte de banco de dados potencial para esses relacionamentos. A propriedade relationship-name para cada relacionamento é necessária e deve ser exclusiva em todos os relacionamentos de uma determinada entidade. Nomes personalizados garantem conexões claras e identificáveis e mantêm a integridade do esquema GraphQL gerado a partir dessas configurações.

Relacionamento	Cardinalidade	Exemplo
um-para-muitos	many	Uma entidade de categoria pode estar relacionada a muitas entidades de todo
muitos-para-um	one	Muitas entidades todo podem se relacionar a uma entidade de categoria
muitos-para-muitos	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

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

Propriedades

Propriedade	Necessário	Tipo	Inadimplência
cardinality	✔️ Sim	string de enum	Nenhum
target.entity	✔️ Sim	string	Nenhum
source.fields	❌ Não	matriz de cadeia de caracteres	Nenhum
target.fields	❌ Não	matriz de cadeia de caracteres	Nenhum
linking.<object-or-entity>	❌ Não	string	Nenhum
linking.source.fields	❌ Não	matriz de cadeia de caracteres	Nenhum
linking.target.fields	❌ Não	matriz de cadeia de caracteres	Nenhum

Exemplos

Ao considerar relacionamentos, é melhor comparar as diferenças entre um-para-muitos, muitos-para-ume muitos-para-muitos relacionamentos.

Um para muitos

Primeiro, vamos considerar um exemplo de um relacionamento com a entidade Category exposta tem uma relação um-para-muitos com a entidade Book. Aqui, a cardinalidade está definida para many. Cada Category pode ter várias entidades Book relacionadas, enquanto cada entidade Book está associada apenas a uma única entidade Category.

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

Neste exemplo, a lista source.fields especifica o campo id da entidade de origem (Category). Este campo é usado para se conectar ao item relacionado na entidade target. Por outro lado, a lista de target.fields especifica o campo category_id da entidade de destino (Book). Este campo é usado para se conectar ao item relacionado na entidade source.

Com essa relação definida, o esquema GraphQL exposto resultante deve ser semelhante a este exemplo.

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

Muitos para um

Em seguida, considere muitos-para-um que define a cardinalidade para one. A entidade Book exposta pode ter uma única entidade Category relacionada. A entidade Category pode ter várias entidades Book relacionadas.

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

Aqui, a lista de source.fields especifica que o campo category_id da entidade de origem (Book) faz referência ao campo id da entidade de destino relacionada (Category). Inversamente, a lista de target.fields especifica a relação inversa. Com essa relação, o esquema GraphQL resultante agora inclui um mapeamento de volta de Livros para Categorias.

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

Muitos para muitos

Finalmente, uma relação muitos-para-muitos é definida com uma cardinalidade de many e mais metadados para definir quais objetos de banco de dados são usados para criar a relação no banco de dados de suporte. Aqui, a entidade Book pode ter várias entidades Author e, inversamente, a entidade Author pode ter várias 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": {
        ...
      }
    }
  }
}

Neste exemplo, os source.fields e target.fields indicam que a tabela de relacionamentos usa o identificador primário (id) das entidades de origem (Book) e de destino (Author). O campo linking.object especifica que a relação é definida no objeto de banco de dados dbo.books_authors. Além disso, linking.source.fields especifica que o campo book_id do objeto de vinculação faz referência ao campo id da entidade Book e linking.target.fields especifica que o campo author_id do objeto de vinculação faz referência ao campo id da entidade Author.

Este exemplo pode ser descrito usando um esquema GraphQL semelhante a este exemplo.

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

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

Cardinalidade

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
entities.{entity}.relationships	cardinality	string	✔️ Sim	Nenhum

Especifica se a entidade de origem atual está relacionada a apenas uma única instância da entidade de destino ou múltipla.

Valores

Aqui está uma lista de valores permitidos para esta propriedade:

	Descrição
one	A origem refere-se apenas a um registro do destino
many	A origem pode estar relacionada a registros de zero a muitos do destino

Entidade-alvo

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
entities.{entity}.relationships	target.entity	string	✔️ Sim	Nenhum

O nome da entidade definida em outro lugar na configuração que é o destino da relação.

Campos de origem

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
entities.{entity}.relationships	source.fields	matriz	❌ Não	Nenhum

Um parâmetro opcional para definir o campo usado para mapeamento na entidade de origem usada para se conectar ao item relacionado na entidade de destino.

Campos de destino

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
entities.{entity}.relationships	target.fields	matriz	❌ Não	Nenhum

Um parâmetro opcional para definir o campo usado para mapeamento na entidade de destino usada para se conectar ao item relacionado na entidade de origem.

Vinculando objeto ou entidade

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
entities.{entity}.relationships	linking.object	string	❌ Não	Nenhum

Para relações muitos-para-muitos, o nome do objeto ou entidade de banco de dados que contém os dados necessários para definir uma relação entre duas outras entidades.

Vinculando campos de origem

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
entities.{entity}.relationships	linking.source.fields	matriz	❌ Não	Nenhum

O nome do objeto de banco de dados ou campo de entidade relacionado à entidade de origem.

Vinculando campos de destino

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
entities.{entity}.relationships	linking.target.fields	matriz	❌ Não	Nenhum

O nome do objeto de banco de dados ou campo de entidade relacionado à entidade de destino.

Cache (entidades)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
entities.{entity}.cache	enabled	Booleano	❌ Não	Falso

Habilita e configura o cache para a entidade.

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

Propriedades

Propriedade	Necessário	Tipo	Inadimplência
enabled	❌ Não	Booleano	Falso
ttl-seconds	❌ Não	inteiro	5

Exemplos

Neste exemplo, o cache é habilitado e os itens expiram após 30 segundos.

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

Ativado (entidade de cache)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
entities.{entity}.cache	enabled	Booleano	❌ Não	Falso

Habilita o cache para a entidade.

Suporte a objetos de banco de dados

Tipo de objeto	Suporte de cache
Tabela	✅ Sim
Visão	✅ Sim
Procedimento armazenado	✖️ Não
Contentor	✖️ Não

Suporte a cabeçalho HTTP

Cabeçalho da solicitação	Suporte de cache
no-cache	✖️ Não
no-store	✖️ Não
max-age	✖️ Não
public	✖️ Não
private	✖️ Não
etag	✖️ Não

Formato

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

Exemplos

Neste exemplo, o cache está desabilitado.

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

TTL em segundos (entidade de cache)

---

Pai	Propriedade	Tipo	Necessário	Inadimplência
entities.cache	ttl-seconds	inteiro	❌ Não	5

Configura o valor TTL (time-to-live) em segundos para itens armazenados em cache. Após esse tempo, os itens são removidos automaticamente do cache. O valor padrão é 5 segundos.

Formato

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

Exemplos

Neste exemplo, o cache é habilitado e os itens expiram após 15 segundos. Quando omitida, essa configuração herda a configuração global ou padrão.

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

Conteúdo relacionado

• Funções de referência
• de referência da interface de linha de comando (CLI)