Usar Verificações de Integridade e o Ponto de Extremidade de Integridade

O Data API Builder disponibiliza um /health endpoint para monitorar a responsividade e a integridade das fontes de dados e entidades da API. Esse ponto de extremidade executa verificações em relação a fontes de dados e entidades configuradas, validando que elas respondem dentro dos limites definidos.

Diagrama que ilustra o fluxo de verificação de integridade.

Pré-requisitos

Você precisa de um arquivo de configuração do DAB existente.

Executar ferramenta

Use dab configure para configurações de integridade do runtime. Para configurações de saúde da fonte de dados e da entidade, atualize o arquivo de configuração.

  1. Defina as configurações de integridade do runtime.

    dab configure \
  --runtime.health.enabled true \
  --runtime.health.roles "admin,monitoring" \
  --runtime.health.cache-ttl-seconds 10 \
  --runtime.health.max-query-parallelism 4

  2. Inicie o DAB.

    dab start

Testar o ponto de extremidade de integridade

  1. Chame o ponto de extremidade /health.

    curl http://localhost:5000/health

  2. Confirme se o status da resposta é Healthy.

Como funcionam as verificações de integridade

Para cada fonte de dados, uma consulta simples específica do banco de dados verifica a conectividade e mede o tempo de resposta. Para cada entidade com REST ou GraphQL habilitado, uma consulta retorna as primeiras N linhas para confirmar a capacidade de resposta. Os procedimentos armazenados são excluídos porque exigem parâmetros e podem não ser determinísticos. O endpoint /health agrega esses resultados em um relatório abrangente que indica a saúde geral.

Configuração

Use o exemplo a seguir para definir o runtime, a fonte de dados e as configurações de integridade da entidade.

{
  "runtime": {
    "health": {
      "enabled": true,
      "roles": ["admin", "monitoring"],
      "cache-ttl-seconds": 10,
      "max-query-parallelism": 4
    }
  },
  "data-source": {
    "health": {
      "enabled": true,
      "name": "primary-sql-db",
      "threshold-ms": 1500
    }
  },
  "entities": {
    "Book": {
      "health": {
        "enabled": true,
        "first": 50,
        "threshold-ms": 500
      }
    }
  }
}

Command-line

Definir configurações de integridade do runtime por meio de dab configure.

  • --runtime.health.enabled
  • --runtime.health.roles
  • --runtime.health.cache-ttl-seconds
  • --runtime.health.max-query-parallelism

Example

dab configure \
  --runtime.health.enabled true \
  --runtime.health.roles "admin,monitoring" \
  --runtime.health.cache-ttl-seconds 10 \
  --runtime.health.max-query-parallelism 4

Configuração resultante

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

Configuração de integridade do runtime

As verificações de integridade são controladas na seção runtime.health:

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

Propriedades

enabled (booliano, padrão: true) habilita ou desabilita o ponto de extremidade de integridade abrangente globalmente.

roles (string[], padrão: null) controla o acesso ao ponto de extremidade /health.

cache-ttl-seconds (inteiro, padrão: 5) define o TTL (tempo de vida útil) do relatório de integridade armazenado em cache.

max-query-parallelism (inteiro, padrão: 4) define as consultas de verificação de integridade simultânea máximas (intervalo: 1-8).

Comportamento de acesso baseado em função

No modo de desenvolvimento (host.mode: development), o ponto de extremidade de integridade é acessível a todos os usuários quando roles não está configurado. Quando roles estiver configurado, somente as funções especificadas poderão acessar o endpoint. No modo de produção (host.mode: production), roles deve ser definido explicitamente. Omitir roles retorna 403 Proibido para todas as solicitações. Para permitir o acesso público, defina "roles": ["anonymous"].

Importante

As funções configuradas aqui controlam o acesso ao endpoint de saúde, não as permissões para operações individuais de entidade. Se uma função não tiver permissão para consultar uma entidade, a verificação de integridade dessa entidade refletirá uma falha, que é o comportamento esperado.

Ponto de extremidade de integridade básico no caminho raiz

Um ponto de extremidade de integridade simplificado em / é sempre acessível publicamente sem autenticação. Ele retorna informações básicas de serviço (versão, status) sem executar nenhuma verificação de integridade.

Configuração de integridade da fonte de dados

Cada fonte de dados pode ser configurada para verificações de integridade em data-source.health:

{
  "data-source": {
    "health": {
      "enabled": true,
      "name": "primary-sql-db",
      "threshold-ms": 1500
    }
  }
}

Propriedades

enabled (booliano, padrão: true) permite verificações de integridade para essa fonte de dados.

name (cadeia de caracteres, padrão: valor do tipo de banco de dados) é o identificador exclusivo mostrado no relatório de integridade.

threshold-ms (inteiro, padrão: 1000) é o tempo máximo de execução de consulta permitido em milissegundos.

A propriedade do name é opcional. Ele ajuda a distinguir várias fontes de dados que compartilham o mesmo tipo de banco de dados (por exemplo, dois bancos de dados SQL) no relatório de integridade.

Configuração de saúde da entidade

As verificações de entidade podem ser habilitadas por entidade em entities.{entity-name}.health:

{
  "entities": {
    "Book": {
      "health": {
        "enabled": true,
        "first": 50,
        "threshold-ms": 500
      }
    }
  }
}

Propriedades

enabled (booliano, padrão: true) permite verificações de integridade para a entidade.

first (inteiro, padrão: 100) define o número de linhas retornadas pela consulta de integridade (intervalo: 1-500).

threshold-ms (inteiro, padrão: 1000) define o tempo máximo de execução de consulta permitido em milissegundos.

Observação

O valor de first deve ser menor ou igual à configuração de tempo de execução para max-page-size. Um valor menor first melhora o desempenho. Se você monitorar muitas entidades, valores mais altos de first podem tornar os relatórios mais lentos.

As verificações de integridade da entidade são executadas para REST e GraphQL, se habilitadas. Cada um aparece como uma entrada separada no relatório com marcas (rest ou graphql).

Considerações sobre desempenho e cache

cache-ttl-seconds impede que requisições sucessivas rápidas sobrecarreguem o sistema e armazena em cache o relatório de estado de integridade completo para o tempo de vida configurado. Defina-o para 0 desabilitar o cache. O padrão é 5 segundos. max-query-parallelism controla o número de consultas de verificação de integridade que são executadas simultaneamente. Valores mais altos aceleram as verificações, mas aumentam a carga do banco de dados. O intervalo é 1-8, e o padrão é 4. Use valores mais baixos se você tiver muitas entidades ou limites de recursos rígidos.

Exemplo de resposta de checagem de saúde

{
  "status": "Healthy",
  "version": "1.2.3",
  "app-name": "dab_oss_1.2.3",
  "currentRole": "admin",
  "timestamp": "2025-01-15T10:30:00Z",
  "configuration": {
    "rest": true,
    "graphql": true,
    "mcp": true,
    "caching": false,
    "telemetry": true,
    "mode": "Production"
  },
  "checks": [
    {
      "status": "Healthy",
      "name": "primary-sql-db",
      "tags": ["data-source"],
      "data": {
        "response-ms": 12,
        "threshold-ms": 1500
      }
    },
    {
      "status": "Healthy",
      "name": "Book",
      "tags": ["rest", "endpoint"],
      "data": {
        "response-ms": 45,
        "threshold-ms": 500
      }
    },
    {
      "status": "Healthy",
      "name": "Book",
      "tags": ["graphql", "endpoint"],
      "data": {
        "response-ms": 38,
        "threshold-ms": 500
      }
    }
  ]
}

O campo currentRole

A resposta de integridade inclui um campo currentRole que indica a função usada para autorizar a solicitação. O DAB resolve a função atual usando a seguinte prioridade:

  1. X-MS-API-ROLE cabeçalho – se presente, a função especificada é usada.
  2. authenticated— se a solicitação incluir uma entidade válida (por exemplo, um token JWT), mas nenhum cabeçalho X-MS-API-ROLE.
  3. anonymous— se nenhum principal estiver presente.

Observação

A funcionalidade do construtor de API de Dados descrita nesta seção está disponível na versão 2.0 e posterior. Para obter mais informações, consulte o que há de novo na versão 2.0.

Outras considerações

As verificações de integridade respeitam a autorização de entidade e ponto de extremidade. Se uma função não tiver permissão para acessar uma entidade, a verificação de integridade relatará isso. Os procedimentos armazenados são excluídos porque exigem parâmetros e podem ter efeitos colaterais. Entidades com rest.enabled: false ou graphql.enabled: false são excluídas dessas verificações. Quando data-source.health.enabled: false, as verificações da fonte de dados são ignoradas.

  • Last updated on