Referenční informace ke schématu konfigurace tvůrce rozhraní Data API

Článek
10/04/2024

Modul tvůrce rozhraní Data API vyžaduje konfigurační soubor. Konfigurační soubor Data API Builderu poskytuje strukturovaný a komplexní přístup k nastavení rozhraní API a podrobně popisuje vše od proměnných prostředí až po konfigurace specifické pro entity. Tento dokument ve formátu JSON začíná vlastností $schema. Toto nastavení ověří dokument.

Vlastnosti database-type a connection-string zajišťují bezproblémovou integraci s databázovými systémy z Azure SQL Database do rozhraní NoSQL API služby Cosmos DB.

Konfigurační soubor může obsahovat například tyto možnosti:

Informace o databázové službě a připojení
Možnosti globální konfigurace a konfigurace modulu runtime
Sada vystavených entit
Metoda ověřování
Pravidla zabezpečení požadovaná pro přístup k identitám
Pravidla mapování názvů mezi rozhraním API a databází
Vztahy mezi entitami, které nelze odvodit
Jedinečné funkce pro konkrétní databázové služby

Přehled syntaxe

Tady je rychlý rozpis primárních "oddílů" v konfiguračním souboru.

{
  "$schema": "...",
  "data-source": { ... },
  "data-source-files": [ ... ],
  "runtime": {
    "rest": { ... },
    "graphql": { .. },
    "host": { ... },
    "cache": { ... },
    "telemetry": { ... },
    "pagination": { ... }
  }
  "entities": [ ... ]
}

Vlastnosti nejvyšší úrovně

Tady je popis vlastností nejvyšší úrovně ve formátu tabulky:

Vlastnost	Popis
$schema	Určuje schéma JSON pro ověření a zajišťuje, aby konfigurace dodržovala požadovaný formát.
zdroje dat	Obsahuje podrobnosti o typu databáze a připojovacím řetězci potřebném k navázání připojení k databázi.
zdrojových souborů dat	Volitelné pole určující jiné konfigurační soubory, které mohou definovat jiné zdroje dat.
modulu runtime	Konfiguruje chování a nastavení modulu runtime, včetně dílčích funkcí pro REST, GraphQL, hostitele, mezipaměti a telemetrických.
entit	Definuje sadu entit (databázových tabulek, zobrazení atd.), které jsou vystaveny prostřednictvím rozhraní API, včetně mapování , oprávněnía relací.

Ukázkové konfigurace

Tady je ukázkový konfigurační soubor, který obsahuje jenom požadované vlastnosti jedné jednoduché entity. Tato ukázka je určená k ilustraci minimálního scénáře.

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('sql-connection-string')"
  },
  "entities": {
    "Book": {
      "source": "dbo.books",
      "permissions": [{
          "actions": ["*"],
          "role": "anonymous"
      }]
    }
  }
}

Příklad složitějšího scénáře najdete v kompletní konfiguraci ukázky.

Prostředí

Konfigurační soubor tvůrce rozhraní Data API může podporovat scénáře, ve kterých potřebujete podporovat více prostředí, podobně jako appSettings.json soubor v ASP.NET Core. Architektura poskytuje tři společné hodnoty prostředí; Development, Staginga Production; ale můžete použít libovolnou hodnotu prostředí, kterou zvolíte. Prostředí, které tvůrce rozhraní Data API používá, musí být nakonfigurováno pomocí proměnné prostředí DAB_ENVIRONMENT.

Představte si příklad, ve kterém chcete mít základní konfiguraci a konfiguraci specifickou pro vývoj. Tento příklad vyžaduje dva konfigurační soubory:

	Životní prostředí
dab-config.json	Základna
dab-config.Development.json	Rozvoj

Pokud chcete použít konfiguraci specifickou pro vývoj, musíte nastavit proměnnou prostředí DAB_ENVIRONMENT na Development.

Konfigurační soubory specifické pro prostředí přepíší hodnoty vlastností v základním konfiguračním souboru. Pokud je v tomto příkladu nastavena hodnota connection-string v obou souborech, použije se hodnota ze souboru *.Development.json.

Projděte si tuto matici, abyste lépe pochopili, která hodnota se používá v závislosti na tom, kde je tato hodnota zadaná (nebo nezadaná) v některém souboru.

	Zadané v základní konfiguraci	Nezadá se v základní konfiguraci
Zadáno v aktuální konfiguraci prostředí	Aktuální prostředí	Aktuální prostředí
Nezadá se v aktuální konfiguraci prostředí	Základna	Žádný

Příklad použití více konfiguračních souborů najdete v tématu použití Tvůrce rozhraní Data API s prostředími.

Vlastnosti konfigurace

Tato část obsahuje všechny možné vlastnosti konfigurace, které jsou k dispozici pro konfigurační soubor.

Schéma

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`$root`	`$schema`	řetězec	✔️ Ano	Žádný

Každý konfigurační soubor začíná vlastností $schema a určuje schématu JSON pro ověření.

Formát

{
  "$schema": <string>
}

Příklady

Soubory schématu jsou k dispozici pro verze 0.3.7-alpha dál na konkrétních adresách URL a zajišťují, že používáte správnou verzi nebo nejnovější dostupné schéma.

https://github.com/Azure/data-api-builder/releases/download/<VERSION>-<suffix>/dab.draft.schema.json

Nahraďte VERSION-suffix požadovanou verzí.

https://github.com/Azure/data-api-builder/releases/download/v0.3.7-alpha/dab.draft.schema.json

Nejnovější verze schématu je vždy k dispozici v https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json.

Tady je několik příkladů platných hodnot schématu.

Verze	Identifikátor uri	Popis
0.3.7-alpha	`https://github.com/Azure/data-api-builder/releases/download/v0.3.7-alpha/dab.draft.schema.json`	Používá schéma konfigurace z alfa verze nástroje.
0.10.23	`https://github.com/Azure/data-api-builder/releases/download/v0.10.23/dab.draft.schema.json`	Používá konfigurační schéma pro stabilní verzi nástroje.
Nejnovější	`https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json`	Používá nejnovější verzi schématu konfigurace.

Poznámka

Verze tvůrce rozhraní Data API před 0.3.7-alpha mohou mít jiný identifikátor URI schématu.

Zdroj dat

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`$root`	`data-source`	řetězec	✔️ Ano	Žádný

Oddíl data-source definuje databázi a přístup k databázi prostřednictvím připojovacího řetězce. Definuje také možnosti databáze. Vlastnost data-source nakonfiguruje přihlašovací údaje potřebné pro připojení k záložní databázi. Oddíl data-source popisuje připojení back-endové databáze a určuje database-type i connection-string.

Formát

{
  "data-source": {
    "database-type": <string>,
    "connection-string": <string>,
    
    // mssql-only
    "options": {
      "set-session-context": <true> (default) | <false>
    },
    
    // cosmosdb_nosql-only
    "options": {
      "database": <string>,
      "container": <string>,
      "schema": <string>
    }
  }
}

Vlastnosti

	Požadovaný	Typ
`database-type`	✔️ Ano	enum string
`connection-string`	✔️ Ano	řetězec
`options`	❌ Ne	objekt

Typ databáze

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`data-source`	`database-type`	enum-string	✔️ Ano	Žádný

Řetězec výčtu sloužící k určení typu databáze, která se má použít jako zdroj dat.

Formát

{
  "data-source": {
    "database-type": <string>
  }
}

Hodnoty typu

Vlastnost type označuje druh back-end databáze.

Typ	Popis	Minimální verze
`mssql`	Azure SQL Database	Žádný
`mssql`	Azure SQL MI	Žádný
`mssql`	SQL Server	SQL 2016
`sqldw`	Azure SQL Data Warehouse	Žádný
`postgresql`	PostgreSQL	v11
`mysql`	MySQL	v8
`cosmosdb_nosql`	Azure Cosmos DB for NoSQL	Žádný
`cosmosdb_postgresql`	Azure Cosmos DB for PostgreSQL	Žádný

Připojovací řetězec

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`data-source`	`connection-string`	řetězec	✔️ Ano	Žádný

Řetězec hodnotu obsahující platný připojovací řetězec pro připojení k cílové databázové službě. Připojovací řetězec ADO.NET pro připojení k back-endové databázi. Další informace najdete v tématu ADO.NET připojovací řetězce.

Formát

{
  "data-source": {
    "connection-string": <string>
  }
}

Odolnost připojení

Tvůrce rozhraní Data API automaticky opakuje databázové požadavky po zjištění přechodných chyb. Logika opakování se řídí strategií Exponenciální reoff, kde je maximální počet opakování pět. Doba opakování po výpočtu dalších požadavků pomocí tohoto vzorce (za předpokladu, že aktuální pokus o opakování je r): $r^2$

Pomocí tohoto vzorce můžete vypočítat čas každého pokusu o opakování v sekundách.

	Sekundy
First	`2`
Second	`4`
třetí	`8`
čtvrtý	`16`
páté	`32`

Azure SQL a SQL Server

Tvůrce rozhraní Data API používá knihovnu SqlClient pro připojení k Azure SQL nebo SQL Serveru pomocí připojovacího řetězce, který zadáte v konfiguračním souboru. Seznam všech podporovaných možností připojovacího řetězce je k dispozici zde: SqlConnection.ConnectionString Vlastnost.

Tvůrce rozhraní DATA API se může také připojit k cílové databázi pomocí identit spravované služby (MSI), když je tvůrce rozhraní DATA API hostovaný v Azure. DefaultAzureCredential definovaná v knihovně Azure.Identity se používá k připojení pomocí známých identit, pokud v připojovacím řetězci nezadáte uživatelské jméno nebo heslo. Další informace najdete v DefaultAzureCredential příklady.

spravovanou identitu přiřazenou uživatelem (UMI): Připojte vlastnosti ověřování a ID uživatele do připojovacího řetězce a nahraďte ho ID klienta přiřazené uživatelem: .
Spravovaná identita přiřazená systémem (SMI): Připojte vlastnost ověřování a vylučte z připojovacího řetězce id uživatele a password argumenty: . Absence UserId a Password vlastnosti připojovacího řetězce signalizuje DAB k ověření pomocí spravované identity přiřazené systémem.

Další informace o konfiguraci identity spravované služby pomocí Azure SQL nebo SQL Serveru najdete v tématu spravované identity v Microsoft Entra for Azure SQL.

Příklady

Hodnota použitá pro připojovací řetězec do značné míry závisí na databázové službě použité ve vašem scénáři. Připojovací řetězec můžete vždy uložit do proměnné prostředí a přistupovat k němu pomocí funkce @env().

	Hodnota	Popis
použití řetězcové hodnoty služby Azure SQL Database	`Server=<server-address>;Database=<name-of-database>;User ID=<username>;Password=<password>;`	Připojovací řetězec k účtu služby Azure SQL Database. Další informace najdete v tématu připojovací řetězce služby Azure SQL Database.
použití řetězcové hodnoty Azure Database for PostgreSQL	`Server=<server-address>;Database=<name-of-database>;Port=5432;User Id=<username>;Password=<password>;Ssl Mode=Require;`	Připojovací řetězec k účtu Azure Database for PostgreSQL. Další informace najdete v tématu připojovací řetězce služby Azure Database for PostgreSQL.
použití řetězcové hodnoty Azure Cosmos DB for NoSQL	`AccountEndpoint=<endpoint>;AccountKey=<key>;`	Připojovací řetězec k účtu Azure Cosmos DB for NoSQL. Další informace najdete v tématu připojovacích řetězců služby Azure Cosmos DB for NoSQL.
použití řetězcové hodnoty Azure Database for MySQL	`Server=<server-address>;Database=<name-of-database>;User ID=<username>;Password=<password>;Sslmode=Required;SslCa=<path-to-certificate>;`	Připojovací řetězec k účtu Azure Database for MySQL. Další informace najdete v tématu připojovací řetězce služby Azure Database for MySQL.
proměnné prostředí Accessu	`@env('database-connection-string')`	Přístup k proměnné prostředí z místního počítače V tomto příkladu se odkazuje na proměnnou prostředí `database-connection-string`.

Spropitné

Osvědčeným postupem je zabránit ukládání citlivých informací do konfiguračního souboru. Pokud je to možné, použijte @env() pro odkaz na proměnné prostředí. Další informace naleznete v tématu @env() funkce.

Tyto ukázky ukazují, jak se jednotlivé typy databáze můžou nakonfigurovat. Váš scénář může být jedinečný, ale tato ukázka je dobrým výchozím místem. Zástupné symboly, jako jsou myserver, myDataBase, mylogina myPassword nahraďte skutečnými hodnotami specifickými pro vaše prostředí.

mssql
```
"data-source": {
  "database-type": "mssql",
  "connection-string": "$env('my-connection-string')",
  "options": {
    "set-session-context": true
  }
}
```
- typický formát připojovacího řetězce: "Server=tcp:myserver.database.windows.net,1433;Initial Catalog=myDataBase;Persist Security Info=False;User ID=mylogin;Password=myPassword;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"
postgresql
```
"data-source": {
  "database-type": "postgresql",
  "connection-string": "$env('my-connection-string')"
}
```
- typický formát připojovacího řetězce: "Host=myserver.postgres.database.azure.com;Database=myDataBase;Username=mylogin@myserver;Password=myPassword;"
mysql
```
"data-source": {
  "database-type": "mysql",
  "connection-string": "$env('my-connection-string')"
}
```
- typický formát připojovacího řetězce: "Server=myserver.mysql.database.azure.com;Database=myDataBase;Uid=mylogin@myserver;Pwd=myPassword;"

cosmosdb_nosql

"data-source": {
  "database-type": "cosmosdb_nosql",
  "connection-string": "$env('my-connection-string')",
  "options": {
    "database": "Your_CosmosDB_Database_Name",
    "container": "Your_CosmosDB_Container_Name",
    "schema": "Path_to_Your_GraphQL_Schema_File"
  }
}

typický formát připojovacího řetězce: "AccountEndpoint=https://mycosmosdb.documents.azure.com:443/;AccountKey=myAccountKey;"

cosmosdb_postgresql
```
"data-source": {
  "database-type": "cosmosdb_postgresql",
  "connection-string": "$env('my-connection-string')"
}
```
- typický formát připojovacího řetězce: "Host=mycosmosdb.postgres.database.azure.com;Database=myDataBase;Username=mylogin@mycosmosdb;Password=myPassword;Port=5432;SSL Mode=Require;"

Poznámka

Zadané možnosti, například database, containera schema, jsou specifické pro rozhraní API NoSQL služby Azure Cosmos DB, nikoli rozhraní API PostgreSQL. Pro službu Azure Cosmos DB využívající rozhraní API PostgreSQL by "možnosti" neobsály database, containerani schema jako v nastavení NoSQL.

Volby

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`data-source`	`options`	objekt	❌ Ne	Žádný

Volitelný oddíl parametrů extra klíč-hodnota pro konkrétní připojení databáze.

Formát

{
  "data-source": {
    "options": {
      "<key-name>": <string>
    }
  }
}

Příklady

Bez ohledu na to, jestli je oddíl options povinný nebo ne, je do značné míry závislý na používané databázové službě.

	Hodnota	Popis
Povolení `SESSION_CONTEXT` v Azure SQL nebo SQL Serveru	`"set-session-context": false`	V případě Azure SQL a SQL Serveru může tvůrce rozhraní Data API využít `SESSION_CONTEXT` k odesílání metadat zadaných uživatelem do podkladové databáze. Tato metadata jsou k dispozici tvůrci rozhraní Data API na základě deklarací identity, které jsou přítomné v přístupovém tokenu. Data `SESSION_CONTEXT` jsou k dispozici pro databázi během připojení k databázi, dokud toto připojení nebude ukončeno. Další informace najdete v tématu kontext relace.

{
  "data-source"{
    "options": {
        "set-session-context": false
    }
  }
}

Soubory zdroje dat

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`$root`	`data-source-files`	Řetězcové pole	❌ Ne	Žádný

Tvůrce rozhraní Data API podporuje více konfiguračních souborů pro různé zdroje dat, přičemž jeden je určený jako soubor nejvyšší úrovně, který spravuje nastavení runtime. Všechny konfigurace sdílejí stejné schéma, což umožňuje runtime nastavení v jakémkoli souboru bez chyb. Podřízené konfigurace se sloučí automaticky, ale cyklické odkazy by se měly vyhnout. Entity je možné rozdělit do samostatných souborů pro lepší správu, ale vztahy mezi entitami musí být ve stejném souboru.

diagram více konfiguračních souborů odkazovaných jako pole v rámci jednoho konfiguračního souboru.

Formát

{
  "data-source-files": [ <string> ]
}

Důležité informace o konfiguračních souborech

Každý konfigurační soubor musí obsahovat vlastnost data-source.
Každý konfigurační soubor musí obsahovat vlastnost entities.
Nastavení runtime se používá pouze z konfiguračního souboru nejvyšší úrovně, i když je součástí jiných souborů.
Podřízené konfigurační soubory můžou také obsahovat vlastní podřízené soubory.
Konfigurační soubory je možné uspořádat do podsložek podle potřeby.
Názvy entit musí být jedinečné ve všech konfiguračních souborech.
Vztahy mezi entitami v různých konfiguračních souborech se nepodporují.

Příklady

{
  "data-source-files": [
    "dab-config-2.json"
  ]
}

{
  "data-source-files": [
    "dab-config-2.json", 
    "dab-config-3.json"
  ]
}

Podporuje se také syntaxe podsložky:

{
  "data-source-files": [
    "dab-config-2.json",
    "my-folder/dab-config-3.json",
    "my-folder/my-other-folder/dab-config-4.json"
  ]
}

Runtime

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`$root`	`runtime`	objekt	✔️ Ano	Žádný

Oddíl runtime popisuje možnosti, které ovlivňují chování modulu runtime a nastavení pro všechny vystavené entity.

Formát

{
  "runtime": {
    "rest": {
      "path": <string> (default: /api),
      "enabled": <true> (default) | <false>,
      "request-body-strict": <true> (default) | <false>
    },
    "graphql": {
      "path": <string> (default: /graphql),
      "enabled": <true> (default) | <false>,
      "allow-introspection": <true> (default) | <false>
    },
    "host": {
      "mode": "production" (default) | "development",
      "cors": {
        "origins": ["<array-of-strings>"],
        "allow-credentials": <true> | <false> (default)
      },
      "authentication": {
        "provider": "StaticWebApps" (default) | ...,
        "jwt": {
          "audience": "<client-id>",
          "issuer": "<issuer-url>"
        }
      }
    }
  },
  "cache": {
    "enabled": <true> | <false> (default),
    "ttl-seconds": <integer; default: 5>
  },
  "pagination": {
    "max-page-size": <integer; default: 100000>,
    "default-page-size": <integer; default: 100>,
    "max-response-size-mb": <integer; default: 158>
  },
  "telemetry": {
    "application-insights": {
      "connection-string": <string>,
      "enabled": <true> | <false> (default)
    }
  }
}

Vlastnosti

	Požadovaný	Typ
`rest`	❌ Ne	objekt
`graphql`	❌ Ne	objekt
`host`	❌ Ne	objekt
`cache`	❌ Ne	objekt

Příklady

Tady je příklad oddílu modulu runtime s několika zadanými běžnými výchozími parametry.

{
  "runtime": {
    "rest": {
      "enabled": true,
      "path": "/api",
      "request-body-strict": true
    },
    "graphql": {
      "enabled": true,
      "path": "/graphql",
      "allow-introspection": true
    },
    "host": {
      "mode": "development",
      "cors": {
        "allow-credentials": false,
        "origins": [
          "*"
        ]
      },
      "authentication": {
        "provider": "StaticWebApps",
        "jwt": {
          "audience": "<client-id>",
          "issuer": "<identity-provider-issuer-uri>"
        }
      }
    },
    "cache": {
      "enabled": true,
      "ttl-seconds": 5
    },
    "pagination": {
      "max-page-size": -1 | <integer; default: 100000>,
      "default-page-size": -1 | <integer; default: 100>,
      "max-response-size-mb": <integer; default: 158>
    },
    "telemetry": {
      "application-insights": {
        "connection-string": "<connection-string>",
        "enabled": true
      }
    }
  }
}

GraphQL (modul runtime)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`runtime`	`graphql`	objekt	❌ Ne	Žádný

Tento objekt definuje, jestli je povolený GraphQL, a název[s] použitý k zveřejnění entity jako typu GraphQL. Tento objekt je nepovinný a používá se pouze v případě, že výchozí název nebo nastavení nestačí. Tato část popisuje globální nastavení koncového bodu GraphQL.

Formát

{
  "runtime": {
    "graphql": {
      "path": <string> (default: /graphql),
      "enabled": <true> (default) | <false>,
      "depth-limit": <integer; default: none>,
      "allow-introspection": <true> (default) | <false>,
      "multiple-mutations": <object>
    }
  }
}

Vlastnosti

Vlastnost	Požadovaný	Typ	Výchozí
`enabled`	❌ Ne	booleovský	Pravdivý
`path`	❌ Ne	řetězec	/graphql (výchozí)
`allow-introspection`	❌ Ne	booleovský	Pravdivý
`multiple-mutations`	❌ Ne	objekt	{ create: { enabled: false } }

Povoleno (modul runtime GraphQL)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`runtime.graphql`	`enabled`	booleovský	❌ Ne	Žádný

Definuje, jestli se mají koncové body GraphQL povolit nebo zakázat globálně. Pokud jsou globálně zakázané, nebudou žádné entity přístupné prostřednictvím požadavků GraphQL bez ohledu na nastavení jednotlivých entit.

Formát

{
  "runtime": {
    "graphql": {
      "enabled": <true> (default) | <false>
    }
  }
}

Příklady

V tomto příkladu je koncový bod GraphQL pro všechny entity zakázaný.

{
  "runtime": {
    "graphql": {
      "enabled": false
    }
  }
}

Limit hloubky (modul runtime GraphQL)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`runtime.graphql`	`depth-limit`	celé číslo	❌ Ne	Žádný

Maximální povolená hloubka dotazu.

Schopnost GraphQL zpracovávat vnořené dotazy na základě definic relací je neuvěřitelné funkce, která uživatelům umožňuje načítat složitá související data v jednom dotazu. Vzhledem k tomu, že uživatelé nadále přidávají vnořené dotazy, zvyšuje se složitost dotazu, což může nakonec ohrozit výkon a spolehlivost databáze i koncového bodu rozhraní API. Pro správu této situace nastaví vlastnost runtime/graphql/depth-limit maximální povolenou hloubku dotazu GraphQL (a mutace). Tato vlastnost umožňuje vývojářům dosáhnout rovnováhy, což uživatelům umožňuje využívat výhody vnořených dotazů a zároveň umisťovat limity, aby zabránili scénářům, které by mohly ohrozit výkon a kvalitu systému.

Příklady

{
  "runtime": {
    "graphql": {
      "depth-limit": 2
    }
  }
}

Cesta (modul runtime GraphQL)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`runtime.graphql`	`path`	řetězec	❌ Ne	/graphql

Definuje cestu URL, kde je dostupný koncový bod GraphQL. Pokud je například tento parametr nastavený na /graphql, zobrazí se koncový bod GraphQL jako /graphql. Ve výchozím nastavení je /graphqlcesta .

Důležitý

Pro tuto vlastnost nejsou povoleny dílčí cesty. Přizpůsobená hodnota cesty pro koncový bod GraphQL není aktuálně dostupná.

Formát

{
  "runtime": {
    "graphql": {
      "path": <string> (default: /graphql)
    }
  }
}

Příklady

V tomto příkladu je kořenový identifikátor URI GraphQL /query.

{
  "runtime": {
    "graphql": {
      "path": "/query"
    }
  }
}

Povolit introspekci (modul runtime GraphQL)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`runtime.graphql`	`allow-introspection`	booleovský	❌ Ne	Pravdivý

Tento logický příznak řídí schopnost provádět dotazy introspekce schématu v koncovém bodu GraphQL. Povolení introspekce umožňuje klientům dotazovat se na schéma na informace o dostupných typech dat, o typech dotazů, které mohou provádět, a dostupných mutacích.

Tato funkce je užitečná při vývoji pro pochopení struktury rozhraní GraphQL API a pro nástroje, které automaticky generují dotazy. V produkčních prostředích ale může být zakázáno zakrýt podrobnosti schématu rozhraní API a zvýšit zabezpečení. Ve výchozím nastavení je povolená introspekce, která umožňuje okamžité a komplexní zkoumání schématu GraphQL.

Formát

{
  "runtime": {
    "graphql": {
      "allow-introspection": <true> (default) | <false>
    }
  }
}

Příklady

V tomto příkladu je introspekce zakázaná.

{
  "runtime": {
    "graphql": {
      "allow-introspection": false
    }
  }
}

Více mutací (modul runtime GraphQL)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`runtime.graphql`	`multiple-mutations`	objekt	❌ Ne	Žádný

Nakonfiguruje všechny operace s více mutací pro modul runtime GraphQL.

Poznámka

Ve výchozím nastavení není povoleno více mutací a musí být explicitně nakonfigurováno tak, aby bylo povoleno.

Formát

{
  "runtime": {
    "graphql": {
      "multiple-mutations": {
        "create": {
          "enabled": <true> (default) | <false>
        }
      }
    }
  }
}

Vlastnosti

	Požadovaný	Typ
`create`	❌ Ne	objekt

Více mutací – vytvoření (modul runtime GraphQL)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`runtime.graphql.multiple-mutations`	`create`	booleovský	❌ Ne	Falešný

Nakonfiguruje několik operací vytváření pro modul runtime GraphQL.

Formát

{
  "runtime": {
    "graphql": {
      "multiple-mutations": {
        "create": {
          "enabled": <true> (default) | <false>
        }
      }
    }
  }
}

Vlastnosti

Vlastnost	Požadovaný	Typ	Výchozí
`enabled`	✔️ Ano	booleovský	Pravdivý

Příklady

V tomto příkladu je pro modul runtime GraphQL povolených více mutací. Konkrétně je více operací vytvoření povoleno zadáním hodnoty true pro vlastnost runtime.graphql.multiple-mutations.create.enabled.

{
  "runtime": {
    "graphql": {
      "multiple-mutations": {
        "create": {
          "enabled": true
        }
      }
    }
  }
}

REST (modul runtime)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`runtime`	`rest`	objekt	❌ Ne	Žádný

Tato část popisuje globální nastavení koncových bodů REST. Tato nastavení slouží jako výchozí hodnoty pro všechny entity, ale je možné je přepsat na základě jednotlivých entit v příslušných konfiguracích.

Formát

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

Vlastnosti

Vlastnost	Požadovaný	Typ	Výchozí
`enabled`	❌ Ne	booleovský	Pravdivý
`path`	❌ Ne	řetězec	/rozhraní api
`request-body-strict`	❌ Ne	booleovský	Pravdivý

Povoleno (modul runtime REST)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`runtime.rest`	`enabled`	booleovský	❌ Ne	Žádný

Logický příznak, který určuje globální dostupnost koncových bodů REST. Pokud jsou zakázané, entity se nedají získat přístup přes REST bez ohledu na nastavení jednotlivých entit.

Formát

{
  "runtime": {
    "rest": {
      "enabled": <true> (default) | <false>,
    }
  }
}

Příklady

V tomto příkladu je koncový bod rozhraní REST API pro všechny entity zakázaný.

{
  "runtime": {
    "rest": {
      "enabled": false
    }
  }
}

Cesta (modul runtime REST)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`runtime.rest`	`path`	řetězec	❌ Ne	"/api"

Nastaví cestu URL pro přístup ke všem zveřejněným koncovým bodům REST. Například nastavení path na /api zpřístupní koncový bod REST na /api/<entity>. Podřízené cesty nejsou povolené. Toto pole je volitelné, přičemž výchozí /api.

Poznámka

Při nasazování tvůrce rozhraní Data API pomocí static Web Apps (Preview) služba Azure automaticky vloží další dílčí cestu /data-api na adresu 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>. To je relevantní jenom pro Static Web Apps.

Formát

{
  "runtime": {
    "rest": {
      "path": <string> (default: /api)
    }
  }
}

Důležitý

Pro tuto vlastnost nejsou povoleny zadané dílčí cesty uživatelem.

Příklady

V tomto příkladu je identifikátor URI kořenového rozhraní REST API /data.

{
  "runtime": {
    "rest": {
      "path": "/data"
    }
  }
}

Spropitné

Pokud definujete entitu Author, bude koncový bod této entity /data/Author.

Text požadavku striktní (modul runtime REST)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`runtime.rest`	`request-body-strict`	booleovský	❌ Ne	Pravdivý

Tento logický příznak určuje, jestli tělo požadavku operace s mutací REST může obsahovat nadbytečná pole. Ve výchozím nastavení je hodnota true, což znamená, že nadbytečná pole v textu požadavku způsobí výjimku BadRequest. Nastavení tohoto příznaku na false ale umožňuje uživatelům zahrnout do textu požadavku další pole, která se ignorují. Je důležité si uvědomit, že tento příznak nemá vliv na požadavky dotazů REST (GET), protože text požadavku se vždy ignoruje pro operace GET.

Poznámka

Tento příznak nemá vliv na požadavky HTTP GET na koncový bod rozhraní REST API. Tělo požadavku je vždy ignorováno pro operace GET.

Formát

{
  "runtime": {
    "rest": {
      "request-body-strict": <true> (default) | <false>
    }
  }
}

Příklady

V tomto příkladu je zakázané přísné ověření textu požadavku.

{
  "runtime": {
    "rest": {
      "request-body-strict": false
    }
  }
}

Hostitel (modul runtime)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`runtime`	`host`	objekt	❌ Ne	Žádný

Oddíl host v konfiguraci modulu runtime poskytuje nastavení zásadní pro provozní prostředí tvůrce rozhraní Data API. Mezi tato nastavení patří provozní režimy, konfigurace CORS a podrobnosti o ověřování.

Formát

{
  "runtime": {
    "host": {
      "mode": "production" (default) | "development",
      "max-response-size-mb": <integer; default: 158>,
      "cors": {
        "origins": ["<array-of-strings>"],
        "allow-credentials": <true> | <false> (default)
      },
      "authentication": {
        "provider": "StaticWebApps" (default) | ...,
        "jwt": {
          "audience": "<client-id>",
          "issuer": "<issuer-url>"
        }
      }
    }
  }
}

Vlastnosti

Vlastnost	Požadovaný	Typ	Výchozí
`mode`	❌ Ne	enum string	výroba
`cors`	❌ Ne	objekt	Žádný
`authentication`	❌ Ne	objekt	Žádný

Příklady

Tady je příklad modulu runtime nakonfigurovaného pro hostování vývoje.

{
  "runtime": {
    "host": {
      "mode": "development",
      "cors": {
        "allow-credentials": false,
        "origins": ["*"]
      },
      "authentication": {
        "provider": "Simulator"
      }
    }
  }
}

Režim (modul runtime hostitele)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`runtime.host`	`mode`	řetězec	❌ Ne	"production"

Definuje, jestli by se modul tvůrce rozhraní Data API měl spouštět v režimu development nebo production. Výchozí hodnota je production.

Chyby podkladové databáze jsou obvykle podrobně zpřístupněny nastavením výchozí úrovně podrobností protokolů na Debug při vývoji. V produkčním prostředí je úroveň podrobností pro protokoly nastavená na Error.

Spropitné

Výchozí úroveň protokolu lze dále přepsat pomocí dab start --LogLevel <level-of-detail>. Další informace naleznete v rozhraní příkazového řádku (CLI) referenční.

Formát

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

Hodnoty

Tady je seznam povolených hodnot pro tuto vlastnost:

	Popis
`production`	Použití při hostování v produkčním prostředí v Azure
`development`	Použití při vývoji na místním počítači

Maximální velikost odpovědi (runtime)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`runtime.host`	`max-response-size-mb`	celé číslo	❌ Ne	158

Nastaví maximální velikost (v megabajtech) pro libovolný daný výsledek. Toto nastavení umožňuje uživatelům nakonfigurovat množství dat, která může paměť hostitelské platformy zpracovávat při streamování dat z podkladových zdrojů dat.

Když uživatelé požadují velké sady výsledků, mohou zatížit databázi a tvůrce rozhraní Data API. Pokud to chcete vyřešit, max-response-size-mb umožňuje vývojářům omezit maximální velikost odpovědi měřenou v megabajtech jako datové proudy ze zdroje dat. Tento limit vychází z celkové velikosti dat, nikoli počtu řádků. Vzhledem k tomu, že se sloupce můžou lišit ve velikosti, můžou některé sloupce (například text, binární soubor, XML nebo JSON) obsahovat až 2 GB, takže jednotlivé řádky mohou být velmi velké. Toto nastavení pomáhá vývojářům chránit své koncové body tím, že omezili velikost odpovědí a zabránili přetížení systému při zachování flexibility pro různé datové typy.

Povolené hodnoty

Hodnota	Výsledek
`null`	Výchozí hodnota je 158 megabajtů, pokud není nastavena nebo explicitně nastavena na `null`.
`integer`	Podporuje se jakékoli kladné 32bitové celé číslo.
`< 0`	Nepodporuje se. Pokud je nastavená hodnota menší než 1 MB, dojde k chybám ověření.

Formát

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

CORS (modul runtime hostitele)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`runtime.host`	`cors`	objekt	❌ Ne	Žádný

Nastavení sdílení prostředků mezi zdroji (CORS) pro hostitele modulu tvůrce dat

Formát

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

Vlastnosti

	Požadovaný	Typ
`allow-credentials`	❌ Ne	booleovský
`origins`	❌ Ne	Řetězcové pole

Povolit přihlašovací údaje (modul runtime hostitele)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`runtime.host.cors`	`allow-credentials`	booleovský	❌ Ne	Falešný

Pokud je hodnota true, nastaví Access-Control-Allow-Credentials hlavičku CORS.

Poznámka

Další informace o hlavičce CORS najdete v referenčníWEB Docs WEB Docs .

Formát

{
  "runtime": {
    "host": {
      "cors": {
        "allow-credentials": <true> (default) | <false>
      }
    }
  }
}

Origins (hostitelský modul runtime)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`runtime.host.cors`	`origins`	Řetězcové pole	❌ Ne	Žádný

Nastaví pole se seznamem povolených zdrojů pro CORS. Toto nastavení umožňuje * zástupný znak pro všechny původy.

Formát

{
  "runtime": {
    "host": {
      "cors": {
        "origins": ["<array-of-strings>"]
      }
    }
  }
}

Příklady

Tady je příklad hostitele, který umožňuje CORS bez přihlašovacích údajů ze všech zdrojů.

{
  "runtime": {
    "host": {
      "cors": {
        "allow-credentials": false,
        "origins": ["*"]
      }
    }
  }
}

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

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`runtime.host`	`authentication`	objekt	❌ Ne	Žádný

Konfiguruje ověřování pro hostitele tvůrce rozhraní Data API.

Formát

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "StaticWebApps" (default) | ...,
        "jwt": {
          "audience": "<string>",
          "issuer": "<string>"
        }
      }
    }
  }
}

Vlastnosti

Vlastnost	Požadovaný	Typ	Výchozí
`provider`	❌ Ne	enum string	StaticWebApps
`jwt`	❌ Ne	objekt	Žádný

ověřování a odpovědnost zákazníků

Tvůrce rozhraní DATA API je navržený tak, aby fungoval v rámci širšího kanálu zabezpečení a před zpracováním požadavků je potřeba nakonfigurovat důležité kroky. Je důležité si uvědomit, že Tvůrce rozhraní Data API neověřuje přímý volající (například vaši webovou aplikaci), ale spíše koncový uživatel na základě platného tokenu JWT poskytnutého důvěryhodným zprostředkovatelem identity (například ID Entra). Když požadavek dosáhne tvůrce rozhraní Data API, předpokládá, že token JWT je platný a zkontroluje ho podle všech požadavků, které jste nakonfigurovali, jako jsou konkrétní deklarace identity. Autorizační pravidla se pak použijí k určení, k čemu může uživatel přistupovat nebo upravovat.

Jakmile autorizace projde, tvůrce rozhraní Data API spustí požadavek pomocí účtu zadaného v připojovacím řetězci. Vzhledem k tomu, že tento účet často vyžaduje zvýšená oprávnění ke zpracování různých požadavků uživatelů, je nezbytné minimalizovat přístupová práva, aby se snížilo riziko. Doporučujeme zabezpečit architekturu konfigurací služby Private Link mezi front-endovou webovou aplikací a koncovým bodem rozhraní API a posílením zabezpečení počítače hostujícího tvůrce rozhraní Data API. Tato opatření pomáhají zajistit, aby vaše prostředí zůstalo zabezpečené, chránilo vaše data a minimalizovalo ohrožení zabezpečení, která by mohla být zneužita pro přístup k citlivým informacím, jejich úpravám nebo exfiltraci.

Zprostředkovatel (modul runtime hostitele)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`runtime.host.authentication`	`provider`	řetězec	❌ Ne	StaticWebApps

Nastavení authentication.provider v konfiguraci host definuje metodu ověřování používanou tvůrcem rozhraní Data API. Určuje, jak rozhraní API ověřuje identitu uživatelů nebo služeb, kteří se pokoušejí o přístup k prostředkům. Toto nastavení umožňuje flexibilitu při nasazování a integraci tím, že podporuje různé mechanismy ověřování přizpůsobené různým prostředím a požadavkům na zabezpečení.

Poskytovatel	Popis
`StaticWebApps`	Dává tvůrci rozhraní DATA API pokyn, aby vyhledala sadu hlaviček HTTP, která se nachází pouze při spuštění v prostředí Static Web Apps.
`AppService`	Pokud je modul runtime hostovaný ve službě Azure AppService s povoleným ověřováním AppService a nakonfigurovaným (EasyAuth).
`AzureAd`	Microsoft Entra Identity musí být nakonfigurovaná tak, aby mohl ověřit požadavek odeslaný tvůrci rozhraní DATA API (serverová aplikace). Další informace naleznete v tématu ověřování microsoft Entra ID.
`Simulator`	Konfigurovatelný zprostředkovatel ověřování, který dává modulu tvůrce rozhraní Data API pokyn, aby zpracovával všechny požadavky jako ověřené. Další informace najdete v tématu místní ověřování.

Formát

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "StaticWebApps" (default) | ...
      }
    }
  }
}

Hodnoty

Tady je seznam povolených hodnot pro tuto vlastnost:

	Popis
`StaticWebApps`	Azure Static Web Apps
`AppService`	Azure App Service
`AzureAD`	Microsoft Entra ID
`Simulator`	Simulátor

Webové tokeny JSON (modul runtime hostitele)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`runtime.host.authentication`	`jwt`	objekt	❌ Ne	Žádný

Pokud je zprostředkovatel ověřování nastavený na AzureAD (Microsoft Entra ID), je tato část nutná k určení cílové skupiny a vystavitelů tokenů JSOn Web Tokens (JWT). Tato data slouží k ověření tokenů vůči vašemu tenantovi Microsoft Entra.

Vyžaduje se, pokud je zprostředkovatel ověřování AzureAD pro ID Microsoft Entra. Tato část musí zadat audience a issuer k ověření přijatého tokenu JWT podle zamýšleného tenanta AzureAD pro ověření.

Nastavení	Popis
obecenstvo	Identifikuje zamýšlený příjemce tokenu; obvykle identifikátor aplikace zaregistrovaný ve službě Microsoft Entra Identity (nebo ve vašem zprostředkovateli identity), který zajišťuje, že token byl skutečně vydán pro vaši aplikaci.
emitent	Určuje adresu URL vydávající autority, což je služba tokenů, která vydala JWT. Tato adresa URL by se měla shodovat s adresou URL vystavitele zprostředkovatele identity, ze které bylo získáno JWT a které ověřuje původ tokenu.

Formát

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "StaticWebApps" (default) | ...,
        "jwt": {
          "audience": "<client-id>",
          "issuer": "<issuer-url>"
        }
      }
    }
  }
}

Vlastnosti

Vlastnost	Požadovaný	Typ	Výchozí
`audience`	❌ Ne	řetězec	Žádný
`issuer`	❌ Ne	řetězec	Žádný

Příklady

Tvůrce rozhraní DATA API (DAB) nabízí flexibilní podporu ověřování, integraci se servery Microsoft Entra Identity a vlastních webových tokenů JSON (JWT). Na této imagi JWT Server představuje ověřovací službu, která vydává tokeny JWT klientům po úspěšném přihlášení. Klient pak token předá daB, který může interrogovat své deklarace identity a vlastnosti.

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

Tady jsou příklady vlastnosti host vzhledem k různým možnostem architektury, které můžete v řešení provést.

Azure Static Web Apps

{
 "host": {
  "mode": "development",
  "cors": {
   "origins": ["https://dev.example.com"],
   "credentials": true
  },
  "authentication": {
   "provider": "StaticWebApps"
  }
 }
}

V StaticWebAppstvůrce rozhraní DATA API očekává, že Azure Static Web Apps ověří požadavek a X-MS-CLIENT-PRINCIPAL hlavička HTTP.

Azure App Service

{
 "host": {
  "mode": "production",
  "cors": {
   "origins": [ "https://api.example.com" ],
   "credentials": false
  },
  "authentication": {
   "provider": "AppService",
   "jwt": {
    "audience": "9e7d452b-7e23-4300-8053-55fbf243b673",
    "issuer": "https://example-appservice-auth.com"
   }
  }
 }
}

Ověřování se deleguje na podporovaného zprostředkovatele identity, kde je možné vydat přístupový token. Získaný přístupový token musí být součástí příchozích požadavků tvůrce rozhraní Data API. Tvůrce rozhraní DATA API pak ověří všechny prezentované přístupové tokeny a zajistí, aby tvůrce rozhraní Data API byl zamýšlenou cílovou skupinou tokenu.

Microsoft Entra ID

{
 "host": {
  "mode": "production",
  "cors": {
   "origins": [ "https://api.example.com" ],
   "credentials": true
  },
  "authentication": {
   "provider": "AzureAD",
   "jwt": {
    "audience": "c123d456-a789-0abc-a12b-3c4d56e78f90",
    "issuer": "https://login.microsoftonline.com/98765f43-21ba-400c-a5de-1f2a3d4e5f6a/v2.0"
   }
  }
 }
}

Simulátor (pouze vývoj)

{
 "host": {
  "mode": "development",
  "authentication": {
   "provider": "Simulator"
  }
 }
}

Cílová skupina (modul runtime hostitele)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`runtime.host.authentication.jwt`	`audience`	řetězec	❌ Ne	Žádný

Cílová skupina tokenu JWT.

Formát

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

Vystavitel (modul runtime hostitele)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`runtime.host.authentication.jwt`	`issuer`	řetězec	❌ Ne	Žádný

Vystavitel tokenu JWT.

Formát

{
  "runtime": {
    "host": {
      "authentication": {
        "jwt": {
          "issuer": "<issuer-url>"
        }
      }
    }
  }
}

Stránkování (modul runtime)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`runtime`	`pagination`	objekt	❌ Ne	Žádný

Konfiguruje limity stránkování.

Formát

{
  "runtime": {
    "pagination": {
      "max-page-size": <integer; default: 100000>,
      "default-page-size": <integer; default: 100>
    }
  }
}

Vlastnosti

Vlastnost	Požadovaný	Typ	Výchozí
`max-page-size`	❌ Ne	celé číslo	100,000
`default-page-size`	❌ Ne	celé číslo	100

Příklad

{
  "runtime": {
    "pagination": {
      "max-page-size": 100000,
      "default-page-size": 1
    }
  }
}

Příklad stránkování REST

V tomto příkladu by vydání https://localhost:5001/api/books REST GET vrátilo jeden záznam v poli value, protože default-page-size byla nastavena na hodnotu 1. Pokud existuje více výsledků, tvůrce rozhraní Data API připojí do odpovědi nextLink. nextLink obsahuje parametr $after pro načtení další stránky dat.

{
  "value": [
    {
      "id": 1000,
      "title": "Prelude to Foundation",
      "year": 1988,
      "pages": 403,
      "series_id": 10000
    }
  ],
  "nextLink": "https://localhost:5001/api/books?$after=W3siRW50aXR5TmFtZSI6ImJvb2tzIiwiRmllbGROYW1lI=="
}

Použití nextLink zajistí, že se vrátí další sada výsledků, i když se data mezi dotazy změnila.

Příklad stránkování GraphQL

Pro GraphQL použijte pro stránkování pole hasNextPage a endCursor. Ty jsou potřeba k načtení další sady výsledků. Bez nich je dotaz stále omezen na výchozí velikost stránky.

query {
  books {
    items {
      id,
      title,
      year,
      pages,
      series_id
    }
    hasNextPage
    endCursor
  }
}

Odpověď obsahuje pole hasNextPage a endCursor:

{
  "data": {
    "books": {
      "items": [
        {
          "id": 1000,
          "title": "Prelude to Foundation",
          "year": 1988,
          "pages": 403,
          "series_id": 10000
        }
      ],
      "hasNextPage": true,
      "endCursor": "W3siRW50aXR5TmFtZSI6ImJvb2tzIiwiRmllbGROYW1lI=="
    }
  }
}

Pokud chcete načíst další stránku, zahrňte do dalšího dotazu hodnotu kurzoru:

query {
  books(after: "W3siRW50aXR5TmFtZSI6ImJvb2tzIiwiRmllbGROYW1lI==") {
    items {
      id
      title
      year
      pages
      series_id
    }
    hasNextPage
    endCursor
  }
}

$limitvelikosti stránky pomocí first nebo :

REST i GraphQL podporují $limit nebo first parametr pro úpravu počtu výsledků na dotaz. Například https://{server}/api/books?$limit=10 omezí výsledek na 10 záznamů a přepisuje default-page-size. Pokud $limit překročí max-page-size, je výsledek omezen na max-page-size.

První hodnota	Výsledek
`-1`	Výchozí hodnota je aktuální nastavení `max-page-size`.
`< max-page-size`	Omezí výsledek na zadanou hodnotu.
`0`	Nepodporuje se.
`< -1`	Nepodporuje se.
`> max-page-size`	Nepodporuje se.

Maximální velikost stránky (modul runtime stránkování)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`runtime.pagination`	`max-page-size`	Int	❌ Ne	100,000

Nastaví maximální počet záznamů nejvyšší úrovně vrácených rozhraním REST nebo GraphQL. Pokud uživatel požaduje více než max-page-size, výsledky jsou omezeny na max-page-size.

Povolené hodnoty

Hodnota	Výsledek
`-1`	Výchozí hodnota je maximální podporovaná hodnota.
`integer`	Podporuje se jakékoli kladné 32bitové celé číslo.
`< -1`	Nepodporuje se.
`0`	Nepodporuje se.

Formát

{
  "runtime": {
    "pagination": {
      "max-page-size": <integer; default: 100000>
    }
  }
}

Výchozí velikost stránky (modul runtime stránkování)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`runtime.pagination`	`default-page-size`	Int	❌ Ne	100

Nastaví výchozí počet záznamů nejvyšší úrovně vrácených při povolení stránkování, ale není k dispozici žádná explicitní velikost stránky.

Povolené hodnoty

Hodnota	Výsledek
`-1`	Výchozí hodnota je aktuální nastavení `max-page-size`.
`integer`	Jakékoli kladné celé číslo menší než aktuální `max-page-size`.
`< -1`	Nepodporuje se.
`0`	Nepodporuje se.

Mezipaměť (modul runtime)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`runtime`	`cache`	objekt	❌ Ne	Žádný

Povolí a nakonfiguruje ukládání do mezipaměti pro celý modul runtime.

Formát

{
  "runtime": {
    "cache": <object>
  }
}

Vlastnosti

Vlastnost	Požadovaný	Typ	Výchozí
`enabled`	❌ Ne	booleovský	Žádný
`ttl-seconds`	❌ Ne	celé číslo	5

Příklady

V tomto příkladu je povolená mezipaměť a po 30 sekundách vyprší platnost položek.

{
  "runtime": {
    "cache": {
      "enabled": true,
      "ttl-seconds": 30
    }
  }
}

Povoleno (modul runtime mezipaměti)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`runtime.cache`	`enabled`	booleovský	❌ Ne	Falešný

Umožňuje globální ukládání do mezipaměti pro všechny entity. Výchozí hodnota falseje .

Formát

{
  "runtime": {
    "cache":  {
      "enabled": <boolean>
    }
  }
}

Příklady

V tomto příkladu je mezipaměť zakázaná.

{
  "runtime": {
    "cache": {
      "enabled": false
    }
  }
}

Hodnota TTL v sekundách (modul runtime mezipaměti)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`runtime.cache`	`ttl-seconds`	celé číslo	❌ Ne	5

Nakonfiguruje hodnotu TTL (Time to Live) v sekundách pro položky uložené v mezipaměti. Po uplynutí této doby se položky automaticky vyříznou z mezipaměti. Výchozí hodnota je 5 sekund.

Formát

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

Příklady

V tomto příkladu je mezipaměť povolená globálně a platnost všech položek vyprší po 15 sekundách.

{
  "runtime": {
    "cache": {
      "enabled": true,
      "ttl-seconds": 15
    }
  }
}

Telemetrie (modul runtime)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`runtime`	`telemetry`	objekt	❌ Ne	Žádný

Tato vlastnost konfiguruje Application Insights pro centralizaci protokolů rozhraní API. Další informace

Formát

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

Application Insights (modul runtime telemetrie)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`runtime.telemetry`	`application-insights`	objekt	✔️ Ano	Žádný

Povoleno (telemetrie Application Insights)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`runtime.telemetry.application-insights`	`enabled`	booleovský	❌ Ne	Pravdivý

Připojovací řetězec (telemetrie Application Insights)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`runtime.telemetry.application-insights`	`connection-string`	řetězec	✔️ Ano	Žádný

Entity

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`$root`	`entities`	objekt	✔️ Ano	Žádný

Oddíl entities slouží jako jádro konfiguračního souboru a vytváří most mezi databázovými objekty a jejich odpovídajícími koncovými body rozhraní API. Tato část mapuje databázové objekty na vystavené koncové body. Tato část obsahuje také mapování vlastností a definici oprávnění. Každá vystavená entita je definována ve vyhrazeném objektu. Název vlastnosti objektu se používá jako název entity, která se má zveřejnit.

Tato část definuje, jak se jednotlivé entity v databázi reprezentují v rozhraní API, včetně mapování vlastností a oprávnění. Každá entita je zapouzdřená do vlastní pododdílu s názvem entity, který funguje jako klíč pro referenci v celé konfiguraci.

Formát

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "enabled": <true; default: true> | <false>,
        "path": <string; default: "<entity-name>">,
        "methods": <array of strings; default: ["GET", "POST"]>
      },
      "graphql": {
        "enabled": <true; default: true> | <false>,
        "type": {
          "singular": <string>,
          "plural": <string>
        },
        "operation": <"query" | "mutation"; default: "query">
      },
      "source": {
        "object": <string>,
        "type": <"view" | "stored-procedure" | "table">,
        "key-fields": <array of strings>,
        "parameters": {
          "<parameter-name>": <string | number | boolean>
        }
      },
      "mappings": {
        "<database-field-name>": <string>
      },
      "relationships": {
        "<relationship-name>": {
          "cardinality": <"one" | "many">,
          "target.entity": <string>,
          "source.fields": <array of strings>,
          "target.fields": <array of strings>,
          "linking.object": <string>,
          "linking.source.fields": <array of strings>,
          "linking.target.fields": <array of strings>
        }
      },
      "permissions": [
        {
          "role": <"anonymous" | "authenticated" | "custom-role-name">,
          "actions": <array of strings>,
          "fields": {
            "include": <array of strings>,
            "exclude": <array of strings>
          },
          "policy": {
            "database": <string>
          }
        }
      ]
    }
  }
}

Vlastnosti

	Požadovaný	Typ
`source`	✔️ Ano	objekt
`permissions`	✔️ Ano	pole
`rest`	❌ Ne	objekt
`graphql`	❌ Ne	objekt
`mappings`	❌ Ne	objekt
`relationships`	❌ Ne	objekt
`cache`	❌ Ne	objekt

Příklady

Tento objekt JSON například dává tvůrci rozhraní Data API pokyn, aby zpřístupnil entitu GraphQL s názvem Author a koncový bod REST dostupný prostřednictvím cesty /Author. Databázová tabulka dbo.authors zálohuje entitu a konfigurace umožňuje každému anonymnímu přístupu ke koncovému bodu.

{
  "entities": {
    "Author": {
      "source": {
        "object": "dbo.authors",
        "type": "table"
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "*"
            }
          ]
        }
      ]
    }
  }
}

Tento příklad deklaruje entitu User. Tento název User se používá kdekoli v konfiguračním souboru, kde se na entity odkazují. Jinak název entity není pro koncové body relevantní.

{
  "entities": {
    "Book": {
      "rest": {
        "enabled": true,
        "path": "/books",
        "methods": ["GET", "POST", "PUT"]
      },
      "graphql": {
        "enabled": true,
        "type": {
          "singular": "Book",
          "plural": "Books"
        },
        "operation": "query"
      },
      "source": {
        "object": "BooksTable",
        "type": "table",
        "key-fields": ["Id"],
        "parameters": {}
      },
      "mappings": {
        "id": "Id",
        "title": "Title",
        "authorId": "AuthorId"
      },
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"],
          "fields": {
            "include": ["id", "title"],
            "exclude": []
          },
          "policy": {
            "database": "@claims.userId eq @item.authorId"
          }
        },
        {
          "role": "admin",
          "actions": ["create", "read", "update", "delete"],
          "fields": {
            "include": ["*"],
            "exclude": []
          },
          "policy": {
            "database": "@claims.userRoles has 'BookAdmin'"
          }
        }
      ]
    }
  }
}

Zdroj

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`entities.{entity}`	`source`	objekt	✔️ Ano	Žádný

Konfigurace {entity}.source připojí entitu vystavenou rozhraní API a její základní databázový objekt. Tato vlastnost určuje tabulku databáze, zobrazení nebo uloženou proceduru, kterou entita představuje, navazování přímého propojení pro načítání a manipulaci s daty.

V jednoduchých scénářích, kdy se entita mapuje přímo na jednoúčelovou tabulku nebo kolekci, potřebuje zdrojová vlastnost pouze název tohoto databázového objektu. Tato jednoduchost usnadňuje rychlé nastavení pro běžné případy použití.

Formát

{
  "entities": {
    "<entity-name>": {
      "source": {
        "object": <string>,
        "type": <"view" | "stored-procedure" | "table">, 
        "key-fields": <array of strings>,
        "parameters": {
          "<name>": <string | number | boolean>
        }
      }
    }
  }
}

Vlastnosti

	Požadovaný	Typ
`object`	✔️ Ano	řetězec
`type`	✔️ Ano	enum string
`parameters`	❌ Ne	objekt
`key-fields`	❌ Ne	Řetězcové pole

Příklady

Tento příklad ukazuje nejjednodušší strukturu pro přidružení entity ke zdrojové tabulce.

{
  "entities": {
    "Author": {
      "source": {
        "object": "dbo.authors",
        "type": "table"
      }
    }
  }
}

Tady je exmaple relace M:N.

diagram relace M:N mezi více databázovými tabulkami

{
  "entities": {
    "Todo": {
      "type": "stored-procedure",
      "source": {
        "type": "stored-procedure",
        "object": "GetUserTodos"
      },
      "parameters": {
        "UserId": 0, 
        "Completed": null,
        "CategoryName": null
      },
      "mapping": {
        "Id": "todo_id",
        "Title": "todo_title",
        "Description": "todo_description",
        "Completed": "todo_completed"
      }
    }
  }
}

Entita Todo zálohovaná uloženou procedurou.
Vlastnost type ve zdroji je nastavena na stored-procedureoznačující druh zdrojového objektu, na který je entita mapována.
Vlastnost object ve zdroji je název uložené procedury v databázi.

V tomto příkladu je do konfigurace entity Todo přidána (volitelná) vlastnost mapping. Určuje, jak se pole v entitě (Id, Title, Descriptiona Completed) mapuje na odpovídající pole v podkladovém zdroji dat nebo uložených parametrech procedury (todo_id, todo_title, todo_descriptiona todo_completed). Toto mapování zajišťuje předání správných dat mezi entitou a uloženou procedurou během operací vytvoření/aktualizace.

Předchozí příklad by použil následující postup SQL.

CREATE PROCEDURE GetUserTodos
    @UserId INT,
    @Completed BIT = NULL,
    @CategoryName NVARCHAR(100) = NULL
AS
BEGIN
    SELECT t.*
    FROM Todo t
    INNER JOIN users_todos ut ON t.id = ut.todo_id
    INNER JOIN Category c ON t.category_id = c.id
    WHERE ut.user_id = @UserId
    AND ISNULL(@Completed, t.completed)
    AND ISNULL(@CategoryName, c.name)
END

@UserId: Povinný parametr bez výchozí hodnoty.
@Completed: Volitelný parametr. V případě potřeby filtruje todos podle jejich stavu dokončení.
@CategoryName: Volitelný parametr. V případě potřeby filtruje todos podle názvu kategorie.

Tady je příklad aktualizací pomocí uložené procedury.

{
  "entities": {
    "Todo": {
      "type": "stored-procedure",
      "source": {
        "object": "UpsertTodo"
      },
      "method": "POST", // Specify the HTTP method as POST
      "parameters": {
        "Id": 0,
        "Title": null,
        "Description": null,
        "Completed": null
      }
    }
  }
}

Tento příklad explicitně nastaví metodu HTTP pro interakci s touto entitou tak, aby POST pomocí vlastnosti metody.

CREATE PROCEDURE UpsertTodo
    @Id INT,
    @Title NVARCHAR(100),
    @Description NVARCHAR(255),
    @Completed BIT
AS
BEGIN
    SET NOCOUNT ON;

    MERGE INTO Todo AS target
    USING (VALUES (@Id, @Title, @Description, @Completed)) AS source (Id, Title, Description, Completed)
    ON target.Id = source.Id
    WHEN MATCHED THEN
        UPDATE SET
            Title = source.Title,
            Description = source.Description,
            Completed = source.Completed
    WHEN NOT MATCHED THEN
        INSERT (Id, Title, Description, Completed)
        VALUES (source.Id, source.Title, source.Description, source.Completed);
END;

Objekt

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`entities.{entity}.source`	`object`	řetězec	✔️ Ano	Žádný

Název databázového objektu, který se má použít.

Příklady

V tomto příkladu object odkazuje na objekt dbo.books v databázi.

{
  "entities": {
    "Book": {
      "source": {
        "object": "dbo.books",
        "type": "table"
      }
    }
  }
}

Typ (entity)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`entities.{entity}.source`	`type`	řetězec	✔️ Ano	Žádný

Vlastnost type identifikuje typ databázového objektu za entitou, patří mezi ně view, tablea stored-procedure. Vlastnost type je povinná a není k dispozici výchozí hodnota.

Formát

{
  "entities": {
    "<entity-name>": {
      "type": <"view" | "stored-procedure" | "table">
    }
  }
}

Hodnoty

Tady je seznam povolených hodnot pro tuto vlastnost:

	Popis
`table`	Představuje tabulku.
`stored-procedure`	Představuje uloženou proceduru.
`view`	Představuje zobrazení.

Příklady

V tomto příkladu type označuje, že tento zdroj je zobrazení v databázi. Tato hodnota ovlivňuje, zda jsou požadovány jiné hodnoty (např. key-fields).

{
  "entities": {
    "Category": {
      "source": {
        "object": "dbo.vw_category_details",
        "type": "view",
        "key-fields": [
          "category_id"
        ]
      }
    }
  }
}

Klíčová pole

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`entities.{entity}.source`	`key-fields`	Řetězcové pole	❌ Ne	Žádný

Nastavení {entity}.key-fields je nezbytné pro entity zálohované zobrazeními, takže Tvůrce rozhraní DATA API ví, jak může v případě potřeby identifikovat a vrátit jednu položku. Pokud je type nastavena na view bez key-fields, modul tvůrce rozhraní Data API odmítne spustit.

Důležitý

Tato vlastnost je vyžadována, pokud typ objektu je view. Tato vlastnost je také povinný typ objektu je table bez definovaného primárního klíče.

Formát

{
  "entities": {
    "<entity-name>": {
      "source": {
        "type": <"view" | "stored-procedure" | "table">,
        "key-fields": <array of strings>
      }
    }
  }
}

Příklady

V tomto příkladu se používá zobrazení dbo.vw_category_details s category_id označeným jako pole klíče.

{
  "entities": {
    "Category": {
      "source": {
        "object": "dbo.vw_category_details",
        "type": "view",
        "key-fields": [
          "category_id"
        ]
      }
    }
  }
}

Parametry

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`entities.{entity}.source`	`parameters`	objekt	❌ Ne	Žádný

Nastavení {entity}.source.parameters je důležité pro entity zálohované uloženými procedurami, což vývojářům umožňuje zadat parametry a jejich výchozí hodnoty. Parametry zajišťují, že pokud nejsou v požadavku HTTP zadané určité parametry, může se systém vrátit k těmto předdefinovaným hodnotám.

Důležitý

Tato vlastnost je vyžadována, pokud typ objektu je stored-procedure.

Formát

{
  "entities": {
    "<entity-name>": {
      "source": {
        "type": "stored-procedure",
        "parameters": {
          "<parameter-name-1>": <string | number | boolean>,
          "<parameter-name-2>": <string | number | boolean>,
          "<parameter-name-3>": <string | number | boolean>
        }
      }
    }
  }
}

Příklady

Tento příklad vyvolá dbo.stp_get_bestselling_books uloženou proceduru, která předává tyto dva parametry:

	Hodnota
`depth`	25
`list`	contoso-best-sellers

{
  "entities": {
    "BestsellingBooks": {
      "source": {
        "object": "dbo.stp_get_bestselling_books",
        "type": "stored-procedure",
        "parameters": {
          "depth": 25,
          "list": "contoso-best-sellers"
        }
      }
    }
  }
}

Dovolení

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`entities.{entity}`	`permissions`	objekt	✔️ Ano	Žádný

Tato část definuje, kdo má přístup ke související entitě a jaké akce jsou povolené. Oprávnění jsou definována v této části v podmínkách rolí. Akce jsou definovány jako typické operace CRUD, včetně: create, read, updatea delete. Oddíl permissions definuje, kdo (z hlediska rolí) má přístup ke související entitě a pomocí kterých akcí. Akce jsou obvyklé operace CRUD: create, read, update, delete.

Formát

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "actions": <["create", "read", "update", "delete", "execute", "*"]>
        }
      ]
    }
  }
}

Akce	Popis
`create`	Umožňuje vytvořit nový záznam v entitě.
`read`	Umožňuje čtení nebo načítání záznamů z entity.
`update`	Umožňuje aktualizovat existující záznamy v entitě.
`delete`	Umožňuje odstranit záznamy z entity.
`execute`	Umožňuje spustit uloženou proceduru nebo operaci související s entitou.
`*`	Uděluje všechny příslušné operace CRUD.

Příklady

V tomto příkladu je definována anonymní role s přístupem ke všem možným akcím.

{
  "entities": {
    "Writer": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["*"]
        }
      ]
    }
  }
}

Můžete také kombinovat a shodovat akce řetězce a pole objektů.

{
  "entities": {
    "Reviewer": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read"
            },
            "create"
          ]        
        }
      ]
    }
  }
}

anonymní role Povolit anonymním uživatelům číst všechna pole kromě secret-field. Použití "include": ["*"] s "exclude": ["secret-field"] efektivně skryje secret-field od anonymních uživatelů a zároveň umožňuje přístup ke všem ostatním polím.

ověřených rolí Povolit ověřeným uživatelům číst a aktualizovat konkrétní pole, explicitně včetně id, titlea secret-field, ale pak vyloučit secret-field. Ukazuje explicitní zahrnutí a následné vyloučení secret-field, ukazující prioritu exclude. Vzhledem k tomu, že secret-field je zahrnuta i vyloučena, je nepřístupná, což odpovídá zamýšlenému pravidlu exclude má přednost.

Role autora Autoři můžou provádět všechny operace * na všech polích bez vyloučení. Soubor označuje "include": ["*"] s prázdným polem "exclude": [] uděluje přístup ke všem polím, protože žádná pole nejsou explicitně vyloučena.

Tato konfigurace představuje výchozí hodnotu, pokud není zadáno nic.

"fields": {
  "include": [],
  "exclude": []
}

Je to v podstatě stejné jako:

"fields": {
  "include": [ "*" ],
  "exclude": []
}

Zvažte také následující nastavení:

"fields": {
  "include": [],
  "exclude": ["*"]
}

Předchozí konfigurace efektivně určuje, že nejsou explicitně zahrnuta žádná pole ("include": [] je prázdná, což znamená, že nejsou povolena žádná pole) a že všechna pole jsou vyloučena ("exclude": ["*"] používá zástupný znak * k označení všech polí).

praktické použití: Taková konfigurace se může zdát neintuitivní, protože omezuje přístup ke všem polím. Dá se ale využít ve scénářích, kdy role může provádět určité akce – například vytvoření entity – bez přístupu k žádným datům.

Stejné chování, ale s jinou syntaxí, by bylo:

"fields": {
  "include": ["Id", "Title"],
  "exclude": ["*"]
}

Předchozí instalační program se pokusí určit, že by měla být zahrnuta pouze pole Id a Title, a zároveň indikuje, že všechna pole by měla být vyloučena se zástupnými znamény * v části exclude. Dalším způsobem, jak vyjádřit stejnou logiku, je:

"fields": {
  "include": ["Id", "Title"],
  "exclude": ["Id", "Title"]
}

Vzhledem k obecnému pravidlu, že seznam exclude má přednost před seznamem include, zadání exclude: ["*"] obvykle znamená, že všechna pole jsou vyloučena, a to i pole uvedená v části include. Na první pohled se proto může zdát, že tato konfigurace brání tomu, aby byla všechna pole přístupná, protože pravidlo vyloučení je dominantní.

Reverzní: Pokud je záměr udělit, je přístup pouze k polím Id a Title, je jasnější a spolehlivější zadat pouze tato pole v oddílu include a nepoužívat exclude se zástupným znakem. Případně můžete upravit logiku oprávnění systému tak, aby explicitně vyhovovala takovým případům za předpokladu, že máte kontrolu nad jeho návrhem. Například:

"fields": {
  "include": ["Id", "Title"],
  "exclude": []
}

Vlastnosti

	Požadovaný	Typ
`role`	✔️ Ano	řetězec
`actions` (pole řetězců) nebo `actions` (pole objektů)	✔️ Ano	object or string array

Role

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`entities.permissions`	`role`	řetězec	✔️ Ano	Žádný

Řetězec obsahující název role, na kterou se vztahuje definované oprávnění. Řetězec role obsahuje název role, na kterou se vztahuje definované oprávnění.

Role nastaví kontext oprávnění, ve kterém se má požadavek spustit. Pro každou entitu definovanou v konfiguraci modulu runtime můžete definovat sadu rolí a přidružených oprávnění, která určují, jak lze k entitě přistupovat v koncových bodech REST i GraphQL. Role nejsou sčítá. Další informace o rolích najdete v tématu autorizace.

Tvůrce rozhraní Data API vyhodnocuje požadavky v kontextu jedné role:

Role	Popis
`anonymous`	Žádný přístupový token se nepředá.
`authenticated`	Zobrazí se platný přístupový token.
`<custom-role>`	Zobrazí se platný přístupový token a `X-MS-API-ROLE` hlavička HTTP je zahrnuta s určením role uživatele, která je zahrnutá také do deklarace identity role přístupového tokenu.

Formát

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "role": <"anonymous" | "authenticated" | "custom-role">,
          "actions": <["create", "read", "update", "delete", "execute", "*"]>,
          "fields": {
            "include": <array of strings>,
            "exclude": <array of strings>
          }
        }
      ]
    }
  }
}

Příklady

Tento příklad definuje roli s názvem reader pouze s oprávněními read na koncovém bodu.

{
  "entities": {
    "Book": {
      "permissions": [
        {
          "role": "reader",
          "actions": [
            "read"
          ]        
        }
      ]
    }
  }
}

Akce (pole řetězců)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`entities.permissions`	`actions`	oneOf [řetězec, pole]	✔️ Ano	Žádný

Pole řetězcových hodnot s podrobnostmi o tom, jaké operace jsou pro přidruženou roli povolené. U databázových objektů table a view je možné role nakonfigurovat tak, aby používaly libovolnou kombinaci create, read, updatenebo akcí delete. U uložených procedur můžou mít role pouze execute akci. Pole actions podrobně popisuje, jaké akce jsou povolené u přidružené role. Pokud je entita buď tabulka, nebo zobrazení, je možné nakonfigurovat role pomocí kombinace akcí: create, read, update, delete.

Akce	Operace SQL
`*`	Zástupný znak, včetně spuštění
`create`	Vložení jednoho nebo více řádků
`read`	Výběr jednoho nebo více řádků
`update`	Úprava jednoho nebo více řádků
`delete`	Odstranění jednoho nebo více řádků
`execute`	Spustí uloženou proceduru.

Poznámka

U uložených procedur se akce se zástupným znakem (*) rozbalí na seznam, který obsahuje pouze execute akci. U tabulek a zobrazení se akce zástupných znaků rozbalí do seznamu, který obsahuje akce create, read, updatea delete.

Příklady

Tento příklad poskytuje create a read oprávnění k první roli s názvem contributor. Druhá role s názvem auditor má pouze oprávnění delete.

{
  "entities": {
    "CheckoutLogs": {
      "permissions": [
        {
          "role": "auditor",
          "actions": [
            "delete"
          ]        
        },
        {
          "role": "contributor",
          "actions": [
            "read",
            "create"
          ]
        }
      ]
    }
  }
}

Tady je další příklad.

{
  ...
  "entities": {
    "<entity-name>": {
      ...
      "permissions": [
        {
          "role": "contributor",
          "actions": ["read", "create"]
        }
      ]
    }
  }
}

Akce (pole objektů)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`entities.permissions`	`actions`	Řetězcové pole	✔️ Ano	Žádný

Poznámka

Formát

{
  "entities": {
    <string>: {
      "permissions": [
        {
          "role": <string>,
          "actions": [
            {
              "action": <string>,
              "fields": <array of strings>,
              "policy": <object>
            }
          ]
        }
      ]
    }
  }
}

Vlastnosti

Vlastnost	Požadovaný	Typ	Výchozí
`action`	✔️ Ano	řetězec	Žádný
`fields`	❌ Ne	Řetězcové pole	Žádný
`policy`	❌ Ne	objekt	Žádný

Příklady

Tento příklad uděluje oprávnění pouze read roli auditor. Role auditor může číst pouze konkrétní data pomocí predikátu definovaného v policy.database. Role auditor je také omezená na pole, která může nebo nemůže číst pomocí vlastnosti fields.

{
  "entities": {
    "CheckoutLogs": {
      "permissions": [
        {
          "role": "auditor",
          "actions": [
            {
              "action": "read",
              "fields": {
                "include": ["*"],
                "exclude": ["last_updated"]
              },
              "policy": {
                "database": "@item.LogDepth lt 3"
              }
            }
          ]
        }
      ]
    }
  }
}

Akce

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`entities.permissions.actions[]`	`action`	řetězec	✔️ Ano	Žádný

Určuje konkrétní operaci povolenou pro databázový objekt.

Hodnoty

Tady je seznam povolených hodnot pro tuto vlastnost:

	Tabulky	Pohledy	Uložené procedury	Popis
`create`	✔️ Ano	✔️ Ano	❌ Ne	Vytvoření nových položek
`read`	✔️ Ano	✔️ Ano	❌ Ne	Čtení existujících položek v bodech
`update`	✔️ Ano	✔️ Ano	❌ Ne	Aktualizace nebo nahrazení existujících položek
`delete`	✔️ Ano	✔️ Ano	❌ Ne	Odebrání existujících položek
`execute`	❌ Ne	❌ Ne	✔️ Ano	Provádění programových operací

Formát

{
  "entities": {
    <string>: {
      "permissions": [
        {
          "role": <string>,
          "actions": [
            {
              "action": <string>,
              "fields": <object>,
              "policy": <object>
            }
          ]
        }
      ]
    }
  }
}

Příklady

Tady je příklad, kdy anonymous uživatelé mohou execute konkrétní uloženou proceduru a read konkrétní tabulku.

{
  "entities": {
    "Author": {
      "source": {
        "object": "dbo.authors",
        "type": "table"
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read"
            }
          ]
        }
      ]
    },
    "BestSellingAuthor": {
      "source": {
        "object": "dbo.stp_get_bestselling_authors",
        "type": "stored-procedure",
        "parameters": {
          "depth": 10
        }
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "execute"
            }
          ]
        }
      ]
    }
  }
}

Pole

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`entities.permissions.actions[]`	`fields`	objekt	❌ Ne	Žádný

Podrobné specifikace, ke kterým mají konkrétní pole povolený přístup k databázovému objektu. Konfigurace role je typ objektu se dvěma vnitřními vlastnostmi, include a exclude. Tyto hodnoty podporují podrobnou definici, které databázové sloupce (pole) mají povolený přístup v oddílu fields.

Formát

{
  "entities": {
    <string>: {
      "permissions": [
        {
          "role": <string>,
          "actions": [
            {
              "action": <string>,
              "fields": {
                "include": <array of strings>,
                "exclude": <array of strings>
              },
              "policy": <object>
            }
          ]
        }
      ]
    }
  }
}

Příklady

V tomto příkladu může role anonymous číst ze všech polí kromě id, ale může použít všechna pole při vytváření položky.

{
  "entities": {
    "Author": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "fields": {
                "include": [ "*" ],
                "exclude": [ "id" ]
              }
            },
            { "action": "create" }
          ]
        }
      ]
    }
  }
}

Zahrnout a vyloučit spolupráci. Zástupný znak * v části include označuje všechna pole. Pole, která jsou uvedena v oddílu exclude, mají přednost před poli, která jsou uvedena v oddílu include. Definice se přeloží na zahrnují všechna pole kromě pole last_updated.

"Book": {
    "source": "books",
    "permissions": [
        {
            "role": "anonymous",
            "actions": [ "read" ],
            // Include All Except Specific Fields
            "fields": {
              "include": [ "*" ],
              "exclude": [ "secret-field" ]
            }
        },
        {
            "role": "authenticated",
            "actions": [ "read", "update" ],
            // Explicit Include and Exclude
            "fields": {
              "include": [ "id", "title", "secret-field" ],
              "exclude": [ "secret-field" ]
            }
        },
        {
            "role": "author",
            "actions": [ "*" ],
            // Include All With No Exclusions (default)
            "fields": {
              "include": ["*"],
              "exclude": []
            }
        }
    ]
}

Politika

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`entities.{entity}.permissions.actions[]`	`policy`	objekt	❌ Ne	Žádný

Oddíl policy definovaný podle actiondefinuje pravidla zabezpečení na úrovni položek (zásady databáze), která omezují výsledky vrácené žádostí. Pododdíl database označuje výraz zásad databáze, který se vyhodnocuje během provádění požadavku.

Formát

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "role": <string>,
          "actions": [
            {
              "action": <string>,
              "fields": <object>,
              "policy": {
                "database": <string>
              }
            }
          ]
        }
      ]
    }
  }
}

Vlastnosti

Vlastnost	Požadovaný	Typ	Výchozí
`database`	✔️ Ano	řetězec	Žádný

Popis

Zásada database: výraz podobný OData, který se překládá do predikátu dotazu, vyhodnocuje databázi, včetně operátorů, jako jsou eq, lta gt. Aby se výsledky vrátily pro požadavek, musí se predikát dotazu požadavku vyřešený ze zásad databáze vyhodnotit tak, aby se při provádění v databázi true.

Ukázkové zásady položek	Predikát
`@item.OwnerId eq 2000`	`WHERE Table.OwnerId = 2000`
`@item.OwnerId gt 2000`	`WHERE Table.OwnerId > 2000`
`@item.OwnerId lt 2000`	`WHERE Table.OwnerId < 2000`

predicate je výraz, který se vyhodnotí jako PRAVDA nebo NEPRAVDA. Predikáty se používají ve vyhledávací podmínce KLAUZULE WHERE a KLAUZULE HAVING, podmínky spojení FROM klauzule a další konstrukty, kde je vyžadována logická hodnota. (Microsoft Learn Docs )

Zásady databáze

Při vytváření výrazu zásad databáze je možné použít dva typy direktiv:

Směrnice	Popis
`@claims`	Přístup k deklaraci identity v rámci ověřeného přístupového tokenu poskytnutého v požadavku
`@item`	Představuje pole entity, pro kterou je definována zásada databáze.

Poznámka

Pokud je nakonfigurované ověřování Azure Static Web Apps (EasyAuth), je v zásadách databáze k dispozici omezený počet typů deklarací identity: identityProvider, userId, userDetailsa userRoles. Další informace najdete v dokumentaci k dat instančního objektu klienta služby Azure Static Web App.

Tady je několik ukázkových zásad databáze:

@claims.userId eq @item.OwnerId
@claims.userId gt @item.OwnerId
@claims.userId lt @item.OwnerId

Tvůrce rozhraní DATA API porovnává hodnotu deklarace identity UserId s hodnotou pole databáze OwnerId. Datová část výsledku obsahuje pouze záznamy, které splňují metadata požadavku i výraz zásady databáze.

Omezení

Zásady databáze jsou podporovány pro tabulky a zobrazení. Uložené procedury nelze konfigurovat pomocí zásad.

Zásady databáze nezabrání provádění požadavků v databázi. Toto chování je způsobeno tím, že jsou vyřešeny jako predikáty ve vygenerovaných dotazech, které se předávají databázovému stroji.

Zásady databáze jsou podporovány pouze pro actionsvytváření, čtení, aktualizace a odstranění. Vzhledem k tomu, že ve volání uložené procedury není žádný predikát, není možné je připojit.

Podporované operátory typu OData

Operátor	Popis	Ukázková syntaxe
`and`	Logický operátor AND	`"@item.status eq 'active' and @item.age gt 18"`
`or`	Logický operátor OR	`"@item.region eq 'US' or @item.region eq 'EU'"`
`eq`	Rovná se	`"@item.type eq 'employee'"`
`gt`	Větší než	`"@item.salary gt 50000"`
`lt`	Méně než	`"@item.experience lt 5"`

Další informace naleznete v tématu binární operátory.

Operátor	Popis	Ukázková syntaxe
`-`	Negate (číselné)	`"@item.balance lt -100"`
`not`	Logická negate (NOT)	`"not @item.status eq 'inactive'"`

Další informace naleznete v tématu unární operátory.

Omezení názvu pole entity

Pravidla: Musí začínat písmenem nebo podtržítkem (_), za nimi až 127 písmen, podtržítka (_) nebo číslicemi (0-9).
dopad: Pole, která nedosáží k těmto pravidlům, se nedají přímo použít v zásadách databáze.
řešení: Pomocí oddílu mappings vytvořte aliasy pro pole, která nesplňují tyto zásady vytváření názvů; mapování zajistí, že všechna pole mohou být zahrnuta do výrazů zásad.

Využití `mappings` pro nekonformní pole

Pokud názvy polí entity nevyhovují pravidlům syntaxe OData nebo je chcete jednoduše aliasovat z jiných důvodů, můžete aliasy definovat v části mappings konfigurace.

{
  "entities": {
    "<entity-name>": {
      "mappings": {
        "<field-1-name>": <string>,
        "<field-2-name>": <string>,
        "<field-3-name>": <string>
      }
    }
  }
}

V tomto příkladu field-1-name je původní název databázového pole, který nesplňuje konvence vytváření názvů OData. Vytvoření mapy pro field-1-name a field-1-alias umožňuje odkazovat na toto pole ve výrazech zásad databáze bez problému. Tento přístup nejen pomáhá dodržovat zásady vytváření názvů OData, ale také zlepšuje přehlednost a přístupnost datového modelu v rámci koncových bodů GraphQL i RESTful.

Příklady

Představte si entitu s názvem Employee v rámci konfigurace rozhraní Data API, která využívá direktivy deklarací identity i položky. Zajišťuje bezpečnou správu přístupu k datům na základě rolí uživatelů a vlastnictví entit:

{
  "entities": {
    "Employee": {
      "source": {
        "object": "HRUNITS",
        "type": "table",
        "key-fields": ["employee NUM"],
        "parameters": {}
      },
      "mappings": {
        "employee NUM": "EmployeeId",
        "employee Name": "EmployeeName",
        "department COID": "DepartmentId"
      },
      "policy": {
        "database": "@claims.role eq 'HR' or @claims.userId eq @item.EmployeeId"
      }
    }
  }
}

definici entity: Entita Employee je nakonfigurovaná pro rozhraní REST a GraphQL, což znamená, že jejich data je možné dotazovat nebo manipulovat prostřednictvím těchto koncových bodů.

konfigurace zdroje: Identifikuje HRUNITS v databázi s employee NUM jako pole klíče.

mapování : Aliasy se používají k mapování employee NUM, employee Namea department COID na EmployeeId, EmployeeNamea DepartmentId, což zjednodušuje názvy polí a potenciálně obfukuje podrobnosti o citlivém schématu databáze.

aplikace zásad: Oddíl policy použije zásady databáze pomocí výrazu podobného OData. Tato zásada omezuje přístup k datům uživatelům s rolí hr (@claims.role eq 'HR') nebo pro uživatele, jejichž UserId deklarace identity odpovídá EmployeeId – alias pole – v databázi (@claims.userId eq @item.EmployeeId). Zajišťuje, aby zaměstnanci měli přístup pouze k vlastním záznamům, pokud nepatří do personálního oddělení. Zásady můžou vynutit zabezpečení na úrovni řádků na základě dynamických podmínek.

Databáze

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`entities.{entity}.permissions.actions.policy`	`database`	objekt	✔️ Ano	Žádný

Formát

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "role": <string>,
          "actions": [
            {
              "action": <string>,
              "fields": {
                "include": <array of strings>,
                "exclude": <array of strings>
              },
              "policy": {
                "database": <string>
              }
            }
          ]
        }
      ]
    }
  }
}

Tato vlastnost označuje výraz zásad databáze, který se vyhodnocuje během provádění požadavku. Řetězec zásady je výraz OData, který je přeložen do predikátu dotazu vyhodnoceného databází. Například výraz zásad @item.OwnerId eq 2000 se přeloží na predikát dotazu WHERE <schema>.<object-name>.OwnerId = 2000.

Poznámka

predikátu je výraz, který vyhýbá , nebo . Predikáty se používají v:

Podmínka hledání klauzulí WHERE
Podmínka hledání klauzulí FROM
Podmínky spojení FROM klauzulí
Jiné konstrukce, kde je vyžadována logická hodnota.

Další informace naleznete v predikáty.

Aby se výsledky vrátily pro požadavek, musí se predikát dotazu požadavku vyřešený ze zásad databáze vyhodnotit tak, aby se při provádění v databázi true.

Při vytváření výrazu zásad databáze se dají použít dva typy direktiv:

	Popis
`@claims`	Přistupuje k deklaraci identity v rámci ověřeného přístupového tokenu poskytnutého v požadavku.
`@item`	Představuje pole entity, pro kterou je definována zásada databáze.

Poznámka

Při konfiguraci ověřování Azure Static Web Apps (EasyAuth) je k dispozici omezený počet typů deklarací identity, které se dají použít v zásadách databáze. Mezi tyto typy deklarací patří: identityProvider, userId, userDetailsa userRoles. Další informace najdete v tématu data objektu zabezpečení klienta Azure Static Web Apps.

Příklady

Výraz základní zásady může například vyhodnotit, jestli je určité pole v tabulce pravdivé. Tento příklad vyhodnotí, jestli je pole soft_deletefalse.

{
  "entities": {
    "Manuscripts": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "@item.soft_delete eq false"
              }
            }
          ]
        }
      ]
    }
  }
}

Predikáty mohou také vyhodnotit typy direktiv claims i item. Tento příklad načte pole UserId z přístupového tokenu a porovná ho s polem owner_id v cílové tabulce databáze.

{
  "entities": {
    "Manuscript": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "@claims.userId eq @item.owner_id"
              }
            }
          ]
        }
      ]
    }
  }
}

Omezení

Zásady databáze jsou podporovány pro tabulky a zobrazení. Uložené procedury nelze konfigurovat pomocí zásad.
Zásady databáze se nedají použít k tomu, aby se zabránilo spuštění požadavku v databázi. Toto omezení je způsobeno tím, že zásady databáze se přeloží jako predikáty dotazů ve vygenerovaných databázových dotazech. Databázový stroj nakonec tyto dotazy vyhodnocuje.
Zásady databáze jsou podporovány pouze pro actionscreate, read, updatea delete.
Syntaxe výrazů OData zásad databáze podporuje pouze tyto scénáře.
- Binární operátory, včetně, ale nikoli pouze; and, or, eq, gta lt. Další informace najdete na webu BinaryOperatorKind.
- Unární operátory, jako jsou - (negate) a operátory not. Další informace najdete na webu UnaryOperatorKind.
Zásady databáze mají také omezení související s názvy polí.
- Názvy polí entity, které začínají písmenem nebo podtržítkem, následované maximálně 127 písmeny, podtržítky nebo číslicemi.
- Tento požadavek je určen pro specifikaci OData. Další informace naleznete v tématu OData Common Schema Definition Language.

Spropitné

Na pole, která neodpovídají uvedeným omezením, nelze odkazovat v zásadách databáze. Jako alternativní řešení nakonfigurujte entitu s oddílem mapování tak, aby přiřazování odpovídajících aliasů k polím.

GraphQL (entity)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`entities.{entity}`	`graphql`	objekt	❌ Ne	Žádný

Tento segment poskytuje integraci entity do schématu GraphQL. Umožňuje vývojářům zadat nebo upravit výchozí hodnoty entity v GraphQL. Toto nastavení zajišťuje, že schéma přesně odpovídá zamýšleným strukturám a konvencím vytváření názvů.

Formát

{
  "entities": {
    "<entity-name>": {
      "graphql": {
        "enabled": <true> (default) | <false>,
        "type": {
          "singular": <string>,
          "plural": <string>
        },
        "operation": "query" (default) | "mutation"
      }
    }
  }
}

{
  "entities": {
    "<entity-name>": {
      "graphql": {
        "enabled": <boolean>,
        "type": <string-or-object>,
        "operation": "query" (default) | "mutation"
      }
    }
  }
}

Vlastnosti

Vlastnost	Požadovaný	Typ	Výchozí
`enabled`	❌ Ne	booleovský	Žádný
`type`	❌ Ne	řetězec nebo objekt	Žádný
`operation`	❌ Ne	enum string	Žádný

Příklady

Tyto dva příklady jsou funkčně ekvivalentní.

{
  "entities": {
    "Author": {
      "graphql": true
    }
  }
}

{
  "entities": {
    "Author": {
      "graphql": {
        "enabled": true
      }
    }
  }
}

V tomto příkladu je definována entita Book, což znamená, že pracujeme se sadou dat souvisejících s knihami v databázi. Konfigurace entity Book v segmentu GraphQL nabízí jasnou strukturu, jak by měla být reprezentována a interagována ve schématu GraphQL.

povolenou vlastnost: Entita Book je zpřístupněna prostřednictvím GraphQL ("enabled": true), což znamená, že vývojáři a uživatelé můžou dotazovat nebo ztlumit data knih prostřednictvím operací GraphQL.

Vlastnost Typ: Entita je reprezentována s jedinečným názvem "Book" a "Books" v množném čísle ve schématu GraphQL. Toto rozlišení zajišťuje, že při dotazování na jednu knihu nebo více knih schéma nabízí intuitivně pojmenované typy (Book pro jednu položku, Books pro seznam), což zvyšuje použitelnost rozhraní API.

Vlastnost operace: Operace je nastavena na "query", což znamená, že primární interakce s entitou Book prostřednictvím GraphQL je určena k dotazování (načítání) dat namísto ztlumení (vytváření, aktualizace nebo odstraňování). Toto nastavení odpovídá typickým vzorům použití, kdy se data knih častěji čtou, než se změnila.

{
  "entities": {
    "Book": {
      ...
      "graphql": {
        "enabled": true,
        "type": {
          "singular": "Book",
          "plural": "Books"
        },
        "operation": "query"
      },
      ...
    }
  }
}

Typ (entita GraphQL)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`entities.{entity}.graphql`	`type`	oneOf [string, object]	❌ Ne	{entity-name}

Tato vlastnost určuje konvenci vytváření názvů pro entitu ve schématu GraphQL. Podporuje skalární řetězcové hodnoty i typy objektů. Hodnota objektu určuje jednotné a množné číslo formuláře. Tato vlastnost poskytuje podrobnou kontrolu nad čitelností schématu a uživatelským prostředím.

Formát

{
  "entities": {
    <entity-name>: {
      "graphql": {
        "type": <string>
      }
    }
  }
}

{
  "entities": {
    <entity-name>: {
      "graphql": {
        "type": {
          "singular": <string>,
          "plural": <string>
        }
      }
    }
  }
}

Vlastnosti

Vlastnost	Požadovaný	Typ	Výchozí
`singular`	❌ Ne	řetězec	Žádný
`plural`	❌ Ne	řetězec	Není k dispozici (výchozí hodnota: jednotné číslo)

Příklady

Pro ještě větší kontrolu nad typem GraphQL můžete nakonfigurovat, jak je název v jednotném čísle a množném čísle reprezentován nezávisle.

Pokud plural chybí nebo vynechá (například skalární hodnota), tvůrce rozhraní DATA API se pokusí název automaticky vyčíslit podle anglických pravidel pro pluralizaci (například: https://engdic.org/singular-and-plural-noun-rules-definitions-examples)

{
  "entities" {
    "<entity-name>": {
      ...
      "graphql": {
        ...
        "type": {
          "singular": "User",
          "plural": "Users"
        }
      }
    }
  }
}

Název vlastní entity lze zadat pomocí parametru type s řetězcovou hodnotou. V tomto příkladu modul automaticky rozlišuje jednotné číslo a množné číslo tohoto názvu pomocí běžných anglických pravidel pro pluralizaci.

{
  "entities": {
    "Author": {
      "graphql": {
        "type": "bookauthor"
      }
    }
  }
}

Pokud se rozhodnete názvy explicitně zadat, použijte vlastnosti type.singular a type.plural. Tento příklad explicitně nastaví oba názvy.

{
  "entities": {
    "Author": {
      "graphql": {
        "type": {
          "singular": "bookauthor",
          "plural": "bookauthors"
        }
      }
    }
  }
}

Oba příklady jsou funkčně ekvivalentní. Oba vrátí stejný výstup JSON pro dotaz GraphQL, který používá název entity bookauthors.

{
  bookauthors {
    items {
      first_name
      last_name
    }
  }
}

{
  "data": {
    "bookauthors": {
      "items": [
        {
          "first_name": "Henry",
          "last_name": "Ross"
        },
        {
          "first_name": "Jacob",
          "last_name": "Hancock"
        },
        ...
      ]
    }
  }
}

Operace (entita GraphQL)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`entities.{entity}.graphql`	`operation`	enum string	❌ Ne	Žádný

U entit mapovaných na uložené procedury určuje vlastnost operation typ operace GraphQL (dotaz nebo mutaci), kde je uložená procedura přístupná. Toto nastavení umožňuje logické uspořádání schématu a dodržování osvědčených postupů GraphQL, aniž by to mělo vliv na funkčnost.

Poznámka

Entita je určena jako uložená procedura nastavením hodnoty vlastnosti {entity}.type na stored-procedure. V případě uložené procedury se automaticky vytvoří nový typ GraphQL executeXXX. Vlastnost operation však umožňuje vývojáři převést umístění tohoto typu do mutation nebo query části schématu. Tato vlastnost umožňuje hygene schématu a bez ohledu na hodnotu operation neexistuje žádný funkční dopad.

Pokud chybí, výchozí operation je mutation.

Formát

{
  "entities": {
    "<entity-name>": {
      "graphql": {
        "operation": "query" (default) | "mutation"
      }
    }
  }
}

Hodnoty

Tady je seznam povolených hodnot pro tuto vlastnost:

	Popis
`query`	Podkladová uložená procedura se zobrazí jako dotaz.
`mutation`	Základní uložená procedura je vystavena jako mutační

Příklady

Pokud je operationmutation, schéma GraphQL by vypadalo přibližně takto:

type Mutation {
  executeGetCowrittenBooksByAuthor(
    searchType: String = "S"
  ): [GetCowrittenBooksByAuthor!]!
}

Pokud je operationquery, schéma GraphQL by vypadalo přibližně takto:

Schéma GraphQL by vypadalo přibližně takto:

type Query {
  executeGetCowrittenBooksByAuthor(
    searchType: String = "S"
  ): [GetCowrittenBooksByAuthor!]!
}

Poznámka

Vlastnost operation se týká pouze umístění operace ve schématu GraphQL, nemění chování operace.

Povoleno (entita GraphQL)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`entities.{entity}.graphql`	`enabled`	booleovský	❌ Ne	Pravdivý

Povolí nebo zakáže koncový bod GraphQL. Určuje, jestli je entita dostupná prostřednictvím koncových bodů GraphQL. Přepnutí vlastnosti enabled umožňuje vývojářům selektivně zveřejnit entity ze schématu GraphQL.

Formát

{
  "entities": {
    "<entity-name>": {
      "graphql": {
        "enabled": <true> (default) | <false>
      }
    }
  }
}

REST (entity)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`entities.{entity}`	`rest`	objekt	❌ Ne	Žádný

Oddíl rest konfiguračního souboru je vyhrazený pro vyladění koncových bodů RESTful pro každou entitu databáze. Tato možnost přizpůsobení zajišťuje, aby vystavené rozhraní REST API odpovídalo konkrétním požadavkům a zlepšilo se jeho nástroje i možnosti integrace. Řeší potenciální neshody mezi výchozím nastavením odvozených a požadovanými chováními koncových bodů.

Formát

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "enabled": <true> (default) | <false>,
        "path": <string; default: "<entity-name>">,
        "methods": <array of strings; default: ["GET", "POST"]>
      }
    }
  }
}

Vlastnosti

Vlastnost	Požadovaný	Typ	Výchozí
`enabled`	✔️ Ano	booleovský	Pravdivý
`path`	❌ Ne	řetězec	`/<entity-name>`
`methods`	❌ Ne	Řetězcové pole	DOSTAT

Příklady

Tyto dva příklady jsou funkčně ekvivalentní.

{
  "entities": {
    "Author": {
      "source": {
        "object": "dbo.authors",
        "type": "table"
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["*"]
        }
      ],
      "rest": true
    }
  }
}

{
  "entities": {
    "Author": {
      ...
      "rest": {
        "enabled": true
      }
    }
  }
}

Tady je další příklad konfigurace REST pro entitu.

{
  "entities" {
    "User": {
      "rest": {
        "enabled": true,
        "path": "/User"
      },
      ...
    }
  }
}

Povoleno (entita REST)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`entities.{entity}.rest`	`enabled`	booleovský	❌ Ne	Pravdivý

Tato vlastnost funguje jako přepínač pro viditelnost entit v rozhraní REST API. Nastavením vlastnosti enabled na true nebo falsemůžou vývojáři řídit přístup ke konkrétním entitám a umožnit tak přizpůsobenou plochu rozhraní API, která odpovídá požadavkům na zabezpečení a funkčnost aplikací.

Formát

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "enabled": <true> (default) | <false>
      }
    }
  }
}

Cesta (entita REST)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`entities.rest`	`path`	řetězec	❌ Ne	Žádný

Vlastnost path určuje segment identifikátoru URI, který se používá pro přístup k entitě prostřednictvím rozhraní REST API. Toto přizpůsobení umožňuje popisnější nebo zjednodušené cesty koncových bodů nad rámec výchozího názvu entity, což vylepšuje možnosti navigace rozhraní API a integraci na straně klienta. Ve výchozím nastavení je /<entity-name>cesta .

Formát

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "path": <string; default: "<entity-name>">
      }
    }
  }
}

Příklady

Tento příklad zveřejňuje entitu Author pomocí koncového bodu /auth.

{
  "entities": {
    "Author": {
      "rest": {
        "path": "/auth"
      }
    }
  }
}

Metody (entita REST)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`entities.{entity}.rest`	`methods`	Řetězcové pole	❌ Ne	Žádný

Platí konkrétně pro uložené procedury, vlastnost methods definuje, na které příkazy HTTP (například GET, POST), na které může procedura reagovat. Metody umožňují přesnou kontrolu nad tím, jak se uložené procedury zveřejňují prostřednictvím rozhraní REST API a zajišťují kompatibilitu se standardy RESTful a očekáváními klientů. Tato část zdůrazňuje závazek platformy k flexibilitě a řízení vývojářů, což umožňuje přesný a intuitivní návrh rozhraní API přizpůsobený konkrétním potřebám každé aplikace.

Pokud tento parametr vynecháte nebo chybí, výchozí methods je POST.

Formát

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "methods": ["GET" (default), "POST"]
      }
    }
  }
}

Hodnoty

Tady je seznam povolených hodnot pro tuto vlastnost:

	Popis
`get`	Zveřejňuje požadavky HTTP GET.
`post`	Zveřejňuje požadavky HTTP POST.

Příklady

Tento příklad dává modulu pokyn, aby stp_get_bestselling_authors uložená procedura podporovala pouze HTTP GET akce.

{
  "entities": {
    "BestSellingAuthor": {
      "source": {
        "object": "dbo.stp_get_bestselling_authors",
        "type": "stored-procedure",
        "parameters": {
          "depth": 10
        }
      },
      "rest": {
        "path": "/best-selling-authors",
        "methods": [ "get" ]
      }
    }
  }
}

Mapování (entity)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`entities.{entity}`	`mappings`	objekt	❌ Ne	Žádný

oddíl mappings umožňuje konfigurovat aliasy nebo vystavené názvy pro pole databázových objektů. Nakonfigurované vystavené názvy se vztahují na koncové body GraphQL i REST.

Důležitý

U entit s povoleným grafem GraphQL musí nakonfigurovaný vystavený název splňovat požadavky na pojmenování GraphQL. Další informace najdete v tématu specifikace názvů GraphQL.

Formát

{
  "entities": {
    "<entity-name>": {
      "mappings": {
        "<field-1-name>": "<field-1-alias>",
        "<field-2-name>": "<field-2-alias>",
        "<field-3-name>": "<field-3-alias>"
      }
    }
  }
}

Příklady

V tomto příkladu je sku_title pole z databázového objektu dbo.magazines vystaveno pomocí názvu title. Podobně se pole sku_status zobrazuje jako status v koncových bodech REST i GraphQL.

{
  "entities": {
    "Magazine": {
      ...
      "mappings": {
        "sku_title": "title",
        "sku_status": "status"
      }
    }
  }
}

Tady je další příklad mapování.

{
  "entities": {
    "Book": {
      ...
      "mappings": {
        "id": "BookID",
        "title": "BookTitle",
        "author": "AuthorName"
      }
    }
  }
}

mapování: Objekt mappings propojuje pole databáze (BookID, BookTitle, AuthorName) na intuitivnější nebo standardizované názvy (id, title, author), které se používají externě. Tento aliasing slouží k několika účelům:

přehlednost akonzistence: Umožňuje používat jasné a konzistentní pojmenování v rozhraní API bez ohledu na základní schéma databáze. Například BookID v databázi je reprezentována jako id v rozhraní API, což vývojářům usnadňuje interakci s koncovým bodem.
dodržování předpisů GraphQL: Poskytnutím mechanismu pro názvy polí aliasů zajišťuje, aby názvy zveřejněné prostřednictvím rozhraní GraphQL splňovaly požadavky na pojmenování GraphQL. Pozornost k názvům je důležitá, protože GraphQL má přísná pravidla týkající se názvů (například bez mezer, nesmí začínat písmenem nebo podtržítkem atd.). Pokud například název databázového pole nesplňuje tato kritéria, můžete ho aliasovat pro vyhovující název prostřednictvím mapování.
flexibilita: Toto aliasování přidá mezi schéma databáze a rozhraní API vrstvu abstrakce, což umožňuje změny v jednom bez nutnosti změn v druhém. Změna názvu pole v databázi například nevyžaduje aktualizaci dokumentace k rozhraní API nebo kódu na straně klienta, pokud mapování zůstává konzistentní.
Obfuskace názvu pole: Mapování umožňuje obfuskaci názvů polí, což může pomoct zabránit neoprávněným uživatelům v odvozování citlivých informací o schématu databáze nebo povaze uložených dat.
Ochrana proprietárních informací: Přejmenováním polí můžete také chránit proprietární názvy nebo obchodní logiku, na které můžou být odkazovány původní názvy polí databáze.

Relace (entity)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`entities.{entity}`	`relationships`	objekt	❌ Ne	Žádný

Tato mapa oddílů obsahuje sadu definic relací, které mapují, jak entity souvisejí s dalšími vystavenými entitami. Tyto definice relací můžou také volitelně obsahovat podrobnosti o podkladových databázových objektech, které slouží k podpoře a vynucování relací. Objekty definované v této části jsou vystaveny jako pole GraphQL v související entitě. Další informace najdete v tématu rozpis relací tvůrce rozhraní Data API.

Poznámka

Relace jsou relevantní pouze pro dotazy GraphQL. Koncové body REST přistupují vždy jenom k jedné entitě a nemůžou vnořené typy vracet.

Oddíl relationships popisuje, jak entity interagují v tvůrci rozhraní Data API, podrobně popisují přidružení a potenciální podporu databází pro tyto relace. Vlastnost relationship-name pro každou relaci je povinná a musí být jedinečná pro všechny relace pro danou entitu. Vlastní názvy zajišťují jasná, identifikovatelná připojení a udržují integritu schématu GraphQL vygenerovaného z těchto konfigurací.

Vztah	Mohutnost	Příklad
1:N	`many`	Jedna entita kategorie může souviset s mnoha entitami úkolů.
M:1	`one`	Mnoho entit úkolů může souviset s jednou entitou kategorie.
M:N	`many`	Jedna entita úkolů může souviset s mnoha entitami uživatelů a jedna entita uživatele může souviset s mnoha entitami úkolů.

Formát

{
  "entities": {
    "<entity-name>": {
      "relationships": {
        "<relationship-name>": {
          "cardinality": "one" | "many",
          "target.entity": "<string>",
          "source.fields": ["<string>"],
          "target.fields": ["<string>"],
          "linking.object": "<string>",
          "linking.source.fields": ["<string>"],
          "linking.target.fields": ["<string>"]
        }
      }
    }
  }
}

Vlastnosti

Vlastnost	Požadovaný	Typ	Výchozí
`cardinality`	✔️ Ano	enum string	Žádný
`target.entity`	✔️ Ano	řetězec	Žádný
`source.fields`	❌ Ne	Řetězcové pole	Žádný
`target.fields`	❌ Ne	Řetězcové pole	Žádný
`linking.<object-or-entity>`	❌ Ne	řetězec	Žádný
`linking.source.fields`	❌ Ne	Řetězcové pole	Žádný
`linking.target.fields`	❌ Ne	Řetězcové pole	Žádný

Příklady

Při zvažování relací je nejlepší porovnat rozdíly mezi 1:N , M:1 a relací M:N.

1:N

Nejprve se podíváme na příklad relace s vystavenou entitou Category má relaci 1:N s entitou Book. Tady je kardinalita nastavená na many. Každá Category může mít více souvisejících Book entit, zatímco každá entita Book je přidružená pouze k jedné Category entitě.

{
  "entities": {
    "Book": {
      ...
    },
    "Category": {
      "relationships": {
        "category_books": {
          "cardinality": "many",
          "target.entity": "Book",
          "source.fields": [ "id" ],
          "target.fields": [ "category_id" ]
        }
      }
    }
  }
}

V tomto příkladu seznam source.fields určuje pole id zdrojové entity (Category). Toto pole slouží k připojení ke související položce v entitě target. Naopak seznam target.fields určuje pole category_id cílové entity (Book). Toto pole slouží k připojení ke související položce v entitě source.

Při definovaném vztahu by se výsledné vystavené schéma GraphQL mělo podobat tomuto příkladu.

type Category
{
  id: Int!
  ...
  books: [BookConnection]!
}

M:1

Dále zvažte M:1, která nastaví kardinalitu na one. Vystavená entita Book může mít jednu související Category entitu. Entita Category může mít více souvisejících Book entit.

{
  "entities": {
    "Book": {
      "relationships": {
        "books_category": {
          "cardinality": "one",
          "target.entity": "Category",
          "source.fields": [ "category_id" ],
          "target.fields": [ "id" ]
        }
      },
      "Category": {
        ...
      }
    }
  }
}

Seznam source.fields určuje, že pole category_id zdrojové entity (Book) odkazuje na pole id související cílové entity (Category). Inverzní target.fields seznam určuje inverzní relaci. Díky této relaci teď výsledné schéma GraphQL obsahuje mapování zpět z Knihy na kategorie.

type Book
{
  id: Int!
  ...
  category: Category
}

M:N

Nakonec je definována relace M:N s kardinalitou many a dalšími metadaty, která definují, které databázové objekty se používají k vytvoření relace v záložní databázi. V této části může entita Book mít více Author entit a naopak entita Author může mít více Book entit.

{
  "entities": {
    "Book": {
      "relationships": {
        ...,
        "books_authors": {
          "cardinality": "many",
          "target.entity": "Author",
          "source.fields": [ "id" ],
          "target.fields": [ "id" ],
          "linking.object": "dbo.books_authors",
          "linking.source.fields": [ "book_id" ],
          "linking.target.fields": [ "author_id" ]
        }
      },
      "Category": {
        ...
      },
      "Author": {
        ...
      }
    }
  }
}

V tomto příkladu source.fields i target.fields obě označují, že tabulka relací používá primární identifikátor (id) entit zdroje (Book) i cílové entity (Author). Pole linking.object určuje, že relace je definována v databázovém objektu dbo.books_authors. Dále linking.source.fields určuje, že pole book_id objektu propojení odkazuje na pole id entity Book a linking.target.fields určuje, že pole author_id objektu propojení odkazuje na pole id entity Author.

Tento příklad lze popsat pomocí schématu GraphQL podobného tomuto příkladu.

type Book
{
  id: Int!
  ...
  authors: [AuthorConnection]!
}

type Author
{
  id: Int!
  ...
  books: [BookConnection]!
}

Mohutnost

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`entities.{entity}.relationships`	`cardinality`	řetězec	✔️ Ano	Žádný

Určuje, jestli aktuální zdrojová entita souvisí pouze s jedinou instancí cílové entity nebo více entit.

Hodnoty

Tady je seznam povolených hodnot pro tuto vlastnost:

	Popis
`one`	Zdroj se vztahuje pouze k jednomu záznamu z cíle.
`many`	Zdroj může souviset se záznamy nulou k mnoha záznamům z cíle.

Cílová entita

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`entities.{entity}.relationships`	`target.entity`	řetězec	✔️ Ano	Žádný

Název entity definované jinde v konfiguraci, která je cílem relace.

Zdrojová pole

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`entities.{entity}.relationships`	`source.fields`	pole	❌ Ne	Žádný

Volitelný parametr pro definování pole použitého pro mapování ve zdrojové zdroji entitě sloužící k připojení ke související položce v cílové entitě.

Spropitné

Toto pole není povinné, pokud existuje cizí klíč omezení databáze mezi dvěma databázovými objekty, které lze použít k automatickému odvození relace.

Cílová pole

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`entities.{entity}.relationships`	`target.fields`	pole	❌ Ne	Žádný

Volitelný parametr pro definování pole použitého pro mapování v cílové entitě sloužící k připojení ke související položce ve zdrojové entitě.

Spropitné

Toto pole není povinné, pokud existuje cizí klíč omezení databáze mezi dvěma databázovými objekty, které lze použít k automatickému odvození relace.

Propojení objektu nebo entity

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`entities.{entity}.relationships`	`linking.object`	řetězec	❌ Ne	Žádný

U relací M:N je název databázového objektu nebo entity obsahující data potřebná k definování relace mezi dvěma dalšími entitami.

Propojení zdrojových polí

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`entities.{entity}.relationships`	`linking.source.fields`	pole	❌ Ne	Žádný

Název databázového objektu nebo pole entity, které souvisí se zdrojnou entitou.

Propojení cílových polí

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`entities.{entity}.relationships`	`linking.target.fields`	pole	❌ Ne	Žádný

Název databázového objektu nebo pole entity, které souvisí s cílovou entitou.

Mezipaměť (entity)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`entities.{entity}.cache`	`enabled`	booleovský	❌ Ne	Falešný

Povolí a nakonfiguruje ukládání do mezipaměti pro entitu.

Formát

You're right; the formatting doesn't match your style. Here’s the corrected version following your preferred documentation format:

```json
{
  "entities": {
    "<entity-name>": {
      "cache": {
        "enabled": <true> (default) | <false>,
        "ttl-seconds": <integer; default: 5>
      }
    }
  }
}

Vlastnosti

Vlastnost	Požadovaný	Typ	Výchozí
`enabled`	❌ Ne	booleovský	Falešný
`ttl-seconds`	❌ Ne	celé číslo	5

Příklady

V tomto příkladu je povolená mezipaměť a po 30 sekundách vyprší platnost položek.

{
  "entities": {
    "Author": {
      "cache": {
        "enabled": true,
        "ttl-seconds": 30
      }
    }
  }
}

Povoleno (entita mezipaměti)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`entities.{entity}.cache`	`enabled`	booleovský	❌ Ne	Falešný

Povolí ukládání do mezipaměti pro entitu.

Podpora databázových objektů

Typ objektu	Podpora mezipaměti
Stůl	✅ Ano
Pohled	✅ Ano
Uložená procedura	✖️ Ne
Kontejner	✖️ Ne

Podpora hlaviček HTTP

Hlavička požadavku	Podpora mezipaměti
`no-cache`	✖️ Ne
`no-store`	✖️ Ne
`max-age`	✖️ Ne
`public`	✖️ Ne
`private`	✖️ Ne
`etag`	✖️ Ne

Formát

{
  "entities": {
    "<entity-name>": {
      "cache": {
        "enabled": <boolean> (default: false)
      }
    }
  }
}

Příklady

V tomto příkladu je mezipaměť zakázaná.

{
  "entities": {
    "Author": {
      "cache": {
        "enabled": false
      }
    }
  }
}

Hodnota TTL v sekundách (entita mezipaměti)

Rodič	Vlastnost	Typ	Požadovaný	Výchozí
`entities.cache`	`ttl-seconds`	celé číslo	❌ Ne	5

Nakonfiguruje hodnotu TTL (Time to Live) v sekundách pro položky uložené v mezipaměti. Po uplynutí této doby se položky automaticky vyříznou z mezipaměti. Výchozí hodnota je 5 sekund.

Formát

{
  "entities": {
    "<entity-name>": {
      "cache": {
        "ttl-seconds": <integer; inherited>
      }
    }
  }
}

Příklady

V tomto příkladu je povolená mezipaměť a po 15 sekundách vyprší platnost položek. Pokud toto nastavení vynecháte, zdědí globální nastavení nebo výchozí nastavení.

{
  "entities": {
    "Author": {
      "cache": {
        "enabled": true,
        "ttl-seconds": 15
      }
    }
  }
}

Referenční Functions
referenční rozhraní příkazového řádku (CLI)

Sdílet prostřednictvím

Referenční informace ke schématu konfigurace tvůrce rozhraní Data API

Přehled syntaxe

Vlastnosti nejvyšší úrovně

Ukázkové konfigurace

Prostředí

Vlastnosti konfigurace

Schéma

Formát

Příklady

Zdroj dat

Formát

Vlastnosti

Typ databáze

Formát

Hodnoty typu

Připojovací řetězec

Formát

Odolnost připojení

Azure SQL a SQL Server

Příklady

Volby

Formát

Příklady

Soubory zdroje dat

Formát

Důležité informace o konfiguračních souborech

Příklady

Runtime

Formát

Vlastnosti

Příklady

GraphQL (modul runtime)

Formát

Vlastnosti

Povoleno (modul runtime GraphQL)

Formát

Příklady

Limit hloubky (modul runtime GraphQL)

Příklady

Cesta (modul runtime GraphQL)

Formát

Příklady

Povolit introspekci (modul runtime GraphQL)

Formát

Příklady

Více mutací (modul runtime GraphQL)

Formát

Vlastnosti

Více mutací – vytvoření (modul runtime GraphQL)

Formát

Vlastnosti

Příklady

REST (modul runtime)

Formát

Vlastnosti

Povoleno (modul runtime REST)

Formát

Příklady

Cesta (modul runtime REST)

Formát

Příklady

Text požadavku striktní (modul runtime REST)

Formát

Příklady

Hostitel (modul runtime)

Formát

Vlastnosti

Příklady

Režim (modul runtime hostitele)

Formát

Hodnoty

Maximální velikost odpovědi (runtime)

Povolené hodnoty

Formát

CORS (modul runtime hostitele)

Formát

Vlastnosti

Povolit přihlašovací údaje (modul runtime hostitele)

Formát