Udostępnij za pomocą

Runtime

Ustawienia konfiguracji określające zachowanie środowiska uruchomieniowego.

Ustawienia stronicowania

Property Default Description
runtime.pagination.max rozmiar strony Definiuje maksymalną liczbę rekordów na stronę
runtime.pagination.default-page-size Ustawia domyślne rekordy na odpowiedź

Ustawienia REST

Property Default Description
runtime.rest.path "/api" Ścieżka podstawowa dla punktów końcowych REST
runtime.rest.enabled true Umożliwia włączanie lub wyłączanie żądań REST dla wszystkich jednostek
runtime.rest.request-body-strict true Nie zezwala na nadmiarowe pola w treści żądania, gdy jest to prawda

Ustawienia języka GraphQL

Property Default Description
runtime.graphql.allow-introspection true Umożliwia wykonywanie zapytań względem bazowego schematu GraphQL
runtime.graphql.path "/graphql" Ścieżka podstawowa punktu końcowego GraphQL
runtime.graphql.enabled true Umożliwia włączanie lub wyłączanie żądań GraphQL dla wszystkich jednostek
runtime.graphql.depth-limit null Maksymalna dozwolona głębokość zapytania GraphQL
runtime.graphql.multiple-mutacje.create.enabled false Umożliwia tworzenie mutacji dla wszystkich jednostek

Ustawienia hosta

Property Default Description
runtime.host.max-response-size-mb 158 Maksymalny rozmiar (MB) odpowiedzi bazy danych dozwolony w jednym wyniku
runtime.host.mode "production" Tryb działania; "production" lub "development"

Ustawienia mechanizmu CORS

Property Default Description
runtime.host.cors.origins [] Dozwolone źródła mechanizmu CORS
runtime.host.cors.allow-credentials false Ustawia wartość nagłówka Access-Control-Allow-Credentials

Ustawienia uwierzytelniania

Property Default Description
runtime.host.authentication.provider null Dostawca uwierzytelniania
runtime.host.authentication.jwt.audience null Odbiorcy JWT
runtime.host.authentication.jwt.issuer null Wystawca JWT

Ustawienia pamięci podręcznej

Property Default Description
runtime.cache.enabled false Umożliwia buforowanie odpowiedzi globalnie
runtime.cache.ttl-seconds 5 Czas wygaśnięcia (w sekundach) dla globalnej pamięci podręcznej

Ustawienia telemetrii

Property Default Description
runtime.telemetry.application-insights.connection-string null Parametry połączenia usługi Application Insights
runtime.telemetry.application-insights.enabled false Włącza lub wyłącza telemetrię usługi Application Insights
runtime.telemetry.open-telemetry.endpoint null Adres URL modułu zbierającego OpenTelemetry
runtime.telemetry.open-telemetry.headers {} Nagłówki eksportu OpenTelemetry
runtime.telemetry.open-telemetry.service-name "dab" Nazwa usługi OpenTelemetry
runtime.telemetry.open-telemetry.exporter-protocol "grpc" Protokół OpenTelemetry ("grpc" lub "httpprotobuf")
runtime.telemetry.open-telemetry.enabled true Włącza lub wyłącza funkcję OpenTelemetry
runtime.telemetry.log-level.namespace null Zastępowanie poziomu dziennika specyficznego dla przestrzeni nazw
runtime.health.enabled true Włącza lub wyłącza globalny punkt końcowy sprawdzania kondycji
runtime.health.roles null Dozwolone role dla kompleksowego punktu końcowego kondycji
runtime.health.cache-ttl-s 5 Czas wygaśnięcia (w sekundach) dla wpisu pamięci podręcznej raportu kontroli kondycji
runtime.health.max równoległość zapytań 4 Maksymalna liczba współbieżnych zapytań dotyczących sprawdzania kondycji (zakres: 1–8)

Omówienie formatu

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

Tryb (środowisko uruchomieniowe hosta)

Parent Property Typ Required Default
runtime host wyliczenie (production | development) ❌ Nie production

Zachowanie programistyczne

  • Enabled Nitro (dawniej Banana Cake Pop) na potrzeby testowania GraphQL
  • Włączony interfejs użytkownika struktury Swagger na potrzeby testowania REST
  • Włączone anonimowe kontrole kondycji
  • Zwiększona szczegółowość rejestrowania (debugowanie)

Format

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

Maksymalny rozmiar odpowiedzi (środowisko uruchomieniowe hosta)

Parent Property Typ Required Default
runtime.host max-response-size-mb liczba całkowita ❌ Nie 158

Ustawia maksymalny rozmiar (w megabajtach) dla dowolnego wyniku. Ponieważ duże odpowiedzi mogą przeciążać system, max-response-size-mb powoduje ograniczenie całkowitego rozmiaru (innego niż liczba wierszy), aby zapobiec przeciążeniu, co jest szczególnie w przypadku dużych kolumn, takich jak tekst lub JSON.

Value Result
nie ustawiono Użyj wartości domyślnej
null Użyj wartości domyślnej
integer Dowolna dodatnia liczba całkowita 32-bitowa
<= 0 Niewspierane

Format

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

GraphQL (środowisko uruchomieniowe)

Parent Property Typ Required Default
runtime graphql obiekt ❌ Nie -

Konfiguracja globalnego języka GraphQL.

Właściwości zagnieżdżone

Parent Property Typ Required Default
runtime.graphql enabled boolean ❌ Nie None
runtime.graphql path ciąg ❌ Nie "/graphql"
runtime.graphql depth-limit liczba całkowita ❌ Nie Brak (nieograniczona)
runtime.graphql allow-introspection boolean ❌ Nie True
runtime.graphql multiple-mutations.create.enabled boolean ❌ Nie False

Uwagi dotyczące właściwości

  • Ścieżki podrzędne nie są dozwolone dla path właściwości .
  • Użyj depth-limit polecenia , aby ograniczyć zagnieżdżone zapytania.
  • Ustaw allow-introspection wartość na , aby false ukryć schemat GraphQL.
  • Służy multiple-mutations do wstawiania wielu jednostek w jednej mutacji.

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

Przykład: wiele mutacji

Configuration

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

Mutacja 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 (środowisko uruchomieniowe)

Parent Property Typ Required Default
runtime rest obiekt ❌ Nie -

Globalna konfiguracja REST.

Właściwości zagnieżdżone

Parent Property Typ Required Default
runtime.rest enabled boolean ❌ Nie None
runtime.rest path ciąg ❌ Nie "/api"
runtime.rest request-body-strict boolean ❌ Nie True

Uwagi dotyczące właściwości

  • Jeśli wartość globalna enabled to false, pojedynczy poziom enabled jednostki nie ma znaczenia.
  • Właściwość path nie obsługuje wartości podścieżki, takich jak /api/data.
  • request-body-strict wprowadzono w celu uproszczenia obiektów POCO platformy .NET.
request-body-strict Behavior
true Dodatkowe pola w treści żądania powodują BadRequest wyjątek.
false Dodatkowe pola w treści żądania są ignorowane.

Format

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

Note

Podczas wdrażania konstruktora interfejsu API danych przy użyciu usługi Static Web Apps (wersja zapoznawcza) usługa platformy Azure automatycznie wprowadza kolejną ścieżkę /data-api podrzędną do adresu URL. To zachowanie zapewnia zgodność z istniejącymi funkcjami statycznej aplikacji internetowej. Wynikowy punkt końcowy będzie /data-api/api/<entity>. Ta uwaga dotyczy tylko usługi Static Web Apps.

Przykład: żądanie-treść-ścisłe

  • Kolumny z wartością default() są ignorowane tylko wtedy INSERT , gdy ich wartość w ładunku to null. W związku INSERT z tym operacje w default() kolumnach, gdy request-body-strict ma wartość true, nie mogą powodować jawnych null wartości. W tym celu wymagana UPDATE jest operacja.
  • Kolumny z elementem default() nie są ignorowane UPDATE niezależnie od wartości ładunku.
  • Obliczone kolumny są zawsze ignorowane.
  • Kolumny generowane automatycznie są zawsze ignorowane.

Przykładowa tabela

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

Dane żądania

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

Wstaw zachowanie, gdy 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.

Ładunek danych odpowiedzi

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

Aktualizowanie zachowania w przypadku request-body-strict = false

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

Ładunek danych odpowiedzi

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

CORS (środowisko uruchomieniowe hosta)

Parent Property Typ Required Default
runtime.host cors obiekt ❌ Nie -

Globalna konfiguracja mechanizmu CORS.

Tip

CORS oznacza "Współużytkowanie zasobów między źródłami". Jest to funkcja zabezpieczeń przeglądarki kontrolująca, czy strony internetowe mogą wysyłać żądania do innej domeny niż ta, która je obsłużyła.

Właściwości zagnieżdżone

Parent Property Typ Required Default
runtime.host.cors allow-credentials boolean ❌ Nie False
runtime.host.cors origins tablica ciągów ❌ Nie None

Note

Właściwość allow-credentials ustawia Access-Control-Allow-Credentials nagłówek CORS.

Format

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

Note

Symbol wieloznaczny * jest prawidłowy jako wartość .origins

Dostawca (środowisko uruchomieniowe hosta uwierzytelniania)

Parent Property Typ Required Default
runtime.host.authentication provider wyliczenie (AppService | EntraId | Custom | Simulator) ❌ Nie AppService

Definiuje metodę uwierzytelniania używanego przez konstruktora interfejsu API danych.

Tylko anonimowy (dostawca uwierzytelniania)

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

Gdy cała authentication sekcja zostanie pominięta z pliku dab-config.json, nie jest używany żaden dostawca uwierzytelniania. W takim przypadku konstruktor interfejsu API danych działa w trybie "brak uwierzytelniania". W tym trybie daB nie szuka żadnych tokenów ani Authorization nagłówków. Nagłówek X-MS-API-ROLE jest również ignorowany w tej konfiguracji.

[! Uwaga] Każde żądanie wchodzące do aparatu jest automatycznie i natychmiast przypisane do roli systemu .anonymous Kontrola dostępu jest następnie obsługiwana wyłącznie przez uprawnienia zdefiniowane dla każdej jednostki.

Przykład uprawnień jednostki.

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

W tym przykładzie, ponieważ żaden dostawca nie authentication jest skonfigurowany, wszystkie żądania przychodzące są automatycznie uznawane za pochodzące od anonymous użytkownika. Tablica permissions dla Book jednostki jawnie przyznaje anonymous rolę do wykonywania read operacji. Każda próba wykonania innych akcji (takich jak create, update, delete) lub uzyskiwanie dostępu do innych jednostek, które nie zostały skonfigurowane na potrzeby anonymous dostępu, zostanie odrzucona.

StaticWebApps (dostawca uwierzytelniania) [przestarzałe]

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

Ten dostawca jest przestarzały, ponieważ funkcja Data Connections usługi Static Web Apps w wersji zapoznawczej została wycofana w listopadzie 2025 r. Mimo że pozostaje ona funkcjonalna, została zaprojektowana pod kątem starszej implementacji uwierzytelniania w usłudze Azure Static Web Apps. Deweloperzy powinni przeprowadzić migrację AppService do dostawcy, aby zapewnić lepszą długoterminową pomoc techniczną i spójność z szerszą platformą "Easy Auth" platformy Azure.

[! Uwaga] Migrowanie nie jest tak proste, jak zmiana nazwy dostawcy w pliku konfiguracji. Dostawcy StaticWebApps i AppService oczekują różnych struktur JSON w nagłówku x-ms-client-principal na potrzeby przetwarzania ról.

AppService (dostawca uwierzytelniania)

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

Ten dostawca jest przeznaczony dla aplikacji hostowanych w usłudze Azure App Service, takich jak Azure Container Apps. Środowisko hostingu platformy Azure obsługuje uwierzytelnianie, a następnie przekazuje informacje o tożsamości użytkownika do aplikacji za pośrednictwem nagłówków żądań. Jest ona przeznaczona dla deweloperów, którzy chcą prostego, gotowego rozwiązania do uwierzytelniania zarządzanego przez platformę Azure.

Ten dostawca nie używa tokenu JWT z nagłówka Authorization . Opiera się on na specjalnym nagłówku , X-MS-CLIENT-PRINCIPALwstrzykiwanym przez platformę App Service. Ten nagłówek zawiera obiekt JSON zakodowany w formacie base64 ze szczegółami tożsamości użytkownika.

Anonimowe: jeśli AppService dostawca jest skonfigurowany, ale żądanie zostanie dostarczone bez nagłówka X-MS-CLIENT-PRINCIPAL , żądanie zostanie przypisane do roli anonymoussystemu .

Zdekodowany kod JSON z nagłówka X-MS-CLIENT-PRINCIPAL zwykle wygląda następująco:

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

Role są zawarte w tablicy claims .

Informacje o nagłówku X-MS-API-ROLE

  • Rola i zachowanie: X-MS-API-ROLE nagłówek służy do określania roli, którą użytkownik chce założyć dla bieżącego żądania. Wartość tego nagłówka musi być zgodna z jedną z wartości roli znalezionych w claims tablicy X-MS-CLIENT-PRINCIPAL obiektu.
  • Czy jest to wymagane?: Nie. X-MS-API-ROLE Jeśli nagłówek jest nieobecny, żądanie jest przetwarzane w kontekście authenticated roli systemu. Oznacza to, że użytkownik jest rozpoznawany jako zalogowany, ale nie jako określona rola zdefiniowana przez aplikację z tokenu.
  • Zachowanie w przypadku dopasowania: jeśli X-MS-API-ROLE nagłówek jest podany, a jego wartość odpowiada roli w jednostce klienta claims, użytkownik przyjmuje rolę dla żądania.
  • Zachowanie w przypadku niezgodności: jeśli X-MS-API-ROLE nagłówek jest podany, ale wartość nie jest zgodna z żadną rolą 403 Forbidden w jednostce klienta, żądanie zostanie odrzucone przy użyciu kodu stanu. Dzięki temu użytkownik nie może ubiegać się o rolę, do której nie został przypisany.

EntraId (dostawca uwierzytelniania)

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

Ten dostawca zabezpiecza punkty końcowe przy użyciu tożsamości użytkowników i aplikacji w usłudze Microsoft Entra. Jest to idealne rozwiązanie dla każdej usługi, w której użytkownicy lub inne usługi potrzebują bezpiecznego dostępu w ramach dzierżawy Firmy Entra.

[! UWAGA] EntraId Dostawca wcześniej nosił nazwę AzureAd. Stara nazwa nadal działa, ale deweloperzy są zachęcani do migrowania ich konfiguracji z AzureAd do EntraId.

Ten dostawca oczekuje standardowego tokenu elementu nośnego JWT w nagłówku Authorization wystawionym przez firmę Microsoft Entra. Token musi być skonfigurowany dla określonej aplikacji (przy użyciu audience oświadczenia). Role użytkownika lub jednostki usługi powinny znajdować się w oświadczeniu w tokenie. Kod wyszukuje roles oświadczenie domyślnie.

Anonimowe: jeśli EntraId dostawca jest skonfigurowany, ale żądanie zostanie dostarczone bez nagłówka Authorization , żądanie zostanie przypisane do roli anonymoussystemu .

Zdekodowany ładunek JWT może wyglądać następująco:

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

Informacje o nagłówku X-MS-API-ROLE

  • Rola i zachowanie: X-MS-API-ROLE nagłówek służy do określania roli, jaką użytkownik chce założyć dla żądania. Wartość tego nagłówka musi być zgodna z jedną z wartości roli znalezionych w roles oświadczeniu tokenu JWT.
  • Czy jest to wymagane?: Nie. X-MS-API-ROLE Jeśli nagłówek jest nieobecny, żądanie jest przetwarzane w kontekście authenticated roli systemu. Oznacza to, że użytkownik jest rozpoznawany jako zalogowany, ale nie jako określona rola zdefiniowana przez aplikację z tokenu.
  • Zachowanie przy dopasowaniu: jeśli X-MS-API-ROLE nagłówek jest dostarczany i pasuje do roli w oświadczeniu roles , kontekst użytkownika jest ustawiony na rolę.
  • Zachowanie w przypadku niezgodności: jeśli X-MS-API-ROLE nagłówek jest podany, ale jego wartość nie pasuje do żadnej roli w oświadczeniu roles , żądanie zostanie odrzucone przy użyciu 403 Forbidden kodu stanu. Dzięki temu użytkownik nie może ubiegać się o rolę, do której nie został przypisany.

Niestandardowy (dostawca uwierzytelniania)

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

Ten dostawca jest przeznaczony dla deweloperów, którzy chcą zintegrować konstruktora interfejsu API danych z dostawcą tożsamości innej firmy (na przykład Auth0, Okta lub niestandardowym serwerem tożsamości), którzy wystawiają JWTs. Zapewnia elastyczność konfigurowania oczekiwanych audience i issuer tokenów.

Dostawca Custom oczekuje standardowego tokenu elementu nośnego JWT w nagłówku Authorization . Kluczową różnicą EntraId od dostawcy jest skonfigurowanie prawidłowego issuer pliku konfiguracji i audience w pliku konfiguracji konstruktora interfejsu API danych. Dostawca weryfikuje token, sprawdzając, czy zaufany urząd go wystawił. Role użytkownika powinny znajdować się w roles oświadczeniu w ładunku JWT.

[! UWAGA] W niektórych przypadkach w zależności od dostawcy tożsamości innej firmy deweloperzy muszą dostosować strukturę swojego zestawu JWT, aby dopasować strukturę oczekiwaną przez konstruktora interfejsu API danych (jak pokazano poniżej).

Anonimowe: jeśli Custom dostawca jest skonfigurowany, ale żądanie zostanie dostarczone bez nagłówka Authorization , żądanie zostanie przypisane do roli anonymoussystemu .

Zdekodowany ładunek JWT dla custom dostawcy może wyglądać następująco:

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

Informacje o nagłówku X-MS-API-ROLE

  • Rola i zachowanie: X-MS-API-ROLE nagłówek działa dokładnie tak samo jak w przypadku dostawcy EntraId . Umożliwia użytkownikowi wybranie jednej z przypisanych ról. Wartość tego nagłówka musi być zgodna z jedną z ról z roles oświadczenia w niestandardowym tokenie JWT.
  • Czy jest to wymagane?: Nie. X-MS-API-ROLE Jeśli nagłówek jest nieobecny, użytkownik jest traktowany jako w roli systemowejauthenticated.
  • Zachowanie przy dopasowaniu: jeśli X-MS-API-ROLE wartość nagłówka pasuje do roli w oświadczeniu JWT roles , kontekst użytkownika jest ustawiony na tej roli na potrzeby autoryzacji.
  • Zachowanie w przypadku niezgodności: jeśli X-MS-API-ROLE wartość nagłówka nie pasuje do żadnej roli w oświadczeniu roles , żądanie zostanie odrzucone przy użyciu 403 Forbidden kodu stanu. Dzięki temu użytkownik nie może ubiegać się o rolę, do której nie został przypisany.

Symulator (dostawca uwierzytelniania)

Ten dostawca jest przeznaczony do ułatwienia deweloperom testowania konfiguracji, zwłaszcza authorization zasad, bez konieczności konfigurowania pełnego dostawcy uwierzytelniania, takiego jak Entra Identity lub EasyAuth. Symuluje authenticated użytkownika.

Dostawca Simulator nie używa tokenów JWT. Uwierzytelnianie jest symulowane. W przypadku korzystania z tego dostawcy wszystkie żądania są traktowane tak, jakby pochodziły z uwierzytelnionego użytkownika.

Informacje o nagłówku X-MS-API-ROLE

  • Rola i zachowanie: X-MS-API-ROLE nagłówek jest jedynym sposobem określania roli podczas korzystania z elementu Simulator. Ponieważ nie ma tokenu z listą ról, system niejawnie ufa roli wysłanej w tym nagłówku.
  • Czy jest to wymagane?: Nie.
  • Zachowanie w przypadku braku: jeśli X-MS-API-ROLE nagłówek jest nieobecny, żądanie jest przetwarzane w kontekście authenticated roli systemu.
  • Zachowanie w przypadku obecności: jeśli X-MS-API-ROLE nagłówek jest obecny, żądanie jest przetwarzane w kontekście roli określonej w wartości nagłówka. Nie ma walidacji na liście oświadczeń, więc deweloper może symulować dowolną rolę, której potrzebują do przetestowania swoich zasad.

Symulator w środowisku produkcyjnym

authentication.provider Jeśli parametr jest ustawiony na Simulator wartość , konstruktor interfejsu runtime.host.modeproductionAPI danych zakończy się niepowodzeniem.

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

JWT (środowisko uruchomieniowe hosta uwierzytelniania)

Parent Property Typ Required Default
runtime.host.authentication jwt obiekt ❌ Nie -

Globalna konfiguracja tokenu internetowego JSON (JWT).

Diagram obsługi tokenów internetowych JSON w narzędziu Data API Builder.

Właściwości zagnieżdżone

Parent Property Typ Required Default
runtime.host.authentication.jwt audience ciąg ❌ Nie None
runtime.host.authentication.jwt issuer ciąg ❌ Nie None

Format

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

Stronicowanie (środowisko uruchomieniowe)

Parent Property Typ Required Default
runtime pagination obiekt ❌ Nie -

Globalne limity stronicowania dla punktów końcowych REST i GraphQL.

Właściwości zagnieżdżone

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

Obsługiwane wartości maksymalnego rozmiaru strony

Value Result
integer Obsługiwana jest dowolna dodatnia liczba całkowita 32-bitowa.
0 Niewspierane.
-1 Wartość domyślna to maksymalna obsługiwana wartość.
< -1 Niewspierane.

Wartości obsługiwane przez domyślny rozmiar strony

Value Result
integer Dowolna dodatnia liczba całkowita mniejsza niż bieżąca max-page-size.
0 Niewspierane.
-1 Wartość domyślna bieżącego ustawienia max-page-size.
< -1 Niewspierane.

Gdy next-link-relative wartość to true, wartości stronicowania nextLink używają względnych adresów URL zamiast bezwzględnych adresów URL.

Value Example
false (ustawienie domyślne) "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

Gdy wartość jest większa niż max-page-size, wyniki są ograniczone do max-page-sizewartości .

Przykład: stronicowanie w interfejsie REST

Request

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

Ładunek danych odpowiedzi

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

Żądaj następnej strony

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

Przykład: stronicowanie w narzędziu GraphQL

Ładunek żądania (zapytanie)

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

Ładunek danych odpowiedzi

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

Żądaj następnej strony

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

Przykład: uzyskiwanie dostępu do żądań max-page-size

max-page-size Użyj wartości, ustawiając $limit wartość (REST) lub first (GraphQL) na -1.

REST

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

GraphQL

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

Pamięć podręczna (środowisko uruchomieniowe)

Parent Property Typ Required Default
runtime cache obiekt ❌ Nie -

Konfiguracja globalnej pamięci podręcznej.

Właściwości zagnieżdżone

Parent Property Typ Required Default
runtime.cache enabled boolean ❌ Nie False
runtime.cache ttl-seconds liczba całkowita ❌ Nie 5

Tip

Właściwość na poziomie cache.ttl-seconds jednostki jest domyślnie ustawiona na tę wartość globalną.

Format

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

Important

Jeśli wartość globalna enabled to false, pojedynczy poziom enabled jednostki nie ma znaczenia.

Telemetria (środowisko uruchomieniowe)

Parent Property Typ Required Default
runtime telemetry obiekt ❌ Nie -

Globalna konfiguracja telemetrii.

Właściwości zagnieżdżone

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

Konfiguruje szczegółowość rejestrowania dla przestrzeni nazw. Jest to zgodne ze standardowymi konwencjami rejestrowania platformy .NET i umożliwia szczegółową kontrolę, chociaż zakłada ona pewną znajomość wewnętrznych elementów konstruktora interfejsu API danych. Konstruktor interfejsu API danych to open source: https://aka.ms/dab

Format

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

Tip

log-level mogą być ładowane na gorąco zarówno w środowisku deweloperskim, jak i produkcyjnym. Jest to obecnie jedyna właściwość, która obsługuje przeładowywanie na gorąco w środowisku produkcyjnym.

Example

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

Application Insights (telemetria)

Parent Property Typ Required Default
runtime.telemetry application-insights obiekt ❌ Nie -

Konfiguruje rejestrowanie w usłudze Application Insights.

Właściwości zagnieżdżone

Parent Property Typ Required Default
runtime.telemetry.application-insights enabled boolean ❌ Nie False
runtime.telemetry.application-insights connection-string ciąg ✔️ Tak None

Format

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

OpenTelemetry (telemetria)

Parent Property Typ Required Default
runtime.telemetry open-telemetry obiekt ❌ Nie -

Konfiguruje rejestrowanie w celu otwarcia telemetrii.

Właściwości zagnieżdżone

Parent Property Typ Required Default
runtime.telemetry.open-telemetry enabled boolean ❌ Nie true
runtime.telemetry.open-telemetry endpoint ciąg ✔️ Tak None
runtime.telemetry.open-telemetry headers ciąg ❌ Nie None
runtime.telemetry.open-telemetry service-name ciąg ❌ Nie "dab"
runtime.telemetry.open-telemetry exporter-protocol wyliczenie (grpc | httpprotobuf) ❌ Nie grpc

Wiele nagłówków jest , rozdzielonych przecinkami.

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

Dowiedz się więcej o OTEL_EXPORTER_OTLP_HEADERS.

Note

GRPC (4317) jest szybszy i obsługuje przesyłanie strumieniowe, ale wymaga większej liczby konfiguracji. Protokół HTTP/protobuf (4318) jest prostszy i łatwiejszy do debugowania, ale mniej wydajny.

Kondycja (środowisko uruchomieniowe)

Parent Property Typ Required Default
runtime health obiekt ❌ Nie -

Konfiguracja globalnego punktu końcowego sprawdzania kondycji (/health).

Właściwości zagnieżdżone

Parent Property Typ Required Default Zakres/notatki
runtime.health enabled boolean ❌ Nie true
runtime.health roles tablica ciągów ✔️ Tak* null *Wymagane w trybie produkcyjnym
runtime.health cache-ttl-seconds liczba całkowita ❌ Nie 5 Min: 0
runtime.health max-query-parallelism liczba całkowita ❌ Nie 4 Min: 1, Maks. 8 (zaciśnięty)

Zachowanie w środowisku deweloperskim a produkcyjnym

Condition Zachowanie programistyczne Zachowanie produkcyjne
health.enabled = fałsz 403 stan 403 stan
health.enabled = prawda Zależy od roli Zależy od roli
roles pominięty lub null Wyświetlona kondycja 403 stan
bieżąca rola nie jest w roles 403 stan 403 stan
bieżąca rola w roles Wyświetlona kondycja Wyświetlona kondycja
roles Zawiera anonymous Wyświetlona kondycja Wyświetlona kondycja

Format

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

Note

Jeśli wartość globalna enabled to false, pojedynczy poziom enabled jednostki nie ma znaczenia.

Example

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