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

Artigo
10/04/2024

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

As propriedades database-type e connection-string garantir a 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:

Informações de conexão e serviço de banco de dados
Opções de configuração global e de runtime
Conjunto de entidades expostas
Método de autenticação
Regras de segurança necessárias para acessar identidades
Regras de mapeamento de nomes entre a API e o 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 adere ao formato necessário.
de fonte de dados	Contém os detalhes sobre o tipo de banco de dados e a cadeia de conexão , necessária para estabelecer a conexão de banco de dados.
de arquivos de fonte de dados	Uma matriz opcional que especifica outros arquivos de configuração que podem definir outras fontes de dados.
de runtime	Configura comportamentos e configurações de runtime, incluindo subpropriedades para REST, graphQL, de host, cachee de 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 , permissões e relações .

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 configuração de exemplo de ponta a ponta.

Ambientes

O arquivo de configuração do construtor de API de Dados pode dar suporte a cenários em que você precisa dar suporte a vários ambientes, semelhante ao arquivo appSettings.json no ASP.NET Core. A estrutura fornece três valores comuns de ambiente; Development, Staginge Production; mas você pode optar por usar qualquer valor de ambiente escolhido. O ambiente usado pelo construtor de API de Dados 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:

	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.

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

Consulte essa 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 de ambiente atual	Ambiente atual	Ambiente atual
Não especificado no de configuração de ambiente atual	Base	Nenhum

Para obter um exemplo de como usar vários arquivos de configuração, consulte usar o construtor de API de Dados com ambientes.

Propriedades de configuração

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

Esquema

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

Cada arquivo de configuração começa com uma propriedade $schema, especificando a de 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 disponível mais recente.

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-alpha	`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.
Mais recente	`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.

Nota

Versões do construtor de API de Dados antes de alfa 0.3.7 podem ter um URI de esquema diferente.

Fonte de dados

Pai	Propriedade	Tipo	Necessário	Inadimplência
`$root`	`data-source`	corda	✔️ 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 as 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	cadeia de caracteres de enumeração
`connection-string`	✔️ Sim	corda
`options`	❌ Não	objeto

Tipo de banco de dados

Pai	Propriedade	Tipo	Necessário	Inadimplência
`data-source`	`database-type`	enumeração de cadeia de caracteres	✔️ Sim	Nenhum

Uma cadeia de caracteres de enumeração 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 mínima
`mssql`	Banco de Dados SQL do Azure	Nenhum
`mssql`	Azure SQL MI	Nenhum
`mssql`	SQL Server	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`	corda	✔️ Sim	Nenhum

Uma cadeia de caracteres valor que contém uma cadeia de conexão válida para se conectar ao serviço de banco de dados de destino. O ADO.NET cadeia de conexão 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 de conexão

O Construtor de API de Dados tenta automaticamente solicitações de banco de dados depois de detectar erros transitórios. A lógica de repetição segue uma estratégia de de retirada exponencial em que o número máximo de repetições é cinco. A duração de retirada de repetição após solicitações subsequentes é calculada usando essa 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`
Terceira	`8`
quarta	`16`
quinta do	`32`

SQL do Azure e SQL Server

O Construtor de API de Dados usa a biblioteca de SqlClient para se conectar ao SQL do Azure ou ao SQL Server usando a cadeia de conexão que você fornece no arquivo de configuração. Uma lista de todas as opções de cadeia de conexão com suporte 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 MSI (Identidades de Serviço Gerenciado) 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.

UMI ( de Identidade Gerenciada Atribuída ao Usuário): acrescente as propriedades de Autenticação de e ID de Usuário à cadeia de conexão ao substituir na ID do cliente da identidade gerenciada atribuída pelo usuário: .
SMI (System Assigned Managed Identity): acrescente a propriedade Authentication e exclua os argumentos UserId e Password da cadeia de conexão: . A ausência das propriedades de cadeia de conexão UserId e Password sinalizará o DAB para autenticar usando uma identidade gerenciada atribuída pelo sistema.

Para obter mais informações sobre como configurar uma Identidade de Serviço Gerenciada com o SQL do Azure ou o SQL Server, consulte Identidades gerenciadas no Microsoft Entra para SQL do 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 com 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 valor da cadeia de caracteres do Banco de Dados do Azure para PostgreSQL	`Server=<server-address>;Database=<name-of-database>;Port=5432;User Id=<username>;Password=<password>;Ssl Mode=Require;`	Cadeia de conexão com uma conta do Banco de Dados do Azure para PostgreSQL. Para obter mais informações, consulte cadeias de conexão do Banco de Dados do Azure para PostgreSQL.
usar o valor da cadeia de caracteres do Azure Cosmos DB para NoSQL	`AccountEndpoint=<endpoint>;AccountKey=<key>;`	Cadeia de conexão com uma conta do Azure Cosmos DB para NoSQL. Para obter mais informações, consulte cadeias de conexão do Azure Cosmos DB para NoSQL.
usar o valor da cadeia de caracteres do Banco de Dados do Azure para MySQL	`Server=<server-address>;Database=<name-of-database>;User ID=<username>;Password=<password>;Sslmode=Required;SslCa=<path-to-certificate>;`	Cadeia de conexão com uma conta do Banco de Dados do Azure para MySQL. Para obter mais informações, consulte cadeias de conexão do Banco de Dados do Azure para MySQL.
de variável de ambiente do Access	`@env('SQL_CONNECTION_STRING')`	Acesse uma variável de ambiente do computador local. Neste exemplo, a variável de ambiente `SQL_CONNECTION_STRING` é referenciada.

Ponta

Como prática recomendada, evite armazenar informações confidenciais em seu arquivo de configuração. Quando 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 exclusivo, mas este exemplo é um bom ponto de partida. Substitua os espaços reservados, como myserver, myDataBase, mylogine myPassword pelos valores reais específicos ao seu ambiente.

mssql
```
"data-source": {
  "database-type": "mssql",
  "connection-string": "$env('my-connection-string')",
  "options": {
    "set-session-context": true
  }
}
```
- formato de cadeia de conexão típico: "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 de cadeia de conexão típico: "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 de cadeia de conexão típico: "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 de cadeia de conexão típico: "AccountEndpoint=https://mycosmosdb.documents.azure.com:443/;AccountKey=myAccountKey;"

cosmosdb_postgresql
```
"data-source": {
  "database-type": "cosmosdb_postgresql",
  "connection-string": "$env('my-connection-string')"
}
```
- formato de cadeia de conexão típico: "Host=mycosmosdb.postgres.database.azure.com;Database=myDataBase;Username=mylogin@mycosmosdb;Password=myPassword;Port=5432;SSL Mode=Require;"

Nota

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 de 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 estão disponíveis para o banco de dados durante a conexão de banco de dados até que essa conexão seja fechada. Para obter mais informações, consulte de contexto da sessão.

Exemplo de procedimento armazenado do 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:

de procedimento armazenado ():
- O procedimento verifica o SESSION_CONTEXT para validar se o chamador tem a função admin ou corresponde à userId fornecida.
- O acesso não autorizado resulta em um erro.
de 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 somente 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 dá suporte a vários arquivos de configuração para fontes de dados diferentes, com um designado como o arquivo de nível superior gerenciando runtime configurações. Todas as configurações compartilham o mesmo esquema, permitindo que runtime configurações em qualquer arquivo sem erros. As configurações filho se mesclam 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 em 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 de runtime é usada apenas do arquivo de configuração de nível superior, mesmo se incluída 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 relações entre entidades em arquivos de configuração diferentes.

Exemplos

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

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

Também há suporte para a sintaxe da subpasta:

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

Runtime

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 do runtime 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 runtime 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 (runtime)

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

Esse objeto define se o GraphQL está habilitado e o nome[s] usado para expor a entidade como um tipo GraphQL. Esse objeto é opcional e usado somente se o nome ou as configurações padrão não forem suficientes. Esta seção descreve as configurações globais do ponto de extremidade do 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	corda	/graphql (padrão)
`allow-introspection`	❌ Não	booleano	Verdadeiro
`multiple-mutations`	❌ Não	objeto	{ create: { enabled: false } }

Habilitado (runtime do GraphQL)

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

Define se deseja habilitar ou desabilitar os pontos de extremidade do GraphQL globalmente. Se desabilitada globalmente, nenhuma entidade estaria acessível por meio de solicitações do GraphQL, independentemente das configurações de entidade individuais.

Formato

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

Exemplos

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

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

Limite de profundidade (runtime 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 relação é 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 atinjam um equilíbrio, permitindo que os usuários aproveitem os benefícios das consultas aninhadas, colocando limites para evitar cenários que possam comprometer o desempenho e a qualidade do sistema.

Exemplos

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

Caminho (runtime do GraphQL)

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

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

Importante

Sub-caminhos não são permitidos para essa propriedade. Um valor de caminho personalizado para o ponto de extremidade do GraphQL não está disponível no momento.

Formato

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

Exemplos

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

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

Permitir introspecção (runtime do GraphQL)

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

Esse sinalizador booliano controla a capacidade de executar consultas de introspecção de esquema no ponto de extremidade do GraphQL. Habilitar a introspecçã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 ser executadas 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, pode estar desabilitado para obscurecer os detalhes do esquema da API e aprimorar a segurança. Por padrão, a introspecção está habilitada, permitindo a exploração imediata e abrangente do esquema GraphQL.

Formato

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

Exemplos

Neste exemplo, a introspecção está desabilitada.

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

Várias mutações (runtime do GraphQL)

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

Configura todas as várias operações de mutação para o runtime do GraphQL.

Nota

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

Várias mutações – criar (runtime 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 runtime do GraphQL.

Formato

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

Propriedades

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

Exemplos

A seguir, demonstra como habilitar e usar várias mutações no runtime do GraphQL. Nesse caso, a operação de 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

Essa configuração permite várias mutações create:

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

Exemplo de mutação do GraphQL

Usando a configuração acima, a seguinte mutação cria vários registros 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 (runtime)

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 respectivas 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	corda	/API
`request-body-strict`	❌ Não	booleano	Verdadeiro

Habilitado (runtime REST)

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

Um sinalizador booliano que determina a disponibilidade global dos pontos de extremidade REST. Se estiver desabilitada, as entidades não poderão ser acessadas via REST, independentemente das configurações de entidade 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 (runtime REST)

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

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

Nota

Ao implantar o construtor de API de Dados usando Aplicativos Web Estáticos (versão prévia), o serviço do Azure injeta automaticamente o subcaminho adicional /data-api na URL. Esse comportamento garante a compatibilidade com os recursos existentes do Aplicativo Web Estático. O ponto de extremidade resultante seria /data-api/api/<entity>. Isso só é relevante para aplicativos Web estáticos.

Formato

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

Importante

Sub-caminhos fornecidos pelo usuário não são permitidos para essa propriedade.

Exemplos

Neste exemplo, o URI da API REST raiz é /data.

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

Ponta

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

Corpo da Solicitação Estrito (Rest Runtime)

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

Essa configuração controla como 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 de tabela causam uma exceção BadRequest.
false: campos extras são ignorados e somente colunas válidas são processadas.

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

Comportamento com configurações de coluna específicas

Colunas com um valor padrão() são ignoradas durante INSERT somente quando seu valor no conteúdo é null. As colunas com padrão() não são ignoradas durante UPDATE independentemente do valor da carga.
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)
);

Configuração de exemplo

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

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

de conteúdo de solicitação:

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

instrução de inserção 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.

de conteúdo 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`

de conteúdo de solicitação:

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

instrução de atualização resultante:

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

de conteúdo de resposta:

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

Host (runtime)

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

A seção host dentro da configuração de runtime fornece configurações cruciais para o ambiente operacional do construtor de API de Dados. Essas configurações incluem modos operacionais, configuração do 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	cadeia de caracteres de enumeração	produção
`cors`	❌ Não	objeto	Nenhum
`authentication`	❌ Não	objeto	Nenhum

Exemplos

Aqui está um exemplo de um runtime configurado para hospedagem de desenvolvimento.

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

Modo (runtime do host)

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

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

Normalmente, os erros de banco de dados subjacentes são expostos em detalhes definindo o nível padrão de detalhes para os logs Debug ao serem executados no desenvolvimento. Na produção, o nível de detalhes dos logs é definido como Error.

Ponta

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

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`	Usar em desenvolvimento no computador local

Comportamentos

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

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 especificado. Essa configuração permite que os usuários configurem a quantidade de dados que a memória da plataforma de host pode manipular ao transmitir dados das fontes de dados subjacentes.

Quando os usuários solicitam grandes conjuntos de resultados, ele pode forçar 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, à medida que os dados são transmitidos da fonte de dados. Esse limite é baseado no tamanho geral dos dados, não no número de linhas. Como as colunas podem variar de 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 pontos de extremidade 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 definido ou definido explicitamente como `null`.
`integer`	Há suporte para qualquer inteiro positivo de 32 bits.
`< 0`	Não há suporte. Os erros de validação ocorrerão se definidos como menores que 1 MB.

Formato

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

CORS (runtime do host)

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

Configurações de CORS (compartilhamento de recursos entre origens) 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 (runtime do host)

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

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

Nota

Para obter mais infromação no cabeçalho CORS Access-Control-Allow-Credentials, consulte referência do CORS do MDN Web Docs.

Formato

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

Origens (runtime 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 (runtime 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	cadeia de caracteres de enumeração	StaticWebApps
`jwt`	❌ Não	objeto	Nenhum

autenticação e responsabilidades do cliente

O construtor de API de dados foi projetado para operar em 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, ID do Entra). Quando uma solicitação atinge o construtor de API de Dados, ele assume que o token JWT é válido e verifica-o em relação a quaisquer pré-requisitos que você configurou, 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 for aprovada, o Construtor de API de Dados executará 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 endurecendo o computador 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 (runtime do host)

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

A configuração de authentication.provider dentro da configuração de host define o método de autenticação usado pelo construtor de 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, dando suporte a vários mecanismos de autenticação adaptados a diferentes ambientes e requisitos de segurança.

Provedor	Descrição
`StaticWebApps`	Instrui o construtor de API de Dados a procurar um conjunto de cabeçalhos HTTP presentes somente ao executar em um ambiente de Aplicativos Web Estáticos.
`AppService`	Quando o runtime é hospedado no Azure AppService com a Autenticação do AppService habilitada e configurada (EasyAuth).
`AzureAd`	A Identidade do Microsoft Entra precisa ser configurada para que possa autenticar uma solicitação enviada ao construtor de API de Dados (o "Aplicativo do Servidor"). Para obter mais informações, consulte microsoft entra ID authentication.
`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 (runtime 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), essa seção será necessária para especificar o público-alvo e os emissores do token JSOn Web Tokens (JWT). Esses dados são usados para validar os tokens no locatário do Microsoft Entra.

Necessário se o provedor de autenticação for AzureAD para a ID do Microsoft Entra. Esta seção deve especificar o audience e issuer para validar o token JWT recebido no locatário AzureAD pretendido para autenticação.

Ambiente	Descrição
público	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.
Emissor	Especifica a URL da autoridade emissora, que é o serviço de token que emitiu o JWT. Essa URL deve corresponder à URL do emissor do provedor de identidade da 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	corda	Nenhum
`issuer`	❌ Não	corda	Nenhum

Exemplos

O DAB (Construtor de API de Dados) oferece suporte à autenticação flexível, integrando-se à Identidade do Microsoft Entra e aos servidores JWT (Token Web JSON personalizados). Nesta imagem, o do servidor JWT representa o serviço de autenticação que emite tokens JWT para clientes após a entrada bem-sucedida. Em seguida, o cliente passa o token para o DAB, que pode interrogar suas declarações e propriedades.

Diagrama de tokens Web JSON com suporte no construtor de API de Dados.

Veja a seguir exemplos da propriedade host, considerando 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 está 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 com suporte em que o token de acesso pode ser emitido. Um token de acesso adquirido deve ser incluído com solicitações de entrada para o construtor de API de Dados. O construtor de API de dados valida os tokens de acesso apresentados, garantindo que o construtor de API de Dados seja o público-alvo pretendido 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"
  }
 }
}

Público-alvo (runtime do host)

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

Audiência para o token JWT.

Formato

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

Emissor (runtime do host)

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

Emissor do token JWT.

Formato

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

Paginação (Runtime)

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

Configura os 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

Configuração de exemplo

{
  "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, a emissão da 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 houver mais resultados, o construtor de API de Dados inclui um nextLink na resposta. O nextLink contém um parâmetro $after para recuperar a próxima página de dados.

Pedir:

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

Para o 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 do `$limit`/`first`	Comportamento
`-1`	Assume o padrão de `max-page-size`.
`< max-page-size`	Limita os resultados ao valor especificado.
`0` ou `< -1`	Não há suporte.
`> max-page-size`	Limitado a `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 (runtime de 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 com suporte.
`integer`	Há suporte para qualquer inteiro positivo de 32 bits.
`< -1`	Não há suporte.
`0`	Não há suporte.

Formato

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

Tamanho da página padrão (runtime 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 de `max-page-size` atual.
`integer`	Qualquer inteiro positivo menor que o `max-page-size`atual.
`< -1`	Não há suporte.
`0`	Não há suporte.

Cache (runtime)

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

Habilita e configura o cache para todo o runtime.

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 está habilitado e os itens expiram após 30 segundos.

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

Habilitado (runtime de cache)

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

Habilita o cache globalmente para todas as entidades. Assume o padrão de false.

Formato

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

Exemplos

Neste exemplo, o cache está desabilitado.

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

TTL em segundos (runtime de cache)

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

Configura o valor de TTL (vida útil) em segundos para itens armazenados em cache. Após esse tempo decorrido, 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 (runtime)

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

Essa 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 (runtime de telemetria)

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

Habilitado (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`	corda	✔️ 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 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 definição de permissão e mapeamento de propriedades. 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 propriedades e permissões. Cada entidade é encapsulada em sua própria subseção, com o nome da entidade agindo 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	array
`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 por meio 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 em que as entidades são referenciadas. Caso contrário, o nome da entidade não é 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 de {entity}.source conecta a entidade exposta à API e seu objeto de banco de dados subjacente. Essa propriedade especifica a tabela de banco de dados, a exibição ou o procedimento armazenado que a entidade representa, estabelecendo um link direto para recuperação e manipulação de dados.

Para cenários simples em que a entidade é mapeada diretamente para uma única tabela de banco de dados, a propriedade de origem 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	corda
`type`	✔️ Sim	cadeia de caracteres de enumeração
`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 do

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

2. Exemplo de procedimento armazenado:

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

SQL

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

de Configuração do

{
  "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`	corda	✔️ Sim	Nenhum

Nome do objeto de banco de dados a ser usado. Se o objeto pertencer ao esquema dbo, especificar o esquema será opcional. Além disso, colchetes em torno de nomes de objeto (por exemplo, [dbo].[Users] vs. dbo.Users) podem ser usados ou omitidos.

Exemplos

SQL

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

de Configuração do

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

notação alternativa sem esquema e colchetes:

Se a tabela estiver no esquema dbo, você poderá 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`	corda	✔️ Sim	Nenhum

A propriedade type identifica o tipo de objeto de banco de dados por trás da entidade, incluindo view, tablee stored-procedure. Essa propriedade é necessária e não tem nenhum 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 do

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

2. Exemplo de exibição:

SQL

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

de Configuração do

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

Observação: Especificar key-fields é importante para exibiçõ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 do

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

Campos de 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, portanto, o Construtor de API de Dados sabe como identificar e retornar um único item. Se type estiver definido como view sem especificar key-fields, o mecanismo se recusará a iniciar. Essa propriedade é permitida com tabelas e procedimentos armazenados, mas não é usada nesses casos.

Importante

Essa propriedade será 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 de chave

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

SQL

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

de Configuração do

{
  "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 em 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 será necessária se o 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 do

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

{
  "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 quais ações.

Formato

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

Ação	Descrição
`create`	Permite a criação de um novo registro na entidade.
`read`	Permite ler ou recuperar registros da entidade.
`update`	Permite atualizar registros existentes na entidade.
`delete`	Permite a exclusão de registros da entidade.
`execute`	Permite a execução de um procedimento ou operação armazenado.
`*`	Concede todas as operações CRUD aplicáveis.

Exemplos

exemplo 1: função anônima na entidade de 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"
          ]        
        }
      ]
    }
  }
}

de 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 ao permitir 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 substituem inclusões.

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

Esta configuração:

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

é efetivamente idêntico a:

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

Considere também esta configuração:

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

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

uso prático: essa configuração pode parecer contraintuitiva, pois restringe o acesso a todos os campos. No entanto, ela pode ser usada 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": ["*"]
}

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

Outra maneira de expressar a mesma lógica seria:

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

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

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

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

Propriedades

	Necessário	Tipo
`role`	✔️ Sim	corda
`actions` (matriz de cadeia de caracteres) ou `actions` (matriz de objeto)	✔️ Sim	matriz de objeto ou cadeia de caracteres

Papel

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

Cadeia de caracteres 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 runtime, 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 Construtor de API de Dados avalia as solicitações no contexto de uma única função:

Papel	Descrição
`anonymous`	Nenhum token de acesso é apresentado
`authenticated`	Um token de acesso válido é apresentado
`<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 permissões de read 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 está 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.

HTTP
C#
JavaScript/TypeScript
python

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 (matriz de cadeia de caracteres)

Pai	Propriedade	Tipo	Necessário	Inadimplência
`entities.permissions`	`actions`	oneOf [cadeia de caracteres, 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 ações de create, read, updateou delete. 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

Nota

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

Exemplos

Este exemplo fornece permissões de create e read para uma função chamada contributor e permissões de delete para 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 de 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 as 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, somente execute é permitido.

Nota

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	corda	Nenhum
`fields`	❌ Não	matriz de cadeia de caracteres	Nenhum
`policy`	❌ Não	objeto	Nenhum

Exemplo

Este exemplo concede apenas read permissão à 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`	corda	✔️ 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 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 nas quais campos específicos têm acesso permitido 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 dão suporte à definição granular de quais colunas de banco de dados (campos) têm acesso permitido 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" }
          ]
        }
      ]
    }
  }
}

Inclua e exclua o trabalho em conjunto. O * curinga na seção include indica todos os campos. Os campos anotados na seção exclude têm precedência sobre campos anotados na seção include. A definição se traduz em 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 (políticas de banco de dados) que limitam os resultados retornados de uma solicitação. A subseção database denota a expressão de política de banco de dados que é 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	corda	Nenhum

Descrição

A política de database: uma expressão semelhante a OData que é convertida 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 de uma política de banco de dados deve ser avaliado como true durante a execução no banco de dados.

Política de Item de Exemplo	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 TRUE ou FALSE. Predicados são usados na condição de pesquisa de cláusulas WHERE e cláusulas HAVING, as condições de junção de cláusulas FROM e outras construções em que um valor booliano é necessário. (Microsoft Learn Docs)

Política de banco de dados

Dois tipos de diretivas podem ser usados para gerenciar a política de banco de dados ao criar uma expressão de política 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 é definida

Nota

Quando Azure Static Web Apps authentication (EasyAuth) estiver configurado, um número limitado de tipos de declarações estará disponível para uso em políticas de banco de dados: identityProvider, userId, userDetailse userRoles. Para obter mais informações, consulte a documentação de dados da entidade de segurança do cliente do Aplicativo Web Estático do Azure.

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 UserId com o valor do campo de banco de dados OwnerId. O conteúdo do resultado inclui apenas registros que atendem metadados de solicitação e 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. 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ó têm suporte para a actionscriar, de leitura, de atualização e excluir. Como não há nenhum predicado em uma chamada de procedimento armazenado, eles não podem ser acrescentados.

Operadores OData compatíveis

Operador	Descrição	Sintaxe de exemplo
`and`	AND lógico	`"@item.status eq 'active' and @item.age gt 18"`
`or`	OR lógico	`"@item.region eq 'US' or @item.region eq 'EU'"`
`eq`	Equals	`"@item.type eq 'employee'"`
`gt`	Maior que	`"@item.salary gt 50000"`
`lt`	Menor que	`"@item.experience lt 5"`

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

Operador	Descrição	Sintaxe de exemplo
`-`	Negar (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 aderirem a essas regras não podem ser usados diretamente nas 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.

Utilizando `mappings` para campos de não conformidade

Se os nomes de campo de entidade não atenderem às regras de sintaxe OData ou simplesmente desejar alias por outros motivos, você poderá definir aliases na seção mappings de 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. Criar 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 na adesão às convenções de nomenclatura OData, mas também aprimora 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 a dados seja gerenciado com segurança com base nas funções de 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"
      }
    }
  }
}

de Definição de Entidade: a entidade Employee está configurada para interfaces REST e GraphQL, indicando que seus dados podem ser consultados ou manipulados por esses pontos de extremidade.

de Configuração de Origem: identifica o HRUNITS no banco de dados, com employee NUM como o campo de 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 de banco de dados.

Policy Application: a seção policy aplica uma política de banco de dados usando uma expressão semelhante a OData. Essa política restringe o acesso a dados a usuários com a função de RH (@claims.role eq 'HR') ou a usuários cuja declaração UserId corresponde a EmployeeId - o alias do campo - no banco de dados (@claims.userId eq @item.EmployeeId). Isso 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 a 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 traduzida para uma consulta predefinida 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.

Nota

Um predicado é uma expressão que é avaliada como TRUE, FALSEou UNKNOWN. Predicados são usados em:

A condição de pesquisa de cláusulas WHERE
A condição de pesquisa de cláusulas FROM
As condições de junção das cláusulas FROM
Outras construções em que um valor booliano é 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 de uma política de banco de dados deve ser avaliado como true durante a execução no banco de dados.

Dois tipos de diretivas podem ser usados para gerenciar a política de banco de dados ao criar uma expressão de política 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 é definida

Nota

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) está configurada. Esses tipos de declaração incluem: identityProvider, userId, userDetailse userRoles. Para obter mais informações, consulte de dados da entidade de segurança do cliente dos Aplicativos Web Estáticos do Azure.

Exemplos

Por exemplo, uma expressão de política básica pode avaliar se um campo específico é verdadeiro dentro da tabela. Este exemplo avalia se o campo soft_delete está 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 ao campo owner_id na tabela de 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. Procedimentos armazenados não podem ser configurados com políticas.
As políticas de banco de dados não podem ser usadas para impedir a execução de uma solicitação em um banco de dados. Essa limitação ocorre porque as políticas de banco de dados são resolvidas como predicados de consulta nas consultas de banco de dados geradas. O mecanismo de banco de dados, em última análise, avalia essas consultas.
As políticas de banco de dados só têm suporte para o actionscreate, read, updatee delete.
A sintaxe de expressão OData da política de banco de dados só dá suporte a esses cenários.
- Operadores binários, incluindo, mas não limitados a; and, or, eq, gte lt. Para obter mais informações, consulte BinaryOperatorKind.
- Operadores unários, como os operadores - (negação) e not. Para obter mais informações, consulte UnaryOperatorKind.
As políticas de banco de dados também têm restrições relacionadas a nomes de campo.
- Nomes de campo de entidade que começam com uma letra ou sublinhado, seguidos por no máximo 127 letras, sublinhados ou dígitos.
- Esse requisito é de acordo com a especificação OData. Para obter mais informações, consulte OData Common Schema Definition Language.

Ponta

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

GraphQL (entidades)

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

Esse segmento fornece a integração de uma entidade ao 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	cadeia de caracteres ou objeto	Nenhum
`operation`	❌ Não	cadeia de caracteres de enumeração	Nenhum

Exemplos

Esses 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 da entidade Book dentro do segmento GraphQL oferece uma estrutura clara sobre como ela deve ser representada e interagida em um esquema GraphQL.

propriedade habilitada: a entidade Book é disponibilizada por meio do GraphQL ("enabled": true), o que significa que desenvolvedores e usuários podem consultar ou alterar dados de livro por meio de operações do 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 intuitivamente nomeados (Book para uma única entrada, Books para uma lista), aumentando a usabilidade da API.

a propriedade Operação: 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 mutar (criar, atualizar ou excluir) ela. Essa configuração se alinha aos padrões de uso típicos em que 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 [cadeia de caracteres, objeto]	❌ Não	{entity-name}

Essa propriedade determina a convenção de nomenclatura para uma entidade dentro do esquema GraphQL. Ele dá suporte a 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	corda	Nenhum
`plural`	❌ Não	corda	N/A (padrão: singular)

Exemplos

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

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`	cadeia de caracteres de enumeração	❌ Não	Nenhum

Para entidades mapeadas para procedimentos armazenados, a propriedade operation designa o tipo de operação GraphQL (consulta ou mutação) em que 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.

Nota

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 coerse o local desse tipo nas partes mutation ou query do esquema. Essa propriedade permite o hygene de esquema e não há nenhum impacto funcional, independentemente de operation valor.

Se estiver ausente, o padrão de operation será 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 se assemelharia a:

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

Quando operation é query, o esquema GraphQL se assemelharia a:

O esquema GraphQL seria semelhante a:

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

Nota

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

Habilitado (entidade GraphQL)

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

Habilita ou desabilita o ponto de extremidade do GraphQL. Controla se uma entidade está disponível por meio de pontos de extremidade do GraphQL. A agregação da 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 a ajustar os pontos de extremidade RESTful para cada entidade de banco de dados. Essa funcionalidade de personalização garante que a API REST exposta corresponda a requisitos específicos, melhorando seus recursos de utilitário e de 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	corda	`/<entity-name>`
`methods`	❌ Não	matriz de cadeia de caracteres	OBTER

Exemplos

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

Habilitado (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, habilitando 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`	corda	❌ Não	Nenhum

A propriedade path especifica o segmento de 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 de entidade padrão, aprimorando a navegação 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 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 sublinha 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 será 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 de que o procedimento armazenado stp_get_bestselling_authors dá suporte apenas a 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 habilita a configuração de aliases ou nomes expostos para campos de objeto de banco de dados. Os nomes expostos configurados se aplicam aos pontos de extremidade GRAPHQL e REST.

Importante

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

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 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 de banco de dados (BookID, BookTitle, AuthorName) a nomes mais intuitivos ou padronizados (id, title, author) que são usados externamente. Esse aliasing serve a várias finalidades:

de 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, 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 do GraphQL: ao fornecer um mecanismo para nomes de campo de alias, ele garante que os nomes expostos por meio 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 aliased a um nome compatível por meio de mapeamentos.
Flexibilidade: esse aliasing adiciona uma camada de abstração entre o esquema de banco de dados e a API, permitindo alterações em uma sem exigir alterações na outra. Por exemplo, uma alteração de nome de campo no banco de dados não exigirá uma atualização para a documentação da API ou o código do lado do cliente se o mapeamento permanecer consistente.
nome do campo Ofuscação: o mapeamento permite a ofuscação de nomes de campo, o que pode ajudar a impedir que usuários não autorizados inferam informações confidenciais sobre o esquema de banco de dados ou a natureza dos dados armazenados.
Protegendo informações proprietárias: renomeando campos, você também pode proteger nomes proprietários ou lógica de negócios que podem ser sugeridos por meio 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 relação que mapeiam como as entidades estão relacionadas a outras entidades expostas. Essas definições de relação também podem incluir, opcionalmente, 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 divisão de relações do construtor de API de Dados.

Nota

As relações são relevantes apenas para consultas GraphQL. Os pontos de extremidade REST acessam apenas uma entidade por 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 potencial suporte de banco de dados para essas relações. A propriedade relationship-name para cada relação é necessária e deve ser exclusiva em todas as relações de uma determinada entidade. Os nomes personalizados garantem conexões claras e identificáveis e mantêm a integridade do esquema GraphQL gerado a partir dessas configurações.

Relação	Cardinalidade	Exemplo
um para muitos	`many`	Uma entidade de categoria pode se relacionar com muitas entidades de todo
muitos para um	`one`	Muitas entidades de todo podem se relacionar com uma entidade de categoria
muitos para muitos	`many`	Uma entidade todo pode se relacionar com muitas entidades de usuário e uma entidade de usuário pode se relacionar com várias entidades de todo

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	cadeia de caracteres de enumeração	Nenhum
`target.entity`	✔️ Sim	corda	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	corda	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 relações, é melhor comparar as diferenças entre um para muitos, muitos para um e relações muitos para muitos.

Um para muitos

Primeiro, vamos considerar um exemplo de uma relação com a entidade Category exposta tem uma relação um para muitos com a entidade Book. Aqui, a cardinalidade está definida como 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). Esse campo é usado para se conectar ao item relacionado na entidade target. Por outro lado, a lista target.fields especifica o campo category_id da entidade de destino (Book). Esse 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 como 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 source.fields especifica que o campo category_id da entidade de origem (Book) referencia o campo id da entidade de destino relacionada (Category). Inversamente, a lista 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

Por fim, 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 backup. Aqui, a entidade Book pode ter várias entidades Author e, por outro lado, 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 relação 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`	corda	✔️ Sim	Nenhum

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

Valores

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

	Descrição
`one`	A origem está relacionada apenas a um registro do destino
`many`	A origem pode se relacionar com registros de zero a muitos do destino

Entidade de destino

Pai	Propriedade	Tipo	Necessário	Inadimplência
`entities.{entity}.relationships`	`target.entity`	corda	✔️ 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`	array	❌ Não	Nenhum

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

Ponta

Esse campo não será necessário se houver uma chave estrangeira contenção 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`	array	❌ Não	Nenhum

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

Ponta

Vinculando objeto ou entidade

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

Para relações muitos para muitos, o nome do objeto de banco de dados ou entidade 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`	array	❌ Não	Nenhum

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

Vinculando campos de destino

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

O nome do objeto de banco de dados ou campo de entidade que está 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 está habilitado e os itens expiram após 30 segundos.

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

Habilitado (entidade 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 ao cache
Mesa	✅ Sim
Vista	✅ Sim
Procedimento armazenado	✖️ Não
Recipiente	✖️ Não

Suporte a cabeçalho HTTP

Cabeçalho de solicitação	Suporte ao 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 cache)

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

Configura o valor de TTL (vida útil) em segundos para itens armazenados em cache. Após esse tempo decorrido, 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 está habilitado e os itens expiram após 15 segundos. Quando omitida, essa configuração herda a configuração global ou o padrão.

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

referência do Functions
referência da CLI (interface de linha de comando)

Compartilhar via

Referência de 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 banco de dados

Formato

Valores de tipo

Cadeia de conexão

Formato

Resiliência de conexão

SQL do Azure e SQL Server

Exemplos

Opções

Formato

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

Exemplo de procedimento armazenado do SQL:

Exemplo de configuração JSON:

Explicação:

Arquivos de fonte de dados

Formato

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

Exemplos

Runtime

Formato

Propriedades

Exemplos

GraphQL (runtime)

Formato

Propriedades

Habilitado (runtime do GraphQL)

Formato

Exemplos

Limite de profundidade (runtime do GraphQL)

Exemplos

Caminho (runtime do GraphQL)

Formato

Exemplos

Permitir introspecção (runtime do GraphQL)

Formato

Exemplos

Várias mutações (runtime do GraphQL)

Formato

Propriedades

Várias mutações – criar (runtime do GraphQL)

Formato

Propriedades

Exemplos

Exemplo de configuração

Exemplo de mutação do GraphQL

REST (runtime)

Formato

Propriedades

Habilitado (runtime REST)

Formato

Exemplos

Caminho (runtime REST)

Formato

Exemplos

Corpo da Solicitação Estrito (Rest Runtime)

Comportamento com configurações de coluna específicas

Formato

Exemplos

Configuração de exemplo

Comportamento INSERT com request-body-strict: false

Comportamento UPDATE com request-body-strict: false

Host (runtime)

Formato

Propriedades

Exemplos

Modo (runtime do host)

Formato

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

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