Condividi tramite


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

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)

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 None

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

Riepilogo provider

Provider Caso d'uso Origine identità Guida pratica
(omesso) Accesso anonimo None
AppService App ospitate in Azure (EasyAuth) X-MS-CLIENT-PRINCIPAL Intestazione Configurare l'autenticazione del servizio app
EntraID Microsoft Entra ID (Azure AD) Token di connessione JWT Configurare l'autenticazione con ID Entra
Custom Provider di identità di terze parti (Okta, Auth0) Token di connessione JWT Configurare l'autenticazione JWT personalizzata
Simulator Solo test locali Simulato Configurare l'autenticazione del simulatore

Note

Il EntraId provider era precedentemente denominato AzureAd. Il nome precedente funziona ancora per la compatibilità.

Solo anonimo (nessun provider)

Quando la authentication sezione viene omessa, DAB funziona in modalità anonima. A tutte le richieste viene assegnato il ruolo di Anonymous sistema.

{
  "host": {
    // authentication section omitted
  }
}

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

Important

Il Simulator provider funziona solo quando runtime.host.mode è development. L'avvio di DAB non riesce se il simulatore è configurato in modalità di produzione.

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 Autorizzazione e ruoli.

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-sizecorrente.
0 Non supportato.
-1 Il valore predefinito è l'impostazione max-page-size corrente.
< -1 Non supportato.

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 più passaggi di configurazione. 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
  }
}