Compartilhar via

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

  • Sub-caminhos 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>
    }
  }
}

Note

Ao implantar o construtor de API de Dados usando Aplicativos Web Estáticos (versão prévia), o serviço do Azure injeta automaticamente outro subcaminho /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>. Esta observação é relevante apenas para aplicativos Web estáticos.

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 fazer isso, 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 AppService

Define o método de autenticação usado pelo construtor de API de Dados.

Somente anônimo (provedor de autenticação)

{
 "host": {
    // omit the authentication section
 }
}

Quando toda authentication a seção é omitida do arquivo dab-config.json, nenhum provedor de autenticação é usado. Nesse caso, o Construtor de API de Dados opera em um modo "sem autenticação". Nesse modo, o DAB não procura tokens ou Authorization cabeçalhos. O X-MS-API-ROLE cabeçalho também é ignorado nessa configuração.

[! Observação] Cada solicitação que entra no mecanismo é atribuída automaticamente e imediatamente à função do sistema .anonymous Em seguida, o controle de acesso é tratado exclusivamente pelas permissões que você define em cada entidade.

Um exemplo de permissões de entidade.

{
  "entities": {
    "Book": {
      "source": "dbo.books",
      "permissions": [
        {
          "role": "anonymous",
          "actions": [ "read" ]
        }
      ]
    }
  }
}

Neste exemplo, como nenhum authentication provedor está configurado, todas as solicitações de entrada são automaticamente consideradas de um anonymous usuário. A permissions matriz da Book entidade concede explicitamente à função a anonymous capacidade de executar read operações. Qualquer tentativa de executar outras ações (como create, update, delete) ou acessar outras entidades não configuradas para anonymous acesso é negada.

StaticWebApps (provedor de autenticação) [preterido]

{
 "host": {
  "authentication": {
   "provider": "StaticWebApps"
  }
 }
}

Esse provedor foi preterido porque o recurso Data Connections de versão prévia dos Aplicativos Web Estáticos foi desativado em novembro de 2025. Embora permaneça funcional, ele foi projetado para uma implementação herdada da autenticação nos Aplicativos Web Estáticos do Azure. Os desenvolvedores devem migrar para o AppService provedor para obter melhor suporte e consistência a longo prazo com a plataforma "Autenticação Fácil" mais ampla do Azure.

[! Observação] A migração não é tão simples quanto alterar o nome do provedor no arquivo de configuração. Os StaticWebApps provedores e os AppService provedores esperam estruturas JSON diferentes dentro do x-ms-client-principal cabeçalho para funções de processamento.

AppService (provedor de autenticação)

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

Esse provedor é para aplicativos hospedados no Serviço de Aplicativo do Azure, como aplicativos de contêiner do Azure. O ambiente de hospedagem do Azure manipula a autenticação e passa as informações de identidade do usuário para o aplicativo por meio de cabeçalhos de solicitação. Ele destina-se a desenvolvedores que desejam uma solução de autenticação simples e pronta para uso gerenciada pela plataforma do Azure.

Esse provedor não usa um token JWT do Authorization cabeçalho. Ele depende de um cabeçalho especial, X-MS-CLIENT-PRINCIPALinjetado pela plataforma do Serviço de Aplicativo. Esse cabeçalho contém um objeto JSON codificado em base64 com os detalhes de identidade do usuário.

Anônimo: se o AppService provedor estiver configurado, mas uma solicitação chegar sem o X-MS-CLIENT-PRINCIPAL cabeçalho, a solicitação será atribuída à função do sistema de anonymous.

O JSON decodificado do X-MS-CLIENT-PRINCIPAL cabeçalho normalmente tem esta aparência:

{
  "auth_typ": "aad",
  "claims": [
    {"typ": "roles", "val": "admin"},
    {"typ": "roles", "val": "contributor"}
  ],
  "name_typ": "...",
  "role_typ": "..."
}

As funções estão contidas na claims matriz.

Sobre o cabeçalho X-MS-API-ROLE

  • Função e Comportamento: o X-MS-API-ROLE cabeçalho é usado para especificar qual função o usuário deseja assumir para a solicitação atual. O valor desse cabeçalho deve corresponder a um dos valores de função encontrados na claims matriz do X-MS-CLIENT-PRINCIPAL objeto.
  • É necessário?: Não. Se o X-MS-API-ROLE cabeçalho estiver ausente, a solicitação será processada no contexto da função do authenticated sistema. Isso significa que o usuário é reconhecido como conectado, mas não como qualquer função específica definida pelo aplicativo do token.
  • Comportamento na correspondência: se o X-MS-API-ROLE cabeçalho for fornecido e seu valor corresponder a uma função na entidade de segurança do claimscliente, o usuário assumirá essa função para a solicitação.
  • Comportamento em Incompatibilidade: se o X-MS-API-ROLE cabeçalho for fornecido, mas o valor não corresponder a nenhuma função na entidade de segurança do cliente, a solicitação será rejeitada com um 403 Forbidden código de status. Isso garante que um usuário não possa reivindicar uma função que não tenha sido atribuída.

EntraId (provedor de autenticação)

{
 "host": {
  "authentication": {
   "provider": "EntraId", // previously AzureAd
   "jwt": {
    "audience": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "issuer": "https://login.microsoftonline.com/98765f43-21ba-400c-a5de-1f2a3d4e5f6a/v2.0"
   }
  }
 }
}

Esse provedor protege pontos de extremidade com identidades de usuário e aplicativo no Microsoft Entra. É ideal para qualquer serviço em que os usuários ou outros serviços precisem de acesso seguro dentro do locatário do Entra.

[! OBSERVAÇÃO] O EntraId provedor foi nomeado AzureAdanteriormente. O nome antigo ainda funciona, mas os desenvolvedores são incentivados a migrar suas configurações de AzureAd para EntraId.

Esse provedor espera um token JWT Bearer padrão no Authorization cabeçalho, emitido pelo Microsoft Entra. O token deve ser configurado para o aplicativo específico (usando a audience declaração). Espera-se que as funções do usuário ou da entidade de serviço estejam em uma declaração dentro do token. O código procura uma roles declaração por padrão.

Anônimo: se o EntraId provedor estiver configurado, mas uma solicitação chegar sem o Authorization cabeçalho, a solicitação será atribuída à função do sistema de anonymous.

Uma carga JWT decodificada pode ter esta aparência:

{
  "aud": "...", // Audience - your API
  "iss": "https://login.microsoftonline.com/{tenant-id}/v2.0", // Issuer
  "oid": "...", // User or principal object ID
  "roles": [
    "reader",
    "writer"
  ],
  // ... other claims
}

Sobre o cabeçalho X-MS-API-ROLE

  • Função e Comportamento: o X-MS-API-ROLE cabeçalho é usado para especificar uma função que o usuário deseja assumir para a solicitação. O valor desse cabeçalho deve corresponder a um dos valores de função encontrados na roles declaração do token JWT.
  • É necessário?: Não. Se o X-MS-API-ROLE cabeçalho estiver ausente, a solicitação será processada no contexto da função do authenticated sistema. Isso significa que o usuário é reconhecido como conectado, mas não como qualquer função específica definida pelo aplicativo do token.
  • Comportamento na correspondência: se o X-MS-API-ROLE cabeçalho for fornecido e corresponder a roles uma função na declaração, o contexto do usuário será definido como essa função.
  • Comportamento em Incompatibilidade: se o X-MS-API-ROLE cabeçalho for fornecido, mas seu valor não corresponder a roles nenhuma função na declaração, a solicitação será rejeitada com um 403 Forbidden código de status. Isso garante que um usuário não possa reivindicar uma função que não tenha sido atribuída.

Personalizado (provedor de autenticação)

{
 "host": {
  "authentication": {
   "provider": "Custom",
   "jwt": {
    "audience": "<client-id-or-api-audience>",
    "issuer": "https://<your-domain>/oauth2/default"
   }
  }
 }
}

Esse provedor é para desenvolvedores que desejam integrar o Construtor de API de Dados a um provedor de identidade de terceiros (como Auth0, Okta ou um servidor de identidade personalizado) que emite JWTs. Ele fornece a flexibilidade para configurar o esperado audience e issuer os tokens.

O Custom provedor espera um token de portador JWT padrão no Authorization cabeçalho. A principal diferença do EntraId provedor é que você configura o arquivo de configuração válido issuer e audience no construtor de API de Dados. O provedor valida o token verificando se a autoridade confiável o emitiu. Espera-se que as funções do usuário estejam em uma roles declaração dentro do conteúdo JWT.

[! OBSERVAÇÃO] Em alguns casos, dependendo do provedor de identidade de terceiros, os desenvolvedores precisam coagir a estrutura de seu JWT para corresponder à estrutura esperada pelo construtor de API de Dados (mostrado abaixo).

Anônimo: se o Custom provedor estiver configurado, mas uma solicitação chegar sem o Authorization cabeçalho, a solicitação será atribuída à função do sistema de anonymous.

Uma carga JWT decodificada para um custom provedor pode ter esta aparência:

{
  "aud": "my-api-audience", // Must match configuration
  "iss": "https://my-custom-issuer.com/", // Must match configuration
  "sub": "user-id",
  "roles": [
    "editor",
    "viewer"
  ],
  // ... other claims
}

Sobre o cabeçalho X-MS-API-ROLE

  • Função e comportamento: o X-MS-API-ROLE cabeçalho funciona exatamente como ele faz com o EntraId provedor. Ele permite que o usuário selecione uma de suas funções atribuídas. O valor desse cabeçalho deve corresponder a uma das funções da roles declaração no token JWT personalizado.
  • É necessário?: Não. Se o X-MS-API-ROLE cabeçalho estiver ausente, o usuário será tratado como estando na função do authenticated sistema.
  • Comportamento na correspondência: se o X-MS-API-ROLE valor do cabeçalho corresponder a uma função na declaração do roles JWT, o contexto do usuário será definido como essa função para fins de autorização.
  • Comportamento em Incompatibilidade: se o X-MS-API-ROLE valor do cabeçalho não corresponder a roles nenhuma função na declaração, a solicitação será rejeitada com um 403 Forbidden código de status. Isso garante que um usuário não possa reivindicar uma função que não tenha sido atribuída.

Simulador (provedor de autenticação)

Esse provedor foi projetado para facilitar que os desenvolvedores testem suas configurações, especialmente authorization as políticas, sem a necessidade de configurar um provedor de autenticação completo, como o Entra Identity ou o EasyAuth. Ele simula um authenticated usuário.

O Simulator provedor não usa tokens JWT. A autenticação é simulada. Ao usar esse provedor, todas as solicitações são tratadas como se fossem provenientes de um usuário autenticado.

Sobre o cabeçalho X-MS-API-ROLE

  • Função e comportamento: o X-MS-API-ROLE cabeçalho é a única maneira de especificar uma função ao usar o Simulator. Como não há nenhum token com uma lista de funções, o sistema confia implicitamente na função enviada nesse cabeçalho.
  • É necessário?: Não.
  • Comportamento na Ausência: se o X-MS-API-ROLE cabeçalho estiver ausente, a solicitação será processada no contexto da função do authenticated sistema.
  • Comportamento na Presença: se o X-MS-API-ROLE cabeçalho estiver presente, a solicitação será processada no contexto da função especificada no valor do cabeçalho. Não há validação em relação a uma lista de declarações, portanto, o desenvolvedor pode simular qualquer função necessária para testar suas políticas.

Simulador em produção

Se estiver authentication.provider definido como Simulator enquanto estiverruntime.host.mode, o production construtor de API de Dados falhará ao iniciar.

"host": {
  "mode": "production", // or "development"
  "authentication": {
    "provider": "Simulator" 
  }
}

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

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

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.

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 configuraçã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
  }
}
  • Last updated on