Naslaginformatie over configuratieschema's voor Data API Builder
De engine van de Data API Builder vereist een configuratiebestand. Het Data API Builder-configuratiebestand biedt een gestructureerde en uitgebreide benadering voor het instellen van uw API, waarbij alles wordt beschreven, van omgevingsvariabelen tot entiteitsspecifieke configuraties. Dit met JSON opgemaakte document begint met een eigenschap $schema
. Met deze instelling wordt het document gevalideerd.
De eigenschappen database-type
en connection-string
zorgen voor naadloze integratie met databasesystemen, van Azure SQL Database naar Cosmos DB NoSQL-API.
Het configuratiebestand kan opties bevatten, zoals:
- Databaseservice- en verbindingsgegevens
- Algemene en runtime-configuratieopties
- Set weergegeven entiteiten
- Verificatiemethode
- Beveiligingsregels die zijn vereist voor toegang tot identiteiten
- Naamtoewijzingsregels tussen API en database
- Relaties tussen entiteiten die niet kunnen worden afgeleid
- Unieke functies voor specifieke databaseservices
Hier volgt een snelle uitsplitsing van de primaire secties in een configuratiebestand.
{
"$schema": "...",
"data-source": { ... },
"data-source-files": [ ... ],
"runtime": {
"rest": { ... },
"graphql": { .. },
"host": { ... },
"cache": { ... },
"telemetry": { ... },
"pagination": { ... }
}
"entities": [ ... ]
}
Hier volgt de beschrijving van de eigenschappen op het hoogste niveau in een tabelindeling:
Eigenschap | Beschrijving |
---|---|
$schema | Hiermee geeft u het JSON-schema voor validatie op, zodat de configuratie voldoet aan de vereiste indeling. |
gegevensbron | Bevat de details over het databasetype en de verbindingsreeks, die nodig zijn om de databaseverbinding tot stand te brengen. |
gegevensbronbestanden | Een optionele matrix die andere configuratiebestanden opgeeft die andere gegevensbronnen kunnen definiëren. |
runtime- | Configureert runtimegedrag en -instellingen, waaronder subproperties voor REST-, GraphQL-, host, cache-en telemetrie. |
entiteiten | Definieert de set entiteiten (databasetabellen, weergaven, enzovoort) die worden weergegeven via de API, met inbegrip van de toewijzingen, machtigingenen relaties. |
Hier volgt een voorbeeldconfiguratiebestand dat alleen vereiste eigenschappen voor één eenvoudige entiteit bevat. Dit voorbeeld is bedoeld om een minimaal scenario te illustreren.
{
"$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": {
"User": {
"source": "dbo.Users",
"permissions": [
{
"role": "anonymous",
"actions": ["*"]
}
]
}
}
}
Zie de end-to-end voorbeeldconfiguratievoor een voorbeeld van een complexer scenario.
Het configuratiebestand van Data API Builder kan scenario's ondersteunen waarbij u meerdere omgevingen moet ondersteunen, vergelijkbaar met het appSettings.json
-bestand in ASP.NET Core. Het framework biedt drie algemene omgevingswaarden; Development
, Staging
en Production
; maar u kunt ervoor kiezen om elke gewenste omgevingswaarde te gebruiken. De omgeving die Data API Builder gebruikt, moet worden geconfigureerd met behulp van de DAB_ENVIRONMENT
omgevingsvariabele.
Bekijk een voorbeeld waarin u een basislijnconfiguratie en een ontwikkelingsspecifieke configuratie wilt. Voor dit voorbeeld zijn twee configuratiebestanden vereist:
Milieu | |
---|---|
dab-config.json | Base |
dab-config.Development.json | Ontwikkeling |
Als u de ontwikkelspecifieke configuratie wilt gebruiken, moet u de DAB_ENVIRONMENT
omgevingsvariabele instellen op Development
.
Omgevingsspecifieke configuratiebestanden overschrijven eigenschapswaarden in het basisconfiguratiebestand. Als in dit voorbeeld de connection-string
waarde is ingesteld in beide bestanden, wordt de waarde van het *.Development.json bestand gebruikt.
Raadpleeg deze matrix om beter te begrijpen welke waarde wordt gebruikt, afhankelijk van waar die waarde is opgegeven (of niet opgegeven) in een van beide bestanden.
opgegeven in de basisconfiguratie | niet opgegeven in de basisconfiguratie | |
---|---|---|
opgegeven in de huidige omgevingsconfiguratie | Huidige omgeving | Huidige omgeving |
Niet opgegeven in de huidige omgevingsconfiguratie | Base | Geen |
Zie Data API Builder gebruiken met omgevingenvoor een voorbeeld van het gebruik van meerdere configuratiebestanden.
Deze sectie bevat alle mogelijke configuratie-eigenschappen die beschikbaar zijn voor een configuratiebestand.
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
$root |
$schema |
snaar | ✔️ Ja | Geen |
Elk configuratiebestand begint met een eigenschap $schema
, waarbij het JSON-schema voor validatie wordt opgegeven.
{
"$schema": <string>
}
Schemabestanden zijn beschikbaar voor versies 0.3.7-alpha
hoger op specifieke URL's, zodat u de juiste versie of het meest recente beschikbare schema gebruikt.
https://github.com/Azure/data-api-builder/releases/download/<VERSION>-<suffix>/dab.draft.schema.json
Vervang VERSION-suffix
door de gewenste versie.
https://github.com/Azure/data-api-builder/releases/download/v0.3.7-alpha/dab.draft.schema.json
De nieuwste versie van het schema is altijd beschikbaar op https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json.
Hier volgen enkele voorbeelden van geldige schemawaarden.
Versie | URI | Beschrijving |
---|---|---|
0.3.7-alfa | https://github.com/Azure/data-api-builder/releases/download/v0.3.7-alpha/dab.draft.schema.json |
Maakt gebruik van het configuratieschema van een alfaversie van het hulpprogramma. |
0.10.23 | https://github.com/Azure/data-api-builder/releases/download/v0.10.23/dab.draft.schema.json |
Maakt gebruik van het configuratieschema voor een stabiele release van het hulpprogramma. |
Laatst | https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json |
Maakt gebruik van de nieuwste versie van het configuratieschema. |
Notitie
Versies van de Data API Builder vóór 0.3.7-alpha mogelijk een andere schema-URI hebben.
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
$root |
data-source |
snaar | ✔️ Ja | Geen |
De sectie data-source
definieert de database en de toegang tot de database via de verbindingsreeks. Er worden ook databaseopties gedefinieerd. De eigenschap data-source
configureert de referenties die nodig zijn om verbinding te maken met de back-updatabase. De sectie data-source
bevat een overzicht van de connectiviteit van back-enddatabases, waarbij zowel de database-type
als connection-string
worden opgegeven.
{
"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>
}
}
}
Vereist | Type | |
---|---|---|
database-type |
✔️ Ja | opsommingstekenreeks |
connection-string |
✔️ Ja | snaar |
options |
❌ Nee | object |
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
data-source |
database-type |
enum-string | ✔️ Ja | Geen |
Een opsommingstekenreeks die wordt gebruikt om het type database op te geven dat moet worden gebruikt als gegevensbron.
{
"data-source": {
"database-type": <string>
}
}
De eigenschap type
geeft het type back-enddatabase aan.
Type | Beschrijving | Minimale versie |
---|---|---|
mssql |
Azure SQL Database | Geen |
mssql |
Azure SQL MI | Geen |
mssql |
SQL Server | SQL 2016 |
sqldw |
Azure SQL Data Warehouse | Geen |
postgresql |
PostgreSQL | v11 |
mysql |
MySQL | v8 |
cosmosdb_nosql |
Azure Cosmos DB voor NoSQL | Geen |
cosmosdb_postgresql |
Azure Cosmos DB for PostgreSQL | Geen |
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
data-source |
connection-string |
snaar | ✔️ Ja | Geen |
Een tekenreeks waarde die een geldige verbindingsreeks bevat om verbinding te maken met de doeldatabaseservice. De ADO.NET verbindingsreeks om verbinding te maken met de back-enddatabase. Zie ADO.NET verbindingsreeksenvoor meer informatie.
{
"data-source": {
"connection-string": <string>
}
}
Data API Builder probeert automatisch databaseaanvragen opnieuw na het detecteren van tijdelijke fouten. De logica voor opnieuw proberen volgt een Strategie voor exponentieel uitstel waarbij het maximum aantal nieuwe pogingen vijfis. De uitstelduur voor opnieuw proberen nadat volgende aanvragen zijn berekend met behulp van deze formule (ervan uitgaande dat de huidige poging voor opnieuw proberen is r
): $r^2$
Met deze formule kunt u de tijd berekenen voor elke nieuwe poging in seconden.
Seconden | |
---|---|
Eerste | 2 |
Second | 4 |
derde | 8 |
vierde | 16 |
Vijfde | 32 |
Data API Builder maakt gebruik van de SqlClient
-bibliotheek om verbinding te maken met Azure SQL of SQL Server met behulp van de verbindingsreeks die u in het configuratiebestand opgeeft. Hier vindt u een lijst met alle ondersteunde verbindingsreeksopties: eigenschap SqlConnection.ConnectionString.
Data API Builder kan ook verbinding maken met de doeldatabase met behulp van Managed Service Identities (MSI) wanneer Data API Builder wordt gehost in Azure. De DefaultAzureCredential
die in Azure.Identity
bibliotheek is gedefinieerd, wordt gebruikt om verbinding te maken met bekende identiteiten wanneer u geen gebruikersnaam of wachtwoord opgeeft in uw verbindingsreeks. Zie DefaultAzureCredential
voorbeeldenvoor meer informatie.
-
door de gebruiker toegewezen beheerde identiteit (UMI): voeg de verificatie- en eigenschappen van de gebruikers-id toe aan de verbindingsreeks terwijl u de client-id van de door de gebruiker toegewezen beheerde identiteit vervangt:
Authentication=Active Directory Managed Identity; User Id=<UMI_CLIENT_ID>;
. -
Door het systeem toegewezen beheerde identiteit (SMI): voeg de eigenschap Authentication toe en sluit de argumenten UserId en Password uit van de verbindingsreeks:
Authentication=Active Directory Managed Identity;
. Het ontbreken van de eigenschappen van de UserId en Wachtwoord verbindingsreeksen geeft DAB aan om te verifiëren met behulp van een door het systeem toegewezen beheerde identiteit.
Zie Beheerde identiteiten in Microsoft Entra voor Azure SQLvoor meer informatie over het configureren van een Managed Service Identity met Azure SQL of SQL Server.
De waarde die wordt gebruikt voor de verbindingsreeks is grotendeels afhankelijk van de databaseservice die in uw scenario wordt gebruikt. U kunt er altijd voor kiezen om de verbindingsreeks op te slaan in een omgevingsvariabele en deze te openen met behulp van de functie @env()
.
Waarde | Beschrijving | |
---|---|---|
Azure SQL Database-tekenreekswaarde gebruiken | Server=<server-address>;Database=<name-of-database>;User ID=<username>;Password=<password>; |
Verbindingsreeks met een Azure SQL Database-account. Zie Azure SQL Database-verbindingsreeksenvoor meer informatie. |
Azure Database for PostgreSQL-tekenreekswaarde gebruiken | Server=<server-address>;Database=<name-of-database>;Port=5432;User Id=<username>;Password=<password>;Ssl Mode=Require; |
Verbindingsreeks voor een Azure Database for PostgreSQL-account. Zie Azure Database for PostgreSQL-verbindingsreeksenvoor meer informatie. |
Azure Cosmos DB for NoSQL-tekenreekswaarde gebruiken | AccountEndpoint=<endpoint>;AccountKey=<key>; |
Verbindingsreeks met een Azure Cosmos DB for NoSQL-account. Zie Azure Cosmos DB for NoSQL-verbindingsreeksenvoor meer informatie. |
Azure Database for MySQL-tekenreekswaarde gebruiken | Server=<server-address>;Database=<name-of-database>;User ID=<username>;Password=<password>;Sslmode=Required;SslCa=<path-to-certificate>; |
Verbindingsreeks voor een Azure Database for MySQL-account. Zie Azure Database for MySQL-verbindingsreeksenvoor meer informatie. |
omgevingsvariabele van Access | @env('SQL_CONNECTION_STRING') |
Toegang tot een omgevingsvariabele vanaf de lokale computer. In dit voorbeeld wordt verwezen naar de omgevingsvariabele SQL_CONNECTION_STRING . |
Fooi
Als best practice vermijdt u het opslaan van gevoelige informatie in uw configuratiebestand. Gebruik indien mogelijk @env()
om te verwijzen naar omgevingsvariabelen. Zie @env()
functievoor meer informatie.
Deze voorbeelden laten alleen zien hoe elk databasetype kan worden geconfigureerd. Uw scenario kan uniek zijn, maar dit voorbeeld is een goede uitgangspunt. Vervang de tijdelijke aanduidingen, zoals myserver
, myDataBase
, mylogin
en myPassword
door de werkelijke waarden die specifiek zijn voor uw omgeving.
mssql
"data-source": { "database-type": "mssql", "connection-string": "$env('my-connection-string')", "options": { "set-session-context": true } }
-
Typische verbindingsreeksindeling:
"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;"
-
Typische verbindingsreeksindeling:
postgresql
"data-source": { "database-type": "postgresql", "connection-string": "$env('my-connection-string')" }
-
Typische verbindingsreeksindeling:
"Host=myserver.postgres.database.azure.com;Database=myDataBase;Username=mylogin@myserver;Password=myPassword;"
-
Typische verbindingsreeksindeling:
mysql
"data-source": { "database-type": "mysql", "connection-string": "$env('my-connection-string')" }
-
Typische verbindingsreeksindeling:
"Server=myserver.mysql.database.azure.com;Database=myDataBase;Uid=mylogin@myserver;Pwd=myPassword;"
-
Typische verbindingsreeksindeling:
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" } }
-
Typische verbindingsreeksindeling:
"AccountEndpoint=https://mycosmosdb.documents.azure.com:443/;AccountKey=myAccountKey;"
-
Typische verbindingsreeksindeling:
cosmosdb_postgresql
"data-source": { "database-type": "cosmosdb_postgresql", "connection-string": "$env('my-connection-string')" }
-
Typische verbindingsreeksindeling:
"Host=mycosmosdb.postgres.database.azure.com;Database=myDataBase;Username=mylogin@mycosmosdb;Password=myPassword;Port=5432;SSL Mode=Require;"
-
Typische verbindingsreeksindeling:
Notitie
De 'opties' die zijn opgegeven, zoals database
, container
en schema
zijn specifiek voor de NoSQL-API van Azure Cosmos DB in plaats van de PostgreSQL-API. Voor Azure Cosmos DB met behulp van de PostgreSQL-API bevatten de 'opties' geen database
, container
of schema
zoals in de NoSQL-installatie.
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
data-source |
options |
object | ❌ Nee | Geen |
Een optionele sectie met extra sleutelwaardeparameters voor specifieke databaseverbindingen.
Of de options
sectie vereist is of niet grotendeels afhankelijk is van de databaseservice die wordt gebruikt.
{
"data-source": {
"options": {
"<key-name>": <string>
}
}
}
Voor Azure SQL en SQL Server kan Data API Builder profiteren van SESSION_CONTEXT
om door de gebruiker opgegeven metagegevens naar de onderliggende database te verzenden. Dergelijke metagegevens zijn beschikbaar voor Data API Builder op grond van de claims die aanwezig zijn in het toegangstoken. De SESSION_CONTEXT
gegevens zijn beschikbaar voor de database tijdens de databaseverbinding totdat deze verbinding is gesloten. Zie sessiecontextvoor meer informatie.
CREATE PROC GetUser @userId INT AS
BEGIN
-- Check if the current user has access to the requested userId
IF SESSION_CONTEXT(N'user_role') = 'admin'
OR SESSION_CONTEXT(N'user_id') = @userId
BEGIN
SELECT Id, Name, Age, IsAdmin
FROM Users
WHERE Id = @userId;
END
ELSE
BEGIN
RAISERROR('Unauthorized access', 16, 1);
END
END;
{
"$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')",
"options": {
"set-session-context": true
}
},
"entities": {
"User": {
"source": {
"object": "dbo.GetUser",
"type": "stored-procedure",
"parameters": {
"userId": "number"
}
},
"permissions": [
{
"role": "authenticated",
"actions": ["execute"]
}
]
}
}
}
opgeslagen procedure (
GetUser
):- De procedure controleert de
SESSION_CONTEXT
om te controleren of de aanroeper de roladmin
heeft of overeenkomt met de opgegevenuserId
. - Onbevoegde toegang resulteert in een fout.
- De procedure controleert de
JSON-configuratie:
-
set-session-context
is ingeschakeld om metagegevens van gebruikers van het toegangstoken door te geven aan de database. - De eigenschap
parameters
wijst deuserId
parameter toe die is vereist voor de opgeslagen procedure. - Het
permissions
blok zorgt ervoor dat alleen geverifieerde gebruikers de opgeslagen procedure kunnen uitvoeren.
-
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
$root |
data-source-files |
tekenreeksmatrix | ❌ Nee | Geen |
Data API Builder ondersteunt meerdere configuratiebestanden voor verschillende gegevensbronnen, met één die is aangewezen als het bestand op het hoogste niveau dat runtime
instellingen beheert. Alle configuraties delen hetzelfde schema, waardoor runtime
instellingen in elk bestand zonder fouten kunnen worden toegestaan. Onderliggende configuraties worden automatisch samengevoegd, maar kringverwijzingen moeten worden vermeden. Entiteiten kunnen worden gesplitst in afzonderlijke bestanden voor beter beheer, maar relaties tussen entiteiten moeten zich in hetzelfde bestand bevinden.
{
"data-source-files": [ <string> ]
}
- Elk configuratiebestand moet de eigenschap
data-source
bevatten. - Elk configuratiebestand moet de eigenschap
entities
bevatten. - De
runtime
-instelling wordt alleen gebruikt vanuit het configuratiebestand op het hoogste niveau, zelfs als deze is opgenomen in andere bestanden. - Onderliggende configuratiebestanden kunnen ook hun eigen onderliggende bestanden bevatten.
- Configuratiebestanden kunnen naar wens in submappen worden ingedeeld.
- Entiteitsnamen moeten uniek zijn voor alle configuratiebestanden.
- Relaties tussen entiteiten in verschillende configuratiebestanden worden niet ondersteund.
{
"data-source-files": [
"dab-config-2.json"
]
}
{
"data-source-files": [
"dab-config-2.json",
"dab-config-3.json"
]
}
De syntaxis van de submap wordt ook ondersteund:
{
"data-source-files": [
"dab-config-2.json",
"my-folder/dab-config-3.json",
"my-folder/my-other-folder/dab-config-4.json"
]
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
$root |
runtime |
object | ✔️ Ja | Geen |
In de sectie runtime
worden opties beschreven die van invloed zijn op het runtimegedrag en de instellingen voor alle weergegeven entiteiten.
{
"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)
}
}
}
Vereist | Type | |
---|---|---|
rest |
❌ Nee | object |
graphql |
❌ Nee | object |
host |
❌ Nee | object |
cache |
❌ Nee | object |
Hier volgt een voorbeeld van een runtimesectie met meerdere algemene standaardparameters die zijn opgegeven.
{
"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
}
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
runtime |
graphql |
object | ❌ Nee | Geen |
Dit object definieert of GraphQL is ingeschakeld en de naam[s] die wordt gebruikt om de entiteit beschikbaar te maken als een GraphQL-type. Dit object is optioneel en wordt alleen gebruikt als de standaardnaam of instellingen niet voldoende zijn. In deze sectie worden de algemene instellingen voor het GraphQL-eindpunt beschreven.
{
"runtime": {
"graphql": {
"path": <string> (default: /graphql),
"enabled": <true> (default) | <false>,
"depth-limit": <integer; default: none>,
"allow-introspection": <true> (default) | <false>,
"multiple-mutations": <object>
}
}
}
Eigenschap | Vereist | Type | Verstek |
---|---|---|---|
enabled |
❌ Nee | booleaans | Waar |
path |
❌ Nee | snaar | /graphql (standaard) |
allow-introspection |
❌ Nee | booleaans | Waar |
multiple-mutations |
❌ Nee | object | { create: { enabled: false } } |
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
runtime.graphql |
enabled |
booleaans | ❌ Nee | Geen |
Hiermee bepaalt u of u de GraphQL-eindpunten globaal wilt in- of uitschakelen. Als deze globaal is uitgeschakeld, zijn er geen entiteiten toegankelijk via GraphQL-aanvragen, ongeacht de instellingen voor afzonderlijke entiteiten.
{
"runtime": {
"graphql": {
"enabled": <true> (default) | <false>
}
}
}
In dit voorbeeld is het GraphQL-eindpunt uitgeschakeld voor alle entiteiten.
{
"runtime": {
"graphql": {
"enabled": false
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
runtime.graphql |
depth-limit |
geheel getal | ❌ Nee | Geen |
De maximaal toegestane querydiepte van een query.
De mogelijkheid van GraphQL om geneste query's af te handelen op basis van relatiedefinities is een ongelooflijke functie, waardoor gebruikers complexe, gerelateerde gegevens in één query kunnen ophalen. Naarmate gebruikers echter geneste query's blijven toevoegen, neemt de complexiteit van de query toe, wat uiteindelijk de prestaties en betrouwbaarheid van zowel de database als het API-eindpunt kan beïnvloeden. Om deze situatie te beheren, stelt de eigenschap runtime/graphql/depth-limit
de maximale toegestane diepte van een GraphQL-query (en mutatie) in. Met deze eigenschap kunnen ontwikkelaars een evenwicht vinden, zodat gebruikers kunnen profiteren van de voordelen van geneste query's terwijl ze limieten plaatsen om scenario's te voorkomen die de prestaties en kwaliteit van het systeem in gevaar kunnen brengen.
{
"runtime": {
"graphql": {
"depth-limit": 2
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
runtime.graphql |
path |
snaar | ❌ Nee | "/graphql" |
Hiermee definieert u het URL-pad waar het GraphQL-eindpunt beschikbaar wordt gesteld. Als deze parameter bijvoorbeeld is ingesteld op /graphql
, wordt het GraphQL-eindpunt weergegeven als /graphql
. Het pad is standaard /graphql
.
Belangrijk
Subpaden zijn niet toegestaan voor deze eigenschap. Er is momenteel geen aangepaste padwaarde voor het GraphQL-eindpunt beschikbaar.
{
"runtime": {
"graphql": {
"path": <string> (default: /graphql)
}
}
}
In dit voorbeeld is de root GraphQL-URI /query
.
{
"runtime": {
"graphql": {
"path": "/query"
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
runtime.graphql |
allow-introspection |
booleaans | ❌ Nee | Waar |
Deze Booleaanse vlag bepaalt de mogelijkheid om schema-introspection-query's uit te voeren op het GraphQL-eindpunt. Door introspectie in te schakelen, kunnen clients query's uitvoeren op het schema voor informatie over de beschikbare typen gegevens, de soorten query's die ze kunnen uitvoeren en de beschikbare mutaties.
Deze functie is handig tijdens de ontwikkeling om inzicht te krijgen in de structuur van de GraphQL-API en voor hulpprogramma's waarmee automatisch query's worden gegenereerd. Voor productieomgevingen is het echter mogelijk uitgeschakeld om de schemadetails van de API te verbergen en de beveiliging te verbeteren. Introspectie is standaard ingeschakeld, waardoor het GraphQL-schema direct en uitgebreid kan worden verkend.
{
"runtime": {
"graphql": {
"allow-introspection": <true> (default) | <false>
}
}
}
In dit voorbeeld is de introspectie uitgeschakeld.
{
"runtime": {
"graphql": {
"allow-introspection": false
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
runtime.graphql |
multiple-mutations |
object | ❌ Nee | Geen |
Hiermee configureert u alle meerdere mutatiebewerkingen voor de GraphQL-runtime.
Notitie
Standaard zijn meerdere mutaties niet ingeschakeld en moeten ze expliciet worden geconfigureerd om te worden ingeschakeld.
{
"runtime": {
"graphql": {
"multiple-mutations": {
"create": {
"enabled": <true> (default) | <false>
}
}
}
}
}
Vereist | Type | |
---|---|---|
create |
❌ Nee | object |
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
runtime.graphql.multiple-mutations |
create |
booleaans | ❌ Nee | Vals |
Hiermee configureert u meerdere bewerkingen voor het maken van de GraphQL-runtime.
{
"runtime": {
"graphql": {
"multiple-mutations": {
"create": {
"enabled": <true> (default) | <false>
}
}
}
}
}
Eigenschap | Vereist | Type | Verstek |
---|---|---|---|
enabled |
✔️ Ja | booleaans | Waar |
Hieronder ziet u hoe u meerdere mutaties kunt inschakelen en gebruiken in de GraphQL-runtime. In dit geval is de create
-bewerking zo geconfigureerd dat het maken van meerdere records in één aanvraag mogelijk is door de eigenschap runtime.graphql.multiple-mutations.create.enabled
in te stellen op true
.
Deze configuratie maakt meerdere create
mutaties mogelijk:
{
"runtime": {
"graphql": {
"multiple-mutations": {
"create": {
"enabled": true
}
}
}
},
"entities": {
"User": {
"source": "dbo.Users",
"permissions": [
{
"role": "anonymous",
"actions": ["create"]
}
]
}
}
}
Met behulp van de bovenstaande configuratie maakt de volgende mutatie meerdere User
records in één bewerking:
mutation {
createUsers(input: [
{ name: "Alice", age: 30, isAdmin: true },
{ name: "Bob", age: 25, isAdmin: false },
{ name: "Charlie", age: 35, isAdmin: true }
]) {
id
name
age
isAdmin
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
runtime |
rest |
object | ❌ Nee | Geen |
In deze sectie worden de algemene instellingen voor de REST-eindpunten beschreven. Deze instellingen fungeren als standaardinstellingen voor alle entiteiten, maar kunnen per entiteit worden overschreven in hun respectieve configuraties.
{
"runtime": {
"rest": {
"path": <string> (default: /api),
"enabled": <true> (default) | <false>,
"request-body-strict": <true> (default) | <false>
}
}
}
Eigenschap | Vereist | Type | Verstek |
---|---|---|---|
enabled |
❌ Nee | booleaans | Waar |
path |
❌ Nee | snaar | /Api |
request-body-strict |
❌ Nee | booleaans | Waar |
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
runtime.rest |
enabled |
booleaans | ❌ Nee | Geen |
Een Booleaanse vlag die de wereldwijde beschikbaarheid van REST-eindpunten bepaalt. Als dit is uitgeschakeld, kunnen entiteiten niet worden geopend via REST, ongeacht de instellingen van afzonderlijke entiteiten.
{
"runtime": {
"rest": {
"enabled": <true> (default) | <false>,
}
}
}
In dit voorbeeld is het REST API-eindpunt uitgeschakeld voor alle entiteiten.
{
"runtime": {
"rest": {
"enabled": false
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
runtime.rest |
path |
snaar | ❌ Nee | "/api" |
Hiermee stelt u het URL-pad in voor toegang tot alle weergegeven REST-eindpunten. Als u bijvoorbeeld path
instelt op /api
het REST-eindpunt toegankelijk maakt op /api/<entity>
. Subpaden zijn niet toegestaan. Dit veld is optioneel, met /api
als de standaardwaarde.
Notitie
Wanneer u Data API Builder implementeert met behulp van Static Web Apps (preview), injecteert de Azure-service automatisch het extra subpad /data-api
naar de URL. Dit gedrag zorgt voor compatibiliteit met bestaande functies voor statische web-apps. Het resulterende eindpunt wordt /data-api/api/<entity>
. Dit is alleen relevant voor Static Web Apps.
{
"runtime": {
"rest": {
"path": <string> (default: /api)
}
}
}
Belangrijk
Door de gebruiker opgegeven subpaden zijn niet toegestaan voor deze eigenschap.
In dit voorbeeld is de ROOT REST API-URI /data
.
{
"runtime": {
"rest": {
"path": "/data"
}
}
}
Fooi
Als u een Author
-entiteit definieert, wordt het eindpunt voor deze entiteit /data/Author
.
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
runtime.rest |
request-body-strict |
booleaans | ❌ Nee | Waar |
Deze instelling bepaalt hoe strikt de aanvraagbody voor REST mutatiebewerkingen (bijvoorbeeld POST
, PUT
, PATCH
) wordt gevalideerd.
-
true
(standaard): extra velden in de aanvraagbody die niet worden toegewezen aan tabelkolommen, veroorzaken eenBadRequest
uitzondering. -
false
: extra velden worden genegeerd en alleen geldige kolommen worden verwerkt.
Deze instelling niet van toepassing op GET
aanvragen, omdat de hoofdtekst van de aanvraag altijd wordt genegeerd.
- Kolommen met een standaardwaarde() worden tijdens
INSERT
alleen genegeerd wanneer de waarde in de nettoladingnull
. Kolommen met een standaard() worden niet genegeerd tijdensUPDATE
ongeacht de nettoladingwaarde. - Berekende kolommen worden altijd genegeerd.
- Automatisch gegenereerde kolommen worden altijd genegeerd.
{
"runtime": {
"rest": {
"request-body-strict": <true> (default) | <false>
}
}
}
CREATE TABLE Users (
Id INT PRIMARY KEY IDENTITY,
Name NVARCHAR(50) NOT NULL,
Age INT DEFAULT 18,
IsAdmin BIT DEFAULT 0,
IsMinor AS IIF(Age <= 18, 1, 0)
);
{
"runtime": {
"rest": {
"request-body-strict": false
}
}
}
nettolading aanvragen:
{
"Id": 999,
"Name": "Alice",
"Age": null,
"IsAdmin": null,
"IsMinor": false,
"ExtraField": "ignored"
}
resulterende invoeginstructie:
INSERT INTO Users (Name) VALUES ('Alice');
-- Default values for Age (18) and IsAdmin (0) are applied by the database.
-- IsMinor is ignored because it’s a computed column.
-- ExtraField is ignored.
-- The database generates the Id value.
nettolading van antwoord:
{
"Id": 1, // Auto-generated by the database
"Name": "Alice",
"Age": 18, // Default applied
"IsAdmin": false, // Default applied
"IsMinor": true // Computed
}
nettolading aanvragen:
{
"Id": 1,
"Name": "Alice Updated",
"Age": null, // explicitely set to 'null'
"IsMinor": true, // ignored because computed
"ExtraField": "ignored"
}
resulterende update-instructie:
UPDATE Users
SET Name = 'Alice Updated', Age = NULL
WHERE Id = 1;
-- IsMinor and ExtraField are ignored.
nettolading van antwoord:
{
"Id": 1,
"Name": "Alice Updated",
"Age": null,
"IsAdmin": false,
"IsMinor": false // Recomputed by the database (false when age is `null`)
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
runtime |
host |
object | ❌ Nee | Geen |
De sectie host
in de runtimeconfiguratie biedt instellingen die essentieel zijn voor de operationele omgeving van de Data API Builder. Deze instellingen omvatten operationele modi, CORS-configuratie en verificatiegegevens.
{
"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>"
}
}
}
}
}
Eigenschap | Vereist | Type | Verstek |
---|---|---|---|
mode |
❌ Nee | opsommingstekenreeks | productie |
cors |
❌ Nee | object | Geen |
authentication |
❌ Nee | object | Geen |
Hier volgt een voorbeeld van een runtime die is geconfigureerd voor het hosten van ontwikkeling.
{
"runtime": {
"host": {
"mode": "development",
"cors": {
"allow-credentials": false,
"origins": ["*"]
},
"authentication": {
"provider": "Simulator"
}
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
runtime.host |
mode |
snaar | ❌ Nee | "productie" |
Hiermee definieert u of de Data API Builder-engine moet worden uitgevoerd in development
- of production
modus. De standaardwaarde is production
.
Normaal gesproken worden de onderliggende databasefouten gedetailleerd weergegeven door het standaardniveau van detail in te stellen voor logboeken op Debug
bij het uitvoeren in ontwikkeling. In productie wordt het detailniveau voor logboeken ingesteld op Error
.
Fooi
Het standaardlogboekniveau kan verder worden overschreven met behulp van dab start --LogLevel <level-of-detail>
. Zie CLI-verwijzing (opdrachtregelinterface)voor meer informatie.
{
"runtime": {
"host": {
"mode": "production" (default) | "development"
}
}
}
Hier volgt een lijst met toegestane waarden voor deze eigenschap:
Beschrijving | |
---|---|
production |
Gebruiken bij het hosten in productie in Azure |
development |
Gebruiken in ontwikkeling op lokale computer |
- Alleen in
development
modus is Swagger beschikbaar. - Alleen in
development
modus is Banana Cake Pop beschikbaar.
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
runtime.host |
max-response-size-mb |
geheel getal | ❌ Nee | 158 |
Hiermee stelt u de maximale grootte (in megabytes) in voor elk gegeven resultaat. Met deze instelling kunnen gebruikers de hoeveelheid gegevens configureren die het geheugen van het hostplatform kan verwerken bij het streamen van gegevens uit de onderliggende gegevensbronnen.
Wanneer gebruikers grote resultatensets aanvragen, kan deze de database en data-API-opbouwfunctie belasten. Om dit te verhelpen, kunnen ontwikkelaars met max-response-size-mb
de maximale antwoordgrootte, gemeten in megabytes, beperken als de gegevensstromen uit de gegevensbron. Deze limiet is gebaseerd op de totale gegevensgrootte, niet op het aantal rijen. Omdat kolommen in grootte kunnen variëren, kunnen sommige kolommen (zoals tekst, binair, XML of JSON) maximaal 2 GB bevatten, waardoor afzonderlijke rijen mogelijk zeer groot zijn. Met deze instelling kunnen ontwikkelaars hun eindpunten beschermen door de responsgrootte te beperken en overbelasting van het systeem te voorkomen en tegelijkertijd flexibiliteit te behouden voor verschillende gegevenstypen.
Waarde | Resultaat |
---|---|
null |
De standaardwaarde is 158 megabytes als deze niet is ingesteld of expliciet is ingesteld op null . |
integer |
Elk positief 32-bits geheel getal wordt ondersteund. |
< 0 |
Niet ondersteund. Validatiefouten treden op als deze is ingesteld op minder dan 1 MB. |
{
"runtime": {
"host": {
"max-response-size-mb": <integer; default: 158>
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
runtime.host |
cors |
object | ❌ Nee | Geen |
CORS-instellingen (Cross-Origin Resource Sharing) voor de Data API Builder-enginehost.
{
"runtime": {
"host": {
"cors": {
"origins": ["<array-of-strings>"],
"allow-credentials": <true> | <false> (default)
}
}
}
}
Vereist | Type | |
---|---|---|
allow-credentials |
❌ Nee | booleaans |
origins |
❌ Nee | tekenreeksmatrix |
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
runtime.host.cors |
allow-credentials |
booleaans | ❌ Nee | Vals |
Indien waar, stelt u de Access-Control-Allow-Credentials
CORS-header in.
{
"runtime": {
"host": {
"cors": {
"allow-credentials": <true> (default) | <false>
}
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
runtime.host.cors |
origins |
tekenreeksmatrix | ❌ Nee | Geen |
Hiermee stelt u een matrix in met een lijst met toegestane oorsprongen voor CORS. Met deze instelling kan het *
jokerteken voor alle origins worden gebruikt.
{
"runtime": {
"host": {
"cors": {
"origins": ["<array-of-strings>"]
}
}
}
}
Hier volgt een voorbeeld van een host waarmee CORS zonder referenties van alle oorsprongen is toegestaan.
{
"runtime": {
"host": {
"cors": {
"allow-credentials": false,
"origins": ["*"]
}
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
runtime.host |
authentication |
object | ❌ Nee | Geen |
Hiermee configureert u verificatie voor de Data API Builder-host.
{
"runtime": {
"host": {
"authentication": {
"provider": "StaticWebApps" (default) | ...,
"jwt": {
"audience": "<string>",
"issuer": "<string>"
}
}
}
}
}
Eigenschap | Vereist | Type | Verstek |
---|---|---|---|
provider |
❌ Nee | opsommingstekenreeks | StaticWebApps |
jwt |
❌ Nee | object | Geen |
verificatie- en klantverantwoordelijkheden
Data API Builder is ontworpen om te werken in een bredere beveiligingspijplijn en er zijn belangrijke stappen om te configureren voordat aanvragen worden verwerkt. Het is belangrijk om te begrijpen dat Data API Builder de directe aanroeper (zoals uw webtoepassing) niet verifieert, maar in plaats daarvan de eindgebruiker, op basis van een geldig JWT-token dat wordt geleverd door een vertrouwde id-provider (bijvoorbeeld Entra-id). Wanneer een aanvraag data-API builder bereikt, wordt ervan uitgegaan dat het JWT-token geldig is en controleert op basis van de vereisten die u hebt geconfigureerd, zoals specifieke claims. Autorisatieregels worden vervolgens toegepast om te bepalen waartoe de gebruiker toegang heeft of kan wijzigen.
Zodra de autorisatie is geslaagd, voert Data API Builder de aanvraag uit met behulp van het account dat is opgegeven in de verbindingsreeks. Omdat voor dit account vaak verhoogde machtigingen zijn vereist om verschillende gebruikersaanvragen af te handelen, is het essentieel om de toegangsrechten te minimaliseren om het risico te beperken. Het is raadzaam om uw architectuur te beveiligen door een Private Link te configureren tussen uw front-endwebtoepassing en het API-eindpunt, en door de machine die als host fungeert voor Data API Builder te beveiligen. Deze maatregelen helpen ervoor te zorgen dat uw omgeving veilig blijft, uw gegevens beschermt en beveiligingsproblemen minimaliseert die kunnen worden misbruikt voor toegang, wijziging of exfiltratie van gevoelige informatie.
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
runtime.host.authentication |
provider |
snaar | ❌ Nee | "StaticWebApps" |
De authentication.provider
-instelling binnen de configuratie van de host
definieert de verificatiemethode die wordt gebruikt door de Data API Builder. Hiermee wordt bepaald hoe de API de identiteit valideert van gebruikers of services die toegang proberen te krijgen tot de resources. Deze instelling biedt flexibiliteit in de implementatie en integratie door ondersteuning te bieden voor verschillende verificatiemechanismen die zijn afgestemd op verschillende omgevingen en beveiligingsvereisten.
Aanbieder | Beschrijving |
---|---|
StaticWebApps |
Instrueert Data API Builder om te zoeken naar een set HTTP-headers die alleen aanwezig zijn wanneer deze worden uitgevoerd in een Static Web Apps-omgeving. |
AppService |
Wanneer de runtime wordt gehost in Azure AppService waarvoor AppService-verificatie is ingeschakeld en geconfigureerd (EasyAuth). |
AzureAd |
Microsoft Entra Identity moet worden geconfigureerd, zodat deze een aanvraag kan verifiëren die wordt verzonden naar Data API Builder (de 'Server-app'). Zie Microsoft Entra ID-verificatievoor meer informatie. |
Simulator |
Een configureerbare verificatieprovider die de Data API Builder-engine instrueert om alle aanvragen te behandelen als geverifieerd. Zie lokale verificatievoor meer informatie. |
{
"runtime": {
"host": {
"authentication": {
"provider": "StaticWebApps" (default) | ...
}
}
}
}
Hier volgt een lijst met toegestane waarden voor deze eigenschap:
Beschrijving | |
---|---|
StaticWebApps |
Azure Static Web Apps |
AppService |
Azure App Service |
AzureAD |
Microsoft Entra-id |
Simulator |
Simulator |
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
runtime.host.authentication |
jwt |
object | ❌ Nee | Geen |
Als de verificatieprovider is ingesteld op AzureAD
(Microsoft Entra-id), is deze sectie vereist om de doelgroep en verleners voor het JSOn-webtoken (JWT) op te geven. Deze gegevens worden gebruikt om de tokens te valideren op basis van uw Microsoft Entra-tenant.
Vereist als de verificatieprovider is AzureAD
voor Microsoft Entra-id. Deze sectie moet de audience
en issuer
opgeven om het ontvangen JWT-token te valideren op basis van de beoogde AzureAD
-tenant voor verificatie.
Montuur | Beschrijving |
---|---|
audiëntie | Identificeert de beoogde ontvanger van het token; doorgaans de toepassings-id die is geregistreerd in Microsoft Entra Identity (of uw id-provider), zodat het token inderdaad is uitgegeven voor uw toepassing. |
Uitgevende instelling | Hiermee geeft u de URL van de verlenende instantie op, de tokenservice die de JWT heeft uitgegeven. Deze URL moet overeenkomen met de URL van de verlener van de id-provider waaruit de JWT is verkregen, waarbij de oorsprong van het token wordt gecontroleerd. |
{
"runtime": {
"host": {
"authentication": {
"provider": "StaticWebApps" (default) | ...,
"jwt": {
"audience": "<client-id>",
"issuer": "<issuer-url>"
}
}
}
}
}
Eigenschap | Vereist | Type | Verstek |
---|---|---|---|
audience |
❌ Nee | snaar | Geen |
issuer |
❌ Nee | snaar | Geen |
De Data API Builder (DAB) biedt flexibele ondersteuning voor verificatie, integratie met Microsoft Entra Identity en aangepaste JSON-webtokenservers (JWT). In deze afbeelding vertegenwoordigt de JWT-server de verificatieservice waarmee JWT-tokens aan clients worden opgegeven bij geslaagde aanmelding. De client geeft het token vervolgens door aan DAB, waarmee de claims en eigenschappen kunnen worden ondervragen.
Hier volgen enkele voorbeelden van de eigenschap host
gegeven verschillende architectuurkeuzen die u in uw oplossing kunt maken.
{
"host": {
"mode": "development",
"cors": {
"origins": ["https://dev.example.com"],
"credentials": true
},
"authentication": {
"provider": "StaticWebApps"
}
}
}
Met StaticWebApps
verwacht Data API Builder dat Azure Static Web Apps de aanvraag verifieert en dat de X-MS-CLIENT-PRINCIPAL
HTTP-header aanwezig is.
{
"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"
}
}
}
}
Verificatie wordt gedelegeerd aan een ondersteunde id-provider waar toegangstoken kan worden uitgegeven. Een verkregen toegangstoken moet worden opgenomen in binnenkomende aanvragen voor Data API Builder. Data API Builder valideert vervolgens alle gepresenteerde toegangstokens, zodat Data API Builder de beoogde doelgroep van het token was.
{
"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"
}
}
}
}
{
"host": {
"mode": "development",
"authentication": {
"provider": "Simulator"
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
runtime.host.authentication.jwt |
audience |
snaar | ❌ Nee | Geen |
Doelgroep voor het JWT-token.
{
"runtime": {
"host": {
"authentication": {
"jwt": {
"audience": "<client-id>"
}
}
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
runtime.host.authentication.jwt |
issuer |
snaar | ❌ Nee | Geen |
Verlener voor het JWT-token.
{
"runtime": {
"host": {
"authentication": {
"jwt": {
"issuer": "<issuer-url>"
}
}
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
runtime |
pagination |
object | ❌ Nee | Geen |
Hiermee configureert u pagineringslimieten voor REST- en GraphQL-eindpunten.
{
"runtime": {
"pagination": {
"max-page-size": <integer; default: 100000>,
"default-page-size": <integer; default: 100>
}
}
}
Eigenschap | Vereist | Type | Verstek |
---|---|---|---|
max-page-size |
❌ Nee | geheel getal | 100,000 |
default-page-size |
❌ Nee | geheel getal | 100 |
{
"runtime": {
"pagination": {
"max-page-size": 1000,
"default-page-size": 2
}
},
"entities": {
"Users": {
"source": "dbo.Users",
"permissions": [
{
"actions": ["read"],
"role": "anonymous"
}
]
}
}
}
In dit voorbeeld retourneert het uitgeven van de REST GET-aanvraag https://localhost:5001/api/users
twee records in de value
matrix omdat de default-page-size
is ingesteld op 2. Als er meer resultaten bestaan, bevat Data API Builder een nextLink
in het antwoord. De nextLink
bevat een $after
parameter voor het ophalen van de volgende pagina met gegevens.
GET https://localhost:5001/api/users
{
"value": [
{
"Id": 1,
"Name": "Alice",
"Age": 30,
"IsAdmin": true,
"IsMinor": false
},
{
"Id": 2,
"Name": "Bob",
"Age": 17,
"IsAdmin": false,
"IsMinor": true
}
],
"nextLink": "https://localhost:5001/api/users?$after=W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI=="
}
Met behulp van de nextLink
kan de client de volgende set resultaten ophalen.
Gebruik voor GraphQL de velden hasNextPage
en endCursor
voor paginering. Deze velden geven aan of er meer resultaten beschikbaar zijn en geven een cursor op voor het ophalen van de volgende pagina.
query {
users {
items {
Id
Name
Age
IsAdmin
IsMinor
}
hasNextPage
endCursor
}
}
{
"data": {
"users": {
"items": [
{
"Id": 1,
"Name": "Alice",
"Age": 30,
"IsAdmin": true,
"IsMinor": false
},
{
"Id": 2,
"Name": "Bob",
"Age": 17,
"IsAdmin": false,
"IsMinor": true
}
],
"hasNextPage": true,
"endCursor": "W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI=="
}
}
}
Als u de volgende pagina wilt ophalen, neemt u de endCursor
waarde op in de volgende query:
query {
users(after: "W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI==") {
items {
Id
Name
Age
IsAdmin
IsMinor
}
hasNextPage
endCursor
}
}
REST en GraphQL maken het mogelijk om het aantal resultaten per query aan te passen met behulp van $limit
(REST) of first
(GraphQL).
$limit
/
first waarde |
Gedrag |
---|---|
-1 |
Standaard ingesteld op max-page-size . |
< max-page-size |
Hiermee beperkt u de resultaten tot de opgegeven waarde. |
0 of < -1 |
Niet ondersteund. |
> max-page-size |
Beperkt tot max-page-size . |
GET https://localhost:5001/api/users?$limit=5
query {
users(first: 5) {
items {
Id
Name
Age
IsAdmin
IsMinor
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
runtime.pagination |
max-page-size |
Int | ❌ Nee | 100,000 |
Hiermee stelt u het maximum aantal records op het hoogste niveau in dat wordt geretourneerd door REST of GraphQL. Als een gebruiker meer dan max-page-size
aanvraagt, worden de resultaten beperkt tot max-page-size
.
Waarde | Resultaat |
---|---|
-1 |
De standaardwaarde wordt ingesteld op de maximaal ondersteunde waarde. |
integer |
Elk positief 32-bits geheel getal wordt ondersteund. |
< -1 |
Niet ondersteund. |
0 |
Niet ondersteund. |
{
"runtime": {
"pagination": {
"max-page-size": <integer; default: 100000>
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
runtime.pagination |
default-page-size |
Int | ❌ Nee | 100 |
Hiermee stelt u het standaardaantal records op het hoogste niveau in dat wordt geretourneerd wanneer paginering is ingeschakeld, maar er geen expliciet paginaformaat wordt opgegeven.
Waarde | Resultaat |
---|---|
-1 |
De standaardinstelling is ingesteld op de huidige max-page-size . |
integer |
Een positief geheel getal kleiner dan de huidige max-page-size . |
< -1 |
Niet ondersteund. |
0 |
Niet ondersteund. |
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
runtime |
cache |
object | ❌ Nee | Geen |
Hiermee schakelt en configureert u caching voor de hele runtime.
{
"runtime": {
"cache": <object>
}
}
Eigenschap | Vereist | Type | Verstek |
---|---|---|---|
enabled |
❌ Nee | booleaans | Geen |
ttl-seconds |
❌ Nee | geheel getal | 5 |
In dit voorbeeld is cache ingeschakeld en verlopen de items na 30 seconden.
{
"runtime": {
"cache": {
"enabled": true,
"ttl-seconds": 30
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
runtime.cache |
enabled |
booleaans | ❌ Nee | Vals |
Hiermee schakelt u caching globaal in voor alle entiteiten. Standaard ingesteld op false
.
{
"runtime": {
"cache": {
"enabled": <boolean>
}
}
}
In dit voorbeeld is cache uitgeschakeld.
{
"runtime": {
"cache": {
"enabled": false
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
runtime.cache |
ttl-seconds |
geheel getal | ❌ Nee | 5 |
Hiermee configureert u de TTL-waarde (Time-to-Live) in seconden voor items in de cache. Na deze tijd worden items automatisch uit de cache verwijderd. De standaardwaarde is 5
seconden.
{
"runtime": {
"cache": {
"ttl-seconds": <integer>
}
}
}
In dit voorbeeld is cache globaal ingeschakeld en verlopen alle items na 15 seconden.
{
"runtime": {
"cache": {
"enabled": true,
"ttl-seconds": 15
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
runtime |
telemetry |
object | ❌ Nee | Geen |
Met deze eigenschap configureert u Application Insights om API-logboeken te centraliseren. Meer informatie.
{
"runtime": {
"telemetry": {
"application-insights": {
"enabled": <true; default: true> | <false>,
"connection-string": <string>
}
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
runtime.telemetry |
application-insights |
object | ✔️ Ja | Geen |
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
runtime.telemetry.application-insights |
enabled |
booleaans | ❌ Nee | Waar |
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
runtime.telemetry.application-insights |
connection-string |
snaar | ✔️ Ja | Geen |
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
$root |
entities |
object | ✔️ Ja | Geen |
De sectie entities
fungeert als de kern van het configuratiebestand, waarbij een brug tussen databaseobjecten en de bijbehorende API-eindpunten tot stand wordt gebracht. In deze sectie worden databaseobjecten toegewezen aan weergegeven eindpunten. Deze sectie bevat ook eigenschappentoewijzing en machtigingsdefinitie. Elke weergegeven entiteit wordt gedefinieerd in een toegewezen object. De eigenschapsnaam van het object wordt gebruikt als de naam van de entiteit die moet worden weergegeven.
In deze sectie wordt gedefinieerd hoe elke entiteit in de database wordt weergegeven in de API, inclusief eigenschapstoewijzingen en machtigingen. Elke entiteit wordt ingekapseld in een eigen subsectie, waarbij de naam van de entiteit fungeert als een sleutel voor verwijzing in de hele configuratie.
{
"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>
}
}
]
}
}
}
Vereist | Type | |
---|---|---|
source |
✔️ Ja | object |
permissions |
✔️ Ja | array |
rest |
❌ Nee | object |
graphql |
❌ Nee | object |
mappings |
❌ Nee | object |
relationships |
❌ Nee | object |
cache |
❌ Nee | object |
Met dit JSON-object geeft u bijvoorbeeld data-API-opbouwfunctie de opdracht om een GraphQL-entiteit met de naam User
en een REST-eindpunt beschikbaar te maken dat bereikbaar is via het /User
pad. De dbo.User
databasetabel maakt een back-up van de entiteit en de configuratie stelt iedereen in staat anoniem toegang te krijgen tot het eindpunt.
{
"entities": {
"User": {
"source": {
"object": "dbo.Users",
"type": "table"
},
"permissions": [
{
"role": "anonymous",
"actions": ["*"]
}
]
}
}
}
In dit voorbeeld wordt de entiteit User
declareren. Deze naam User
wordt overal in het configuratiebestand gebruikt waarnaar naar entiteiten wordt verwezen. Anders is de entiteitsnaam niet relevant voor de eindpunten.
{
"entities": {
"User": {
"source": {
"object": "dbo.Users",
"type": "table",
"key-fields": ["Id"],
"parameters": {} // only when source.type = stored-procedure
},
"rest": {
"enabled": true,
"path": "/users",
"methods": [] // only when source.type = stored-procedure
},
"graphql": {
"enabled": true,
"type": {
"singular": "User",
"plural": "Users"
},
"operation": "query"
},
"mappings": {
"id": "Id",
"name": "Name",
"age": "Age",
"isAdmin": "IsAdmin"
},
"permissions": [
{
"role": "authenticated",
"actions": ["read"], // "execute" only when source.type = stored-procedure
"fields": {
"include": ["id", "name", "age", "isAdmin"],
"exclude": []
},
"policy": {
"database": "@claims.userId eq @item.id"
}
},
{
"role": "admin",
"actions": ["create", "read", "update", "delete"],
"fields": {
"include": ["*"],
"exclude": []
},
"policy": {
"database": "@claims.userRole eq 'UserAdmin'"
}
}
]
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
entities.{entity} |
source |
object | ✔️ Ja | Geen |
De {entity}.source
-configuratie verbindt de door API beschikbaar gemaakte entiteit en het onderliggende databaseobject. Met deze eigenschap geeft u de databasetabel, weergave of opgeslagen procedure op die de entiteit vertegenwoordigt, waarbij een directe koppeling tot stand wordt gebracht voor het ophalen en bewerken van gegevens.
Voor eenvoudige scenario's waarbij de entiteit rechtstreeks wordt toegewezen aan één databasetabel, heeft de broneigenschap alleen de naam van dat databaseobject nodig. Met deze eenvoud kunt u snel instellen voor veelvoorkomende gebruiksvoorbeelden: "source": "dbo.User"
.
{
"entities": {
"<entity-name>": {
"source": {
"object": <string>,
"type": <"view" | "stored-procedure" | "table">,
"key-fields": <array of strings>,
"parameters": { // only when source.type = stored-procedure
"<name>": <string | number | boolean>
}
}
}
}
}
Vereist | Type | |
---|---|---|
object |
✔️ Ja | snaar |
type |
✔️ Ja | opsommingstekenreeks |
parameters |
❌ Nee | object |
key-fields |
❌ Nee | tekenreeksmatrix |
1. Eenvoudige tabeltoewijzing:
In dit voorbeeld ziet u hoe u een User
-entiteit koppelt aan een brontabel dbo.Users
.
SQL-
CREATE TABLE dbo.Users (
Id INT PRIMARY KEY,
Name NVARCHAR(100),
Age INT,
IsAdmin BIT
);
configuratie
{
"entities": {
"User": {
"source": {
"object": "dbo.Users",
"type": "table"
}
}
}
}
2. Voorbeeld van opgeslagen procedure:
In dit voorbeeld ziet u hoe u een User
entiteit koppelt aan een bronpro dbo.GetUsers
.
SQL-
CREATE PROCEDURE GetUsers
@IsAdmin BIT
AS
SELECT Id, Name, Age, IsAdmin
FROM dbo.Users
WHERE IsAdmin = @IsAdmin;
configuratie
{
"entities": {
"User": {
"source": {
"type": "stored-procedure",
"object": "GetUsers",
"parameters": {
"IsAdmin": "boolean"
}
},
"mappings": {
"Id": "id",
"Name": "name",
"Age": "age",
"IsAdmin": "isAdmin"
}
}
}
}
De eigenschap mappings
is optioneel voor opgeslagen procedures.
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
entities.{entity}.source |
object |
snaar | ✔️ Ja | Geen |
De naam van het databaseobject dat moet worden gebruikt. Als het object deel uitmaakt van het dbo
schema, is het opgeven van het schema optioneel. Daarnaast kunnen vierkante haken rond objectnamen (bijvoorbeeld [dbo].[Users]
versus dbo.Users
) worden gebruikt of weggelaten.
SQL-
CREATE TABLE dbo.Users (
Id INT PRIMARY KEY,
Name NVARCHAR(100),
Age INT,
IsAdmin BIT
);
configuratie
{
"entities": {
"User": {
"source": {
"object": "dbo.Users",
"type": "table"
}
}
}
}
alternatieve notatie zonder schema en vierkante haken:
Als de tabel zich in het dbo
schema bevindt, kunt u het schema of de accolades weglaten:
{
"entities": {
"User": {
"source": {
"object": "Users",
"type": "table"
}
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
entities.{entity}.source |
type |
snaar | ✔️ Ja | Geen |
De eigenschap type
identificeert het type databaseobject achter de entiteit, waaronder view
, table
en stored-procedure
. Deze eigenschap is vereist en heeft geen standaardwaarde.
{
"entities": {
"<entity-name>": {
"type": <"view" | "stored-procedure" | "table">
}
}
}
Waarde | Beschrijving |
---|---|
table |
Vertegenwoordigt een tabel. |
stored-procedure |
Vertegenwoordigt een opgeslagen procedure. |
view |
Vertegenwoordigt een weergave. |
1. Tabelvoorbeeld:
SQL-
CREATE TABLE dbo.Users (
Id INT PRIMARY KEY,
Name NVARCHAR(100),
Age INT,
IsAdmin BIT
);
configuratie
{
"entities": {
"User": {
"source": {
"object": "dbo.Users",
"type": "table"
}
}
}
}
2. Voorbeeld weergeven:
SQL-
CREATE VIEW dbo.AdminUsers AS
SELECT Id, Name, Age
FROM dbo.Users
WHERE IsAdmin = 1;
configuratie
{
"entities": {
"AdminUsers": {
"source": {
"object": "dbo.AdminUsers",
"type": "view",
"key-fields": ["Id"]
},
"mappings": {
"Id": "id",
"Name": "name",
"Age": "age"
}
}
}
}
Opmerking: Het opgeven van key-fields
is belangrijk voor weergaven omdat ze geen inherente primaire sleutels hebben.
3. Voorbeeld van opgeslagen procedure:
SQL-
CREATE PROCEDURE dbo.GetUsers (@IsAdmin BIT)
AS
SELECT Id, Name, Age, IsAdmin
FROM dbo.Users
WHERE IsAdmin = @IsAdmin;
configuratie
{
"entities": {
"User": {
"source": {
"type": "stored-procedure",
"object": "GetUsers",
"parameters": {
"IsAdmin": "boolean"
}
}
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
entities.{entity}.source |
key-fields |
tekenreeksmatrix | ❌ Nee | Geen |
De eigenschap {entity}.key-fields
is met name nodig voor entiteiten die worden ondersteund door weergaven, zodat Data API Builder weet hoe één item kan worden geïdentificeerd en geretourneerd. Als type
is ingesteld op view
zonder key-fields
op te geven, weigert de motor te starten. Deze eigenschap is toegestaan met tabellen en opgeslagen procedures, maar wordt in deze gevallen niet gebruikt.
Belangrijk
Deze eigenschap is vereist als het type object een view
is.
{
"entities": {
"<entity-name>": {
"source": {
"type": <"view" | "stored-procedure" | "table">,
"key-fields": <array of strings>
}
}
}
}
In dit voorbeeld wordt de dbo.AdminUsers
weergave gebruikt met Id
aangegeven als het sleutelveld.
SQL-
CREATE VIEW dbo.AdminUsers AS
SELECT Id, Name, Age
FROM dbo.Users
WHERE IsAdmin = 1;
configuratie
{
"entities": {
"AdminUsers": {
"source": {
"object": "dbo.AdminUsers",
"type": "view",
"key-fields": ["Id"]
}
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
entities.{entity}.source |
parameters |
object | ❌ Nee | Geen |
De eigenschap parameters
binnen entities.{entity}.source
wordt gebruikt voor entiteiten die worden ondersteund door opgeslagen procedures. Het zorgt voor de juiste toewijzing van parameternamen en gegevenstypen die zijn vereist voor de opgeslagen procedure.
Belangrijk
De eigenschap parameters
is vereist als de type
van het object is stored-procedure
en de parameter is vereist.
{
"entities": {
"<entity-name>": {
"source": {
"type": "stored-procedure",
"parameters": {
"<parameter-name-1>": <string | number | boolean>,
"<parameter-name-2>": <string | number | boolean>
}
}
}
}
}
SQL-
CREATE PROCEDURE dbo.GetUsers AS
SELECT Id, Name, Age, IsAdmin FROM dbo.Users;
configuratie
{
"entities": {
"Users": {
"source": {
"object": "dbo.GetUsers",
"type": "stored-procedure"
}
}
}
}
SQL-
CREATE PROCEDURE dbo.GetUser (@userId INT) AS
SELECT Id, Name, Age, IsAdmin FROM dbo.Users
WHERE Id = @userId;
configuratie
{
"entities": {
"User": {
"source": {
"object": "dbo.GetUser",
"type": "stored-procedure",
"parameters": {
"userId": "number"
}
}
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
entities.{entity} |
permissions |
object | ✔️ Ja | Geen |
In deze sectie wordt gedefinieerd wie toegang heeft tot de gerelateerde entiteit en welke acties zijn toegestaan. Machtigingen worden gedefinieerd in termen van rollen en CRUD-bewerkingen: create
, read
, update
en delete
. De sectie permissions
geeft aan welke rollen toegang hebben tot de gerelateerde entiteit en welke acties kunnen worden gebruikt.
{
"entities": {
"<entity-name>": {
"permissions": [
{
"actions": ["create", "read", "update", "delete", "execute", "*"]
}
]
}
}
}
Actie | Beschrijving |
---|---|
create |
Hiermee kunt u een nieuwe record in de entiteit maken. |
read |
Hiermee kunt u records lezen of ophalen uit de entiteit. |
update |
Hiermee kunt u bestaande records in de entiteit bijwerken. |
delete |
Hiermee staat u toe dat records uit de entiteit worden verwijderd. |
execute |
Hiermee kunt u een opgeslagen procedure of bewerking uitvoeren. |
* |
Verleent alle toepasselijke CRUD-bewerkingen. |
voorbeeld 1: Anonieme rol voor gebruikersentiteit
In dit voorbeeld wordt de rol anonymous
gedefinieerd met toegang tot alle mogelijke acties op de User
-entiteit.
{
"entities": {
"User": {
"permissions": [
{
"role": "anonymous",
"actions": ["*"]
}
]
}
}
}
voorbeeld 2: gemengde acties voor anonieme rol
In dit voorbeeld ziet u hoe u tekenreeks- en objectmatrixacties voor de entiteit User
kunt combineren.
{
"entities": {
"User": {
"permissions": [
{
"role": "anonymous",
"actions": [
{ "action": "read" },
"create"
]
}
]
}
}
}
anonieme rol: hiermee kunnen anonieme gebruikers alle velden lezen behalve een hypothetisch gevoelig veld (bijvoorbeeld secret-field
). Als u "include": ["*"]
gebruikt met "exclude": ["secret-field"]
worden secret-field
verborgen terwijl u toegang tot alle andere velden toestaat.
geverifieerde rol: hiermee kunnen geverifieerde gebruikers specifieke velden lezen en bijwerken. U kunt bijvoorbeeld expliciet id
, name
en age
opnemen, maar met uitzondering van isAdmin
laten zien hoe uitsluitingen insluitingen overschrijven.
beheerdersrol: beheerders kunnen alle bewerkingen (*
) uitvoeren op alle velden zonder uitsluitingen. Het opgeven van "include": ["*"]
met een lege "exclude": []
matrix verleent toegang tot alle velden.
Deze configuratie:
"fields": {
"include": [],
"exclude": []
}
is in feite identiek aan:
"fields": {
"include": ["*"],
"exclude": []
}
Houd ook rekening met deze installatie:
"fields": {
"include": [],
"exclude": ["*"]
}
Hiermee wordt aangegeven dat er geen velden expliciet worden opgenomen en dat alle velden worden uitgesloten, waardoor de toegang doorgaans volledig wordt beperkt.
Praktische gebruik: een dergelijke configuratie kan contra-intuïtief lijken omdat hiermee de toegang tot alle velden wordt beperkt. Het kan echter worden gebruikt in scenario's waarin een rol bepaalde acties uitvoert (zoals het maken van een entiteit) zonder toegang te krijgen tot een van de gegevens.
Hetzelfde gedrag, maar met verschillende syntaxis, zou het volgende zijn:
"fields": {
"include": ["Id", "Name"],
"exclude": ["*"]
}
Deze instelling probeert alleen Id
- en Name
velden op te nemen, maar sluit alle velden uit vanwege het jokerteken in exclude
.
Een andere manier om dezelfde logica uit te drukken, is:
"fields": {
"include": ["Id", "Name"],
"exclude": ["Id", "Name"]
}
Aangezien exclude
voorrang heeft op include
, betekent het opgeven van exclude: ["*"]
dat alle velden worden uitgesloten, zelfs die in include
. Op het eerste gezicht lijkt deze configuratie dus te voorkomen dat velden toegankelijk zijn.
De omgekeerde: als de bedoeling is om alleen toegang te verlenen tot Id
en Name
velden, is het duidelijker en betrouwbaarder om alleen die velden in de include
sectie op te geven zonder een uitsluitings-jokerteken te gebruiken:
"fields": {
"include": ["Id", "Name"],
"exclude": []
}
Vereist | Type | |
---|---|---|
role |
✔️ Ja | snaar |
actions (tekenreeksmatrix)of actions (objectmatrix) |
✔️ Ja | object- of tekenreeksmatrix |
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
entities.permissions |
role |
snaar | ✔️ Ja | Geen |
Tekenreeks met de naam van de rol waarop de gedefinieerde machtiging van toepassing is. Rollen stellen de machtigingscontext in waarin een aanvraag moet worden uitgevoerd. Voor elke entiteit die is gedefinieerd in de runtimeconfiguratie, kunt u een set rollen en bijbehorende machtigingen definiëren die bepalen hoe de entiteit kan worden geopend via REST- en GraphQL-eindpunten. Rollen zijn niet additief.
Data API Builder evalueert aanvragen in de context van één rol:
Rol | Beschrijving |
---|---|
anonymous |
Er wordt geen toegangstoken weergegeven |
authenticated |
Er wordt een geldig toegangstoken weergegeven |
<custom-role> |
Er wordt een geldig toegangstoken weergegeven en de X-MS-API-ROLE HTTP-header geeft een rol op die aanwezig is in het token |
{
"entities": {
"<entity-name>": {
"permissions": [
{
"role": <"anonymous" | "authenticated" | "custom-role">,
"actions": ["create", "read", "update", "delete", "execute", "*"],
"fields": {
"include": <array of strings>,
"exclude": <array of strings>
}
}
]
}
}
}
In dit voorbeeld wordt een rol gedefinieerd met de naam reader
met alleen read
machtigingen voor de entiteit User
.
{
"entities": {
"User": {
"permissions": [
{
"role": "reader",
"actions": ["read"]
}
]
}
}
}
U kunt <custom-role>
gebruiken wanneer een geldig toegangstoken wordt weergegeven en de X-MS-API-ROLE
HTTP-header is opgenomen, waarbij u een gebruikersrol opgeeft die ook is opgenomen in de rolclaim van het toegangstoken. Hieronder ziet u voorbeelden van GET-aanvragen voor de User
-entiteit, waaronder zowel het bearer-token voor autorisatie als de X-MS-API-ROLE
header, op de REST-eindpuntbasis /api
op localhost
met behulp van verschillende talen.
-
HTTP-
- C#-
- JavaScript/TypeScript-
-
Python-
GET https://localhost:5001/api/User
Authorization: Bearer <your_access_token>
X-MS-API-ROLE: custom-role
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
entities.permissions |
actions |
oneOf [tekenreeks, matrix] | ✔️ Ja | Geen |
Een matrix met tekenreekswaarden waarin wordt beschreven welke bewerkingen zijn toegestaan voor de bijbehorende rol. Voor table
- en view
-databaseobjecten kunnen rollen elke combinatie van create
, read
, update
of delete
acties gebruiken. Voor opgeslagen procedures kunnen rollen alleen de execute
actie hebben.
Actie | SQL-bewerking |
---|---|
* |
Jokerteken, inclusief uitvoeren |
create |
Een of meer rijen invoegen |
read |
Een of meer rijen selecteren |
update |
Een of meer rijen wijzigen |
delete |
Een of meer rijen verwijderen |
execute |
Een opgeslagen procedure uitvoeren |
Notitie
Voor opgeslagen procedures wordt de actie jokerteken (*
) alleen uitgebreid naar de execute
actie. Voor tabellen en weergaven wordt deze uitgebreid naar create
, read
, update
en delete
.
In dit voorbeeld worden create
- en read
machtigingen verleend voor een rol met de naam contributor
en delete
machtigingen voor een rol met de naam auditor
op de User
-entiteit.
{
"entities": {
"User": {
"permissions": [
{
"role": "auditor",
"actions": ["delete"]
},
{
"role": "contributor",
"actions": ["read", "create"]
}
]
}
}
}
Een ander voorbeeld:
{
"entities": {
"User": {
"permissions": [
{
"role": "contributor",
"actions": ["read", "create"]
}
]
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
entities.permissions |
actions |
tekenreeksmatrix | ✔️ Ja | Geen |
Een matrix met actieobjecten met details van toegestane bewerkingen voor de bijbehorende rol. Voor table
- en view
-objecten kunnen rollen elke combinatie van create
, read
, update
of delete
gebruiken. Voor opgeslagen procedures is alleen execute
toegestaan.
Notitie
Voor opgeslagen procedures wordt de actie jokerteken (*
) uitgebreid tot alleen execute
. Voor tabellen/weergaven wordt deze uitgebreid naar create
, read
, update
en delete
.
{
"entities": {
"<entity-name>": {
"permissions": [
{
"role": <string>,
"actions": [
{
"action": <string>,
"fields": <array of strings>,
"policy": <object>
}
]
}
]
}
}
}
Eigenschap | Vereist | Type | Verstek |
---|---|---|---|
action |
✔️ Ja | snaar | Geen |
fields |
❌ Nee | tekenreeksmatrix | Geen |
policy |
❌ Nee | object | Geen |
In dit voorbeeld wordt alleen read
machtiging verleend aan de auditor
rol voor de User
-entiteit, met veld- en beleidsbeperkingen.
{
"entities": {
"User": {
"permissions": [
{
"role": "auditor",
"actions": [
{
"action": "read",
"fields": {
"include": ["*"],
"exclude": ["last_login"]
},
"policy": {
"database": "@item.IsAdmin eq false"
}
}
]
}
]
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
entities.permissions.actions[] |
action |
snaar | ✔️ Ja | Geen |
Hiermee geeft u de specifieke bewerking op die is toegestaan voor het databaseobject.
Tabellen | Weergaven | Opgeslagen procedures | Beschrijving | |
---|---|---|---|---|
create |
✔️ Ja | ✔️ Ja | ❌ Nee | Nieuwe items maken |
read |
✔️ Ja | ✔️ Ja | ❌ Nee | Bestaande items lezen |
update |
✔️ Ja | ✔️ Ja | ❌ Nee | Items bijwerken of vervangen |
delete |
✔️ Ja | ✔️ Ja | ❌ Nee | Items verwijderen |
execute |
❌ Nee | ❌ Nee | ✔️ Ja | Programmatische bewerkingen uitvoeren |
{
"entities": {
"<entity-name>": {
"permissions": [
{
"role": "<role>",
"actions": [
{
"action": "<string>",
"fields": {
"include": [/* fields */],
"exclude": [/* fields */]
},
"policy": {
"database": "<predicate>"
}
}
]
}
]
}
}
}
Hier volgt een voorbeeld waarin anonymous
gebruikers een opgeslagen procedure mogen execute
en read
uit de User
tabel.
{
"entities": {
"User": {
"source": {
"object": "dbo.Users",
"type": "table"
},
"permissions": [
{
"role": "anonymous",
"actions": [
{
"action": "read"
}
]
}
]
},
"GetUser": {
"source": {
"object": "dbo.GetUser",
"type": "stored-procedure",
"parameters": {
"userId": "number"
}
},
"permissions": [
{
"role": "anonymous",
"actions": [
{
"action": "execute"
}
]
}
]
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
entities.permissions.actions[] |
fields |
object | ❌ Nee | Geen |
Gedetailleerde specificaties waarvoor specifieke velden toegang hebben tot het databaseobject. Rolconfiguratie is een objecttype met twee interne eigenschappen, include
en exclude
. Deze waarden ondersteunen gedetailleerd definiëren welke databasekolommen (velden) toegang hebben in de sectie fields
.
{
"entities": {
<string>: {
"permissions": [
{
"role": <string>,
"actions": [
{
"action": <string>,
"fields": {
"include": <array of strings>,
"exclude": <array of strings>
},
"policy": <object>
}
]
}
]
}
}
}
In dit voorbeeld mag de rol anonymous
lezen uit alle velden behalve id
, maar kan alle velden gebruiken bij het maken van een item.
{
"entities": {
"Author": {
"permissions": [
{
"role": "anonymous",
"actions": [
{
"action": "read",
"fields": {
"include": [ "*" ],
"exclude": [ "id" ]
}
},
{ "action": "create" }
]
}
]
}
}
}
Werk samen opnemen en uitsluiten. Het jokerteken *
in de sectie include
geeft alle velden aan. De velden die in de sectie exclude
worden vermeld, hebben voorrang op velden die zijn genoteerd in de include
sectie. De definitie wordt omgezet in alle velden bevatten, met uitzondering van het veld '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": []
}
}
]
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
entities.{entity}.permissions.actions[] |
policy |
object | ❌ Nee | Geen |
De sectie policy
, gedefinieerd per action
, definieert beveiligingsregels op itemniveau (databasebeleid) die de resultaten van een aanvraag beperken. De subsectie database
geeft de expressie van het databasebeleid aan die wordt geëvalueerd tijdens de uitvoering van de aanvraag.
{
"entities": {
"<entity-name>": {
"permissions": [
{
"role": <string>,
"actions": [
{
"action": <string>,
"fields": <object>,
"policy": {
"database": <string>
}
}
]
}
]
}
}
}
Eigenschap | Vereist | Type | Verstek |
---|---|---|---|
database |
✔️ Ja | snaar | Geen |
Het database
beleid: een OData-achtige expressie die wordt vertaald in een querypredicaat dat de database evalueert, inclusief operators zoals eq
, lt
en gt
. Om resultaten voor een aanvraag te kunnen retourneren, moet het querypredicaat van de aanvraag dat is opgelost vanuit een databasebeleid, true
evalueren bij uitvoering op basis van de database.
Voorbeelditembeleid | Predikaat |
---|---|
@item.OwnerId eq 2000 |
WHERE Table.OwnerId = 2000 |
@item.OwnerId gt 2000 |
WHERE Table.OwnerId > 2000 |
@item.OwnerId lt 2000 |
WHERE Table.OwnerId < 2000 |
Een
predicate
is een expressie die RESULTEERT in WAAR of ONWAAR. Predicaten worden gebruikt in de zoekvoorwaarde van WHERE-componenten en HAVING--componenten, de joinvoorwaarden van FROM-componenten en andere constructies waarbij een Boole-waarde is vereist. (Microsoft Learn Docs)
Er kunnen twee typen instructies worden gebruikt voor het beheren van databasebeleid bij het ontwerpen van een databasebeleidsexpressie:
Richtlijn | Beschrijving |
---|---|
@claims |
Toegang krijgen tot een claim binnen het gevalideerde toegangstoken dat is opgegeven in de aanvraag |
@item |
Vertegenwoordigt een veld van de entiteit waarvoor het databasebeleid is gedefinieerd |
Notitie
Wanneer Azure Static Web Apps-verificatie (EasyAuth) is geconfigureerd, zijn er een beperkt aantal claimtypen beschikbaar voor gebruik in databasebeleid: identityProvider
, userId
, userDetails
en userRoles
. Zie de client-principalgegevens van Azure Static Web App documentatie voor meer informatie.
Hier volgen enkele voorbeelden van databasebeleid:
@claims.userId eq @item.OwnerId
@claims.userId gt @item.OwnerId
@claims.userId lt @item.OwnerId
Data API Builder vergelijkt de waarde van de UserId
claim met de waarde van het databaseveld OwnerId
. De nettolading van het resultaat bevat alleen records die voldoen aan zowel de metagegevens van de aanvraag als de expressie van het databasebeleid.
Databasebeleid wordt ondersteund voor tabellen en weergaven. Opgeslagen procedures kunnen niet worden geconfigureerd met beleid.
Databasebeleid voorkomt niet dat aanvragen worden uitgevoerd in de database. Dit gedrag komt doordat ze worden omgezet als predicaten in de gegenereerde query's die worden doorgegeven aan de database-engine.
Databasebeleidsregels worden alleen ondersteund voor het actions
maken, lezen, bijwerken en verwijderen. Omdat er geen predicaat is in een opgeslagen procedure-aanroep, kunnen ze niet worden toegevoegd.
Bediener | Beschrijving | Voorbeeldsyntaxis |
---|---|---|
and |
Logische EN | "@item.status eq 'active' and @item.age gt 18" |
or |
Logische OR | "@item.region eq 'US' or @item.region eq 'EU'" |
eq |
Is gelijk aan | "@item.type eq 'employee'" |
gt |
Groter dan | "@item.salary gt 50000" |
lt |
Kleiner dan | "@item.experience lt 5" |
Zie binaire operatorsvoor meer informatie.
Bediener | Beschrijving | Voorbeeldsyntaxis |
---|---|---|
- |
Negate (numeriek) | "@item.balance lt -100" |
not |
Logische negate (NIET) | "not @item.status eq 'inactive'" |
Zie unaire operatorsvoor meer informatie.
-
Regels: Moet beginnen met een letter of onderstrepingsteken (
_
), gevolgd door maximaal 127 letters, onderstrepingstekens (_
) of cijfers (0-9
). - Impact: velden die niet aan deze regels zijn gekoppeld, kunnen niet rechtstreeks worden gebruikt in databasebeleid.
-
Solution: gebruik de sectie
mappings
om aliassen te maken voor velden die niet voldoen aan deze naamconventies; toewijzingen zorgen ervoor dat alle velden kunnen worden opgenomen in beleidsexpressies.
Als de namen van uw entiteitsvelden niet voldoen aan de regels voor de OData-syntaxis of als u ze om andere redenen wilt aliasen, kunt u aliassen definiëren in de sectie mappings
van uw configuratie.
{
"entities": {
"<entity-name>": {
"mappings": {
"<field-1-name>": <string>,
"<field-2-name>": <string>,
"<field-3-name>": <string>
}
}
}
}
In dit voorbeeld is field-1-name
de oorspronkelijke naam van het databaseveld die niet voldoet aan de naamconventies van OData. Door een toewijzing te maken voor field-1-name
en field-1-alias
kan dit veld zonder problemen worden verwezen in expressies van databasebeleid. Deze benadering helpt niet alleen bij het naleven van de OData-naamconventies, maar verbetert ook de duidelijkheid en toegankelijkheid van uw gegevensmodel binnen zowel GraphQL- als RESTful-eindpunten.
Overweeg een entiteit met de naam Employee
binnen een gegevens-API-configuratie die gebruikmaakt van zowel claims als itemrichtlijnen. Het zorgt ervoor dat gegevenstoegang veilig wordt beheerd op basis van gebruikersrollen en entiteitseigendom:
{
"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"
}
}
}
}
Entiteitsdefinitie: de Employee
-entiteit is geconfigureerd voor REST- en GraphQL-interfaces, waarmee wordt aangegeven dat de gegevens kunnen worden opgevraagd of gemanipuleerd via deze eindpunten.
bronconfiguratie: identificeert de HRUNITS
in de database, met employee NUM
als sleutelveld.
toewijzingen: Aliassen worden gebruikt om respectievelijk employee NUM
, employee Name
en department COID
toe te wijzen aan EmployeeId
, EmployeeName
en DepartmentId
, waardoor veldnamen worden vereenvoudigd en mogelijk gevoelige databaseschemagegevens worden verborgen.
beleidstoepassing: in de sectie policy
wordt een databasebeleid toegepast met behulp van een OData-achtige expressie. Dit beleid beperkt de gegevenstoegang tot gebruikers met de hr-rol (@claims.role eq 'HR'
) of gebruikers van wie UserId
claim overeenkomt met EmployeeId
- de veldalias - in de database (@claims.userId eq @item.EmployeeId
). Het zorgt ervoor dat werknemers alleen toegang hebben tot hun eigen records, tenzij ze bij de HR-afdeling horen. Beleidsregels kunnen beveiliging op rijniveau afdwingen op basis van dynamische voorwaarden.
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
entities.{entity}.permissions.actions.policy |
database |
object | ✔️ Ja | Geen |
De sectie policy
, gedefinieerd per action
, definieert beveiligingsregels op itemniveau (databasebeleid) die de resultaten van een aanvraag beperken. De subsectie database
geeft de expressie van het databasebeleid aan die wordt geëvalueerd tijdens de uitvoering van de aanvraag.
{
"entities": {
"<entity-name>": {
"permissions": [
{
"role": <string>,
"actions": [
{
"action": <string>,
"fields": {
"include": <array of strings>,
"exclude": <array of strings>
},
"policy": {
"database": <string>
}
}
]
}
]
}
}
}
Deze eigenschap geeft de expressie van het databasebeleid aan die wordt geëvalueerd tijdens de uitvoering van de aanvraag. De beleidsreeks is een OData-expressie die wordt vertaald in een query die door de database wordt geëvalueerd. De beleidsexpressie @item.OwnerId eq 2000
wordt bijvoorbeeld vertaald naar het querypredicaat WHERE <schema>.<object-name>.OwnerId = 2000
.
Notitie
Een predicaat is een expressie die wordt geëvalueerd voor TRUE
, FALSE
of UNKNOWN
. Predicaten worden gebruikt in:
- De zoekvoorwaarde van
WHERE
-componenten - De zoekvoorwaarde van
FROM
-componenten - De joinvoorwaarden van
FROM
-componenten - Andere constructies waarbij een Booleaanse waarde is vereist.
Zie predicatenvoor meer informatie.
Om resultaten voor een aanvraag te kunnen retourneren, moet het querypredicaat van de aanvraag dat is opgelost vanuit een databasebeleid, true
evalueren bij uitvoering op basis van de database.
Er kunnen twee typen instructies worden gebruikt om het databasebeleid te beheren bij het ontwerpen van een databasebeleidsexpressie:
Beschrijving | |
---|---|
@claims |
Hiermee opent u een claim binnen het gevalideerde toegangstoken dat is opgegeven in de aanvraag |
@item |
Vertegenwoordigt een veld van de entiteit waarvoor het databasebeleid is gedefinieerd |
Notitie
Er is een beperkt aantal claimtypen beschikbaar voor gebruik in databasebeleid wanneer Azure Static Web Apps-verificatie (EasyAuth) is geconfigureerd. Deze claimtypen zijn: identityProvider
, userId
, userDetails
en userRoles
. Zie Azure Static Web Apps-clientprincipaalgegevensvoor meer informatie.
Een basisbeleidsexpressie kan bijvoorbeeld evalueren of een specifiek veld waar is in de tabel. In dit voorbeeld wordt geëvalueerd of het veld soft_delete
is false
.
{
"entities": {
"Manuscripts": {
"permissions": [
{
"role": "anonymous",
"actions": [
{
"action": "read",
"policy": {
"database": "@item.soft_delete eq false"
}
}
]
}
]
}
}
}
Predicaten kunnen ook zowel claims
als item
richtlijntypen evalueren. In dit voorbeeld wordt het UserId
veld opgehaald uit het toegangstoken en vergeleken met het owner_id
veld in de doeldatabasetabel.
{
"entities": {
"Manuscript": {
"permissions": [
{
"role": "anonymous",
"actions": [
{
"action": "read",
"policy": {
"database": "@claims.userId eq @item.owner_id"
}
}
]
}
]
}
}
}
- Databasebeleid wordt ondersteund voor tabellen en weergaven. Opgeslagen procedures kunnen niet worden geconfigureerd met beleid.
- Databasebeleid kan niet worden gebruikt om te voorkomen dat een aanvraag wordt uitgevoerd in een database. Deze beperking komt doordat databasebeleidsregels worden omgezet als querypredicaten in de gegenereerde databasequery's. De database-engine evalueert deze query's uiteindelijk.
- Databasebeleid wordt alleen ondersteund voor de
actions
create
,read
,update
endelete
. - De syntaxis van de OData-expressie voor databasebeleid ondersteunt deze scenario's alleen.
- Binaire operatoren, waaronder, maar niet beperkt tot;
and
,or
,eq
,gt
enlt
. ZieBinaryOperatorKind
voor meer informatie. - Unaire operators zoals de operatoren
-
(negate) ennot
. ZieUnaryOperatorKind
voor meer informatie.
- Binaire operatoren, waaronder, maar niet beperkt tot;
- Databasebeleidsregels hebben ook beperkingen met betrekking tot veldnamen.
- Namen van entiteitsvelden die beginnen met een letter of onderstrepingsteken, gevolgd door maximaal 127 letters, onderstrepingstekens of cijfers.
- Deze vereiste is per OData-specificatie. Zie Algemene schemadefinitietaal van ODatavoor meer informatie.
Fooi
In databasebeleid kunnen niet worden verwezen naar velden die niet voldoen aan de genoemde beperkingen. Als tijdelijke oplossing configureert u de entiteit met een toewijzingssectie om aliassen toe te wijzen aan de velden.
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
entities.{entity} |
graphql |
object | ❌ Nee | Geen |
Dit object definieert of GraphQL is ingeschakeld en de naam[s] die wordt gebruikt om de entiteit beschikbaar te maken als een GraphQL-type. Dit object is optioneel en wordt alleen gebruikt als de standaardnaam of instellingen niet voldoende zijn.
Dit segment biedt de integratie van een entiteit in het GraphQL-schema. Hiermee kunnen ontwikkelaars standaardwaarden voor de entiteit in GraphQL opgeven of wijzigen. Deze instelling zorgt ervoor dat het schema de beoogde structuur- en naamconventies nauwkeurig weergeeft.
{
"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"
}
}
}
}
Eigenschap | Vereist | Type | Verstek |
---|---|---|---|
enabled |
❌ Nee | booleaans | Geen |
type |
❌ Nee | tekenreeks of object | Geen |
operation |
❌ Nee | opsommingstekenreeks | Geen |
Deze twee voorbeelden zijn functioneel gelijkwaardig.
{
"entities": {
"Author": {
"graphql": true
}
}
}
{
"entities": {
"Author": {
"graphql": {
"enabled": true
}
}
}
}
In dit voorbeeld wordt de gedefinieerde entiteit Book
, waarmee wordt aangegeven dat we te maken hebben met een set gegevens die betrekking hebben op boeken in de database. De configuratie voor de Book
-entiteit in het GraphQL-segment biedt een duidelijke structuur over hoe deze moet worden weergegeven en ermee moet worden gecommuniceerd in een GraphQL-schema.
eigenschap ingeschakeld: de entiteit Book
wordt beschikbaar gesteld via GraphQL ("enabled": true
), wat betekent dat ontwikkelaars en gebruikers boekgegevens kunnen opvragen of dempen via GraphQL-bewerkingen.
eigenschap Type: de entiteit wordt weergegeven met de enkelvoudige naam "Book"
en de meervoudsnaam "Books"
in het GraphQL-schema. Dit onderscheid zorgt ervoor dat bij het uitvoeren van query's op één boek of meerdere boeken het schema intuïtief benoemde typen (Book
voor één vermelding, Books
voor een lijst), waardoor de bruikbaarheid van de API wordt verbeterd.
eigenschap Bewerking: de bewerking is ingesteld op "query"
, wat aangeeft dat de primaire interactie met de Book
-entiteit via GraphQL is bedoeld om query's uit te voeren op gegevens (ophalen) in plaats van deze gegevens te dempen (maken, bijwerken of verwijderen). Deze instelling is afgestemd op typische gebruikspatronen waarbij boekgegevens vaker worden gelezen dan gewijzigd.
{
"entities": {
"Book": {
...
"graphql": {
"enabled": true,
"type": {
"singular": "Book",
"plural": "Books"
},
"operation": "query"
},
...
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
entities.{entity}.graphql |
type |
oneOf [tekenreeks, object] | ❌ Nee | {entity-name} |
Deze eigenschap bepaalt de naamconventie voor een entiteit in het GraphQL-schema. Het ondersteunt zowel scalaire tekenreekswaarden als objecttypen. De objectwaarde geeft de enkelvoudige en meervoudvormen aan. Deze eigenschap biedt gedetailleerde controle over de leesbaarheid en gebruikerservaring van het schema.
{
"entities": {
<entity-name>: {
"graphql": {
"type": <string>
}
}
}
}
{
"entities": {
<entity-name>: {
"graphql": {
"type": {
"singular": <string>,
"plural": <string>
}
}
}
}
}
Eigenschap | Vereist | Type | Verstek |
---|---|---|---|
singular |
❌ Nee | snaar | Geen |
plural |
❌ Nee | snaar | N.b. (standaard: enkelvoud) |
Voor nog meer controle over het GraphQL-type kunt u configureren hoe de enkelvoudige en meervoudsnaam onafhankelijk wordt weergegeven.
Als plural
ontbreekt of weglaat (zoals scalaire waarde) wordt geprobeerd de naam automatisch te pluraliseren, volgt u de Engelse regels voor pluralisatie (bijvoorbeeld: https://engdic.org/singular-and-plural-noun-rules-definitions-examples)
{
"entities" {
"<entity-name>": {
...
"graphql": {
...
"type": {
"singular": "User",
"plural": "Users"
}
}
}
}
}
Een aangepaste entiteitsnaam kan worden opgegeven met behulp van de parameter type
met een tekenreekswaarde. In dit voorbeeld maakt de engine automatisch onderscheid tussen de enkelvoudige en meervoudsvarianten van deze naam met behulp van algemene Engelse regels voor pluralisatie.
{
"entities": {
"Author": {
"graphql": {
"type": "bookauthor"
}
}
}
}
Als u ervoor kiest om de namen expliciet op te geven, gebruikt u de eigenschappen type.singular
en type.plural
. In dit voorbeeld worden beide namen expliciet ingesteld.
{
"entities": {
"Author": {
"graphql": {
"type": {
"singular": "bookauthor",
"plural": "bookauthors"
}
}
}
}
}
Beide voorbeelden zijn functioneel gelijkwaardig. Ze retourneren beide dezelfde JSON-uitvoer voor een GraphQL-query die gebruikmaakt van de naam van de bookauthors
entiteit.
{
bookauthors {
items {
first_name
last_name
}
}
}
{
"data": {
"bookauthors": {
"items": [
{
"first_name": "Henry",
"last_name": "Ross"
},
{
"first_name": "Jacob",
"last_name": "Hancock"
},
...
]
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
entities.{entity}.graphql |
operation |
opsommingstekenreeks | ❌ Nee | Geen |
Voor entiteiten die zijn toegewezen aan opgeslagen procedures, wijst de eigenschap operation
het GraphQL-bewerkingstype (query of mutatie) aan waar de opgeslagen procedure toegankelijk is. Met deze instelling kunt u het schema logisch organiseren en voldoen aan best practices voor GraphQL, zonder dat dit van invloed is op de functionaliteit.
Notitie
Een entiteit wordt opgegeven als een opgeslagen procedure door de eigenschapswaarde van de {entity}.type
in te stellen op stored-procedure
. In het geval van een opgeslagen procedure wordt automatisch een nieuw GraphQL-type executeXXX gemaakt. Met de eigenschap operation
kan de ontwikkelaar echter de locatie van dat type koppelen aan de mutation
of query
onderdelen van het schema. Met deze eigenschap kunt u schema-hygene gebruiken en is er geen functionele impact, ongeacht operation
waarde.
Als de operation
standaard ontbreekt, wordt mutation
.
{
"entities": {
"<entity-name>": {
"graphql": {
"operation": "query" (default) | "mutation"
}
}
}
}
Hier volgt een lijst met toegestane waarden voor deze eigenschap:
Beschrijving | |
---|---|
query |
De onderliggende opgeslagen procedure wordt weergegeven als een query |
mutation |
De onderliggende opgeslagen procedure wordt blootgesteld als mutatie |
Wanneer operation
is mutation
, ziet het GraphQL-schema er ongeveer als volgt uit:
type Mutation {
executeGetCowrittenBooksByAuthor(
searchType: String = "S"
): [GetCowrittenBooksByAuthor!]!
}
Wanneer operation
is query
, ziet het GraphQL-schema er ongeveer als volgt uit:
Het GraphQL-schema lijkt op:
type Query {
executeGetCowrittenBooksByAuthor(
searchType: String = "S"
): [GetCowrittenBooksByAuthor!]!
}
Notitie
De eigenschap operation
gaat alleen over de plaatsing van de bewerking in het GraphQL-schema. Het gedrag van de bewerking wordt niet gewijzigd.
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
entities.{entity}.graphql |
enabled |
booleaans | ❌ Nee | Waar |
Hiermee schakelt u het GraphQL-eindpunt in of uit. Hiermee bepaalt u of een entiteit beschikbaar is via GraphQL-eindpunten. Door de eigenschap enabled
in te schakelen, kunnen ontwikkelaars selectief entiteiten uit het GraphQL-schema beschikbaar maken.
{
"entities": {
"<entity-name>": {
"graphql": {
"enabled": <true> (default) | <false>
}
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
entities.{entity} |
rest |
object | ❌ Nee | Geen |
De rest
sectie van het configuratiebestand is toegewezen aan het verfijnen van de RESTful-eindpunten voor elke database-entiteit. Deze aanpassingsmogelijkheid zorgt ervoor dat de weergegeven REST API overeenkomt met specifieke vereisten, waardoor zowel het hulpprogramma als de integratiemogelijkheden worden verbeterd. Het adresseert mogelijke niet-overeenkomende waarden tussen de standaardinstellingen en het gewenste eindpuntgedrag.
{
"entities": {
"<entity-name>": {
"rest": {
"enabled": <true> (default) | <false>,
"path": <string; default: "<entity-name>">,
"methods": <array of strings; default: ["GET", "POST"]>
}
}
}
}
Eigenschap | Vereist | Type | Verstek |
---|---|---|---|
enabled |
✔️ Ja | booleaans | Waar |
path |
❌ Nee | snaar | /<entity-name> |
methods |
❌ Nee | tekenreeksmatrix | TOEVOEGEN |
Deze twee voorbeelden zijn functioneel gelijkwaardig.
{
"entities": {
"Author": {
"source": {
"object": "dbo.authors",
"type": "table"
},
"permissions": [
{
"role": "anonymous",
"actions": ["*"]
}
],
"rest": true
}
}
}
{
"entities": {
"Author": {
...
"rest": {
"enabled": true
}
}
}
}
Hier volgt een ander voorbeeld van een REST-configuratie voor een entiteit.
{
"entities" {
"User": {
"rest": {
"enabled": true,
"path": "/User"
},
...
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
entities.{entity}.rest |
enabled |
booleaans | ❌ Nee | Waar |
Deze eigenschap fungeert als wisselknop voor de zichtbaarheid van entiteiten binnen de REST API. Door de eigenschap enabled
in te stellen op true
of false
, kunnen ontwikkelaars de toegang tot specifieke entiteiten beheren, waardoor een aangepast API-oppervlak wordt ingeschakeld dat overeenkomt met de vereisten voor toepassingsbeveiliging en -functionaliteit.
{
"entities": {
"<entity-name>": {
"rest": {
"enabled": <true> (default) | <false>
}
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
entities.rest |
path |
snaar | ❌ Nee | Geen |
De eigenschap path
geeft het URI-segment op dat wordt gebruikt voor toegang tot een entiteit via de REST API. Met deze aanpassing kunnen meer beschrijvende of vereenvoudigde eindpuntpaden worden gebruikt buiten de standaardentiteitsnaam, waardoor API-navigatie en integratie aan de clientzijde worden verbeterd. Het pad is standaard /<entity-name>
.
{
"entities": {
"<entity-name>": {
"rest": {
"path": <string; default: "<entity-name>">
}
}
}
}
In dit voorbeeld wordt de Author
entiteit weergegeven met behulp van het /auth
-eindpunt.
{
"entities": {
"Author": {
"rest": {
"path": "/auth"
}
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
entities.{entity}.rest |
methods |
tekenreeksmatrix | ❌ Nee | Geen |
Specifiek van toepassing op opgeslagen procedures bepaalt de eigenschap methods
welke HTTP-woorden (bijvoorbeeld GET, POST) de procedure kan beantwoorden. Methoden maken nauwkeurige controle mogelijk over de manier waarop opgeslagen procedures beschikbaar worden gesteld via de REST API, waardoor compatibiliteit met RESTful-standaarden en clientwachttijden wordt gewaarborgd. In deze sectie wordt de toezegging van het platform onderstreept voor flexibiliteit en beheer door ontwikkelaars, zodat het ontwerp van de API nauwkeurig en intuïtief is afgestemd op de specifieke behoeften van elke toepassing.
Als u dit weglaat of ontbreekt, wordt de standaardinstelling methods
POST
.
{
"entities": {
"<entity-name>": {
"rest": {
"methods": ["GET" (default), "POST"]
}
}
}
}
Hier volgt een lijst met toegestane waarden voor deze eigenschap:
Beschrijving | |
---|---|
get |
HTTP GET-aanvragen beschikbaar maken |
post |
HTTP POST-aanvragen beschikbaar maken |
In dit voorbeeld wordt de engine geïnstrueerd dat de stp_get_bestselling_authors
opgeslagen procedure alleen ondersteuning biedt voor HTTP GET
acties.
{
"entities": {
"BestSellingAuthor": {
"source": {
"object": "dbo.stp_get_bestselling_authors",
"type": "stored-procedure",
"parameters": {
"depth": "number"
}
},
"rest": {
"path": "/best-selling-authors",
"methods": [ "get" ]
}
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
entities.{entity} |
mappings |
object | ❌ Nee | Geen |
De sectie mappings
maakt het configureren van aliassen of weergegeven namen mogelijk voor databaseobjectvelden. De geconfigureerde weergegeven namen zijn van toepassing op zowel de GraphQL- als REST-eindpunten.
Belangrijk
Voor entiteiten waarvoor GraphQL is ingeschakeld, moet de geconfigureerde weergegeven naam voldoen aan de naamgevingsvereisten voor GraphQL. Zie GraphQL-namenspecificatievoor meer informatie.
{
"entities": {
"<entity-name>": {
"mappings": {
"<field-1-name>": "<field-1-alias>",
"<field-2-name>": "<field-2-alias>",
"<field-3-name>": "<field-3-alias>"
}
}
}
}
In dit voorbeeld wordt het sku_title
veld van het databaseobject dbo.magazines
weergegeven met behulp van de naam title
. Op dezelfde manier wordt het sku_status
veld weergegeven als status
in zowel REST- als GraphQL-eindpunten.
{
"entities": {
"Magazine": {
...
"mappings": {
"sku_title": "title",
"sku_status": "status"
}
}
}
}
Hier volgt nog een voorbeeld van toewijzingen.
{
"entities": {
"Book": {
...
"mappings": {
"id": "BookID",
"title": "BookTitle",
"author": "AuthorName"
}
}
}
}
Toewijzingen: het mappings
-object koppelt de databasevelden (BookID
, BookTitle
, AuthorName
) aan intuïtievere of gestandaardiseerde namen (id
, title
, author
) die extern worden gebruikt. Deze aliasing dient voor verschillende doeleinden:
Clarity and Consistency: hiermee kunt u duidelijke en consistente namen in de API gebruiken, ongeacht het onderliggende databaseschema.
BookID
in de database wordt bijvoorbeeld weergegeven alsid
in de API, waardoor ontwikkelaars gemakkelijker kunnen communiceren met het eindpunt.GraphQL Compliance: Door een mechanisme voor aliasveldnamen op te geven, zorgt dit ervoor dat de namen die via de GraphQL-interface worden weergegeven, voldoen aan de graphQL-naamgevingsvereisten. Aandacht voor namen is belangrijk omdat GraphQL strikte regels heeft voor namen (bijvoorbeeld geen spaties, moet beginnen met een letter of onderstrepingsteken, enzovoort). Als een databaseveldnaam bijvoorbeeld niet aan deze criteria voldoet, kan deze worden gealiaseerd naar een compatibele naam via toewijzingen.
Flexibiliteit: met deze aliasing wordt een abstractielaag toegevoegd tussen het databaseschema en de API, waardoor wijzigingen in de ene kunnen worden aangebracht zonder dat hiervoor wijzigingen in de andere nodig zijn. Een veldnaamwijziging in de database vereist bijvoorbeeld geen update naar de API-documentatie of code aan de clientzijde als de toewijzing consistent blijft.
veldnaam verdoezelen: toewijzing maakt het mogelijk om veldnamen te verdoezelen, waardoor onbevoegde gebruikers gevoelige informatie over het databaseschema of de aard van de opgeslagen gegevens kunnen afleiden.
Eigendomsinformatie beveiligen: door velden een andere naam te geven, kunt u ook bedrijfseigen namen of bedrijfslogica beveiligen die kan worden gehint door de oorspronkelijke veldnamen van de database.
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
entities.{entity} |
relationships |
object | ❌ Nee | Geen |
Deze sectietoewijzingen bevatten een set relatiedefinities die toewijzen hoe entiteiten zijn gerelateerd aan andere weergegeven entiteiten. Deze relatiedefinities kunnen eventueel ook details bevatten over de onderliggende databaseobjecten die worden gebruikt om de relaties te ondersteunen en af te dwingen. Objecten die in deze sectie zijn gedefinieerd, worden weergegeven als GraphQL-velden in de gerelateerde entiteit. Zie voor meer informatie uitsplitsing van relaties van data-API-opbouwfuncties.
Notitie
Relaties zijn alleen relevant voor GraphQL-query's. REST-eindpunten hebben toegang tot slechts één entiteit tegelijk en kunnen geen geneste typen retourneren.
In de sectie relationships
wordt beschreven hoe entiteiten communiceren binnen de opbouwfunctie voor gegevens-API's, met gedetailleerde informatie over koppelingen en mogelijke databaseondersteuning voor deze relaties. De eigenschap relationship-name
voor elke relatie is vereist en moet uniek zijn voor alle relaties voor een bepaalde entiteit. Aangepaste namen zorgen voor duidelijke, identificeerbare verbindingen en onderhouden de integriteit van het GraphQL-schema dat is gegenereerd op basis van deze configuraties.
Verwantschap | Kardinaliteit | Voorbeeld |
---|---|---|
een-op-veel | many |
Eén categorieentiteit kan betrekking hebben op veel takentiteiten |
veel-op-een | one |
Veel takentiteiten kunnen betrekking hebben op één categorieentiteit |
veel-op-veel | many |
Een todo-entiteit kan betrekking hebben op veel gebruikersentiteiten en één gebruikersentiteit kan betrekking hebben op veel todo-entiteiten |
{
"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>"]
}
}
}
}
}
Eigenschap | Vereist | Type | Verstek |
---|---|---|---|
cardinality |
✔️ Ja | opsommingstekenreeks | Geen |
target.entity |
✔️ Ja | snaar | Geen |
source.fields |
❌ Nee | tekenreeksmatrix | Geen |
target.fields |
❌ Nee | tekenreeksmatrix | Geen |
linking.<object-or-entity> |
❌ Nee | snaar | Geen |
linking.source.fields |
❌ Nee | tekenreeksmatrix | Geen |
linking.target.fields |
❌ Nee | tekenreeksmatrix | Geen |
Wanneer u relaties overweegt, kunt u het beste de verschillen vergelijken tussen een-op-veel-, veel-op-een-en veel-op-veel-relaties.
Laten we eerst een voorbeeld van een relatie met de weergegeven Category
entiteit een een-op-veel--relatie met de Book
entiteit hebben. Hier is de kardinaliteit ingesteld op many
. Elke Category
kan meerdere gerelateerde Book
entiteiten hebben, terwijl elke Book
entiteit slechts aan één Category
entiteit is gekoppeld.
{
"entities": {
"Book": {
...
},
"Category": {
"relationships": {
"category_books": {
"cardinality": "many",
"target.entity": "Book",
"source.fields": [ "id" ],
"target.fields": [ "category_id" ]
}
}
}
}
}
In dit voorbeeld geeft de source.fields
lijst het id
veld van de bronentiteit (Category
). Dit veld wordt gebruikt om verbinding te maken met het gerelateerde item in de entiteit target
. Omgekeerd geeft de target.fields
lijst het category_id
veld van de doelentiteit (Book
). Dit veld wordt gebruikt om verbinding te maken met het gerelateerde item in de entiteit source
.
Als deze relatie is gedefinieerd, moet het resulterende weergegeven GraphQL-schema er ongeveer uitzien als in dit voorbeeld.
type Category
{
id: Int!
...
books: [BookConnection]!
}
Overweeg vervolgens veel-op-een- die de kardinaliteit instelt op one
. De weergegeven Book
-entiteit kan één gerelateerde Category
entiteit hebben. De Category
-entiteit kan meerdere gerelateerde Book
entiteiten hebben.
{
"entities": {
"Book": {
"relationships": {
"books_category": {
"cardinality": "one",
"target.entity": "Category",
"source.fields": [ "category_id" ],
"target.fields": [ "id" ]
}
},
"Category": {
...
}
}
}
}
Hier geeft de source.fields
lijst aan dat het category_id
veld van de bronentiteit (Book
) verwijst naar het id
veld van de gerelateerde doelentiteit (Category
). Inverse geeft de target.fields
lijst de inverse relatie aan. Met deze relatie bevat het resulterende GraphQL-schema nu een toewijzing van Boeken naar Categorieën.
type Book
{
id: Int!
...
category: Category
}
Ten slotte wordt een veel-op-veel- relatie gedefinieerd met een kardinaliteit van many
en meer metagegevens om te definiëren welke databaseobjecten worden gebruikt om de relatie in de back-updatabase te maken. Hier kan de Book
-entiteit meerdere Author
entiteiten hebben en omgekeerd kan de Author
-entiteit meerdere Book
entiteiten hebben.
{
"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": {
...
}
}
}
}
In dit voorbeeld geven de source.fields
en target.fields
beide aan dat de relatietabel de primaire id (id
) van de bron- (Book
) en de doelentiteiten (Author
) gebruikt. Het linking.object
veld geeft aan dat de relatie is gedefinieerd in het dbo.books_authors
databaseobject. Verder geeft linking.source.fields
aan dat het book_id
veld van het koppelingsobject verwijst naar het id
veld van de Book
entiteit en linking.target.fields
geeft aan dat het author_id
veld van het koppelingsobject verwijst naar het id
veld van de Author
-entiteit.
Dit voorbeeld kan worden beschreven met behulp van een GraphQL-schema dat vergelijkbaar is met dit voorbeeld.
type Book
{
id: Int!
...
authors: [AuthorConnection]!
}
type Author
{
id: Int!
...
books: [BookConnection]!
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
entities.{entity}.relationships |
cardinality |
snaar | ✔️ Ja | Geen |
Hiermee geeft u op of de huidige bronentiteit is gerelateerd aan slechts één exemplaar van de doelentiteit of meerdere exemplaren.
Hier volgt een lijst met toegestane waarden voor deze eigenschap:
Beschrijving | |
---|---|
one |
De bron heeft slechts één record van het doel |
many |
De bron kan betrekking hebben op nul-op-veel-records van het doel |
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
entities.{entity}.relationships |
target.entity |
snaar | ✔️ Ja | Geen |
De naam van de entiteit die ergens anders is gedefinieerd in de configuratie die het doel van de relatie is.
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
entities.{entity}.relationships |
source.fields |
array | ❌ Nee | Geen |
Een optionele parameter voor het definiëren van het veld dat wordt gebruikt voor toewijzing in de bron- entiteit die wordt gebruikt om verbinding te maken met het gerelateerde item in de doelentiteit.
Fooi
Dit veld is niet vereist als er een refererende sleutel is beperking van de database tussen de twee databaseobjecten die kunnen worden gebruikt om de relatie automatisch af te stellen.
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
entities.{entity}.relationships |
target.fields |
array | ❌ Nee | Geen |
Een optionele parameter voor het definiëren van het veld dat wordt gebruikt voor toewijzing in de doel- entiteit die wordt gebruikt om verbinding te maken met het gerelateerde item in de bronentiteit.
Fooi
Dit veld is niet vereist als er een refererende sleutel is beperking van de database tussen de twee databaseobjecten die kunnen worden gebruikt om de relatie automatisch af te stellen.
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
entities.{entity}.relationships |
linking.object |
snaar | ❌ Nee | Geen |
Voor veel-op-veel-relaties is de naam van het databaseobject of de entiteit die de gegevens bevat die nodig zijn om een relatie tussen twee andere entiteiten te definiëren.
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
entities.{entity}.relationships |
linking.source.fields |
array | ❌ Nee | Geen |
De naam van het databaseobject of het entiteitsveld dat is gerelateerd aan de bronentiteit.
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
entities.{entity}.relationships |
linking.target.fields |
array | ❌ Nee | Geen |
De naam van het databaseobject of het entiteitsveld dat is gerelateerd aan de doelentiteit.
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
entities.{entity}.cache |
enabled |
booleaans | ❌ Nee | Vals |
Hiermee schakelt en configureert u caching voor de entiteit.
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>
}
}
}
}
Eigenschap | Vereist | Type | Verstek |
---|---|---|---|
enabled |
❌ Nee | booleaans | Vals |
ttl-seconds |
❌ Nee | geheel getal | 5 |
In dit voorbeeld is cache ingeschakeld en verlopen de items na 30 seconden.
{
"entities": {
"Author": {
"cache": {
"enabled": true,
"ttl-seconds": 30
}
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
entities.{entity}.cache |
enabled |
booleaans | ❌ Nee | Vals |
Hiermee schakelt u caching in voor de entiteit.
Objecttype | Cacheondersteuning |
---|---|
Tafel | ✅ Ja |
Bekijken | ✅ Ja |
Opgeslagen procedure | ✖️ Nee |
Container | ✖️ Nee |
Aanvraagheader | Cacheondersteuning |
---|---|
no-cache |
✖️ Nee |
no-store |
✖️ Nee |
max-age |
✖️ Nee |
public |
✖️ Nee |
private |
✖️ Nee |
etag |
✖️ Nee |
{
"entities": {
"<entity-name>": {
"cache": {
"enabled": <boolean> (default: false)
}
}
}
}
In dit voorbeeld is cache uitgeschakeld.
{
"entities": {
"Author": {
"cache": {
"enabled": false
}
}
}
}
Ouder | Eigenschap | Type | Vereist | Verstek |
---|---|---|---|---|
entities.cache |
ttl-seconds |
geheel getal | ❌ Nee | 5 |
Hiermee configureert u de TTL-waarde (Time-to-Live) in seconden voor items in de cache. Na deze tijd worden items automatisch uit de cache verwijderd. De standaardwaarde is 5
seconden.
{
"entities": {
"<entity-name>": {
"cache": {
"ttl-seconds": <integer; inherited>
}
}
}
}
In dit voorbeeld is cache ingeschakeld en verlopen de items na 15 seconden. Als u deze instelling weglaat, neemt deze instelling de globale instelling of standaardinstelling over.
{
"entities": {
"Author": {
"cache": {
"enabled": true,
"ttl-seconds": 15
}
}
}
}