Partilhar via

Runtime

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

Configurações de paginação

Property Default Description
runtime.pagination.max de tamanho de página 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 estranhos no corpo da solicitação quando verdadeiro

Configurações do GraphQL

Property Default Description
runtime.graphql.allow-introspecção true Permite consultar o esquema subjacente do GraphQL
runtime.graphql.path "/graphql" Caminho base para o ponto de extremidade GraphQL
runtime.graphql.enabled true Permite ativar ou desativar pedidos GraphQL para todas as entidades
runtime.graphql.depth-limit null Profundidade máxima permitida de uma consulta GraphQL
runtime.graphql.multiple-mutations.create.enabled false Permite múltiplas mutações de criação para todas as entidades

Configurações do host

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

Configurações do CORS

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

Definições de autenticação

Property Default Description
runtime.host.authentication.provider null Fornecedor de autenticação
runtime.host.authentication.jwt.audiência null Audiência JWT
runtime.host.authentication.jwt.issuer null Emissor JWT

Configurações de cache

Property Default Description
runtime.cache.enabled false Permite o armazenamento em cache de respostas globalmente
runtime.cache.ttl-segundos 5 Tempo de vida (segundos) para 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 Ativa ou desativa o OpenTelemetry
runtime.telemetry.log-level.namespace null Substituição de 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-segundos 5 Tempo de vida (segundos) para a entrada de cache do relatório de verificação de integridade
runtime.health.max-consulta-paralelismo 4 Consultas máximas de verificação de saúde concorrentes (intervalo: 1-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 (tempo de execução do host)

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

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)

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

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.

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

Format

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

GraphQL (tempo de execução)

Parent Property Tipo Required Default
runtime graphql objecto ❌ 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 (de caracteres) ❌ Não "/graphql"
runtime.graphql depth-limit número inteiro ❌ Não Nenhum (ilimitado)
runtime.graphql allow-introspection boolean ❌ Não True
runtime.graphql multiple-mutations.create.enabled boolean ❌ Não False

Notas sobre o imóvel

  • 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: 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)

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

Configuração REST global.

Propriedades aninhadas

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

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.
request-body-strict Behavior
true Campos extras no corpo da solicitação causam uma BadRequest exceção.
false Os 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 (visualização), o serviço do Azure injeta automaticamente outro subcaminho /data-api para a url. Esse comportamento garante a compatibilidade com os recursos existentes do Static Web App. O parâmetro de avaliação resultante seria /data-api/api/<entity>. Esta observação só é relevante para Static Web Apps.

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 isso, uma UPDATE operação é necessária.
  • 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)

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

Configuração global do CORS.

Tip

CORS significa "Cross-Origin Resource Sharing" (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 atendeu.

Propriedades aninhadas

Parent Property Tipo Required Default
runtime.host.cors allow-credentials boolean ❌ Não False
runtime.host.cors origins array de strings ❌ 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 (tempo de execução do host de autenticação)

Parent Property Tipo Required Default
runtime.host.authentication provider enum (AppServiceCustom | SimulatorEntraId | | ) ❌ 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 a authentication 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 "no-auth". Neste modo, o DAB não procura tokens ou Authorization cabeçalhos. O X-MS-API-ROLE cabeçalho também é ignorado nesta configuração.

[! Nota] Cada solicitação que entra no mecanismo é automaticamente e imediatamente atribuída a função do sistema de anonymous. O controle de acesso é então tratado exclusivamente pelas permissões definidas 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 como sendo de um anonymous usuário. A permissions matriz para a Book entidade concede explicitamente à anonymous função a capacidade de executar read operações. Qualquer tentativa de executar outras ações (como create, , updatedelete) 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 visualização de Aplicativos Web estáticos foi desativado em novembro de 2025. Embora permaneça funcional, ele foi projetado para uma implementação herdada de autenticação em Aplicativos Web Estáticos do Azure. Os desenvolvedores devem migrar para o AppService provedor para obter melhor suporte de longo prazo e consistência com a plataforma "Easy Auth" mais ampla do Azure.

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

AppService (provedor de autenticação)

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

Este provedor é para aplicativos hospedados no Serviço de Aplicativo do Azure, como Aplicativos de Contêiner do Azure. O ambiente de hospedagem do Azure lida com a autenticação e, em seguida, passa as informações de identidade do usuário para o aplicativo por meio de cabeçalhos de solicitação. Destina-se a programadores que pretendam uma solução de autenticação simples e pronta a utilizar gerida pela plataforma Azure.

Este provedor não usa um token JWT do Authorization cabeçalho. Ele conta com um cabeçalho especial, X-MS-CLIENT-PRINCIPAL, injetado 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 cabeçalho normalmente tem esta X-MS-CLIENT-PRINCIPAL 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.
  • É obrigatório?: Não. Se o X-MS-API-ROLE cabeçalho estiver ausente, a solicitação será processada no contexto da authenticated função do sistema. Isso significa que o usuário é reconhecido como conectado, mas não como qualquer função específica definida pelo aplicativo a partir 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 claimssegurança do cliente, o usuário assumirá essa função para a solicitação.
  • Comportamento na 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 código de 403 Forbidden status. Isso garante que um usuário não possa reivindicar uma função que não lhe foi 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"
   }
  }
 }
}

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

[! NOTA] 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

Este 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.
  • É obrigatório?: Não. Se o X-MS-API-ROLE cabeçalho estiver ausente, a solicitação será processada no contexto da authenticated função do sistema. Isso significa que o usuário é reconhecido como conectado, mas não como qualquer função específica definida pelo aplicativo a partir do token.
  • Comportamento na correspondência: se o X-MS-API-ROLE cabeçalho for fornecido e corresponder a uma função na roles 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 nenhuma função na roles declaração, a solicitação será rejeitada com um código de 403 Forbidden status. Isso garante que um usuário não possa reivindicar uma função que não lhe foi atribuída.

Personalizado (provedor de autenticação)

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

Este provedor é para desenvolvedores que desejam integrar o construtor de API de dados com 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 dos tokens.

O Custom provedor espera um token JWT Bearer padrão no Authorization cabeçalho. A principal diferença do EntraId provedor é que você configura o válido issuer e audience no arquivo de configuração do 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 reivindicação dentro da carga útil JWT.

[! NOTA] 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 funciona 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.
  • É obrigató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 valor do cabeçalho corresponder a X-MS-API-ROLE 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 na incompatibilidade: se o X-MS-API-ROLE valor do cabeçalho não corresponder a nenhuma função na declaração, a roles solicitação será rejeitada com um código de 403 Forbidden status. Isso garante que um usuário não possa reivindicar uma função que não lhe foi atribuída.

Simulador (provedor de autenticação)

Este provedor foi projetado para tornar mais fácil para os desenvolvedores testarem suas configurações, especialmente authorization 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.
  • É obrigató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 authenticated função do 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 o authentication.provider estiver definido como Simulator while the is runtime.host.mode, o production construtor de API de dados falhará ao iniciar.

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

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

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

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

Diagrama de suporte a tokens web JSON no construtor de API de dados.

Propriedades aninhadas

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

Format

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

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

Parent Property Tipo Required Default
runtime pagination objecto ❌ 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 suportados com tamanho máximo de página

Value Result
integer Qualquer inteiro positivo de 32 bits é suportado.
0 Não suportado.
-1 O padrão é o valor máximo suportado.
< -1 Não suportado.

Valores suportados com tamanho de página padrão

Value Result
integer Qualquer número inteiro positivo menor que o max-page-sizeatual.
0 Não suportado.
-1 O padrão é a configuração max-page-size atual.
< -1 Não suportado.

Quando next-link-relative é 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

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

Cache (tempo de execução)

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

Configuração de cache global.

Propriedades aninhadas

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

Tip

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

Format

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

Important

Se global enabled for false, o nível enabled da entidade individual não importa.

Telemetria (tempo de execução)

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

Configuração de telemetria global.

Propriedades aninhadas

Parent Property Tipo Required Default
runtime.telemetry log-level dictionary ❌ Não None
runtime.telemetry application-insights objecto ❌ Não -
runtime.telemetry open-telemetry objecto ❌ Não -

Configura a verbosidade do registro em log por namespace. Isso segue as convenções padrão de log do .NET e permite controle granular, embora presuma alguma familiaridade com os internos do construtor de API de dados. 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"
      }
    }
  }
}

Tip

log-level pode ser recarregado a quente tanto no desenvolvimento quanto na produção. Atualmente, é a única propriedade que suporta recarga a quente 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 objecto ❌ 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 (de caracteres) ✔️ 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 objecto ❌ 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 (de caracteres) ✔️ Sim None
runtime.telemetry.open-telemetry headers cadeia (de caracteres) ❌ Não None
runtime.telemetry.open-telemetry service-name cadeia (de caracteres) ❌ Não ""
runtime.telemetry.open-telemetry exporter-protocol enum (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 suporta streaming, mas requer mais configuração. HTTP/protobuf (4318) é mais simples e fácil de depurar, mas menos eficiente.

Integridade (tempo de execução)

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

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

Propriedades aninhadas

Parent Property Tipo Required Default Alcance/Notas
runtime.health enabled boolean ❌ Não true
runtime.health roles array de strings ✔️ Sim* null *Obrigatório em modo de produção
runtime.health cache-ttl-seconds número inteiro ❌ Não 5 Mínimo: 0
runtime.health max-query-parallelism número inteiro ❌ Não 4 Mínimo: 1, Máximo: 8 (apertado)

Comportamento no desenvolvimento vs. produção

Condition Comportamento de Desenvolvimento Comportamento de Produção
health.enabled = falso 403 Situação 403 Situação
health.enabled = verdadeiro Depende da função Depende da função
roles omitida ou null Saúde exibida 403 Situação
papel atual não em roles 403 Situação 403 Situação
papel atual em roles Saúde exibida Saúde exibida
roles inclui anonymous Saúde exibida Saúde 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 da entidade individual não importa.

Example

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