Runtime

Impostazioni di configurazione che determinano il comportamento di runtime.

Impostazioni di paginazione

Impostazioni REST

Impostazioni di GraphQL

Impostazioni host

Impostazioni CORS

Impostazioni di autenticazione

Impostazioni della cache

Impostazioni di compressione

Impostazioni di telemetria

Impostazioni mcp

Panoramica del 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`)
        }
      }
    }
  }
}

Modalità (runtime host)

Comportamento di sviluppo

• Enabled Nitro (in precedenza Banana Cake Pop) per i test di GraphQL
• Interfaccia utente di Swagger abilitata per i test REST
• Controlli di integrità anonimi abilitati
• Maggiore dettaglio della registrazione (debug)

Format

{
  "runtime": {
    "host": {
      "mode": "production" (default) | "development"
    }
  }
}

Dimensioni massime della risposta (runtime host)

Imposta le dimensioni massime (in megabyte) per qualsiasi risultato specificato. Poiché le risposte di grandi dimensioni possono sovraccaricare il sistema, max-response-size-mb limitare le dimensioni totali (diverse dal numero di righe) per evitare l'overload, in particolare con colonne di grandi dimensioni come testo o JSON.

Format

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

GraphQL (runtime)

Configurazione globale di GraphQL.

Proprietà annidate

Note delle proprietà

• I percorsi secondari non sono consentiti per la path proprietà .
• Usare depth-limit per vincolare le query nidificate.
• Impostare allow-introspection su false per nascondere lo schema GraphQL.
• Usare multiple-mutations per inserire più entità in una singola mutazione.

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

Esempio: più mutazioni

Configuration

{
  "runtime": {
    "graphql": {
      "multiple-mutations": {
        "create": {
          "enabled": true
        }
      }
    }
  },
  "entities": {
    "User": {
      "source": "dbo.Users",
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["create"] // entity permissions are required
        }
      ]
    }
  }
}

Mutazione 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 di esecuzione)

Configurazione REST globale.

Proprietà annidate

Note delle proprietà

• Se global enabled è false, il livello enabled di entità individuale non è rilevante.
• La path proprietà non supporta valori di sottopercorso come /api/data.
• request-body-strict è stato introdotto per semplificare gli oggetti POCO .NET.

Format

{
  "runtime": {
    "rest": {
      "enabled": <true> (default) | <false>,
      "path": <string> (default: /api),
      "request-body-strict": <true> (default) | <false>
    }
  }
}

Esempio: request-body-strict

• Le colonne con un default() valore vengono ignorate durante INSERT solo quando il relativo valore nel payload è null. Di conseguenza, INSERT le operazioni in default() colonne, quando request-body-strict è true, non possono generare valori espliciti null . Per eseguire questo comportamento, è necessaria un'operazione UPDATE .
• Le colonne con un default() oggetto non vengono ignorate durante UPDATE indipendentemente dal valore del payload.
• Le colonne calcolate vengono sempre ignorate.
• Le colonne generate automaticamente vengono sempre ignorate.

Tabella di esempio

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

Payload della richiesta

{
  "Id": 999,
  "Name": "Alice",
  "Age": null,
  "IsAdmin": null,
  "IsMinor": false,
  "ExtraField": "ignored"
}

Comportamento di inserimento 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.

Carico della risposta

{
  "Id": 1,          // Auto-generated by the database
  "Name": "Alice",
  "Age": 18,        // Default applied
  "IsAdmin": false, // Default applied
  "IsMinor": true   // Computed
}

Aggiornare il comportamento quando request-body-strict = false

UPDATE Users
SET Name = 'Alice Updated', Age = NULL
WHERE Id = 1;
-- IsMinor and ExtraField are ignored.

Carico della risposta

{
  "Id": 1,
  "Name": "Alice Updated",
  "Age": null,
  "IsAdmin": false,
  "IsMinor": false // Recomputed by the database (false when age is `null`)
}

CORS (runtime host)

Configurazione CORS globale.

Proprietà annidate

Format

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

Provider (runtime host di autenticazione)

Seleziona il metodo di autenticazione. Ogni provider convalida l'identità in modo diverso. Per la configurazione dettagliata, vedere le guide pratiche nella tabella seguente.

Riepilogo provider

Non autenticato (impostazione predefinita)

Quando Unauthenticated è impostato (o non è specificato alcun provider), DAB non controlla o convalida alcun token JWT. Tutte le richieste vengono eseguite come anonymous ruolo. Un servizio front-end, ad esempio Gestione API di Azure o un gateway applicazione, può comunque gestire l'autenticazione o i criteri di accesso prima che le richieste raggiungano DAB, ma DAB continua a autorizzare solo come anonymous.

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

AppService

Considera attendibili le intestazioni di identità inserite da EasyAuth del servizio app di Azure.

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

EntraID

Convalida i token JWT emessi dall'ID Microsoft Entra.

{
  "host": {
    "authentication": {
      "provider": "EntraId",
      "jwt": {
        "audience": "<application-id>",
        "issuer": "https://login.microsoftonline.com/<tenant-id>/v2.0"
      }
    }
  }
}

Custom

Convalida i token JWT dai provider di identità di terze parti.

{
  "host": {
    "authentication": {
      "provider": "Custom",
      "jwt": {
        "audience": "<api-audience>",
        "issuer": "https://<your-idp-domain>/"
      }
    }
  }
}

Simulatore

Simula l'autenticazione per lo sviluppo e il test locali.

{
  "host": {
    "authentication": {
      "provider": "Simulator"
    }
  }
}

Selezione dei ruoli

Per tutti i provider ad eccezione del simulatore, l'intestazione X-MS-API-ROLE seleziona il ruolo da usare dalle attestazioni dell'utente autenticato. Se omesso, la richiesta usa il ruolo di Authenticated sistema. Per informazioni dettagliate sulla valutazione dei ruoli, vedere Panoramica dell'autorizzazione.

JWT (runtime host di autenticazione)

Configurazione JWT (Global JSON Web Token).

Proprietà annidate

* Sia audience che issuer sono necessari quando l'oggetto jwt è presente. L'oggetto jwt stesso è obbligatorio quando il provider è EntraID, AzureADo Custom.

Format

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

Paginazione (runtime)

Limiti di paginazione globali per gli endpoint REST e GraphQL.

Proprietà annidate

Valori supportati max-page-size

Valori supportati per le dimensioni predefinite della pagina

Comportamento relativo al collegamento successivo

Quando next-link-relative è true, i valori di paginazione nextLink usano URL relativi anziché URL assoluti.

Format

{
  "runtime": {
    "pagination": {
      "max-page-size": <integer; default: 100000>,
      "default-page-size": <integer; default: 100>,
      "next-link-relative": <boolean; default: false>
    }
  }
}

Esempio: paging in REST

Request

GET https://localhost:5001/api/users

Carico della risposta

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

Pagina Successiva richiesta

GET https://localhost:5001/api/users?$after=W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI==

Esempio: Paging in GraphQL

Payload della richiesta (query)

query {
  users {
    items {
      Id
      Name
      Age
      IsAdmin
      IsMinor
    }
    hasNextPage
    endCursor
  }
}

Carico della risposta

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

Pagina Successiva richiesta

query {
  users(after: "W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI==") {
    items {
      Id
      Name
      Age
      IsAdmin
      IsMinor
    }
    hasNextPage
    endCursor
  }
}

Esempio: accesso alle max-page-size richieste

Usare il max-page-size valore impostando $limit (REST) o first (GraphQL) su -1.

REST

GET https://localhost:5001/api/users?$limit=-1

GraphQL

query {
  users(first: -1) {
    items {
      ...
    }
  }
}

Compressione (runtime)

Configurazione della compressione della risposta HTTP. Se abilitata, DAB comprime i corpi di risposta per ridurre le dimensioni del payload e migliorare la velocità di trasferimento.

Proprietà annidate

Valori supportati per level

Intestazioni HTTP client

La compressione viene richiamata dall'intestazione del Accept-Encoding client. Gli algoritmi supportati sono Gzip e Brotli. L'impostazione level configura la strategia di compressione quando sia il client che il server supportano più algoritmi.

Intestazioni supportate

Format

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

Example

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

Cache (runtime)

Configurazione della Cache globale.

Proprietà annidate

Format

{
  "runtime": {
    "cache":  {
      "enabled": <boolean>,
      "ttl-seconds": <integer>,
      "level-2": {
        "enabled": <boolean>,
        "provider": "redis",
        "connection-string": <string>,
        "partition": <string>
      }
    }
  }
}

Quando level-2.enabled è true, DAB usa il provider di cache distribuito configurato oltre alla cache in memoria locale. Un'entità configurata con livello L1L2 di cache controlla prima la cache locale, quindi la cache distribuita, prima di passare al database.

Telemetria (runtime)

Configurazione della telemetria globale.

Proprietà annidate

Configura il livello di dettaglio della registrazione per ogni spazio dei nomi. Questa configurazione segue le convenzioni di registrazione standard di .NET e consente un controllo granulare, anche se presuppone una certa familiarità con gli elementi interni di Generatore API dati. Il generatore di API dati è open source: 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 la registrazione in Application Insights.

Proprietà annidate

Format

{
  "runtime": {
    "telemetry": {
      "application-insights": {
        "enabled": <true; default: true> | <false>
        "connection-string": <string>
      }
    }
  }
}

OpenTelemetry (telemetria)

Configura la registrazione in Apri telemetria.

Proprietà annidate

Più intestazioni sono , separate da virgole.

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

Altre informazioni sulle OTEL_EXPORTER_OTLP_HEADERS.

Azure Log Analytics (telemetria)

Configura la registrazione ad Azure Log Analytics tramite un endpoint di raccolta dati. Se abilitata, DAB invia i dati di telemetria in batch a un intervallo configurabile.

Proprietà annidate

* auth è obbligatorio quando enabled è true.

* Obbligatorio quando enabled è true.

• dab-identifier: un'etichetta passata a Log Analytics per distinguere i log provenienti dal generatore di API dati.
• flush-interval-seconds— intervallo di tempo (in secondi) tra l'invio di batch di dati di telemetria.
• custom-table-name: nome della tabella personalizzata in Azure Log Analytics in cui vengono archiviati i dati.
• dcr-immutable-id: ID non modificabile della regola di raccolta dati che definisce la modalità di raccolta dei dati.
• dce-endpoint: l'URL dell'endpoint di raccolta dati usato per inviare dati di 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"
        }
      }
    }
  }
}

File (telemetria)

Configura la scrittura di log di telemetria in un file locale. Se abilitata, DAB scrive l'output del log strutturato nel percorso del file specificato con intervalli di sequenza e limiti di dimensioni configurabili.

Proprietà annidate

* path è obbligatorio quando enabled è true.

Valori di intervallo in sequenza

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 il server MCP (SQL Model Context Protocol), che espone le entità di database come strumenti MCP per gli agenti di intelligenza artificiale.

Proprietà annidate

La dml-tools proprietà accetta un valore booleano per abilitare o disabilitare tutti gli strumenti o un oggetto per controllare i singoli strumenti:

Lo aggregate-records strumento accetta un valore booleano o un oggetto con altre impostazioni:

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

Per abilitare o disabilitare tutti gli strumenti DML contemporaneamente, impostare su "dml-tools"true o false.

Quando si disabilita uno strumento a livello di runtime, lo strumento non viene mai visualizzato nella risposta MCP tools/list e non può essere richiamato, indipendentemente dalle autorizzazioni a livello di entità. Per altre informazioni sui singoli strumenti DML, vedere Strumenti DML (Data Manipulation Language).

Uso dell'interfaccia della riga di comando

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

Integrità (runtime)

Configurazione dell'endpoint controllo integrità globale (/health).

Proprietà annidate

Comportamento in fase di sviluppo e produzione

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