Runtime

Impostazioni di configurazione che determinano il comportamento di runtime.

Impostazioni di paginazione

Property	Default	Description
runtime.pagination.max-page-size	Definisce il numero massimo di record per pagina
runtime.pagination.default-page-size	Imposta i record predefiniti per risposta

Impostazioni REST

Property	Default	Description
runtime.rest.path	`"/api"`	Percorso di base per gli endpoint REST
runtime.rest.enabled	`true`	Consente di abilitare o disabilitare le richieste REST per tutte le entità
runtime.rest.request-body-strict	`true`	Non consente campi estranei nel corpo della richiesta quando true

Impostazioni di GraphQL

Property	Default	Description
runtime.graphql.allow-introspection	`true`	Consente l'esecuzione di query sullo schema GraphQL sottostante
runtime.graphql.path	`"/graphql"`	Percorso di base per l'endpoint GraphQL
runtime.graphql.enabled	`true`	Consente di abilitare o disabilitare le richieste GraphQL per tutte le entità
runtime.graphql.depth-limit	`null`	Profondità massima consentita di una query GraphQL
runtime.graphql.multiple-mutations.create.enabled	`false`	Consente mutazioni multiple per tutte le entità

Impostazioni host

Property	Default	Description
runtime.host.max-response-size-mb	`158`	Dimensione massima (MB) della risposta al database consentita in un singolo risultato
runtime.host.mode	`"production"`	Modalità di esecuzione; `"production"` o `"development"`

Impostazioni CORS

Property	Default	Description
runtime.host.cors.origins	`[]`	Origini CORS consentite
runtime.host.cors.allow-credentials	`false`	Imposta il valore per l'intestazione access-control-Allow-Credentials

Impostazioni di autenticazione

Property	Default	Description
runtime.host.authentication.provider	`null`	Provider di autenticazione
runtime.host.authentication.jwt.audience	`null`	Destinatari JWT
runtime.host.authentication.jwt.issuer	`null`	Autorità emittente JWT

Impostazioni della cache

Property	Default	Description
runtime.cache.enabled	`false`	Abilita la memorizzazione nella cache delle risposte a livello globale
runtime.cache.ttl-seconds	`5`	Durata (secondi) per la cache globale

Impostazioni di telemetria

Property	Default	Description
runtime.telemetry.application-insights.connection-string	`null`	Stringa di connessione di Application Insights
runtime.telemetry.application-insights.enabled	`false`	Abilita o disabilita i dati di telemetria di Application Insights
runtime.telemetry.open-telemetry.endpoint	`null`	URL dell'agente di raccolta OpenTelemetry
runtime.telemetry.open-telemetry.headers	`{}`	Intestazioni di esportazione OpenTelemetry
runtime.telemetry.open-telemetry.service-name	`"dab"`	Nome del servizio OpenTelemetry
runtime.telemetry.open-telemetry.exporter-protocol	`"grpc"`	Protocollo OpenTelemetry ("grpc" o "httpprotobuf")
runtime.telemetry.open-telemetry.enabled	`true`	Abilita o disabilita OpenTelemetry
runtime.telemetry.log-level.namespace	`null`	Override del livello di log specifico dello spazio dei nomi
runtime.health.enabled	`true`	Abilita o disabilita l'endpoint di controllo integrità a livello globale
runtime.health.roles	`null`	Ruoli consentiti per l'endpoint di integrità completo
runtime.health.cache-ttl-seconds	`5`	Durata (secondi) per la voce della cache del report di controllo integrità
parallelismo di runtime.health.max query	`4`	Numero massimo di query simultanee di controllo integrità (intervallo: 1-8)

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: "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`)
  }
}

Modalità (runtime host)

Parent	Property	Type	Required	Default
`runtime`	`host`	enumerazione (`production` \| `development`)	❌ No	`production`

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)

Parent	Property	Type	Required	Default
`runtime.host`	`max-response-size-mb`	integer	❌ No	158

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.

Value	Result
non impostato	Usa valore predefinito
`null`	Usa valore predefinito
`integer`	Qualsiasi intero positivo a 32 bit
`<= 0`	Non supportato

Format

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

GraphQL (runtime)

Parent	Property	Type	Required	Default
`runtime`	`graphql`	object	❌ No	-

Configurazione globale di GraphQL.

Proprietà annidate

Parent	Property	Type	Required	Default
`runtime.graphql`	`enabled`	boolean	❌ No	None
`runtime.graphql`	`path`	string	❌ No	"/graphql"
`runtime.graphql`	`depth-limit`	integer	❌ No	Nessuno (illimitato)
`runtime.graphql`	`allow-introspection`	boolean	❌ No	True
`runtime.graphql`	`multiple-mutations.create.enabled`	boolean	❌ No	False

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> (default) | <false>
        }
    }
  }
}

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)

Parent	Property	Type	Required	Default
`runtime`	`rest`	object	❌ No	-

Configurazione REST globale.

Proprietà annidate

Parent	Property	Type	Required	Default
`runtime.rest`	`enabled`	boolean	❌ No	None
`runtime.rest`	`path`	string	❌ No	"/api"
`runtime.rest`	`request-body-strict`	boolean	❌ No	True

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.

`request-body-strict`	Behavior
`true`	I campi aggiuntivi nel corpo della richiesta causano un'eccezione `BadRequest` .
`false`	I campi aggiuntivi nel corpo della richiesta vengono ignorati.

Format

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

Note

Quando si distribuisce Generatore API dati usando App Web statiche (anteprima), il servizio di Azure inserisce automaticamente un altro sottopercorso /data-api nell'URL. Questo comportamento garantisce la compatibilità con le funzionalità di App Web statiche esistenti. L'endpoint risultante sarà /data-api/api/<entity>. Questa nota è rilevante solo per le app Web statiche.

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 . A tale scopo, è 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)

Parent	Property	Type	Required	Default
`runtime.host`	`cors`	object	❌ No	-

Configurazione CORS globale.

Tip

CORS è l'acronimo di "Cross-Origin Resource Sharing". Si tratta di una funzionalità di sicurezza del browser che controlla se le pagine Web possono effettuare richieste a un dominio diverso da quello che li ha serviti.

Proprietà annidate

Parent	Property	Type	Required	Default
`runtime.host.cors`	`allow-credentials`	boolean	❌ No	False
`runtime.host.cors`	`origins`	matrice di stringhe	❌ No	None

Note

La allow-credentials proprietà imposta l'intestazione Access-Control-Allow-Credentials CORS.

Format

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

Note

Il carattere jolly * è valido come valore per origins.

Provider (runtime host di autenticazione)

Parent	Property	Type	Required	Default
`runtime.host.authentication`	`provider`	enumerazione (`AppService` \| `EntraId` \| `Custom` \| `Simulator`)	❌ No	`AppService`

Definisce il metodo di autenticazione usato dal generatore di API dati.

Solo anonimo (provider di autenticazione)

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

Quando l'intera authentication sezione viene omessa dal file di dab-config.json, non viene usato alcun provider di autenticazione. In questo caso, il generatore di API dati opera in modalità "no-auth". In questa modalità, DAB non cerca token o Authorization intestazioni. L'intestazione X-MS-API-ROLE viene ignorata anche in questa configurazione.

[! Nota] A ogni richiesta che entra nel motore viene assegnato automaticamente e immediatamente il ruolo di sistema di anonymous. Il controllo di accesso viene quindi gestito esclusivamente dalle autorizzazioni definite per ogni entità.

Esempio di autorizzazioni per le entità.

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

In questo esempio, poiché non è configurato alcun authentication provider, tutte le richieste in ingresso vengono considerate automaticamente da un anonymous utente. La permissions matrice per l'entità Book concede in modo esplicito al anonymous ruolo la possibilità di eseguire read operazioni. Qualsiasi tentativo di eseguire altre azioni (ad esempio create, update, delete) o l'accesso ad altre entità non configurate per anonymous l'accesso viene negato.

StaticWebApps (provider di autenticazione) [deprecato]

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

Questo provider è deprecato perché la funzionalità Data Connections di anteprima app Web statiche è stata ritirata a novembre 2025. Anche se rimane funzionale, è stato progettato per un'implementazione legacy dell'autenticazione in App Web statiche di Azure. Gli sviluppatori devono eseguire la migrazione al AppService provider per una migliore coerenza e supporto a lungo termine con la piattaforma "Easy Auth" di Azure più ampia.

[! Nota] La migrazione non è semplice come la modifica del nome del provider nel file di configurazione. I StaticWebApps provider e AppService prevedono strutture JSON diverse all'interno dell'intestazione per l'elaborazione x-ms-client-principal dei ruoli.

AppService (provider di autenticazione)

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

Questo provider è destinato alle applicazioni ospitate nel servizio app di Azure, ad esempio App Azure Container. L'ambiente di hosting di Azure gestisce l'autenticazione e quindi passa le informazioni sull'identità dell'utente all'applicazione tramite intestazioni di richiesta. È destinato agli sviluppatori che vogliono una soluzione di autenticazione semplice e predefinita gestita dalla piattaforma Azure.

Questo provider non usa un token JWT dall'intestazione Authorization . Si basa su un'intestazione speciale, X-MS-CLIENT-PRINCIPAL, inserita dalla piattaforma del servizio app. Questa intestazione contiene un oggetto JSON con codifica Base64 con i dettagli dell'identità dell'utente.

Anonimo: se il AppService provider è configurato ma una richiesta arriva senza l'intestazione X-MS-CLIENT-PRINCIPAL , la richiesta viene assegnata al ruolo di sistema di anonymous.

Il codice JSON decodificato dall'intestazione X-MS-CLIENT-PRINCIPAL è in genere simile al seguente:

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

I ruoli sono contenuti all'interno della claims matrice.

Informazioni sull'intestazione diAPI-ROLE X-MS

Ruolo e comportamento: l'intestazione X-MS-API-ROLE viene usata per specificare il ruolo che l'utente desidera presupporre per la richiesta corrente. Il valore di questa intestazione deve corrispondere a uno dei valori del ruolo trovati nella claims matrice dell'oggetto X-MS-CLIENT-PRINCIPAL .
È obbligatorio?: No. Se l'intestazione X-MS-API-ROLE è assente, la richiesta viene elaborata nel contesto del ruolo di authenticated sistema. Ciò significa che l'utente viene riconosciuto come connesso, ma non come ruolo specifico definito dall'applicazione dal token.
Comportamento in corrispondenza: se l'intestazione X-MS-API-ROLE viene specificata e il relativo valore corrisponde a un ruolo nell'entità client, claimsl'utente assume tale ruolo per la richiesta.
Comportamento in caso di mancata corrispondenza: se l'intestazione X-MS-API-ROLE viene specificata ma il valore non corrisponde ad alcun ruolo nell'entità client, la richiesta viene rifiutata con un 403 Forbidden codice di stato. In questo modo, un utente non può richiedere un ruolo a cui non è stato assegnato.

EntraId (provider di autenticazione)

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

Questo provider protegge gli endpoint con identità utente e applicazione in Microsoft Entra. È ideale per qualsiasi servizio in cui gli utenti o altri servizi necessitano di accesso sicuro all'interno del tenant Entra.

[! NOTA] Il EntraId provider era precedentemente denominato AzureAd. Il nome precedente funziona ancora, ma gli sviluppatori sono invitati a eseguire la migrazione delle configurazioni da AzureAd a EntraId.

Questo provider prevede un token JWT Bearer standard nell'intestazione Authorization , rilasciato da Microsoft Entra. Il token deve essere configurato per l'applicazione specifica (usando l'attestazione audience ). I ruoli per l'utente o l'entità servizio devono trovarsi in un'attestazione all'interno del token. Il codice cerca un'attestazione roles per impostazione predefinita.

Anonimo: se il EntraId provider è configurato ma una richiesta arriva senza l'intestazione Authorization , la richiesta viene assegnata al ruolo di sistema di anonymous.

Un payload JWT decodificato potrebbe essere simile al seguente:

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

Informazioni sull'intestazione diAPI-ROLE X-MS

Ruolo e comportamento: l'intestazione X-MS-API-ROLE viene usata per specificare un ruolo che l'utente desidera assumere per la richiesta. Il valore di questa intestazione deve corrispondere a uno dei valori del ruolo trovati nell'attestazione roles del token JWT.
È obbligatorio?: No. Se l'intestazione X-MS-API-ROLE è assente, la richiesta viene elaborata nel contesto del ruolo di authenticated sistema. Ciò significa che l'utente viene riconosciuto come connesso, ma non come ruolo specifico definito dall'applicazione dal token.
Comportamento in corrispondenza: se l'intestazione X-MS-API-ROLE viene specificata e corrisponde a un ruolo nell'attestazione roles , il contesto dell'utente viene impostato su tale ruolo.
Comportamento non corrispondente: se l'intestazione X-MS-API-ROLE viene specificata ma il relativo valore non corrisponde ad alcun ruolo nell'attestazione roles , la richiesta viene rifiutata con un 403 Forbidden codice di stato. In questo modo, un utente non può richiedere un ruolo a cui non è stato assegnato.

Personalizzato (provider di autenticazione)

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

Questo provider è destinato agli sviluppatori che vogliono integrare Data API Builder con un provider di identità di terze parti (ad esempio Auth0, Okta o un server di identità personalizzato) che rilascia JWT. Offre la flessibilità necessaria per configurare i token previsti audience e issuer i token.

Il Custom provider prevede un token JWT Bearer standard nell'intestazione Authorization . La differenza principale del EntraId provider consiste nel configurare il file di configurazione valido issuer e audience nel file di configurazione del generatore di API dati. Il provider convalida il token controllando che l'autorità attendibile l'ha emessa. I ruoli dell'utente devono trovarsi in un'attestazione roles all'interno del payload JWT.

[! NOTA] In alcuni casi, a seconda del provider di identità di terze parti, gli sviluppatori devono coercire la struttura del token JWT in modo che corrisponda alla struttura prevista dal generatore di API dati (illustrato di seguito).

Anonimo: se il Custom provider è configurato ma una richiesta arriva senza l'intestazione Authorization , la richiesta viene assegnata al ruolo di sistema di anonymous.

Un payload JWT decodificato per un custom provider potrebbe essere simile al seguente:

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

Informazioni sull'intestazione diAPI-ROLE X-MS

Ruolo e comportamento: l'intestazione X-MS-API-ROLE funziona esattamente come funziona con il EntraId provider. Consente all'utente di selezionare uno dei ruoli assegnati. Il valore di questa intestazione deve corrispondere a uno dei ruoli dell'attestazione roles nel token JWT personalizzato.
È obbligatorio?: No. Se l'intestazione X-MS-API-ROLE è assente, l'utente viene considerato come nel ruolo di authenticated sistema.
Comportamento in corrispondenza: se il X-MS-API-ROLE valore dell'intestazione corrisponde a un ruolo nell'attestazione del roles token JWT, il contesto dell'utente viene impostato su tale ruolo a scopo di autorizzazione.
Comportamento in caso di mancata corrispondenza: se il X-MS-API-ROLE valore dell'intestazione non corrisponde ad alcun ruolo nell'attestazione roles , la richiesta viene rifiutata con un 403 Forbidden codice di stato. In questo modo, un utente non può richiedere un ruolo a cui non è stato assegnato.

Simulatore (provider di autenticazione)

Questo provider è progettato per semplificare per gli sviluppatori di testare la configurazione, in particolare authorization i criteri, senza dover configurare un provider di autenticazione completo come Entra Identity o EasyAuth. Simula un authenticated utente.

Il Simulator provider non usa token JWT. L'autenticazione viene simulata. Quando si usa questo provider, tutte le richieste vengono considerate come se provenissero da un utente autenticato.

Informazioni sull'intestazione diAPI-ROLE X-MS

Ruolo e comportamento: l'intestazione X-MS-API-ROLE è l'unico modo per specificare un ruolo quando si usa .Simulator Poiché non è presente alcun token con un elenco di ruoli, il sistema considera implicitamente attendibile il ruolo inviato in questa intestazione.
È obbligatorio?: No.
Comportamento in assenza: se l'intestazione X-MS-API-ROLE è assente, la richiesta viene elaborata nel contesto del ruolo di authenticated sistema.
Comportamento in presenza: se l'intestazione X-MS-API-ROLE è presente, la richiesta viene elaborata nel contesto del ruolo specificato nel valore dell'intestazione. Non esiste alcuna convalida rispetto a un elenco di attestazioni, quindi lo sviluppatore può simulare qualsiasi ruolo necessario per testare i criteri.

Simulatore in produzione

authentication.provider Se è impostato su Simulator mentre runtime.host.mode è production, il generatore di API dati non verrà avviato.

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

JWT (runtime host di autenticazione)

Parent	Property	Type	Required	Default
`runtime.host.authentication`	`jwt`	object	❌ No	-

Configurazione JWT (Global JSON Web Token).

Diagramma del supporto dei token Web JSON in Generatore API dati.

Proprietà annidate

Parent	Property	Type	Required	Default
`runtime.host.authentication.jwt`	`audience`	string	❌ No	None
`runtime.host.authentication.jwt`	`issuer`	string	❌ No	None

Format

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

Paginazione (runtime)

Parent	Property	Type	Required	Default
`runtime`	`pagination`	object	❌ No	-

Limiti di paginazione globali per gli endpoint REST e GraphQL.

Proprietà annidate

Parent	Property	Type	Required	Default
`runtime.pagination`	`max-page-size`	int	❌ No	100,000
`runtime.pagination`	`default-page-size`	int	❌ No	100
`runtime.pagination`	`next-link-relative`	boolean	❌ No	`false`

Valori supportati max-page-size

Value	Result
`integer`	È supportato qualsiasi numero intero positivo a 32 bit.
`0`	Non supportato.
`-1`	Il valore predefinito è il valore massimo supportato.
`< -1`	Non supportato.

Valori supportati per le dimensioni predefinite della pagina

Value	Result
`integer`	Qualsiasi numero intero positivo minore del `max-page-size`corrente.
`0`	Non supportato.
`-1`	Il valore predefinito è l'impostazione `max-page-size` corrente.
`< -1`	Non supportato.

Comportamento relativo al collegamento successivo

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

Value	Example
`false` (impostazione predefinita)	`"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 il valore è maggiore di max-page-size, i risultati vengono limitati a max-page-size.

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

Cache (runtime)

Parent	Property	Type	Required	Default
`runtime`	`cache`	object	❌ No	-

Configurazione della Cache globale.

Proprietà annidate

Parent	Property	Type	Required	Default
`runtime.cache`	`enabled`	boolean	❌ No	False
`runtime.cache`	`ttl-seconds`	integer	❌ No	5

Tip

Per impostazione predefinita, la proprietà a livello cache.ttl-seconds di entità corrisponde a questo valore globale.

Format

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

Important

Se global enabled è false, il livello enabled di entità individuale non è rilevante.

Telemetria (runtime)

Parent	Property	Type	Required	Default
`runtime`	`telemetry`	object	❌ No	-

Configurazione della telemetria globale.

Proprietà annidate

Parent	Property	Type	Required	Default
`runtime.telemetry`	`log-level`	dictionary	❌ No	None
`runtime.telemetry`	`application-insights`	object	❌ No	-
`runtime.telemetry`	`open-telemetry`	object	❌ No	-

Configura il livello di dettaglio della registrazione per ogni spazio dei nomi. Ciò 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"
      }
    }
  }
}

Tip

log-level può essere ricaricato a caldo sia nello sviluppo che nella produzione. È attualmente l'unica proprietà che supporta il ricaricamento rapido nell'ambiente di produzione.

Example

{
  "runtime": {
    "telemetry": {
      "log-level": {
        "Azure.DataApiBuilder.Core.Configurations.RuntimeConfigValidator": "debug",
        "Azure.DataApiBuilder.Core": "information",
        "default": "warning"
      }
    }
  }
}

Application Insights (telemetria)

Parent	Property	Type	Required	Default
`runtime.telemetry`	`application-insights`	object	❌ No	-

Configura la registrazione in Application Insights.

Proprietà annidate

Parent	Property	Type	Required	Default
`runtime.telemetry.application-insights`	`enabled`	boolean	❌ No	False
`runtime.telemetry.application-insights`	`connection-string`	string	✔️ Sì	None

Format

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

OpenTelemetry (telemetria)

Parent	Property	Type	Required	Default
`runtime.telemetry`	`open-telemetry`	object	❌ No	-

Configura la registrazione in Apri telemetria.

Proprietà annidate

Parent	Property	Type	Required	Default
`runtime.telemetry.open-telemetry`	`enabled`	boolean	❌ No	true
`runtime.telemetry.open-telemetry`	`endpoint`	string	✔️ Sì	None
`runtime.telemetry.open-telemetry`	`headers`	string	❌ No	None
`runtime.telemetry.open-telemetry`	`service-name`	string	❌ No	"dab"
`runtime.telemetry.open-telemetry`	`exporter-protocol`	enumerazione (`grpc` \| `httpprotobuf`)	❌ No	`grpc`

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.

Note

gRPC (4317) è più veloce e supporta lo streaming, ma richiede una configurazione maggiore. HTTP/protobuf (4318) è più semplice e più semplice da eseguire, ma meno efficiente.

Integrità (runtime)

Parent	Property	Type	Required	Default
`runtime`	`health`	object	❌ No	-

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

Proprietà annidate

Parent	Property	Type	Required	Default	Intervallo/Note
`runtime.health`	`enabled`	boolean	❌ No	`true`
`runtime.health`	`roles`	matrice di stringhe	✔️ Sì*	`null`	*Obbligatorio in modalità di produzione
`runtime.health`	`cache-ttl-seconds`	integer	❌ No	`5`	Min: 0
`runtime.health`	`max-query-parallelism`	integer	❌ No	`4`	Min: 1, Max: 8 (bloccato)

Comportamento in fase di sviluppo e produzione

Condition	Comportamento di sviluppo	Comportamento di produzione
`health.enabled` = falso	`403` stato	`403` stato
`health.enabled` = vero	Dipende dal ruolo	Dipende dal ruolo
`roles` omesso o `null`	Integrità visualizzata	`403` stato
ruolo corrente non in `roles`	`403` stato	`403` stato
ruolo corrente in `roles`	Integrità visualizzata	Integrità visualizzata
`roles` Include `anonymous`	Integrità visualizzata	Integrità visualizzata

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 è false, il livello enabled di entità individuale non è rilevante.

Example

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

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-09-24

Condividi tramite

Runtime

Impostazioni di paginazione

Impostazioni REST

Impostazioni di GraphQL

Impostazioni host

Impostazioni CORS

Impostazioni di autenticazione

Impostazioni della cache

Impostazioni di telemetria

Panoramica del formato

Modalità (runtime host)

Comportamento di sviluppo

Format

Dimensioni massime della risposta (runtime host)

Format

GraphQL (runtime)

Proprietà annidate

Note delle proprietà

Format

Esempio: più mutazioni

REST (tempo di esecuzione)

Proprietà annidate

Note delle proprietà

Format

Esempio: request-body-strict

Comportamento di inserimento quando request-body-strict = false

Aggiornare il comportamento quando request-body-strict = false

CORS (runtime host)

Proprietà annidate

Format

Provider (runtime host di autenticazione)

Solo anonimo (provider di autenticazione)

StaticWebApps (provider di autenticazione) [deprecato]

AppService (provider di autenticazione)

Informazioni sull'intestazione diAPI-ROLE X-MS

EntraId (provider di autenticazione)

Informazioni sull'intestazione diAPI-ROLE X-MS

Personalizzato (provider di autenticazione)

Informazioni sull'intestazione diAPI-ROLE X-MS

Simulatore (provider di autenticazione)

Informazioni sull'intestazione diAPI-ROLE X-MS

Simulatore in produzione

JWT (runtime host di autenticazione)

Proprietà annidate

Format

Paginazione (runtime)

Proprietà annidate

Valori supportati max-page-size

Valori supportati per le dimensioni predefinite della pagina

Comportamento relativo al collegamento successivo

Format

Esempio: paging in REST

Esempio: Paging in GraphQL

Esempio: accesso alle max-page-size richieste

Cache (runtime)

Proprietà annidate

Format

Telemetria (runtime)

Proprietà annidate

Format

Example

Application Insights (telemetria)

Proprietà annidate

Format

OpenTelemetry (telemetria)

Proprietà annidate

Format

Example

Integrità (runtime)

Proprietà annidate

Comportamento in fase di sviluppo e produzione

Format

Example

Commenti e suggerimenti

Risorse aggiuntive

Comportamento di inserimento quando `request-body-strict = false`

Aggiornare il comportamento quando `request-body-strict = false`

Esempio: accesso alle `max-page-size` richieste