Statuscontroles en het statuseindpunt gebruiken

Data API Builder biedt een /health eindpunt voor het bewaken van de reactiesnelheid en status van de gegevensbronnen en entiteiten van uw API. Met dit eindpunt worden controles uitgevoerd op basis van geconfigureerde gegevensbronnen en entiteiten, waarbij wordt gecontroleerd of ze reageren binnen de drempelwaarden die u hebt ingesteld.

Hoe gezondheidscontroles werken

• Voor elke gegevensbron controleert een eenvoudige databasespecifieke query de connectiviteit en meet de reactietijd.
• Voor elke entiteit waarvoor REST of GraphQL is ingeschakeld, retourneert een query de eerste N rijen om de reactiesnelheid te bevestigen.
• Opgeslagen procedures worden automatisch uitgesloten van statuscontroles omdat ze parameters vereisen en mogelijk niet deterministisch zijn.
• Het /health eindpunt voegt deze resultaten samen in een uitgebreid rapport dat de algehele status aangeeft.

Configuratie van runtime-gezondheid

Statuscontroles worden beheerd in de runtime.health sectie:

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

Op rollen gebaseerd toegangsgedrag

• Ontwikkelingsmodus (host.mode: development):

  • Wanneer roles niet geconfigureerd: statuseindpunt toegankelijk voor alle gebruikers (behandeld als anoniem)
  • Wanneer roles is geconfigureerd: alleen opgegeven rollen hebben toegang tot het eindpunt

• Productiemodus (host.mode: production):

  • roles moet expliciet worden gedefinieerd
  • Het weglaten van roles resulteert in 403 Verboden voor alle verzoeken.
  • Als u openbare toegang wilt toestaan, stelt u "roles": ["anonymous"]

Basis gezondheidseindpunt op het rootpad

Een vereenvoudigd statuseindpunt op / is altijd openbaar toegankelijk zonder verificatie. Het retourneert basisservicegegevens (versie, status) zonder statuscontroles uit te voeren.

Statusconfiguratie van gegevensbron

Elke gegevensbron kan worden geconfigureerd voor statuscontroles in data-source.health:

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

Configuratie van entiteitsgezondheid

Entiteitscontroles kunnen per entiteit worden ingeschakeld in entities.{entity-name}.health:

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

Entiteitsstatuscontroles worden uitgevoerd voor zowel REST als GraphQL als ingeschakeld. Elke vermelding wordt weergegeven als een afzonderlijke vermelding in het rapport met tags (rest of graphql).

Overwegingen voor prestaties en caching

Gezondheidscontrolecache (cache-ttl-seconds):

• Voorkomt dat snelle aanvragen het systeem overweldigen
• Slaat het volledige statusrapport voor de geconfigureerde TTL in de cache op
• Stel in op 0 om caching uit te schakelen
• Standaard: 5 seconden

Parallelle uitvoering van query's (max-query-parallelism):

• Hiermee bepaalt u hoeveel statuscontrolequery's gelijktijdig worden uitgevoerd
• Hogere waarden versnellen controles maar verhogen de belasting van de database
• Bereik: 1-8
• Standaard: 4
• Lagere waarden gebruiken als u veel entiteiten of strikte resourcelimieten hebt

Voorbeeld van statuscontroleantwoord

{
  "status": "Healthy",
  "version": "1.2.3",
  "app-name": "dab_oss_1.2.3",
  "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
      }
    }
  ]
}

Aanvullende overwegingen

• Gezondheidscontroles respecteren entiteits- en eindpuntautorisatie. Als een rol niet gemachtigd is om toegang te krijgen tot een entiteit, rapporteert de gezondheidscontrole dit.
• Opgeslagen procedures worden uitgesloten omdat ze parameters vereisen en mogelijk bijwerkingen hebben.
• Entiteiten met rest.enabled: false of graphql.enabled: false worden uitgesloten van deze controles.
• Wanneer data-source.health.enabled: falseworden controles van gegevensbronnen overgeslagen.