Sdílet prostřednictvím

Runtime

Nastavení konfigurace, která určují chování modulu runtime.

Nastavení stránkování

Property Default Description
velikost stránky runtime.pagination.max Definuje maximální počet záznamů na stránku.
runtime.pagination.default-page-size Nastaví výchozí záznamy na odpověď.

Nastavení REST

Property Default Description
runtime.rest.path "/api" Základní cesta pro koncové body REST
runtime.rest.enabled true Povolení nebo zakázání požadavků REST pro všechny entity
runtime.rest.request-body-strict true Zakáže nadbytečná pole v textu požadavku, pokud je true.

Nastavení GraphQL

Property Default Description
runtime.graphql.allow-introspection true Umožňuje dotazování základního schématu GraphQL.
runtime.graphql.path "/graphql" Základní cesta pro koncový bod GraphQL
runtime.graphql.enabled true Povolí nebo zakáže požadavky GraphQL pro všechny entity.
runtime.graphql.depth-limit null Maximální povolená hloubka dotazu GraphQL
runtime.graphql.multiple-muts.create.enabled false Umožňuje vícenásobné vytváření mutací pro všechny entity.

Nastavení hostitele

Property Default Description
runtime.host.max-response-size-mb 158 Maximální velikost (MB) odpovědi databáze povolená v jednom výsledku
runtime.host.mode "production" Spuštěný režim; "production" nebo "development"

Nastavení CORS

Property Default Description
runtime.host.cors.origins [] Povolené zdroje CORS
runtime.host.cors.allow-credentials false Nastaví hodnotu pro hlavičku Access-Control-Allow-Credentials.

Nastavení ověřování

Property Default Description
runtime.host.authentication.provider null Zprostředkovatel ověřování
runtime.host.authentication.jwt.audience null Cílová skupina JWT
runtime.host.authentication.jwt.issuer null Vystavitel JWT

Nastavení mezipaměti

Property Default Description
runtime.cache.enabled false Umožňuje globální ukládání odpovědí do mezipaměti.
runtime.cache.ttl-seconds 5 Doba života (sekundy) pro globální mezipaměť

Nastavení telemetrie

Property Default Description
runtime.telemetry.application-insights.connection-string null Připojovací řetězec Application Insights
runtime.telemetry.application-insights.enabled false Povolí nebo zakáže telemetrii Application Insights.
runtime.telemetry.open-telemetry.endpoint null Adresa URL kolektoru OpenTelemetry
runtime.telemetry.open-telemetry.headers {} Hlavičky exportu OpenTelemetry
runtime.telemetry.open-telemetry.service-name "dab" Název služby OpenTelemetry
runtime.telemetry.open-telemetry.export-protocol "grpc" Protokol OpenTelemetry ("grpc" nebo "httpprotobuf")
runtime.telemetry.open-telemetry.enabled true Povolí nebo zakáže OpenTelemetry.
runtime.telemetry.log-level.namespace null Přepsání na úrovni protokolu specifické pro obor názvů
runtime.health.enabled true Povolí nebo zakáže koncový bod kontroly stavu globálně.
runtime.health.roles null Povolené role pro komplexní koncový bod stavu
runtime.health.cache-ttl-seconds 5 Doba života (sekundy) pro položku mezipaměti sestavy kontroly stavu
runtime.health.max-dotazování-paralelismus 4 Maximální počet souběžných dotazů na kontrolu stavu (rozsah: 1–8)

Přehled formátu

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

Režim (modul runtime hostitele)

Parent Property Typ Required Default
runtime host enum (production | development) ❌ Ne production

Chování vývoje

  • Povoleno Nitro (dříve Banana Cake Pop) pro testování GraphQL
  • Povolené uživatelské rozhraní Swagger pro testování REST
  • Povolené anonymní kontroly stavu
  • Zvýšená úroveň podrobností protokolování (ladění)

Format

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

Maximální velikost odpovědi (modul runtime hostitele)

Parent Property Typ Required Default
runtime.host max-response-size-mb integer ❌ Ne 158

Nastaví maximální velikost (v megabajtech) pro libovolný daný výsledek. Vzhledem k tomu, že velké odpovědi můžou systém zatížit, max-response-size-mb zakládá celkovou velikost (liší se od počtu řádků), aby se zabránilo přetížení, což je zejména u velkých sloupců, jako je text nebo JSON.

Value Result
nenastaveno Použít výchozí
null Použít výchozí
integer Jakékoli kladné 32bitové celé číslo
<= 0 Není podporováno

Format

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

GraphQL (modul runtime)

Parent Property Typ Required Default
runtime graphql objekt ❌ Ne -

Globální konfigurace GraphQL

Vnořené vlastnosti

Parent Property Typ Required Default
runtime.graphql enabled boolean ❌ Ne None
runtime.graphql path řetězec ❌ Ne "/graphql"
runtime.graphql depth-limit integer ❌ Ne Žádné (neomezené)
runtime.graphql allow-introspection boolean ❌ Ne True
runtime.graphql multiple-mutations.create.enabled boolean ❌ Ne False

Poznámky k vlastnostem

  • Pro vlastnost nejsou povoleny path dílčí cesty.
  • Slouží depth-limit k omezení vnořených dotazů.
  • Nastavte allow-introspection na false skrytí schématu GraphQL.
  • Slouží multiple-mutations k vložení více entit do jedné mutaci.

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

Příklad: více mutací

Configuration

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

GraphQL mutací

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 (modul runtime)

Parent Property Typ Required Default
runtime rest objekt ❌ Ne -

Globální konfigurace REST.

Vnořené vlastnosti

Parent Property Typ Required Default
runtime.rest enabled boolean ❌ Ne None
runtime.rest path řetězec ❌ Ne "/api"
runtime.rest request-body-strict boolean ❌ Ne True

Poznámky k vlastnostem

  • Pokud je enabledglobální false hodnota , na jednotlivých úrovních enabled entit nezáleží.
  • Vlastnost path nepodporuje hodnoty dílčích cest, jako je /api/data.
  • request-body-strict byla zavedena, aby se zjednodušily objekty POCO .NET.
request-body-strict Behavior
true Nadbytečná pole v textu požadavku způsobují BadRequest výjimku.
false Další pole v textu požadavku se ignorují.

Format

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

Note

Při nasazování Tvůrce rozhraní Data API pomocí static Web Apps (Preview) služba Azure automaticky vloží jinou dílčí cestu /data-api k adrese URL. Toto chování zajišťuje kompatibilitu se stávajícími funkcemi statické webové aplikace. Výsledný koncový bod by byl /data-api/api/<entity>. Tato poznámka je relevantní jenom pro Static Web Apps.

Příklad: request-body-strict

  • Sloupce s default() hodnotou jsou ignorovány pouze v INSERT případech, kdy je nulljejich hodnota v datové části . V důsledku toho INSERT operace do default() sloupců, pokud request-body-strict je true, nemohou vést k explicitním null hodnotám. K tomu UPDATE je potřeba provést operaci.
  • Sloupce s default() hodnotou datové části se neignorují UPDATE bez ohledu na hodnotu datové části.
  • Počítané sloupce se vždy ignorují.
  • Automaticky generované sloupce jsou vždy ignorovány.

Ukázková tabulka

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

Obsah žádosti

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

Vložit chování při 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.

Odpověďové zatížení

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

Aktualizovat chování při request-body-strict = false

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

Odpověďové zatížení

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

CORS (modul runtime hostitele)

Parent Property Typ Required Default
runtime.host cors objekt ❌ Ne -

Globální konfigurace CORS

Tip

CORS je zkratka pro sdílení prostředků mezi zdroji. Jedná se o funkci zabezpečení prohlížeče, která určuje, jestli webové stránky můžou vyhovět jiné doméně, než která je obsluhovala.

Vnořené vlastnosti

Parent Property Typ Required Default
runtime.host.cors allow-credentials boolean ❌ Ne False
runtime.host.cors origins Řetězcové pole ❌ Ne None

Note

Vlastnost allow-credentials nastaví hlavičku Access-Control-Allow-Credentials CORS.

Format

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

Note

Zástupný znak * je platný jako hodnota pro origins.

Zprostředkovatel (modul runtime hostitele ověřování)

Parent Property Typ Required Default
runtime.host.authentication provider enum (AppServiceSimulator | | EntraId | Custom) ❌ Ne AppService

Definuje metodu ověřování používanou tvůrcem rozhraní DATA API.

Pouze anonymní (zprostředkovatel ověřování)

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

Pokud se celý authentication oddíl ze souboru dab-config.json vynechá, nepoužije se žádný zprostředkovatel ověřování. V tomto případě tvůrce rozhraní DATA API funguje v režimu bez ověřování. V tomto režimu DAB nevyhledává žádné tokeny ani Authorization hlavičky. Hlavička X-MS-API-ROLE je v této konfiguraci ignorována.

[! Poznámka] Každý požadavek, který přichází do modulu, je automaticky a okamžitě přiřazena systémové role anonymous. Řízení přístupu se pak zpracovává výhradně oprávněními, která definujete pro každou entitu.

Příklad oprávnění entity.

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

V tomto příkladu se vzhledem k tomu, že není nakonfigurovaný žádný authentication zprostředkovatel, všechny příchozí požadavky se automaticky považují za uživatele anonymous . Pole permissions entity Book explicitně uděluje anonymous roli schopnost provádět read operace. Jakékoli pokusy o provedení jiných akcí (například create, update) deletenebo přístupu k jiným entitěm, které nejsou nakonfigurované pro anonymous přístup, se odepře.

StaticWebApps (auth provider) [zastaralé]

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

Tento poskytovatel je zastaralý, protože funkce Data Connections Static Web Apps ve verzi Preview byla vyřazena v listopadu 2025. I když zůstává funkční, byl navržen pro starší implementaci ověřování ve službě Azure Static Web Apps. Vývojáři by měli na poskytovatele migrovat AppService , aby měli lepší dlouhodobou podporu a konzistenci s širší platformou Azure Easy Auth.

[! Poznámka] Migrace není tak jednoduchá jako změna názvu zprostředkovatele v konfiguračním souboru. Poskytovatelé StaticWebApps očekávají AppService různé struktury JSON v hlavičce x-ms-client-principal pro zpracování rolí.

AppService (zprostředkovatel ověřování)

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

Tento poskytovatel je určený pro aplikace hostované ve službě Azure App Service, jako je Azure Container Apps. Hostitelské prostředí Azure zpracovává ověřování a pak předává informace o identitě uživatele do aplikace prostřednictvím hlaviček požadavků. Je určená pro vývojáře, kteří chtějí jednoduché, zastaralé řešení ověřování spravované platformou Azure.

Tento zprostředkovatel nepoužívá token JWT z hlavičky Authorization . Spoléhá na speciální hlavičku vloženou X-MS-CLIENT-PRINCIPALplatformou služby App Service. Tato hlavička obsahuje objekt JSON kódovaný v base64 s podrobnostmi o identitě uživatele.

Anonymní: Pokud AppService je poskytovatel nakonfigurovaný, ale požadavek přijde bez X-MS-CLIENT-PRINCIPAL hlavičky, požadavek se přiřadí systémové roli anonymous.

Dekódovaný JSON z X-MS-CLIENT-PRINCIPAL hlavičky obvykle vypadá takto:

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

Role jsou obsaženy v claims poli.

O hlavičce X-MS-API-ROLE

  • Role a chování: Hlavička X-MS-API-ROLE slouží k určení role, kterou chce uživatel pro aktuální požadavek předpokládat. Hodnota této hlavičky se musí shodovat s jednou z hodnot rolí nalezených v claims poli objektu X-MS-CLIENT-PRINCIPAL .
  • Je to povinné?: Ne. Pokud hlavička X-MS-API-ROLE chybí, požadavek se zpracuje v kontextu authenticated systémové role. To znamená, že uživatel je rozpoznán jako přihlášený, ale ne jako žádná konkrétní role definovaná aplikací z tokenu.
  • Chování při porovnávání: Pokud je hlavička X-MS-API-ROLE zadaná a její hodnota odpovídá roli v objektu zabezpečení claimsklienta, uživatel předpokládá, že role pro požadavek.
  • Chování při neshodě: Pokud je hlavička X-MS-API-ROLE zadaná, ale hodnota neodpovídá žádné roli v objektu zabezpečení klienta, požadavek se odmítne se stavovým kódem 403 Forbidden . Tím se zajistí, že uživatel nemůže deklarovat roli, kterou ještě nepřiřadil.

EntraId (zprostředkovatel ověřování)

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

Tento zprostředkovatel zabezpečuje koncové body pomocí identit uživatelů a aplikací v Microsoft Entra. Je ideální pro jakoukoli službu, ve které uživatelé nebo jiné služby potřebují zabezpečený přístup v rámci tenanta Entra.

[! POZNÁMKA] EntraId Zprostředkovatel byl dříve pojmenován AzureAd. Starý název stále funguje, ale vývojářům se doporučuje migrovat své konfigurace z AzureAd do EntraId.

Tento poskytovatel očekává standardní token JWT Bearer v Authorization hlavičce vydané společností Microsoft Entra. Token musí být nakonfigurovaný pro konkrétní aplikaci (pomocí audience deklarace identity). Očekává se, že role uživatele nebo instančního objektu budou v deklaraci identity v tokenu. Kód ve výchozím nastavení hledá roles deklaraci identity.

Anonymní: Pokud EntraId je poskytovatel nakonfigurovaný, ale požadavek přijde bez Authorization hlavičky, požadavek se přiřadí systémové roli anonymous.

Dekódovaná datová část JWT může vypadat takto:

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

O hlavičce X-MS-API-ROLE

  • Role a chování: Hlavička X-MS-API-ROLE slouží k určení role, kterou chce uživatel pro požadavek předpokládat. Hodnota této hlavičky se musí shodovat s jednou z hodnot rolí nalezených v roles deklaraci tokenu JWT.
  • Je to povinné?: Ne. Pokud hlavička X-MS-API-ROLE chybí, požadavek se zpracuje v kontextu authenticated systémové role. To znamená, že uživatel je rozpoznán jako přihlášený, ale ne jako žádná konkrétní role definovaná aplikací z tokenu.
  • Chování při porovnávání: Pokud je hlavička X-MS-API-ROLE zadaná a odpovídá roli v roles deklaraci identity, kontext uživatele se nastaví na tuto roli.
  • Chování při neshodě: Pokud je hlavička X-MS-API-ROLE zadaná, ale její hodnota neodpovídá žádné roli v roles deklaraci identity, požadavek se odmítne se stavovým kódem 403 Forbidden . Tím se zajistí, že uživatel nemůže deklarovat roli, kterou ještě nepřiřadil.

Vlastní (zprostředkovatel ověřování)

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

Tento zprostředkovatel je určený pro vývojáře, kteří chtějí integrovat tvůrce rozhraní Data API se zprostředkovatelem identity třetí strany (například Auth0, Okta nebo vlastním serverem identity), který vydává JWT. Poskytuje flexibilitu při konfiguraci očekávaných audience tokenů a issuer tokenů.

Custom Zprostředkovatel očekává v Authorization hlavičce standardní token JWT Bearer. Klíčovým rozdílem od EntraId poskytovatele je, že nakonfigurujete platný issuer a audience v konfiguračním souboru tvůrce rozhraní Data API. Zprostředkovatel ověří token tím, že zkontroluje, jestli ho důvěryhodná autorita vydala. Očekává se, že role uživatele budou v roles deklarací identity v datové části JWT.

[! POZNÁMKA] V některých případech musí vývojáři v závislosti na zprostředkovateli identity třetí strany převést strukturu JWT tak, aby odpovídaly struktuře očekávané tvůrcem rozhraní Data API (viz níže).

Anonymní: Pokud Custom je poskytovatel nakonfigurovaný, ale požadavek přijde bez Authorization hlavičky, požadavek se přiřadí systémové roli anonymous.

Dekódovaná datová část JWT pro custom poskytovatele může vypadat takto:

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

O hlavičce X-MS-API-ROLE

  • Role a chování: Hlavička X-MS-API-ROLE funguje přesně stejně jako u EntraId zprostředkovatele. Umožňuje uživateli vybrat jednu ze svých přiřazených rolí. Hodnota této hlavičky musí odpovídat jedné z rolí z roles deklarace identity ve vlastním tokenu JWT.
  • Je to povinné?: Ne. Pokud hlavička X-MS-API-ROLE chybí, uživatel se považuje za roli authenticated systému.
  • Chování při porovnávání: Pokud X-MS-API-ROLE hodnota hlavičky odpovídá roli v deklaraci identity JWT roles , kontext uživatele se nastaví na tuto roli pro účely autorizace.
  • Chování při neshodě: Pokud X-MS-API-ROLE hodnota hlavičky neodpovídá žádné roli v roles deklaraci identity, požadavek se odmítne se stavovým kódem 403 Forbidden . Tím se zajistí, že uživatel nemůže deklarovat roli, kterou ještě nepřiřadil.

Simulátor (zprostředkovatel ověřování)

Tento poskytovatel je navržený tak, aby vývojářům usnadnil testování konfigurace, zejména authorization zásad, aniž by museli nastavovat úplného zprostředkovatele ověřování, jako je Entra Identity nebo EasyAuth. Simuluje authenticated uživatele.

Poskytovatel Simulator nepoužívá tokeny JWT. Ověřování se simuluje. Při použití tohoto poskytovatele se všechny požadavky považují za příchozí od ověřeného uživatele.

O hlavičce X-MS-API-ROLE

  • Role a chování: Záhlaví X-MS-API-ROLE je jediný způsob, jak určit roli při použití Simulator. Vzhledem k tomu, že neexistuje žádný token se seznamem rolí, systém implicitně důvěřuje roli poslané v této hlavičce.
  • Je to povinné?: Ne.
  • Chování při absenci: Pokud hlavička X-MS-API-ROLE chybí, požadavek se zpracuje v kontextu authenticated systémové role.
  • Chování při přítomnosti: Pokud je hlavička X-MS-API-ROLE přítomná, požadavek se zpracuje v kontextu role zadané v hodnotě hlavičky. V seznamu deklarací identity není žádné ověření, takže vývojář může simulovat libovolnou roli, kterou potřebují k otestování zásad.

Simulátor v produkčním prostředí

Pokud je nastavená authentication.providerSimulator na dobu, runtime.host.mode která je productionnastavená, tvůrce rozhraní DATA API se nespustí.

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

JWT (modul runtime hostitele ověřování)

Parent Property Typ Required Default
runtime.host.authentication jwt objekt ❌ Ne -

Globální konfigurace webového tokenu JSON (JWT).

Diagram podpory webových tokenů JSON v Tvůrci rozhraní Data API

Vnořené vlastnosti

Parent Property Typ Required Default
runtime.host.authentication.jwt audience řetězec ❌ Ne None
runtime.host.authentication.jwt issuer řetězec ❌ Ne None

Format

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

Stránkování (modul runtime)

Parent Property Typ Required Default
runtime pagination objekt ❌ Ne -

Globální limity stránkování pro koncové body REST a GraphQL

Vnořené vlastnosti

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

Maximální podporovaná velikost stránky

Value Result
integer Podporuje se jakékoli kladné 32bitové celé číslo.
0 Není podporováno.
-1 Výchozí hodnota je maximální podporovaná hodnota.
< -1 Není podporováno.

Podporované hodnoty výchozí velikosti stránky

Value Result
integer Jakékoli kladné celé číslo menší než aktuální max-page-size.
0 Není podporováno.
-1 Výchozí hodnota je aktuální nastavení max-page-size.
< -1 Není podporováno.

Pokud next-link-relative je tomu tak true, hodnoty stránkování nextLink používají relativní adresy URL místo absolutních adres URL.

Value Example
false (výchozí) "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

Pokud je hodnota větší než max-page-size, výsledky jsou omezeny na max-page-sizehodnotu .

Příklad: Stránkování v REST

Request

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

Odpověďové zatížení

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

Další stránka žádosti

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

Příklad: Stránkování v GraphQL

Datová část požadavku (dotaz)

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

Odpověďové zatížení

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

Další stránka žádosti

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

Příklad: Přístup k žádostem max-page-size

max-page-size Použijte hodnotu nastavením $limit (REST) nebo first (GraphQL) na -1.

REST

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

GraphQL

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

Mezipaměť (modul runtime)

Parent Property Typ Required Default
runtime cache objekt ❌ Ne -

Konfigurace globální mezipaměti.

Vnořené vlastnosti

Parent Property Typ Required Default
runtime.cache enabled boolean ❌ Ne False
runtime.cache ttl-seconds integer ❌ Ne 5

Tip

Vlastnost na úrovni cache.ttl-seconds entity se ve výchozím nastavení nastaví na tuto globální hodnotu.

Format

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

Important

Pokud je enabledglobální false hodnota , na jednotlivých úrovních enabled entit nezáleží.

Telemetrie (modul runtime)

Parent Property Typ Required Default
runtime telemetry objekt ❌ Ne -

Globální konfigurace telemetrie

Vnořené vlastnosti

Parent Property Typ Required Default
runtime.telemetry log-level dictionary ❌ Ne None
runtime.telemetry application-insights objekt ❌ Ne -
runtime.telemetry open-telemetry objekt ❌ Ne -

Konfiguruje úroveň podrobností protokolování pro každý obor názvů. To se řídí standardními konvencemi protokolování .NET a umožňuje podrobné řízení, i když předpokládá určitou znalost interních prvků Tvůrce rozhraní Data API. Tvůrce rozhraní Data API je open source: https://aka.ms/dab

Format

{
  "runtime": {
    "telemetry": {
      "log-level": {
        "namespace": "log-level",
        "namespace": "log-level"
      }
    }
  }
}

Tip

log-level lze znovu načíst za provozu ve vývoji i v produkčním prostředí. V současné době je to jediná vlastnost, která podporuje opětovné načítání za provozu v produkčním prostředí.

Example

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

Application Insights (telemetrie)

Parent Property Typ Required Default
runtime.telemetry application-insights objekt ❌ Ne -

Konfiguruje protokolování do Application Insights.

Vnořené vlastnosti

Parent Property Typ Required Default
runtime.telemetry.application-insights enabled boolean ❌ Ne False
runtime.telemetry.application-insights connection-string řetězec ✔️ Ano None

Format

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

OpenTelemetry (telemetrie)

Parent Property Typ Required Default
runtime.telemetry open-telemetry objekt ❌ Ne -

Konfiguruje protokolování pro otevření telemetrie.

Vnořené vlastnosti

Parent Property Typ Required Default
runtime.telemetry.open-telemetry enabled boolean ❌ Ne true
runtime.telemetry.open-telemetry endpoint řetězec ✔️ Ano None
runtime.telemetry.open-telemetry headers řetězec ❌ Ne None
runtime.telemetry.open-telemetry service-name řetězec ❌ Ne "dab"
runtime.telemetry.open-telemetry exporter-protocol enum (grpc | httpprotobuf) ❌ Ne grpc

Více záhlaví jsou , oddělená čárkami.

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

Přečtěte si další informace o OTEL_EXPORTER_OTLP_HEADERS.

Note

GRPC (4317) je rychlejší a podporuje streamování, ale vyžaduje více nastavení. HTTP/protobuf (4318) je jednodušší a jednodušší ladit, ale méně efektivní.

Stav (modul runtime)

Parent Property Typ Required Default
runtime health objekt ❌ Ne -

Konfigurace koncového bodu globální kontroly stavu (/health).

Vnořené vlastnosti

Parent Property Typ Required Default Rozsah/poznámky
runtime.health enabled boolean ❌ Ne true
runtime.health roles Řetězcové pole ✔️ Ano* null *Požadováno v produkčním režimu
runtime.health cache-ttl-seconds integer ❌ Ne 5 Min: 0
runtime.health max-query-parallelism integer ❌ Ne 4 Min: 1, Max: 8 (upínací)

Chování při vývoji vs. produkčního prostředí

Condition Chování při vývoji Chování v produkčním prostředí
health.enabled = nepravda 403 stav 403 stav
health.enabled = pravda Závisí na roli. Závisí na roli.
roles vynecháno nebo null Zobrazený stav 403 stav
aktuální role není v roles 403 stav 403 stav
aktuální role v roles Zobrazený stav Zobrazený stav
roles zahrnuje anonymous Zobrazený stav Zobrazený stav

Format

{
  "health": {
    "enabled": <true> (default) | <false>,
    "roles": [ <string> ], // required in production
    "cache-ttl-seconds": <integer; default: 5>,
    "max-query-parallelism": <integer; default: 4>
  }
}

Note

Pokud je enabledglobální false hodnota , na jednotlivých úrovních enabled entit nezáleží.

Example

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