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

Artigo
01/15/2025

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

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.

Observação

As versões do construtor de API de dados anteriores a 0.3.7-alpha podem ter um URI de esquema diferente.

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('SQL_CONNECTION_STRING')`	Acesse uma variável de ambiente a partir da máquina local. Neste exemplo, a variável de ambiente `SQL_CONNECTION_STRING` é referenciada.

Dica

Como prática recomendada, evite armazenar informações confidenciais em seu arquivo de configuração. Sempre que possível, use @env() para fazer referência a variáveis de ambiente. Para obter mais informações, consulte @env() função.

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

Observação

As "opções" especificadas, como database, containere schema, são específicas da API NoSQL do Azure Cosmos DB em vez da API do PostgreSQL. Para o Azure Cosmos DB usando a API do PostgreSQL, as "opções" não incluiriam database, containerou schema como na configuração do NoSQL.

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.

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.

Formato

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

opções: { set-session-context: boolean }

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.

Exemplo de procedimento armazenado SQL:

CREATE PROC GetUser @userId INT AS
BEGIN
    -- Check if the current user has access to the requested userId
    IF SESSION_CONTEXT(N'user_role') = 'admin' 
        OR SESSION_CONTEXT(N'user_id') = @userId
    BEGIN
        SELECT Id, Name, Age, IsAdmin
        FROM Users
        WHERE Id = @userId;
    END
    ELSE
    BEGIN
        RAISERROR('Unauthorized access', 16, 1);
    END
END;

Exemplo de configuração JSON:

{
  "$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')",
    "options": {
      "set-session-context": true
    }
  },
  "entities": {
    "User": {
      "source": {
        "object": "dbo.GetUser",
        "type": "stored-procedure",
        "parameters": {
          "userId": "number"
        }
      },
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["execute"]
        }
      ]
    }
  }
}

Explicação:

Stored Procedure (GetUser):
- O procedimento verifica o SESSION_CONTEXT para validar se o chamador tem a função admin ou corresponde ao userId fornecido.
- O acesso não autorizado resulta em um erro.
Configuração JSON:
- set-session-context está habilitado para passar metadados do usuário do token de acesso para o banco de dados.
- A propriedade parameters mapeia o parâmetro userId exigido pelo procedimento armazenado.
- O bloco permissions garante que apenas usuários autenticados possam executar o procedimento armazenado.

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.

Diagrama de vários arquivos de configuração referenciados como uma matriz dentro de um único arquivo de configuração.

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.

Importante

Subcaminhos não são permitidos para esta propriedade. Um valor de caminho personalizado para o ponto de extremidade GraphQL não está disponível no momento.

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.

Observação

Por padrão, várias mutações não estão habilitadas e devem ser configuradas explicitamente para serem habilitadas.

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

O seguinte demonstra como habilitar e usar várias mutações no tempo de execução do GraphQL. Nesse caso, a operação create é configurada para permitir a criação de vários registros em uma única solicitação, definindo a propriedade runtime.graphql.multiple-mutations.create.enabled como true.

Exemplo de configuração

Esta configuração permite múltiplas create mutações:

{
  "runtime": {
    "graphql": {
      "multiple-mutations": {
        "create": {
          "enabled": true
        }
      }
    }
  },
  "entities": {
    "User": {
      "source": "dbo.Users",
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["create"]
        }
      ]
    }
  }
}

Exemplo de mutação GraphQL

Usando a configuração acima, a seguinte mutação cria vários registros de User em uma única operação:

mutation {
  createUsers(input: [
    { name: "Alice", age: 30, isAdmin: true },
    { name: "Bob", age: 25, isAdmin: false },
    { name: "Charlie", age: 35, isAdmin: true }
  ]) {
    id
    name
    age
    isAdmin
  }
}

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.

Observação

Ao implantar o construtor de API de Dados usando Aplicativos Web Estáticos (visualização), o serviço do Azure injeta automaticamente o /data-api de subcaminho adicional à url. Esse comportamento garante a compatibilidade com os recursos existentes do Static Web App. O parâmetro de avaliação resultante seria /data-api/api/<entity>. Isso só é relevante para aplicativos Web estáticos.

Formato

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

Importante

Os subcaminhos fornecidos pelo usuário não são permitidos para essa propriedade.

Exemplos

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

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

Dica

Se você definir uma entidade Author, o ponto de extremidade para essa entidade será /data/Author.

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

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

Essa configuração controla o quão estritamente o corpo da solicitação para operações de mutação REST (por exemplo, POST, PUT, PATCH) é validado.

true (padrão): Campos extras no corpo da solicitação que não são mapeados para colunas da tabela causam uma exceção BadRequest.
false: Campos extras são ignorados e apenas colunas válidas são processadas.

Essa configuração não se aplica a solicitações GET, pois o corpo da solicitação é sempre ignorado.

Comportamento com configurações de coluna específicas

As colunas com um valor default() são ignoradas durante INSERT somente quando seu valor na carga útil é null. As colunas com um default() não são ignoradas durante UPDATE independentemente do valor da carga útil.
As colunas computadas são sempre ignoradas.
As colunas geradas automaticamente são sempre ignoradas.

Formato

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

Exemplos

CREATE TABLE Users (
    Id INT PRIMARY KEY IDENTITY,
    Name NVARCHAR(50) NOT NULL,
    Age INT DEFAULT 18,
    IsAdmin BIT DEFAULT 0,
    IsMinor AS IIF(Age <= 18, 1, 0)
);

Exemplo de configuração

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

Comportamento INSERT com `request-body-strict: false`

Solicitar carga útil:

{
  "Id": 999,
  "Name": "Alice",
  "Age": null,
  "IsAdmin": null,
  "IsMinor": false,
  "ExtraField": "ignored"
}

Instrução Insert resultante:

INSERT INTO Users (Name) VALUES ('Alice');
-- Default values for Age (18) and IsAdmin (0) are applied by the database.
-- IsMinor is ignored because it’s a computed column.
-- ExtraField is ignored.
-- The database generates the Id value.

Carga útil de resposta:

{
  "Id": 1,          // Auto-generated by the database
  "Name": "Alice",
  "Age": 18,        // Default applied
  "IsAdmin": false, // Default applied
  "IsMinor": true   // Computed
}

Comportamento UPDATE com `request-body-strict: false`

Solicitar carga útil:

{
  "Id": 1,
  "Name": "Alice Updated",
  "Age": null,     // explicitely set to 'null'
  "IsMinor": true, // ignored because computed
  "ExtraField": "ignored"
}

Declaração de Atualização Resultante:

UPDATE Users
SET Name = 'Alice Updated', Age = NULL
WHERE Id = 1;
-- IsMinor and ExtraField are ignored.

Carga útil de resposta:

{
  "Id": 1,
  "Name": "Alice Updated",
  "Age": null,
  "IsAdmin": false,
  "IsMinor": false // Recomputed by the database (false when age is `null`)
}

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.

Dica

O nível de log padrão pode ser substituído usando dab start --LogLevel <level-of-detail>. Para obter mais informações, consulte referência da interface de linha de comando (CLI).

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

Comportamentos

Apenas no modo development Swagger está disponível.
Apenas no modo development Banana Cake Pop está disponível.

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.

Observação

Para obter mais informações sobre o cabeçalho Access-Control-Allow-Credentials CORS, consulte referência do MDN Web Docs CORS.

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.

Diagrama de suporte a tokens web JSON no construtor de API de dados.

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 para pontos de extremidade REST e GraphQL.

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 de configuração

{
  "runtime": {
    "pagination": {
      "max-page-size": 1000,
      "default-page-size": 2
    }
  },
  "entities": {
    "Users": {
      "source": "dbo.Users",
      "permissions": [
        {
          "actions": ["read"],
          "role": "anonymous"
        }
      ]
    }
  }
}

Exemplo de paginação REST

Neste exemplo, emitir a solicitação REST GET https://localhost:5001/api/users retornaria dois registros na matriz value porque o default-page-size está definido como 2. Se existirem mais resultados, o construtor de API de dados incluirá um nextLink na resposta. O nextLink contém um parâmetro $after para recuperar a próxima página de dados.

Pedido:

GET https://localhost:5001/api/users

Resposta:

{
  "value": [
    {
      "Id": 1,
      "Name": "Alice",
      "Age": 30,
      "IsAdmin": true,
      "IsMinor": false
    },
    {
      "Id": 2,
      "Name": "Bob",
      "Age": 17,
      "IsAdmin": false,
      "IsMinor": true
    }
  ],
  "nextLink": "https://localhost:5001/api/users?$after=W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI=="
}

Usando o nextLink, o cliente pode buscar o próximo conjunto de resultados.

Exemplo de paginação GraphQL

Para GraphQL, use os campos hasNextPage e endCursor para paginação. Esses campos indicam se mais resultados estão disponíveis e fornecem um cursor para buscar a próxima página.

Consulta:

query {
  users {
    items {
      Id
      Name
      Age
      IsAdmin
      IsMinor
    }
    hasNextPage
    endCursor
  }
}

Resposta:

{
  "data": {
    "users": {
      "items": [
        {
          "Id": 1,
          "Name": "Alice",
          "Age": 30,
          "IsAdmin": true,
          "IsMinor": false
        },
        {
          "Id": 2,
          "Name": "Bob",
          "Age": 17,
          "IsAdmin": false,
          "IsMinor": true
        }
      ],
      "hasNextPage": true,
      "endCursor": "W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI=="
    }
  }
}

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

Consulta com cursor:

query {
  users(after: "W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI==") {
    items {
      Id
      Name
      Age
      IsAdmin
      IsMinor
    }
    hasNextPage
    endCursor
  }
}

Ajustando o tamanho da página

REST e GraphQL permitem ajustar o número de resultados por consulta usando $limit (REST) ou first (GraphQL).

Valor `$limit`/`first`	Comportamento
`-1`	O padrão é `max-page-size`.
`< max-page-size`	Limita os resultados ao valor especificado.
`0` ou `< -1`	Não suportado.
`> max-page-size`	Tampado em `max-page-size`.

Exemplo de consulta REST:

GET https://localhost:5001/api/users?$limit=5

Exemplo de consulta GraphQL:

query {
  users(first: 5) {
    items {
      Id
      Name
      Age
      IsAdmin
      IsMinor
    }
  }
}

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-size`atual.
`< -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 User e um ponto de extremidade REST acessível através do caminho /User. A tabela de banco de dados dbo.User apoia a entidade e a configuração permite que qualquer pessoa acesse o ponto de extremidade anonimamente.

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["*"]
        }
      ]
    }
  }
}

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": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table",
        "key-fields": ["Id"],
        "parameters": {} // only when source.type = stored-procedure
      },
      "rest": {
        "enabled": true,
        "path": "/users",
        "methods": [] // only when source.type = stored-procedure
      },
      "graphql": {
        "enabled": true,
        "type": {
          "singular": "User",
          "plural": "Users"
        },
        "operation": "query"
      },
      "mappings": {
        "id": "Id",
        "name": "Name",
        "age": "Age",
        "isAdmin": "IsAdmin"
      },
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"],  // "execute" only when source.type = stored-procedure
          "fields": {
            "include": ["id", "name", "age", "isAdmin"],
            "exclude": []
          },
          "policy": {
            "database": "@claims.userId eq @item.id"
          }
        },
        {
          "role": "admin",
          "actions": ["create", "read", "update", "delete"],
          "fields": {
            "include": ["*"],
            "exclude": []
          },
          "policy": {
            "database": "@claims.userRole eq 'UserAdmin'"
          }
        }
      ]
    }
  }
}

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 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: "source": "dbo.User".

Formato

{
  "entities": {
    "<entity-name>": {
      "source": {
        "object": <string>,
        "type": <"view" | "stored-procedure" | "table">, 
        "key-fields": <array of strings>,
        "parameters": {  // only when source.type = stored-procedure
          "<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

1. Mapeamento de tabela simples:

Este exemplo mostra como associar uma entidade User a uma tabela de origem dbo.Users.

SQL

CREATE TABLE dbo.Users (
  Id INT PRIMARY KEY,
  Name NVARCHAR(100),
  Age INT,
  IsAdmin BIT
);

de configuração

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      }
    }
  }
}

2. Exemplo de procedimento armazenado:

Este exemplo mostra como associar uma entidade User a um proc dbo.GetUsersde origem.

SQL

CREATE PROCEDURE GetUsers 
     @IsAdmin BIT 
AS
SELECT Id, Name, Age, IsAdmin
FROM dbo.Users
WHERE IsAdmin = @IsAdmin;

de configuração

{
  "entities": {
    "User": {
      "source": {
        "type": "stored-procedure",
        "object": "GetUsers",
        "parameters": {
          "IsAdmin": "boolean"
        }
      },
      "mappings": {
        "Id": "id",
        "Name": "name",
        "Age": "age",
        "IsAdmin": "isAdmin"
      }
    }
  }
}

A propriedade mappings é opcional para procedimentos armazenados.

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. Se o objeto pertencer ao esquema dbo, especificar o esquema é opcional. Além disso, colchetes em torno de nomes de objetos (por exemplo, [dbo].[Users] vs. dbo.Users) podem ser usados ou omitidos.

Exemplos

SQL

CREATE TABLE dbo.Users (
  Id INT PRIMARY KEY,
  Name NVARCHAR(100),
  Age INT,
  IsAdmin BIT
);

de configuração

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      }
    }
  }
}

Notação alternativa sem esquema e parênteses:

Se a tabela estiver no esquema dbo, você pode omitir o esquema ou colchetes:

{
  "entities": {
    "User": {
      "source": {
        "object": "Users",
        "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, incluindo view, tablee stored-procedure. Esta propriedade é necessária e não tem valor padrão.

Formato

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

Valores

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

Exemplos

1. Exemplo de tabela:

SQL

CREATE TABLE dbo.Users (
  Id INT PRIMARY KEY,
  Name NVARCHAR(100),
  Age INT,
  IsAdmin BIT
);

de configuração

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      }
    }
  }
}

2. Ver exemplo:

SQL

CREATE VIEW dbo.AdminUsers AS
SELECT Id, Name, Age
FROM dbo.Users
WHERE IsAdmin = 1;

de configuração

{
  "entities": {
    "AdminUsers": {
      "source": {
        "object": "dbo.AdminUsers",
        "type": "view",
        "key-fields": ["Id"]
      },
      "mappings": {
        "Id": "id",
        "Name": "name",
        "Age": "age"
      }
    }
  }
}

Nota: Especificar key-fields é importante para visualizações porque elas não têm chaves primárias inerentes.

3. Exemplo de procedimento armazenado:

SQL

CREATE PROCEDURE dbo.GetUsers (@IsAdmin BIT)
AS
SELECT Id, Name, Age, IsAdmin
FROM dbo.Users
WHERE IsAdmin = @IsAdmin;

de configuração

{
  "entities": {
    "User": {
      "source": {
        "type": "stored-procedure",
        "object": "GetUsers",
        "parameters": {
          "IsAdmin": "boolean"
        }
      }
    }
  }
}

Domínios-chave

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

A propriedade {entity}.key-fields é particularmente necessária para entidades apoiadas por exibições, para que o Data API Builder saiba como identificar e retornar um único item. Se type estiver definido para view sem especificar key-fields, o motor recusa-se a arrancar. Essa propriedade é permitida com tabelas e procedimentos armazenados, mas não é usada nesses casos.

Importante

Esta propriedade é necessária se o tipo de objeto for um view.

Formato

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

Exemplo: Exibir com campos-chave

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

SQL

CREATE VIEW dbo.AdminUsers AS
SELECT Id, Name, Age
FROM dbo.Users
WHERE IsAdmin = 1;

de configuração

{
  "entities": {
    "AdminUsers": {
      "source": {
        "object": "dbo.AdminUsers",
        "type": "view",
        "key-fields": ["Id"]
      }
    }
  }
}

Parâmetros

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

A propriedade parameters dentro entities.{entity}.source é usada para entidades apoiadas por procedimentos armazenados. Ele garante o mapeamento adequado de nomes de parâmetros e tipos de dados exigidos pelo procedimento armazenado.

Importante

A propriedade parametersé necessária se a type do objeto for stored-procedure e o parâmetro for necessário.

Formato

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

Exemplo 1: Procedimento armazenado sem parâmetros

SQL

CREATE PROCEDURE dbo.GetUsers AS
SELECT Id, Name, Age, IsAdmin FROM dbo.Users;

de configuração

{
  "entities": {
    "Users": {
      "source": {
        "object": "dbo.GetUsers",
        "type": "stored-procedure"
      }
    }
  }
}

Exemplo 2: Procedimento armazenado com parâmetros

SQL

CREATE PROCEDURE dbo.GetUser (@userId INT) AS
SELECT Id, Name, Age, IsAdmin FROM dbo.Users
WHERE Id = @userId;

de configuração

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.GetUser",
        "type": "stored-procedure",
        "parameters": {
          "userId": "number"
        }
      }
    }
  }
}

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 em termos de funções e operações CRUD: create, read, updatee delete. A seção permissions especifica quais funções podem acessar a entidade relacionada e usando quais ações.

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.
`*`	Subvenciona todas as operações CRUD aplicáveis.

Exemplos

Exemplo 1: Função anônima no de entidade do usuário

Neste exemplo, a função anonymous é definida com acesso a todas as ações possíveis na entidade User.

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

Exemplo 2: Ações mistas para de função anônima

Este exemplo mostra como misturar ações de cadeia de caracteres e matriz de objetos para a entidade User.

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

Função Anônima: Permite que usuários anônimos leiam todos os campos, exceto um campo sensível hipotético (por exemplo, secret-field). Usar "include": ["*"] com "exclude": ["secret-field"] oculta secret-field enquanto permite o acesso a todos os outros campos.

de Função Autenticada: Permite que usuários autenticados leiam e atualizem campos específicos. Por exemplo, incluir explicitamente id, namee age mas excluindo isAdmin pode demonstrar como as exclusões se sobrepõem às inclusões.

Função de administrador: Os administradores podem executar todas as operações (*) em todos os campos sem exclusões. A especificação de "include": ["*"] com uma matriz "exclude": [] vazia concede acesso a todos os campos.

Esta configuração:

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

é efetivamente idêntica a:

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

Considere também esta configuração:

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

Isso especifica que nenhum campo é explicitamente incluído e todos os campos são excluídos, o que normalmente restringe totalmente o acesso.

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

O mesmo comportamento, mas com sintaxe diferente, seria:

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

Esta configuração tenta incluir apenas campos Id e Name, mas exclui todos os campos devido ao curinga no exclude.

Outra forma de expressar a mesma lógica seria:

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

Dado que exclude tem precedência sobre include, especificar exclude: ["*"] significa que todos os campos são excluídos, mesmo os include. Assim, à primeira vista, esta configuração pode parecer impedir que quaisquer campos sejam acessíveis.

Oinverso: Se a intenção for conceder acesso apenas aos campos Id e Name, é mais claro e confiável especificar apenas os campos na seção include sem usar um curinga de exclusão:

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

Propriedades

	Necessário	Tipo
`role`	✔️ Sim	string
`actions` (string-array) ou `actions` (matriz-objeto)	✔️ 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. 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 por meio de pontos de extremidade REST e GraphQL. As funções não são aditivas.

O Data API Builder 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` especifica uma função presente no token

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 na entidade User.

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

Você pode usar <custom-role> quando 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á contida na declaração de funções do token de acesso. Abaixo estão exemplos de solicitações GET para a entidade User, incluindo o token de portador de autorização e o cabeçalho X-MS-API-ROLE, na base do ponto de extremidade REST /api em localhost usando idiomas diferentes.

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

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

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

const response = await fetch('https://localhost:5001/api/User', {
  headers: { 
    "Authorization": "Bearer <your_access_token>",
    "X-MS-API-ROLE": "custom-role"
  }
});

import requests

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

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 usar qualquer combinação de create, read, updateou delete ações. Para procedimentos armazenados, as funções só podem ter a ação execute.

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

Observação

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

Exemplos

Este exemplo dá permissões de create e read a uma função chamada contributor e permissões de delete a uma função chamada auditor na entidade User.

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

Outro exemplo:

{
  "entities": {
    "User": {
      "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 objetos de ação detalhando operações permitidas para a função associada. Para objetos table e view, as funções podem usar qualquer combinação de create, read, updateou delete. Para procedimentos armazenados, apenas execute é permitido.

Observação

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

Formato

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

Exemplo

Este exemplo concede apenas read permissão para a função auditor na entidade User, com restrições de campo e política.

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

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

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

Formato

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "role": "<role>",
          "actions": [
            {
              "action": "<string>",
              "fields": {
                "include": [/* fields */],
                "exclude": [/* fields */]
              },
              "policy": {
                "database": "<predicate>"
              }
            }
          ]
        }
      ]
    }
  }
}

Exemplo

Aqui está um exemplo em que anonymous usuários têm permissão para execute um procedimento armazenado e read a partir da tabela User.

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read"
            }
          ]
        }
      ]
    },
    "GetUser": {
      "source": {
        "object": "dbo.GetUser",
        "type": "stored-procedure",
        "parameters": {
          "userId": "number"
        }
      },
      "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

Observação

Quando autenticação de de Aplicativos Web Estáticos do Azure (EasyAuth) é configurada, um número limitado de tipos de declarações está disponível para uso em políticas de banco de dados: identityProvider, userId, userDetailse userRoles. Para obter mais informações, consulte a documentação do de dados principal do Client do Azure Static Web App.

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

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.

Observação

Um predicado é uma expressão que avalia como TRUE, FALSEou UNKNOWN. Os predicados são utilizados em:

A condição de pesquisa das cláusulas WHERE
A condição de pesquisa das cláusulas FROM
As condições de adesão das cláusulas FROM
Outras construções onde um valor booleano é necessário.

Para obter mais informações, consulte predicados.

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

Observação

Um número limitado de tipos de declaração está disponível para uso em políticas de banco de dados quando a autenticação de Aplicativos Web Estáticos do Azure (EasyAuth) é configurada. Esses tipos de declaração incluem: identityProvider, userId, userDetailse userRoles. Para obter mais informações, consulte dados principais do cliente do Azure Static Web Apps.

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.

Dica

Os campos que não estão em conformidade com as restrições mencionadas não podem ser referenciados nas políticas de banco de dados. Como solução alternativa, configure a entidade com uma seção de mapeamentos para atribuir aliases conformes aos campos.

GraphQL (entidades)

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

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.

Observação

Uma entidade é especificada para ser um procedimento armazenado definindo o valor da propriedade {entity}.type como stored-procedure. No caso de um procedimento armazenado, um novo tipo GraphQL executeXXX é criado automaticamente. No entanto, a propriedade operation permite que o desenvolvedor coaja a localização desse tipo nas partes mutation ou query do esquema. Esta propriedade permite o esquema hygene e não há impacto funcional, independentemente do valor operation.

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

Observação

A propriedade operation é apenas sobre o posicionamento da operação no esquema GraphQL, ela não altera o comportamento da operação.

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

Importante

Para entidades com o GraphQL habilitado, o nome exposto configurado deve atender aos requisitos de nomenclatura do GraphQL. Para obter mais informações, consulte GraphQL names specification.

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.

Observação

Os relacionamentos são relevantes apenas para consultas GraphQL. Os pontos de extremidade REST acessam apenas uma entidade de cada vez e não podem retornar tipos aninhados.

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.

Dica

Este campo não é obrigatório se houver uma restrição de de chave estrangeira no banco de dados entre os dois objetos de banco de dados que podem ser usados para inferir a relação automaticamente.

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.

Dica

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

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

Partilhar via

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

Visão geral da sintaxe

Propriedades de nível superior

Configurações de exemplo

Ambientes

Propriedades de configuração

Esquema

Formato

Exemplos

Fonte de dados

Formato

Propriedades

Tipo de base de dados

Formato

Valores de tipo

Cadeia de conexão

Formato

Resiliência da conexão

Azure SQL e SQL Server

Exemplos

Opções

Formato

opções: { set-session-context: boolean }

Exemplo de procedimento armazenado SQL:

Exemplo de configuração JSON:

Explicação:

Arquivos de fonte de dados

Formato

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

Exemplos

Tempo de execução

Formato

Propriedades

Exemplos

GraphQL (tempo de execução)

Formato

Propriedades

Ativado (tempo de execução do GraphQL)

Formato

Exemplos

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

Exemplos

Caminho (tempo de execução do GraphQL)

Formato

Exemplos

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

Formato

Exemplos

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

Formato

Propriedades

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

Formato

Propriedades

Exemplos

Exemplo de configuração

Exemplo de mutação GraphQL

REST (tempo de execução)

Formato

Propriedades

Ativado (tempo de execução REST)

Formato

Exemplos

Caminho (tempo de execução REST)

Formato

Exemplos

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

Comportamento com configurações de coluna específicas

Formato

Exemplos

Exemplo de configuração

Comportamento INSERT com request-body-strict: false

Comportamento UPDATE com request-body-strict: false

Host (tempo de execução)

Formato

Propriedades

Exemplos

Modo (tempo de execução do host)

Formato

Comportamento INSERT com `request-body-strict: false`

Comportamento UPDATE com `request-body-strict: false`