Runtime

Definições de configuração que determinam o comportamento do tempo de execução.

Configurações de paginação

Configurações REST

Configurações do GraphQL

Configurações do host

Configurações do CORS

Definições de autenticação

Configurações de cache

Definições de compressão

Configurações de telemetria

Definições MCP

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: "Unauthenticated"),
        "jwt": {
          "audience": "<string>",
          "issuer": "<string>"
        }
      }
    }
  },
    "compression": {
      "level": <"optimal"> (default) | <"fastest"> | <"none">
    },
    "cache": {
      "enabled": <true>|<false> (default: `false`),
      "ttl-seconds": <integer> (default: `5`),
      "level-2": {
        "enabled": <true>|<false> (default: `false`),
        "provider": <"redis">,
        "connection-string": <string>,
        "partition": <string>
      }
    },
    "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`)
      },
      "azure-log-analytics": {
        "enabled": <true>|<false> (default: `false`),
        "dab-identifier": <string> (default: "DabLogs"),
        "flush-interval-seconds": <integer> (default: `5`),
        "auth": {
          "custom-table-name": <string>,
          "dcr-immutable-id": <string>,
          "dce-endpoint": <string>
        }
      },
      "file": {
        "enabled": <true>|<false> (default: `false`),
        "path": <string> (default: "/logs/dab-log.txt"),
        "rolling-interval": <string> (default: "Day"),
        "retained-file-count-limit": <integer> (default: `1`),
        "file-size-limit-bytes": <integer> (default: `1048576`)
      },
      "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`)
    },
    "mcp": {
      "enabled": <true>|<false> (default: `true`),
      "path": <string> (default: `"/mcp"`),
      "description": <string>,
      "dml-tools": <true>|<false> | {
        "describe-entities": <true>|<false> (default: `true`),
        "create-record": <true>|<false> (default: `true`),
        "read-records": <true>|<false> (default: `true`),
        "update-record": <true>|<false> (default: `true`),
        "delete-record": <true>|<false> (default: `true`),
        "execute-entity": <true>|<false> (default: `true`),
        "aggregate-records": <true>|<false> | {
          "enabled": <true>|<false> (default: `true`),
          "query-timeout": <integer> (default: `30`)
        }
      }
    }
  }
}

Modo (tempo de execução do host)

Comportamento de desenvolvimento

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

Format

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

Tamanho máximo da resposta (tempo de execução do host)

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

Format

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

GraphQL (tempo de execução)

Configuração global do GraphQL.

Propriedades aninhadas

Notas sobre o imóvel

• Não são permitidos subcaminhos na 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> | <false> (default)
        }
      }
    }
  }
}

Exemplo: mutações múltiplas

Configuration

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

Mutação 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)

Configuração REST global.

Propriedades aninhadas

Notas sobre o imóvel

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

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 apenas INSERT quando o seu valor na carga útil é null. Como consequência, INSERT as operações em default() colunas, quando request-body-strict é true, não podem resultar em valores explícitos null . Para conseguir este comportamento, é necessária uma UPDATE operação.
• As colunas com um default() não são ignoradas durante UPDATE independentemente do valor da carga útil.
• As colunas computadas são sempre ignoradas.
• As colunas geradas automaticamente são sempre ignoradas.

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

Solicitar carga útil

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

Carga útil de 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.

Carga útil de resposta

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

CORS (tempo de execução do host)

Configuração global do CORS.

Propriedades aninhadas

Format

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

Provedor (tempo de execução do host de autenticação)

Seleciona o método de autenticação. Cada prestador valida a identidade de forma diferente. Para a configuração passo a passo, consulte os guias práticos na tabela seguinte.

Resumo do prestador

Não autenticado (por defeito)

Quando Unauthenticated está definido (ou sem fornecedor especificado), o DAB não inspeciona nem valida nenhum JWT. Todos os pedidos são executados como o anonymous papel. Um serviço front-end como o Azure API Management ou um gateway de aplicação ainda pode gerir a política de autenticação ou acesso antes de os pedidos chegarem ao DAB, mas o DAB continua a autorizar apenas como anonymous.

{
  "host": {
    "authentication": {
      "provider": "Unauthenticated"
    }
  }
}

AppService

Trusts identity headers injected by Azure App Service EasyAuth.

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

EntraID

Valida tokens JWT emitidos pelo Microsoft Entra ID.

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

Personalizado

Valida tokens JWT de fornecedores de identidade terceiros.

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

Simulador

Simula autenticação para desenvolvimento e testes locais.

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

Seleção de funções

Para todos os fornecedores, exceto o Simulator, o X-MS-API-ROLE cabeçalho seleciona qual o papel a usar a partir das reivindicações do utilizador autenticado. Se for omitido, o pedido utiliza o papel do Authenticated sistema. Para detalhes sobre a avaliação de funções, consulte Visão geral da Autorização.

JWT (Tempo de execução do host de autenticação)

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

Propriedades aninhadas

* Tanto audience como issuer são necessários quando o jwt objeto está presente. O jwt próprio objeto é necessário quando o fornecedor é EntraID, AzureAD, ou Custom.

Format

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

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

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

Propriedades aninhadas

Valores suportados com tamanho máximo de página

Valores suportados com tamanho de página padrão

Comportamento relativo ao próximo elo

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

Format

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

Exemplo: paginação em REST

Request

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

Carga útil de 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=="
}

Solicitar Página Seguinte

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

Exemplo: Paging no GraphQL

Solicitar carga útil (Consulta)

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

Carga útil de 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=="
    }
  }
}

Solicitar Página Seguinte

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

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

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

REST

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

GraphQL

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

Compressão (tempo de execução)

Configuração de compressão de resposta HTTP. Quando ativado, o DAB comprime os corpos de resposta para reduzir o tamanho da carga útil e melhorar as velocidades de transferência.

Propriedades aninhadas

Valores suportados para level

Cabeçalhos HTTP do cliente

A compressão é invocada pelo cabeçalho do Accept-Encoding cliente. Os algoritmos suportados são Gzip e Brotli. A level definição configura a estratégia de compressão quando tanto o cliente como o servidor suportam múltiplos algoritmos.

Cabeçalhos suportados

Format

{
  "runtime": {
    "compression": {
      "level": <"optimal"> (default) | <"fastest"> | <"none">
    }
  }
}

Example

{
  "runtime": {
    "compression": {
      "level": "optimal"
    }
  }
}

Cache (tempo de execução)

Configuração de cache global.

Propriedades aninhadas

Format

{
  "runtime": {
    "cache":  {
      "enabled": <boolean>,
      "ttl-seconds": <integer>,
      "level-2": {
        "enabled": <boolean>,
        "provider": "redis",
        "connection-string": <string>,
        "partition": <string>
      }
    }
  }
}

Quando level-2.enabled é true, o DAB utiliza o fornecedor de cache distribuído configurado além da cache local em memória. Uma entidade configurada com nível L1L2 de cache verifica primeiro a cache local, depois a cache distribuída, antes de ir para a base de dados.

Telemetria (tempo de execução)

Configuração de telemetria global.

Propriedades aninhadas

Configura a verbosidade do registro em log por namespace. Esta configuração segue as convenções padrão de registo do .NET e permite controlo granular, embora presuma alguma familiaridade com os internos do Data API builder. O construtor de API de dados é de código aberto: https://aka.ms/dab

Format

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

Example

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

Application Insights (telemetria)

Configura o registro em log no Application Insights.

Propriedades aninhadas

Format

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

OpenTelemetry (telemetria)

Configura o registro em log para Abrir Telemetria.

Propriedades aninhadas

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.

Azure Log Analytics (telemetria)

Configura o registo no Azure Log Analytics através de um endpoint de recolha de dados. Quando ativado, o DAB envia dados de telemetria em lotes a intervalos configuráveis.

Propriedades aninhadas

* auth é necessário quando enabled é true.

* Obrigatório quando enabled é true.

• dab-identifier—um rótulo passado ao Log Analytics para ajudar a diferenciar quais os logs que provêm do Data API Builder.
• flush-interval-seconds—o intervalo de tempo (em segundos) entre o envio de lotes de dados de telemetria.
• custom-table-name—o nome da tabela personalizada no Azure Log Analytics onde os dados são armazenados.
• dcr-immutable-id—o ID imutável da regra de recolha de dados que define como os dados são recolhidos.
• dce-endpoint—a URL do endpoint de recolha de dados usada para enviar dados de telemetria.

Format

{
  "runtime": {
    "telemetry": {
      "azure-log-analytics": {
        "enabled": <true> | <false> (default),
        "dab-identifier": <string> (default: "DabLogs"),
        "flush-interval-seconds": <integer> (default: 5),
        "auth": {
          "custom-table-name": "<string>",
          "dcr-immutable-id": "<string>",
          "dce-endpoint": "<string>"
        }
      }
    }
  }
}

Example

{
  "runtime": {
    "telemetry": {
      "azure-log-analytics": {
        "enabled": true,
        "dab-identifier": "MyDabInstance",
        "flush-interval-seconds": 10,
        "auth": {
          "custom-table-name": "DabTelemetry_CL",
          "dcr-immutable-id": "dcr-abc123def456",
          "dce-endpoint": "https://my-dce.eastus-1.ingest.monitor.azure.com"
        }
      }
    }
  }
}

Ficheiro (telemetria)

Configura a escrita de registos de telemetria num ficheiro local. Quando ativado, o DAB escreve saída de log estruturada no caminho do ficheiro especificado com intervalos rolantes configuráveis e limites de tamanho.

Propriedades aninhadas

* path é necessário quando enabled é true.

Valores de intervalo rolante

Format

{
  "runtime": {
    "telemetry": {
      "file": {
        "enabled": <true> | <false> (default),
        "path": <string> (default: "/logs/dab-log.txt"),
        "rolling-interval": <"Day"> (default) | <"Minute"> | <"Hour"> | <"Month"> | <"Year"> | <"Infinite">,
        "retained-file-count-limit": <integer> (default: 1),
        "file-size-limit-bytes": <integer> (default: 1048576)
      }
    }
  }
}

Example

{
  "runtime": {
    "telemetry": {
      "file": {
        "enabled": true,
        "path": "/var/log/dab/dab-telemetry.txt",
        "rolling-interval": "Hour",
        "retained-file-count-limit": 24,
        "file-size-limit-bytes": 5242880
      }
    }
  }
}

MCP (duração do tempo)

Configura o SQL Model Context Protocol (MCP) Server, que expõe entidades de base de dados como ferramentas MCP para agentes de IA.

Propriedades aninhadas

A dml-tools propriedade aceita um booleano para ativar ou desativar todas as ferramentas, ou um objeto para controlar ferramentas individuais:

A aggregate-records ferramenta aceita um booleano ou um objeto com mais definições:

Format

{
  "runtime": {
    "mcp": {
      "enabled": <true> (default) | <false>,
      "path": <string> (default: "/mcp"),
      "description": <string>,
      "dml-tools": {
        "describe-entities": <true> | <false>,
        "create-record": <true> | <false>,
        "read-records": <true> | <false>,
        "update-record": <true> | <false>,
        "delete-record": <true> | <false>,
        "execute-entity": <true> | <false>,
        "aggregate-records": {
          "enabled": <true> | <false>,
          "query-timeout": <integer; default: 30>
        }
      }
    }
  }
}

Example

{
  "runtime": {
    "mcp": {
      "enabled": true,
      "dml-tools": {
        "describe-entities": true,
        "create-record": true,
        "read-records": true,
        "update-record": true,
        "delete-record": true,
        "execute-entity": true,
        "aggregate-records": {
          "enabled": true,
          "query-timeout": 30
        }
      }
    }
  }
}

Para ativar ou desativar todas as ferramentas DML ao mesmo tempo, defina "dml-tools" para true ou false.

Quando desativas uma ferramenta ao nível do runtime, a ferramenta nunca aparece na resposta MCP tools/list e não pode ser invocada, independentemente das permissões ao nível da entidade. Para mais informações sobre ferramentas DML individuais, consulte ferramentas de linguagem de manipulação de dados (DML).

Usando a CLI

dab configure --runtime.mcp.enabled true
dab configure --runtime.mcp.path "/mcp"
dab configure --runtime.mcp.dml-tools.describe-entities true
dab configure --runtime.mcp.dml-tools.create-record true
dab configure --runtime.mcp.dml-tools.read-records true
dab configure --runtime.mcp.dml-tools.update-record true
dab configure --runtime.mcp.dml-tools.delete-record true
dab configure --runtime.mcp.dml-tools.execute-entity true
dab configure --runtime.mcp.dml-tools.aggregate-records.enabled true

Integridade (tempo de execução)

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

Propriedades aninhadas

Comportamento no desenvolvimento vs. produção

Format

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

Example

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