Runtime

Configurações que determinam o comportamento do runtime.

Configurações de paginação

Property	Default	Description
tamanho da página runtime.pagination.max	Define o máximo de registros por página
runtime.pagination.default-page-size	Define registros padrão por resposta

Configurações REST

Property	Default	Description
runtime.rest.path	"/api"	Caminho base para pontos de extremidade REST
runtime.rest.enabled	true	Permite habilitar ou desabilitar solicitações REST para todas as entidades
runtime.rest.request-body-strict	true	Não permite campos desnecessários no corpo da solicitação quando verdadeiro

Configurações do GraphQL

Property	Default	Description
runtime.graphql.allow-introspection	true	Permite a consulta do esquema GraphQL subjacente
runtime.graphql.path	"/graphql"	Caminho base para o ponto de extremidade do GraphQL
runtime.graphql.enabled	true	Permite habilitar ou desabilitar solicitações do GraphQL para todas as entidades
runtime.graphql.depth-limit	null	Profundidade máxima permitida de uma consulta GraphQL
runtime.graphql.multiple-mutações.create.enabled	false	Permite mutações de criação múltipla para todas as entidades

Configurações de host

Property	Default	Description
runtime.host.max-response-size-mb	158	Tamanho máximo (MB) da resposta do banco de dados permitida em um único resultado
runtime.host.mode	"production"	Modo de execução; "production" ou "development"

Configurações do CORS

Property	Default	Description
runtime.host.cors.origins	[]	Origens de CORS permitidas
runtime.host.cors.allow-credentials	false	Define o valor do cabeçalho access-control-Allow-Credentials

Configurações de autenticação

Property	Default	Description
runtime.host.authentication.provider	null	Provedor de autenticação
runtime.host.authentication.jwt.audience	null	Público-alvo do JWT
runtime.host.authentication.jwt.issuer	null	Emissor JWT

Configurações de cache

Property	Default	Description
runtime.cache.enabled	false	Habilita o cache de respostas globalmente
runtime.cache.ttl-seconds	5	Tempo de vida útil (segundos) para o cache global

Configurações de telemetria

Property	Default	Description
runtime.telemetry.application-insights.connection-string	null	Cadeia de conexão do Application Insights
runtime.telemetry.application-insights.enabled	false	Habilita ou desabilita a telemetria do Application Insights
runtime.telemetry.open-telemetry.endpoint	null	URL do coletor OpenTelemetry
runtime.telemetry.open-telemetry.headers	{}	Cabeçalhos de exportação OpenTelemetry
runtime.telemetry.open-telemetry.service-name	"dab"	Nome do serviço OpenTelemetry
runtime.telemetry.open-telemetry.exporter-protocol	"grpc"	Protocolo OpenTelemetry ("grpc" ou "httpprotobuf")
runtime.telemetry.open-telemetry.enabled	true	Habilita ou desabilita o OpenTelemetry
runtime.telemetry.log-level.namespace	null	Substituição do nível de log específico do namespace
runtime.health.enabled	true	Habilita ou desabilita o ponto de extremidade de verificação de integridade globalmente
runtime.health.roles	null	Funções permitidas para o ponto de extremidade de integridade abrangente
runtime.health.cache-ttl-seconds	5	Tempo de vida útil (segundos) para a entrada do cache do relatório de verificação de integridade
runtime.health.max-query-parallelism	4	Consultas de verificação de integridade simultânea máximas (intervalo: 1 a 8)

Visão geral do formato

{
  "runtime": {
    "pagination": {
      "max-page-size": <integer|null> (default: `100000`),
      "default-page-size": <integer|null> (default: `100`)
    },
    "rest": {
      "path": <string> (default: "/api"),
      "enabled": <true>|<false>,
      "request-body-strict": <true>|<false> (default: `true`)
    },
    "graphql": {
      "path": <string> (default: "/graphql"),
      "enabled": <true>|<false>,
      "allow-introspection": <true>|<false>,
      "depth-limit": <integer|null> (default: `null`),
      "multiple-mutations": {
        "create": {
          "enabled": <true>|<false> (default: `false`)
        }
      }
    },
    "host": {
      "mode": <"production"> (default) | <"development">,
      "max-response-size-mb": <integer|null> (default: `158`),
      "cors": {
        "origins": [ "<string>" ],
        "allow-credentials": <true>|<false> (default: `false`)
      },
      "authentication": {
        "provider": <string> (default: "AppService"),
        "jwt": {
          "audience": "<string>",
          "issuer": "<string>"
        }
      }
    }
  },
  "cache": {
    "enabled": <true>|<false> (default: `false`),
    "ttl-seconds": <integer> (default: `5`)
  },
  "telemetry": {
    "application-insights": {
      "connection-string": "<string>",
      "enabled": <true>|<false> (default: `true`)
    },
    "open-telemetry": {
      "endpoint": "<string>",
      "headers": "<string>",
      "service-name": <string> (default: "dab"),
      "exporter-protocol": <"grpc"> (default) | <"httpprotobuf">,
      "enabled": <true>|<false> (default: `true`)
    },
    "log-level": {
      // namespace keys
      "<namespace>": <"trace"|"debug"|"information"|"warning"|"error"|"critical"|"none"|null>
    }
  },
  "health": {
    "enabled": <true>|<false> (default: `true`),
    "roles": [ "<string>" ],
    "cache-ttl-seconds": <integer> (default: `5`),
    "max-query-parallelism": <integer> (default: `4`)
  }
}

Modo (runtime do host)

Parent	Property	Tipo	Required	Default
runtime	host	enumeração (production | development)	❌ Não	production

Comportamento de desenvolvimento

• Nitro habilitado (anteriormente Banana Cake Pop) para teste do GraphQL
• Interface do usuário do Swagger habilitada para teste REST
• Verificações de integridade anônimas habilitadas
• Maior verbosidade de registro em log (Depuração)

Format

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

Tamanho máximo da resposta (runtime do host)

Parent	Property	Tipo	Required	Default
runtime.host	max-response-size-mb	inteiro	❌ Não	158

Define o tamanho máximo (em megabytes) para qualquer resultado especificado. Como respostas grandes podem forçar o sistema, max-response-size-mb limita o tamanho total (diferente da contagem de linhas) para evitar sobrecarga, que é especialmente com colunas grandes, como texto ou JSON.

Value	Result
não definido	Usar padrão
null	Usar padrão
integer	Qualquer inteiro positivo de 32 bits
<= 0	Sem suporte

Format

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

GraphQL (runtime)

Parent	Property	Tipo	Required	Default
runtime	graphql	objeto	❌ Não	-

Configuração global do GraphQL.

Propriedades aninhadas

Parent	Property	Tipo	Required	Default
runtime.graphql	enabled	boolean	❌ Não	None
runtime.graphql	path	cadeia	❌ Não	"/graphql"
runtime.graphql	depth-limit	inteiro	❌ Não	Nenhum (ilimitado)
runtime.graphql	allow-introspection	boolean	❌ Não	True
runtime.graphql	multiple-mutations.create.enabled	boolean	❌ Não	False

Notas de propriedade

• Os subcaminhos não são permitidos para a path propriedade.
• Use depth-limit para restringir consultas aninhadas.
• Defina allow-introspection para false ocultar o esquema GraphQL.
• Use multiple-mutations para inserir várias entidades em uma única mutação.

Format

{
  "runtime": {
    "graphql": {
      "enabled": <true> (default) | <false>
      "depth-limit": <integer|null> (default: `null`),
      "path": <string> (default: /graphql),
      "allow-introspection": <true> (default) | <false>,
      "multiple-mutations": {
        "create": {
          "enabled": <true> (default) | <false>
        }
    }
  }
}

Exemplo: várias mutações

Configuration

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

Mutação do GraphQL

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

REST (tempo de execução)

Parent	Property	Tipo	Required	Default
runtime	rest	objeto	❌ Não	-

Configuração REST global.

Propriedades aninhadas

Parent	Property	Tipo	Required	Default
runtime.rest	enabled	boolean	❌ Não	None
runtime.rest	path	cadeia	❌ Não	"/api"
runtime.rest	request-body-strict	boolean	❌ Não	True

Notas de propriedade

• Se global enabled for false, o nível enabled de entidade individual não importará.
• A path propriedade não dá suporte a valores de subcaminho como /api/data.
• request-body-strict foi introduzido para ajudar a simplificar objetos POCO do .NET.

request-body-strict	Behavior
true	Campos extras no corpo da solicitação causam uma BadRequest exceção.
false	Campos extras no corpo da solicitação são ignorados.

Format

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

Exemplo: request-body-strict

• As colunas com um default() valor são ignoradas somente durante INSERT quando o valor na carga é null. Como consequência, INSERT as operações em default() colunas, quando request-body-strict estiverem true, não podem resultar em valores explícitos null . Para realizar esse comportamento, uma UPDATE operação é necessária.
• As colunas com um default() não são ignoradas durante UPDATE , independentemente do valor da carga.
• As colunas computadas são sempre ignoradas.
• Colunas geradas automaticamente são sempre ignoradas.

Tabela de exemplo

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

Conteúdo da solicitação

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

Inserir comportamento quando request-body-strict = false

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.

Payload da resposta

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

Atualizar o comportamento quando request-body-strict = false

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

Payload da resposta

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

CORS (runtime do host)

Parent	Property	Tipo	Required	Default
runtime.host	cors	objeto	❌ Não	-

Configuração global do CORS.

Tip

CORS significa "Compartilhamento de recursos entre origens". É um recurso de segurança do navegador que controla se as páginas da Web podem fazer solicitações para um domínio diferente daquele que as serviu.

Propriedades aninhadas

Parent	Property	Tipo	Required	Default
runtime.host.cors	allow-credentials	boolean	❌ Não	False
runtime.host.cors	origins	Matriz de cadeia de caracteres	❌ Não	None

Note

A allow-credentials propriedade define o Access-Control-Allow-Credentials cabeçalho CORS.

Format

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

Note

O curinga * é válido como um valor para origins.

Provedor (runtime do host de autenticação)

Parent	Property	Tipo	Required	Default
runtime.host.authentication	provider	enumeração (AppService | EntraId | Custom | Simulator)	❌ Não	None

Seleciona o método de autenticação. Cada provedor valida a identidade de forma diferente. Para obter a configuração passo a passo, consulte os guias de instruções vinculados abaixo.

Resumo do provedor

Fornecedor	Caso de uso	Origem da identidade	Guia de instruções
(omitido)	Acesso somente anônimo	None	—
AppService	Aplicativos hospedados no Azure (EasyAuth)	X-MS-CLIENT-PRINCIPAL cabeçalho	Configurar a autenticação do Serviço de Aplicativo
EntraID	Microsoft Entra ID (Azure AD)	Token de portador JWT	Configurar autenticação do Entra ID
Custom	IdPs de terceiros (Okta, Auth0)	Token de portador JWT	Configurar a autenticação JWT personalizada
Simulator	Somente testes locais	Simulado	Configurar a autenticação do Simulador

Note

O EntraId provedor foi nomeado AzureAdanteriormente. O nome antigo ainda funciona para compatibilidade.

Somente anônimo (sem provedor)

Quando a seção é omitida, o authentication DAB opera no modo somente anônimo. Todas as solicitações recebem a função do Anonymous sistema.

{
  "host": {
    // authentication section omitted
  }
}

AppService

Confia em cabeçalhos de identidade injetados pelo EasyAuth do Serviço de Aplicativo do Azure.

{
  "host": {
    "authentication": {
      "provider": "AppService"
    }
  }
}

EntraID

Valida tokens JWT emitidos pela ID do Microsoft Entra.

{
  "host": {
    "authentication": {
      "provider": "EntraId",
      "jwt": {
        "audience": "<application-id>",
        "issuer": "https://login.microsoftonline.com/<tenant-id>/v2.0"
      }
    }
  }
}

Personalizado

Valida tokens JWT de provedores de identidade de terceiros.

{
  "host": {
    "authentication": {
      "provider": "Custom",
      "jwt": {
        "audience": "<api-audience>",
        "issuer": "https://<your-idp-domain>/"
      }
    }
  }
}

Simulador

Simula a autenticação para desenvolvimento e teste local.

{
  "host": {
    "authentication": {
      "provider": "Simulator"
    }
  }
}

Important

O Simulator provedor só funciona quando runtime.host.mode é development. O DAB falhará ao iniciar se o Simulador estiver configurado no modo de produção.

Seleção de função

Para todos os provedores, exceto Simulador, o X-MS-API-ROLE cabeçalho seleciona qual função usar nas declarações do usuário autenticado. Se omitida, a solicitação usará a função do Authenticated sistema. Para obter detalhes sobre a avaliação de função, consulte Autorização e funções.

JWT (runtime do host de autenticação)

Parent	Property	Tipo	Required	Default
runtime.host.authentication	jwt	objeto	❌ Não	-

Configuração global do JWT (Token Web JSON).

Propriedades aninhadas

Parent	Property	Tipo	Required	Default
runtime.host.authentication.jwt	audience	cadeia	❌ Não	None
runtime.host.authentication.jwt	issuer	cadeia	❌ Não	None

Format

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

Paginação (Runtime)

Parent	Property	Tipo	Required	Default
runtime	pagination	objeto	❌ Não	-

Limites globais de paginação para pontos de extremidade REST e GraphQL.

Propriedades aninhadas

Parent	Property	Tipo	Required	Default
runtime.pagination	max-page-size	int	❌ Não	100,000
runtime.pagination	default-page-size	int	❌ Não	100
runtime.pagination	next-link-relative	boolean	❌ Não	false

Valores compatíveis com tamanho máximo de página

Value	Result
integer	Há suporte para qualquer inteiro positivo de 32 bits.
0	Não há suporte.
-1	O padrão é o valor máximo com suporte.
< -1	Não há suporte.

Valores com suporte de tamanho de página padrão

Value	Result
integer	Qualquer inteiro positivo menor que o max-page-sizeatual.
0	Não há suporte.
-1	O padrão é a configuração de max-page-size atual.
< -1	Não há suporte.

Comportamento relativo do próximo link

Quando next-link-relative for true, os valores de paginação nextLink usam URLs relativas em vez de URLs absolutas.

Value	Example
false (padrão)	"nextLink": "https://localhost:5001/api/users?$after=..."
true	"nextLink": "/api/users?$after=..."

Format

{
  "runtime": {
    "pagination": {
      "max-page-size": <integer; default: 100000>,
      "default-page-size": <integer; default: 100>,
      "next-link-relative": <boolean; default: false>
    }
  }
}

Note

Quando o valor é maior que max-page-size, os resultados são limitados a max-page-size.

Exemplo: Paginação em REST

Request

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

Payload da 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=="
}

Próxima Página da Solicitação

GET https://localhost:5001/api/users?$after=W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI==

Exemplo: Paginação no GraphQL

Conteúdo da solicitação (consulta)

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

Payload da 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=="
    }
  }
}

Próxima Página da Solicitação

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

Exemplo: acessando max-page-size em solicitações

Use o max-page-size valor definindo $limit (REST) ou first (GraphQL) para -1.

REST

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

GraphQL

query {
  users(first: -1) {
    items {
      ...
    }
  }
}

Cache (runtime)

Parent	Property	Tipo	Required	Default
runtime	cache	objeto	❌ Não	-

Configuração do Cache Global.

Propriedades aninhadas

Parent	Property	Tipo	Required	Default
runtime.cache	enabled	boolean	❌ Não	False
runtime.cache	ttl-seconds	inteiro	❌ Não	5

Tip

A propriedade de nível cache.ttl-seconds de entidade usa como padrão esse valor global.

Format

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

Important

Se global enabled for false, o nível enabled de entidade individual não importará.

Telemetria (runtime)

Parent	Property	Tipo	Required	Default
runtime	telemetry	objeto	❌ Não	-

Configuração de telemetria global.

Propriedades aninhadas

Parent	Property	Tipo	Required	Default
runtime.telemetry	log-level	dicionário	❌ Não	None
runtime.telemetry	application-insights	objeto	❌ Não	-
runtime.telemetry	open-telemetry	objeto	❌ Não	-

Configura a verbosidade de log por namespace. Isso segue as convenções de log padrão do .NET e permite o controle granular, embora ele assuma alguma familiaridade com os internos do construtor de API de Dados. O construtor de API de dados é de software livre: https://aka.ms/dab

Format

{
  "runtime": {
    "telemetry": {
      "log-level": {
        "namespace": "log-level",
        "namespace": "log-level"
      }
    }
  }
}

Tip

log-level pode ser recarregado a quente no desenvolvimento e na produção. Atualmente, é a única propriedade que dá suporte ao recarregamento frequente na produção.

Example

{
  "runtime": {
    "telemetry": {
      "log-level": {
        "Azure.DataApiBuilder.Core.Configurations.RuntimeConfigValidator": "debug",
        "Azure.DataApiBuilder.Core": "information",
        "default": "warning"
      }
    }
  }
}

Application Insights (telemetria)

Parent	Property	Tipo	Required	Default
runtime.telemetry	application-insights	objeto	❌ Não	-

Configura o registro em log no Application Insights.

Propriedades aninhadas

Parent	Property	Tipo	Required	Default
runtime.telemetry.application-insights	enabled	boolean	❌ Não	False
runtime.telemetry.application-insights	connection-string	cadeia	✔️ Sim	None

Format

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

OpenTelemetry (telemetria)

Parent	Property	Tipo	Required	Default
runtime.telemetry	open-telemetry	objeto	❌ Não	-

Configura o registro em log para Abrir Telemetria.

Propriedades aninhadas

Parent	Property	Tipo	Required	Default
runtime.telemetry.open-telemetry	enabled	boolean	❌ Não	true
runtime.telemetry.open-telemetry	endpoint	cadeia	✔️ Sim	None
runtime.telemetry.open-telemetry	headers	cadeia	❌ Não	None
runtime.telemetry.open-telemetry	service-name	cadeia	❌ Não	"dab"
runtime.telemetry.open-telemetry	exporter-protocol	enumeração (grpc | httpprotobuf)	❌ Não	grpc

Vários cabeçalhos são , separados (vírgula).

Format

{
  "runtime": {
    "telemetry": {
      "open-telemetry": {
        "enabled": <true> (default) | <false>,
        "endpoint": <string>,
        "headers": <string>,
        "service-name": <string> (default: "dab"),
        "exporter-protocol": <"grpc" (default) | "httpprotobuf">
      }
    }
  }
}

Example

{
  "runtime": {
    "telemetry": {
      "open-telemetry": {
        "enabled": true,
        // a gRPC endpoint example
        "endpoint": "http://localhost:4317",
        // an HTTP/protobuf endpoint example
        "endpoint": "http://localhost:4318/v1/metrics",
        "headers": "api-key=key,other-config-value=value",
        "service-name": "dab",
      }
    }
  }
}

Saiba mais sobre OTEL_EXPORTER_OTLP_HEADERS.

Note

gRPC (4317) é mais rápido e dá suporte ao streaming, mas requer mais etapas de instalação. HTTP/protobuf (4318) é mais simples e fácil de depurar, mas menos eficiente.

Integridade (runtime)

Parent	Property	Tipo	Required	Default
runtime	health	objeto	❌ Não	-

Configuração do ponto de extremidade de verificação de integridade global (/health).

Propriedades aninhadas

Parent	Property	Tipo	Required	Default	Intervalo/notas
runtime.health	enabled	boolean	❌ Não	true
runtime.health	roles	Matriz de cadeia de caracteres	✔️ Sim*	null	*Obrigatório no modo de produção
runtime.health	cache-ttl-seconds	inteiro	❌ Não	5	Min: 0
runtime.health	max-query-parallelism	inteiro	❌ Não	4	Min: 1, Máximo: 8 (preso)

Comportamento em desenvolvimento versus produção

Condition	Comportamento de desenvolvimento	Comportamento de produção
health.enabled = falso	403 estado	403 estado
health.enabled = verdadeiro	Depende da função	Depende da função
roles omitido ou null	Integridade exibida	403 estado
função atual não em roles	403 estado	403 estado
função atual em roles	Integridade exibida	Integridade exibida
roles inclui anonymous	Integridade exibida	Integridade exibida

Format

{
  "health": {
    "enabled": <true> (default) | <false>,
    "roles": [ <string> ], // required in production
    "cache-ttl-seconds": <integer; default: 5>,
    "max-query-parallelism": <integer; default: 4>
  }
}

Note

Se global enabled for false, o nível enabled de entidade individual não importará.

Example

{
  "health": {
    "enabled": true,
    "roles": ["admin", "support"],
    "cache-ttl-seconds": 10,
    "max-query-parallelism": 6
  }
}