Udostępnij za pośrednictwem


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 Unauthenticated 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
runtime.cache.level-2.enabled false Włącza globalnie rozproszoną pamięć podręczną poziomu 2
runtime.cache.level-2.provider "redis" Dostawca rozproszonej pamięci podręcznej dla pamięci podręcznej poziomu 2
runtime.cache.level-2.connection-string null Parametry połączenia dla dostawcy pamięci podręcznej poziomu 2
runtime.cache.level-2.partition null Opcjonalna nazwa partycji dla izolowania rozproszonego miejsca w pamięci podręcznej

Ustawienia kompresji

Property Default Description
runtime.compression.level optimal Poziom kompresji odpowiedzi HTTP (optimal, fastestlub none)

Ustawienia telemetrii

Property Default Description
runtime.telemetry.application-insights.connection-string null Parametry połączenia usługi Application Insights
runtime.telemetry.application-insights.enabled true 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.open-telemetry.enabled true Włącza lub wyłącza funkcję OpenTelemetry
runtime.telemetry.azure-log-analytics.enabled false Włącza lub wyłącza usługę Azure Log Analytics
runtime.telemetry.azure-log-analytics.dab-identifier "DabLogs" Identyfikator języka DAB w usłudze Azure Log Analytics
runtime.telemetry.azure-log-analytics.flush-interval-seconds 5 Interwał między wypychaniami wsadowymi dziennika (w sekundach)
runtime.telemetry.azure-log-analytics.auth.custom-table-name null Niestandardowa nazwa tabeli dla usługi Azure Log Analytics
runtime.telemetry.azure-log-analytics.auth.dcr-immutable-id null Niezmienny identyfikator reguły zbierania danych
runtime.telemetry.azure-log-analytics.auth.dce-endpoint null Adres URL punktu końcowego zbierania danych
runtime.telemetry.file.enabled false Włącza lub wyłącza rejestrowanie ujścia plików
runtime.telemetry.file.path "/logs/dab-log.txt" Ścieżka pliku dzienników telemetrii
runtime.telemetry.file.rolling-interval "Day" Interwał kroczący dla plików dziennika
runtime.telemetry.file.retained-file-count-limit 1 Maksymalna liczba zachowanych plików dziennika
runtime.telemetry.file.file-size-limit-bytes 1048576 Maksymalny rozmiar pliku w bajtach przed stopniowem
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)

Ustawienia mcp

Property Default Description
runtime.mcp.enabled true Włącza lub wyłącza globalny punkt końcowy MCP
runtime.mcp.path "/mcp" Ścieżka podstawowa punktu końcowego MCP
runtime.mcp.description null Opis serwera wysyłany do klientów MCP podczas inicjowania
runtime.mcp.dml-tools true Włącza lub wyłącza wszystkie narzędzia DML lub obiekt dla kontrolki poszczególnych narzędzi
runtime.mcp.dml-tools.describe-entities true Włącza narzędzie describe_entities
runtime.mcp.dml-tools.create-record true Włącza narzędzie create_record
runtime.mcp.dml-tools.read-records true Włącza narzędzie read_records
runtime.mcp.dml-tools.update-record true Włącza narzędzie update_record
runtime.mcp.dml-tools.delete-record true Włącza narzędzie delete_record
runtime.mcp.dml-tools.execute-entity true Włącza narzędzie execute_entity
runtime.mcp.dml-tools.aggregate-records true Włącza narzędzie aggregate_records (wartość logiczna lub obiekt z limitem czasu zapytania)

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: "Unauthenticated"),
        "jwt": {
          "audience": "<string>",
          "issuer": "<string>"
        }
      }
    }
  },
    "compression": {
      "level": <"optimal"> (default) | <"fastest"> | <"none">
    },
    "cache": {
      "enabled": <true>|<false> (default: `false`),
      "ttl-seconds": <integer> (default: `5`),
      "level-2": {
        "enabled": <true>|<false> (default: `false`),
        "provider": <"redis">,
        "connection-string": <string>,
        "partition": <string>
      }
    },
    "telemetry": {
      "application-insights": {
        "connection-string": "<string>",
        "enabled": <true>|<false> (default: `true`)
      },
      "open-telemetry": {
        "endpoint": "<string>",
        "headers": "<string>",
        "service-name": <string> (default: "dab"),
        "exporter-protocol": <"grpc"> (default) | <"httpprotobuf">,
        "enabled": <true>|<false> (default: `true`)
      },
      "azure-log-analytics": {
        "enabled": <true>|<false> (default: `false`),
        "dab-identifier": <string> (default: "DabLogs"),
        "flush-interval-seconds": <integer> (default: `5`),
        "auth": {
          "custom-table-name": <string>,
          "dcr-immutable-id": <string>,
          "dce-endpoint": <string>
        }
      },
      "file": {
        "enabled": <true>|<false> (default: `false`),
        "path": <string> (default: "/logs/dab-log.txt"),
        "rolling-interval": <string> (default: "Day"),
        "retained-file-count-limit": <integer> (default: `1`),
        "file-size-limit-bytes": <integer> (default: `1048576`)
      },
      "log-level": {
        // namespace keys
        "<namespace>": <"trace"|"debug"|"information"|"warning"|"error"|"critical"|"none"|null>
      }
    },
    "health": {
      "enabled": <true>|<false> (default: `true`),
      "roles": [ "<string>" ],
      "cache-ttl-seconds": <integer> (default: `5`),
      "max-query-parallelism": <integer> (default: `4`)
    },
    "mcp": {
      "enabled": <true>|<false> (default: `true`),
      "path": <string> (default: `"/mcp"`),
      "description": <string>,
      "dml-tools": <true>|<false> | {
        "describe-entities": <true>|<false> (default: `true`),
        "create-record": <true>|<false> (default: `true`),
        "read-records": <true>|<false> (default: `true`),
        "update-record": <true>|<false> (default: `true`),
        "delete-record": <true>|<false> (default: `true`),
        "execute-entity": <true>|<false> (default: `true`),
        "aggregate-records": <true>|<false> | {
          "enabled": <true>|<false> (default: `true`),
          "query-timeout": <integer> (default: `30`)
        }
      }
    }
  }
}

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

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

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. Aby osiągnąć to zachowanie, 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, która kontroluje, 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> | <false> (default),
        "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 (Unauthenticated | StaticWebApps | AppService | EntraId | Custom | Simulator) ❌ Nie Unauthenticated

Wybiera metodę uwierzytelniania. Każdy dostawca weryfikuje tożsamość inaczej. Aby zapoznać się z konfiguracją krok po kroku, zobacz przewodniki z instrukcjami w poniższej tabeli.

Note

Funkcja narzędzia Data API Builder 2.0 opisana w tej sekcji jest obecnie dostępna w wersji zapoznawczej i może ulec zmianie przed ogólną dostępnością. Aby uzyskać więcej informacji, zobacz Co nowego w wersji 2.0.

Podsumowanie dostawcy

Provider Przypadek użycia Źródło tożsamości Przewodnik z instrukcjami
Unauthenticated Język DAB znajduje się za zaufanym frontonem (ustawienie domyślne) Brak — wszystkie żądania są uruchamiane jako anonymous Konfigurowanie dostawcy nieuwierzytelnionego
AppService Aplikacje hostowane na platformie Azure (EasyAuth) X-MS-CLIENT-PRINCIPAL Nagłówka Konfigurowanie uwierzytelniania usługi App Service
EntraID Microsoft Entra ID (Azure AD) Token elementu nośnego JWT Konfigurowanie uwierzytelniania Entra ID
Custom Dostawcy tożsamości innych firm (Okta, Auth0) Token elementu nośnego JWT Konfigurowanie niestandardowego uwierzytelniania JWT
Simulator Tylko lokalne testowanie Symulowany Konfigurowanie uwierzytelniania symulatora

Note

EntraId Dostawca wcześniej nosił nazwę AzureAd. Stara nazwa nadal działa pod kątem zgodności.

Nieuwierzytelnione (ustawienie domyślne)

Gdy Unauthenticated jest ustawiony (lub nie określono dostawcy), daB nie sprawdza ani nie weryfikuje żadnego zestawu JWT. Wszystkie żądania są uruchamiane jako anonymous rola. Usługa frontonu, taka jak usługa Azure API Management lub brama aplikacji, nadal może obsługiwać zasady uwierzytelniania lub dostępu, zanim żądania dotrą do języka DAB, ale usługa DAB nadal autoryzuje się tylko jako anonymous.

Important

Gdy Unauthenticated jest aktywny, authenticated a role niestandardowe zdefiniowane w uprawnieniach jednostki nigdy nie są aktywowane. Jeśli konfiguracja zawiera te role, daB emituje ostrzeżenie podczas uruchamiania.

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

AppService

Nagłówki tożsamości zaufania wprowadzone przez usługę Azure App Service EasyAuth.

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

EntraID

Weryfikuje tokeny JWT wystawione przez identyfikator Firmy Microsoft Entra.

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

Custom

Weryfikuje tokeny JWT od dostawców tożsamości innych firm.

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

Symulator

Symuluje uwierzytelnianie na potrzeby lokalnego programowania i testowania.

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

Important

Dostawca Simulator działa tylko wtedy, gdy runtime.host.mode ma wartość development. Nie można uruchomić narzędzia DAB, jeśli symulator jest skonfigurowany w trybie produkcyjnym.

Wybór roli

W przypadku wszystkich dostawców z wyjątkiem symulatora X-MS-API-ROLE nagłówek wybiera rolę do użycia z oświadczeń uwierzytelnionego użytkownika. W przypadku pominięcia żądanie używa Authenticated roli systemu. Aby uzyskać szczegółowe informacje na temat oceny ról, zobacz Omówienie autoryzacji.

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 ✔️ Tak* None
runtime.host.authentication.jwt issuer ciąg ✔️ Tak* None

* Zarówno, jak audience i issuer są wymagane, gdy jwt obiekt jest obecny. Sam jwt obiekt jest wymagany, gdy dostawca to EntraID, AzureADlub Custom.

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

Kompresja (środowisko uruchomieniowe)

Note

Funkcja narzędzia Data API Builder 2.0 opisana w tej sekcji jest obecnie dostępna w wersji zapoznawczej i może ulec zmianie przed ogólną dostępnością. Aby uzyskać więcej informacji, zobacz Co nowego w wersji 2.0.

Parent Property Typ Required Default
runtime compression obiekt ❌ Nie -

Konfiguracja kompresji odpowiedzi HTTP. Po włączeniu funkcja DAB kompresuje treść odpowiedzi, aby zmniejszyć rozmiar ładunku i zwiększyć szybkość transferu.

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

Parent Property Typ Required Default
runtime.compression level ciąg ❌ Nie "optimal"

Obsługiwane wartości dla level

Value Description Oszczędności kompresji Wpływ na wydajność
optimal Współczynnik i szybkość równoważenia (wartość domyślna) Gzip: 90,5% / Brotli: 92.2% Umiarkowane użycie procesora CPU, niewielkie opóźnienie
fastest Priorytetowo określa szybkość w stosunku Gzip: 89,8% / Brotli: 91.1% Niskie użycie procesora CPU, minimalne opóźnienie
none Brak kompresji 0% (punkt odniesienia: 12 673 bajty) None

Nagłówki HTTP klienta

Kompresja jest wywoływana Accept-Encoding przez nagłówek klienta. Obsługiwane algorytmy to Gzip i Brotli. To level ustawienie konfiguruje strategię kompresji, gdy klient i serwer obsługują wiele algorytmów.

Obsługiwane nagłówki

Nagłówek HTTP Używany algorytm
Accept-Encoding: gzip Gzip
Accept-Encoding: br Brotli

Format

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

Example

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

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
runtime.cache level-2 obiekt ❌ Nie -
Parent Property Typ Required Default
runtime.cache.level-2 enabled boolean ❌ Nie False
runtime.cache.level-2 provider ciąg ❌ Nie redis
runtime.cache.level-2 connection-string ciąg ❌ Nie None
runtime.cache.level-2 partition ciąg ❌ Nie None

Tip

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

Tip

Aby zapoznać się z kompleksową konfiguracją, zachowaniem na poziomie pamięci podręcznej i przykładami usługi Redis, zobacz Implementowanie pamięci podręcznej na poziomie 2.

Format

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

Important

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

Gdy level-2.enabled element to true, daB używa skonfigurowanego dostawcy rozproszonej pamięci podręcznej oprócz lokalnej pamięci podręcznej w pamięci. Jednostka skonfigurowana przy użyciu poziomu L1L2 pamięci podręcznej najpierw sprawdza lokalną pamięć podręczną, a następnie rozproszoną pamięć podręczną przed przejściem do bazy danych.

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 -
runtime.telemetry azure-log-analytics obiekt ❌ Nie -
runtime.telemetry file obiekt ❌ Nie -

Konfiguruje szczegółowość rejestrowania dla przestrzeni nazw. Ta konfiguracja jest zgodna ze standardowymi konwencjami rejestrowania platformy .NET i umożliwia szczegółową kontrolę, chociaż zakłada pewną znajomość wewnętrznych funkcji 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 true
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

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

Azure Log Analytics (telemetria)

Parent Property Typ Required Default
runtime.telemetry azure-log-analytics obiekt ❌ Nie -

Konfiguruje rejestrowanie w usłudze Azure Log Analytics za pośrednictwem punktu końcowego zbierania danych. Po włączeniu język DAB wysyła dane telemetryczne w partiach w konfigurowalnym interwale.

Note

Funkcja narzędzia Data API Builder 2.0 opisana w tej sekcji jest obecnie dostępna w wersji zapoznawczej i może ulec zmianie przed ogólną dostępnością. Aby uzyskać więcej informacji, zobacz Co nowego w wersji 2.0.

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

Parent Property Typ Required Default
runtime.telemetry.azure-log-analytics enabled boolean ❌ Nie false
runtime.telemetry.azure-log-analytics dab-identifier ciąg ❌ Nie "DabLogs"
runtime.telemetry.azure-log-analytics flush-interval-seconds liczba całkowita ❌ Nie 5
runtime.telemetry.azure-log-analytics auth obiekt ✔️ Tak* -

* auth jest wymagany, gdy enabled ma wartość true.

Parent Property Typ Required Default
runtime.telemetry.azure-log-analytics.auth custom-table-name ciąg ✔️ Tak* null
runtime.telemetry.azure-log-analytics.auth dcr-immutable-id ciąg ✔️ Tak* null
runtime.telemetry.azure-log-analytics.auth dce-endpoint ciąg ✔️ Tak* null

* Wymagane, gdy enabled ma wartość true.

  • dab-identifier— etykieta przekazana do usługi Log Analytics, aby ułatwić odróżnienie dzienników od konstruktora interfejsu API danych.
  • flush-interval-seconds— interwał czasu (w sekundach) między wysyłaniem partii danych telemetrycznych.
  • custom-table-name— nazwa tabeli niestandardowej w usłudze Azure Log Analytics, w której są przechowywane dane.
  • dcr-immutable-id— niezmienny identyfikator reguły zbierania danych, która definiuje sposób zbierania danych.
  • dce-endpoint— adres URL punktu końcowego zbierania danych używany do wysyłania danych telemetrycznych.

Format

{
  "runtime": {
    "telemetry": {
      "azure-log-analytics": {
        "enabled": <true> | <false> (default),
        "dab-identifier": <string> (default: "DabLogs"),
        "flush-interval-seconds": <integer> (default: 5),
        "auth": {
          "custom-table-name": "<string>",
          "dcr-immutable-id": "<string>",
          "dce-endpoint": "<string>"
        }
      }
    }
  }
}

Example

{
  "runtime": {
    "telemetry": {
      "azure-log-analytics": {
        "enabled": true,
        "dab-identifier": "MyDabInstance",
        "flush-interval-seconds": 10,
        "auth": {
          "custom-table-name": "DabTelemetry_CL",
          "dcr-immutable-id": "dcr-abc123def456",
          "dce-endpoint": "https://my-dce.eastus-1.ingest.monitor.azure.com"
        }
      }
    }
  }
}

Plik (telemetria)

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

Konfiguruje zapisywanie dzienników telemetrii w pliku lokalnym. Po włączeniu język DAB zapisuje dane wyjściowe dziennika strukturalnego do określonej ścieżki pliku z konfigurowalnymi interwałami kroczącymi i limitami rozmiaru.

Note

Funkcja narzędzia Data API Builder 2.0 opisana w tej sekcji jest obecnie dostępna w wersji zapoznawczej i może ulec zmianie przed ogólną dostępnością. Aby uzyskać więcej informacji, zobacz Co nowego w wersji 2.0.

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

Parent Property Typ Required Default
runtime.telemetry.file enabled boolean ❌ Nie false
runtime.telemetry.file path ciąg ✔️ Tak* "/logs/dab-log.txt"
runtime.telemetry.file rolling-interval wyliczenie ❌ Nie "Day"
runtime.telemetry.file retained-file-count-limit liczba całkowita ❌ Nie 1
runtime.telemetry.file file-size-limit-bytes liczba całkowita ❌ Nie 1048576

* path jest wymagany, gdy enabled ma wartość true.

Wartości interwałów rolowych

Value Description
Minute Nowy plik dziennika co minutę
Hour Nowy plik dziennika co godzinę
Day Nowy plik dziennika codziennie (ustawienie domyślne)
Month Nowy plik dziennika co miesiąc
Year Nowy plik dziennika co roku
Infinite Nigdy nie przerzucaj do nowego pliku

Format

{
  "runtime": {
    "telemetry": {
      "file": {
        "enabled": <true> | <false> (default),
        "path": <string> (default: "/logs/dab-log.txt"),
        "rolling-interval": <"Day"> (default) | <"Minute"> | <"Hour"> | <"Month"> | <"Year"> | <"Infinite">,
        "retained-file-count-limit": <integer> (default: 1),
        "file-size-limit-bytes": <integer> (default: 1048576)
      }
    }
  }
}

Example

{
  "runtime": {
    "telemetry": {
      "file": {
        "enabled": true,
        "path": "/var/log/dab/dab-telemetry.txt",
        "rolling-interval": "Hour",
        "retained-file-count-limit": 24,
        "file-size-limit-bytes": 5242880
      }
    }
  }
}

MCP (środowisko uruchomieniowe)

Parent Property Typ Required Default
runtime mcp obiekt ❌ Nie -

Konfiguruje serwer MCP (SQL Model Context Protocol), który uwidacznia jednostki bazy danych jako narzędzia MCP dla agentów sztucznej inteligencji.

Note

Funkcja narzędzia Data API Builder 2.0 opisana w tej sekcji jest obecnie dostępna w wersji zapoznawczej i może ulec zmianie przed ogólną dostępnością. Aby uzyskać więcej informacji, zobacz Co nowego w wersji 2.0.

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

Parent Property Typ Required Default
runtime.mcp enabled boolean ❌ Nie true
runtime.mcp path ciąg ❌ Nie "/mcp"
runtime.mcp description ciąg ❌ Nie null
runtime.mcp dml-tools wartość logiczna lub obiekt ❌ Nie true

Właściwość dml-tools akceptuje wartość logiczną w celu włączenia lub wyłączenia wszystkich narzędzi albo obiektu do sterowania poszczególnymi narzędziami:

Parent Property Typ Required Default
runtime.mcp.dml-tools describe-entities boolean ❌ Nie true
runtime.mcp.dml-tools create-record boolean ❌ Nie true
runtime.mcp.dml-tools read-records boolean ❌ Nie true
runtime.mcp.dml-tools update-record boolean ❌ Nie true
runtime.mcp.dml-tools delete-record boolean ❌ Nie true
runtime.mcp.dml-tools execute-entity boolean ❌ Nie true
runtime.mcp.dml-tools aggregate-records wartość logiczna lub obiekt ❌ Nie true

Narzędzie aggregate-records akceptuje wartość logiczną lub obiekt z większymi ustawieniami:

Parent Property Typ Required Default Zakres
runtime.mcp.dml-tools.aggregate-records enabled boolean ❌ Nie true
runtime.mcp.dml-tools.aggregate-records query-timeout liczba całkowita ❌ Nie 30 1–600 sekund

Format

{
  "runtime": {
    "mcp": {
      "enabled": <true> (default) | <false>,
      "path": <string> (default: "/mcp"),
      "description": <string>,
      "dml-tools": {
        "describe-entities": <true> | <false>,
        "create-record": <true> | <false>,
        "read-records": <true> | <false>,
        "update-record": <true> | <false>,
        "delete-record": <true> | <false>,
        "execute-entity": <true> | <false>,
        "aggregate-records": {
          "enabled": <true> | <false>,
          "query-timeout": <integer; default: 30>
        }
      }
    }
  }
}

Example

{
  "runtime": {
    "mcp": {
      "enabled": true,
      "dml-tools": {
        "describe-entities": true,
        "create-record": true,
        "read-records": true,
        "update-record": true,
        "delete-record": true,
        "execute-entity": true,
        "aggregate-records": {
          "enabled": true,
          "query-timeout": 30
        }
      }
    }
  }
}

Aby włączyć lub wyłączyć wszystkie narzędzia DML jednocześnie, ustaw wartość "dml-tools" lub truefalse .

Po wyłączeniu narzędzia na poziomie środowiska uruchomieniowego narzędzie nigdy nie pojawia się w odpowiedzi MCP tools/list i nie może być wywoływane, niezależnie od uprawnień na poziomie jednostki. Aby uzyskać więcej informacji na temat poszczególnych narzędzi DML, zobacz Narzędzia języka manipulowania danymi (DML).

Korzystanie z interfejsu wiersza polecenia (CLI)

dab configure --runtime.mcp.enabled true
dab configure --runtime.mcp.path "/mcp"
dab configure --runtime.mcp.dml-tools.describe-entities true
dab configure --runtime.mcp.dml-tools.create-record true
dab configure --runtime.mcp.dml-tools.read-records true
dab configure --runtime.mcp.dml-tools.update-record true
dab configure --runtime.mcp.dml-tools.delete-record true
dab configure --runtime.mcp.dml-tools.execute-entity true
dab configure --runtime.mcp.dml-tools.aggregate-records.enabled true

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: Jeden, Max: Osiem (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
  }
}