Runtime

Configurações que determinam o comportamento do runtime.

Configurações de paginação

Configurações REST

Configurações do GraphQL

Configurações de host

Configurações do CORS

Configurações de autenticação

Configurações de cache

Configurações de compactação

Configurações de telemetria

Configurações do 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 (runtime do host)

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)

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.

Format

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

GraphQL (runtime)

Configuração global do GraphQL.

Propriedades aninhadas

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> | <false> (default)
        }
      }
    }
  }
}

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)

Configuração REST global.

Propriedades aninhadas

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.

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)

Configuração global do CORS.

Propriedades aninhadas

Format

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

Provedor (runtime do host de autenticação)

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 na tabela a seguir.

Resumo do provedor

Não autenticado (padrão)

Quando Unauthenticated é definido (ou nenhum provedor é especificado), o DAB não inspeciona nem valida qualquer JWT. Todas as solicitações são executadas como a anonymous função. Um serviço front-end, como o Gerenciamento de API do Azure ou um gateway de aplicativo, ainda pode lidar com a autenticação ou a política de acesso antes que as solicitações cheguem ao DAB, mas o DAB continua autorizando apenas como anonymous.

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

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

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 a visão geral de autorização.

JWT (runtime do host de autenticação)

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

Propriedades aninhadas

* Ambos audience e issuer são necessários quando o jwt objeto está presente. O jwt objeto em si é necessário quando o provedor é EntraID, AzureADou Custom.

Format

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

Paginação (Runtime)

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

Propriedades aninhadas

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

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

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.

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

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

Compactação (runtime)

Configuração de compactação de resposta HTTP. Quando habilitado, o DAB compacta os corpos de resposta para reduzir os tamanhos de carga e melhorar as velocidades de transferência.

Propriedades aninhadas

Valores com suporte para level

Cabeçalhos HTTP do cliente

A compactação é invocada pelo cabeçalho do Accept-Encoding cliente. Os algoritmos com suporte são Gzip e Brotli. A level configuração configura a estratégia de compactação quando o cliente e o servidor dão suporte a vários algoritmos.

Cabeçalhos com suporte

Format

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

Example

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

Cache (runtime)

Configuração do 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 usa o provedor de cache distribuído configurado, além do cache na memória local. Uma entidade configurada com o nível L1L2 de cache verifica primeiro o cache local, depois o cache distribuído, antes de ir para o banco de dados.

Telemetria (runtime)

Configuração de telemetria global.

Propriedades aninhadas

Configura a verbosidade de log por namespace. Essa configuração segue as convenções de log padrão do .NET e permite o controle granular, embora 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"
      }
    }
  }
}

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 registro em log no Azure Log Analytics por meio de um ponto de extremidade de coleta de dados. Quando habilitado, o DAB envia dados de telemetria em lotes em um intervalo configurável.

Propriedades aninhadas

* auth é necessário quando enabled é true.

* Obrigatório quando enabled for true.

• dab-identifier— um rótulo passado para o Log Analytics para ajudar a diferenciar quais logs vêm do construtor de API de Dados.
• 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 em que os dados são armazenados.
• dcr-immutable-id— a ID imutável da regra de coleta de dados que define como os dados são coletados.
• dce-endpoint— a URL do ponto de extremidade de coleta 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"
        }
      }
    }
  }
}

Arquivo (telemetria)

Configura a gravação de logs de telemetria em um arquivo local. Quando habilitado, o DAB grava a saída de log estruturada no caminho do arquivo especificado com intervalos de rolagem configuráveis e limites de tamanho.

Propriedades aninhadas

* path é necessário quando enabled é true.

Valores de intervalo sem interrupção

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

Configura o servidor MCP (Protocolo de Contexto de Modelo sql), que expõe entidades de banco de dados como ferramentas MCP para agentes de IA.

Propriedades aninhadas

A dml-tools propriedade aceita um booliano para habilitar ou desabilitar todas as ferramentas ou um objeto para controlar ferramentas individuais:

A aggregate-records ferramenta aceita um booliano ou um objeto com mais configuraçõ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 habilitar ou desabilitar todas as ferramentas DML de uma só vez, defina "dml-tools" como true ou false.

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

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

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

Propriedades aninhadas

Comportamento em desenvolvimento versus 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
  }
}