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

Overzicht van syntaxis

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": [ ... ]
}

Eigenschappen op het hoogste niveau

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.

Voorbeeldconfiguraties

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.

Omgevingen

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, Stagingen 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.

Configuratie-eigenschappen

Deze sectie bevat alle mogelijke configuratie-eigenschappen die beschikbaar zijn voor een configuratiebestand.

Schema


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.

Formatteren

{
  "$schema": <string>
}

Voorbeelden

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.

Gegevensbron


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-stringworden opgegeven.

Formatteren

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

Eigenschappen

Vereist Type
database-type ✔️ Ja opsommingstekenreeks
connection-string ✔️ Ja snaar
options ❌ Nee object

Databasetype


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.

Formatteren

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

Waarden typen

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

Verbindingsreeks


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.

Formatteren

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

Verbindingstolerantie

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

Azure SQL en SQL Server

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.

Voorbeelden

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, myloginen 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;"
  • 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;"
  • 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;"
  • 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;"
  • 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;"

Notitie

De 'opties' die zijn opgegeven, zoals database, containeren 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, containerof schema zoals in de NoSQL-installatie.

Opties


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.

Formatteren

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

opties: { set-session-context: booleaanse }

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.

Voorbeeld van opgeslagen SQL-procedure:
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;
JSON-configuratievoorbeeld:
{
  "$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"]
        }
      ]
    }
  }
}

Uitleg:

  1. opgeslagen procedure (GetUser):

    • De procedure controleert de SESSION_CONTEXT om te controleren of de aanroeper de rol admin heeft of overeenkomt met de opgegeven userId.
    • Onbevoegde toegang resulteert in een fout.
  2. JSON-configuratie:

    • set-session-context is ingeschakeld om metagegevens van gebruikers van het toegangstoken door te geven aan de database.
    • De eigenschap parameters wijst de userId parameter toe die is vereist voor de opgeslagen procedure.
    • Het permissions blok zorgt ervoor dat alleen geverifieerde gebruikers de opgeslagen procedure kunnen uitvoeren.

Gegevensbronbestanden


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.

diagram van meerdere configuratiebestanden waarnaar wordt verwezen als een matrix binnen één configuratiebestand.

Formatteren

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

Overwegingen voor configuratiebestanden

  • 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.

Voorbeelden

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

Runtime


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.

Formatteren

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

Eigenschappen

Vereist Type
rest ❌ Nee object
graphql ❌ Nee object
host ❌ Nee object
cache ❌ Nee object

Voorbeelden

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

GraphQL (runtime)


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.

Formatteren

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

Eigenschappen

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

Ingeschakeld (GraphQL-runtime)


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.

Formatteren

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

Voorbeelden

In dit voorbeeld is het GraphQL-eindpunt uitgeschakeld voor alle entiteiten.

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

Dieptelimiet (GraphQL-runtime)


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.

Voorbeelden

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

Pad (GraphQL-runtime)


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.

Formatteren

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

Voorbeelden

In dit voorbeeld is de root GraphQL-URI /query.

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

Inleiding toestaan (GraphQL-runtime)


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.

Formatteren

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

Voorbeelden

In dit voorbeeld is de introspectie uitgeschakeld.

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

Meerdere mutaties (GraphQL runtime)


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.

Formatteren

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

Eigenschappen

Vereist Type
create ❌ Nee object

Meerdere mutaties - create (GraphQL runtime)


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.

Formatteren

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

Eigenschappen

Eigenschap Vereist Type Verstek
enabled ✔️ Ja booleaans Waar

Voorbeelden

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.

Configuratievoorbeeld

Deze configuratie maakt meerdere create mutaties mogelijk:

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

Voorbeeld van GraphQL-mutatie

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

REST (runtime)


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.

Formatteren

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

Eigenschappen

Eigenschap Vereist Type Verstek
enabled ❌ Nee booleaans Waar
path ❌ Nee snaar /Api
request-body-strict ❌ Nee booleaans Waar

Ingeschakeld (REST-runtime)


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.

Formatteren

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

Voorbeelden

In dit voorbeeld is het REST API-eindpunt uitgeschakeld voor alle entiteiten.

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

Pad (REST-runtime)


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.

Formatteren

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

Belangrijk

Door de gebruiker opgegeven subpaden zijn niet toegestaan voor deze eigenschap.

Voorbeelden

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.

Aanvraagbody strikt (REST Runtime)


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 een BadRequest 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.

Gedrag met specifieke kolomconfiguraties

  • Kolommen met een standaardwaarde() worden tijdens INSERT alleen genegeerd wanneer de waarde in de nettolading null. Kolommen met een standaard() worden niet genegeerd tijdens UPDATE ongeacht de nettoladingwaarde.
  • Berekende kolommen worden altijd genegeerd.
  • Automatisch gegenereerde kolommen worden altijd genegeerd.

Formatteren

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

Voorbeelden

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)
);
Voorbeeldconfiguratie
{
  "runtime": {
    "rest": {
      "request-body-strict": false
    }
  }
}
INSERT-gedrag met 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
}
UPDATEgedrag met request-body-strict: false

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

Host (runtime)


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.

Formatteren

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

Eigenschappen

Eigenschap Vereist Type Verstek
mode ❌ Nee opsommingstekenreeks productie
cors ❌ Nee object Geen
authentication ❌ Nee object Geen

Voorbeelden

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

Modus (hostruntime)


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.

Formatteren

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

Waarden

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

Gedrag

  • Alleen in development modus is Swagger beschikbaar.
  • Alleen in development modus is Banana Cake Pop beschikbaar.

Maximale antwoordgrootte (runtime)


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.

Toegestane waarden

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.

Formatteren

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

CORS (hostruntime)


Ouder Eigenschap Type Vereist Verstek
runtime.host cors object ❌ Nee Geen

CORS-instellingen (Cross-Origin Resource Sharing) voor de Data API Builder-enginehost.

Formatteren

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

Eigenschappen

Vereist Type
allow-credentials ❌ Nee booleaans
origins ❌ Nee tekenreeksmatrix

Referenties toestaan (hostruntime)


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.

Notitie

Zie Access-Control-Allow-Credentialsvoor meer informatie over de CORS-header.

Formatteren

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

Origins (hostruntime)


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.

Formatteren

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

Voorbeelden

Hier volgt een voorbeeld van een host waarmee CORS zonder referenties van alle oorsprongen is toegestaan.

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

Verificatie (hostruntime)


Ouder Eigenschap Type Vereist Verstek
runtime.host authentication object ❌ Nee Geen

Hiermee configureert u verificatie voor de Data API Builder-host.

Formatteren

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

Eigenschappen

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.

Provider (hostruntime)


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.

Formatteren

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

Waarden

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

JSON-webtokens (hostruntime)


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.

Formatteren

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

Eigenschappen

Eigenschap Vereist Type Verstek
audience ❌ Nee snaar Geen
issuer ❌ Nee snaar Geen

Voorbeelden

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.

Diagram van JSON-webtokens ondersteunen in Data API Builder.

Hier volgen enkele voorbeelden van de eigenschap host gegeven verschillende architectuurkeuzen die u in uw oplossing kunt maken.

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

Met StaticWebAppsverwacht Data API Builder dat Azure Static Web Apps de aanvraag verifieert en dat de X-MS-CLIENT-PRINCIPAL HTTP-header aanwezig is.

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

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.

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

Doelgroep (hostruntime)


Ouder Eigenschap Type Vereist Verstek
runtime.host.authentication.jwt audience snaar ❌ Nee Geen

Doelgroep voor het JWT-token.

Formatteren

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

Verlener (hostruntime)


Ouder Eigenschap Type Vereist Verstek
runtime.host.authentication.jwt issuer snaar ❌ Nee Geen

Verlener voor het JWT-token.

Formatteren

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

Paginering (runtime)


Ouder Eigenschap Type Vereist Verstek
runtime pagination object ❌ Nee Geen

Hiermee configureert u pagineringslimieten voor REST- en GraphQL-eindpunten.

Formatteren

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

Eigenschappen

Eigenschap Vereist Type Verstek
max-page-size ❌ Nee geheel getal 100,000
default-page-size ❌ Nee geheel getal 100

Voorbeeldconfiguratie

{
  "runtime": {
    "pagination": {
      "max-page-size": 1000,
      "default-page-size": 2
    }
  },
  "entities": {
    "Users": {
      "source": "dbo.Users",
      "permissions": [
        {
          "actions": ["read"],
          "role": "anonymous"
        }
      ]
    }
  }
}

Voorbeeld van REST-paginering

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.

Verzoek:
GET https://localhost:5001/api/users
Antwoord:
{
  "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 nextLinkkan de client de volgende set resultaten ophalen.

Voorbeeld van GraphQL-paginering

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.

Vraag:
query {
  users {
    items {
      Id
      Name
      Age
      IsAdmin
      IsMinor
    }
    hasNextPage
    endCursor
  }
}
Antwoord:
{
  "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 met cursor:
query {
  users(after: "W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI==") {
    items {
      Id
      Name
      Age
      IsAdmin
      IsMinor
    }
    hasNextPage
    endCursor
  }
}

Paginaformaat aanpassen

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.
Voorbeeld van REST-query:
GET https://localhost:5001/api/users?$limit=5
Voorbeeld van GraphQL-query:
query {
  users(first: 5) {
    items {
      Id
      Name
      Age
      IsAdmin
      IsMinor
    }
  }
}

Maximale paginagrootte (pagineringsruntime)

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-sizeaanvraagt, worden de resultaten beperkt tot max-page-size.

Toegestane waarden

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.

Formatteren

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

Standaardpaginaformaat (pagineringsruntime)

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.

Toegestane waarden

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.

Cache (runtime)


Ouder Eigenschap Type Vereist Verstek
runtime cache object ❌ Nee Geen

Hiermee schakelt en configureert u caching voor de hele runtime.

Formatteren

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

Eigenschappen

Eigenschap Vereist Type Verstek
enabled ❌ Nee booleaans Geen
ttl-seconds ❌ Nee geheel getal 5

Voorbeelden

In dit voorbeeld is cache ingeschakeld en verlopen de items na 30 seconden.

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

Ingeschakeld (Cacheruntime)


Ouder Eigenschap Type Vereist Verstek
runtime.cache enabled booleaans ❌ Nee Vals

Hiermee schakelt u caching globaal in voor alle entiteiten. Standaard ingesteld op false.

Formatteren

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

Voorbeelden

In dit voorbeeld is cache uitgeschakeld.

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

TTL in seconden (Cacheruntime)


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.

Formatteren

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

Voorbeelden

In dit voorbeeld is cache globaal ingeschakeld en verlopen alle items na 15 seconden.

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

Telemetrie (runtime)


Ouder Eigenschap Type Vereist Verstek
runtime telemetry object ❌ Nee Geen

Met deze eigenschap configureert u Application Insights om API-logboeken te centraliseren. Meer informatie.

Formatteren

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

Application Insights (telemetrieruntime)


Ouder Eigenschap Type Vereist Verstek
runtime.telemetry application-insights object ✔️ Ja Geen

Ingeschakeld (Application Insights-telemetrie)


Ouder Eigenschap Type Vereist Verstek
runtime.telemetry.application-insights enabled booleaans ❌ Nee Waar

Verbindingsreeks (Application Insights-telemetrie)


Ouder Eigenschap Type Vereist Verstek
runtime.telemetry.application-insights connection-string snaar ✔️ Ja Geen

Entiteiten


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.

Formatteren

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

Eigenschappen

Vereist Type
source ✔️ Ja object
permissions ✔️ Ja array
rest ❌ Nee object
graphql ❌ Nee object
mappings ❌ Nee object
relationships ❌ Nee object
cache ❌ Nee object

Voorbeelden

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'"
          }
        }
      ]
    }
  }
}

Bron


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".

Formatteren

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

Eigenschappen

Vereist Type
object ✔️ Ja snaar
type ✔️ Ja opsommingstekenreeks
parameters ❌ Nee object
key-fields ❌ Nee tekenreeksmatrix

Voorbeelden

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.

Object


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.

Voorbeelden

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

Type (entiteiten)


Ouder Eigenschap Type Vereist Verstek
entities.{entity}.source type snaar ✔️ Ja Geen

De eigenschap type identificeert het type databaseobject achter de entiteit, waaronder view, tableen stored-procedure. Deze eigenschap is vereist en heeft geen standaardwaarde.

Formatteren

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

Waarden

Waarde Beschrijving
table Vertegenwoordigt een tabel.
stored-procedure Vertegenwoordigt een opgeslagen procedure.
view Vertegenwoordigt een weergave.

Voorbeelden

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

Sleutelvelden


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-fieldsop 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 viewis.

Formatteren

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

Voorbeeld: Weergeven met sleutelvelden

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

Parameters


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.

Formatteren

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

SQL-

CREATE PROCEDURE dbo.GetUsers AS
SELECT Id, Name, Age, IsAdmin FROM dbo.Users;

configuratie

{
  "entities": {
    "Users": {
      "source": {
        "object": "dbo.GetUsers",
        "type": "stored-procedure"
      }
    }
  }
}
Voorbeeld 2: Opgeslagen procedure met parameters

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

Machtigingen


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, updateen delete. De sectie permissions geeft aan welke rollen toegang hebben tot de gerelateerde entiteit en welke acties kunnen worden gebruikt.

Formatteren

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

Voorbeelden

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, nameen 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": []
}

Eigenschappen

Vereist Type
role ✔️ Ja snaar
actions (tekenreeksmatrix)
of actions (objectmatrix)
✔️ Ja object- of tekenreeksmatrix

Rol


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

Formatteren

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

Voorbeelden

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.

GET https://localhost:5001/api/User
Authorization: Bearer <your_access_token>
X-MS-API-ROLE: custom-role

Acties (tekenreeksmatrix)


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, updateof 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, updateen delete.

Voorbeelden

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

Acties (objectmatrix)


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, updateof deletegebruiken. 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, updateen delete.

Formatteren

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

Eigenschappen

Eigenschap Vereist Type Verstek
action ✔️ Ja snaar Geen
fields ❌ Nee tekenreeksmatrix Geen
policy ❌ Nee object Geen

Voorbeeld

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

Actie


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.

Waarden

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

Formatteren

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "role": "<role>",
          "actions": [
            {
              "action": "<string>",
              "fields": {
                "include": [/* fields */],
                "exclude": [/* fields */]
              },
              "policy": {
                "database": "<predicate>"
              }
            }
          ]
        }
      ]
    }
  }
}

Voorbeeld

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

Velden


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.

Formatteren

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

Voorbeelden

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": []
            }
        }
    ]
}

Beleid


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.

Formatteren

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

Eigenschappen

Eigenschap Vereist Type Verstek
database ✔️ Ja snaar Geen

Beschrijving

Het database beleid: een OData-achtige expressie die wordt vertaald in een querypredicaat dat de database evalueert, inclusief operators zoals eq, lten 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)

Databasebeleid

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, userDetailsen 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.

Beperkingen

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 actionsmaken, lezen, bijwerken en verwijderen. Omdat er geen predicaat is in een opgeslagen procedure-aanroep, kunnen ze niet worden toegevoegd.

Ondersteunde OData-achtige operators
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.

Beperkingen voor entiteitsveldnamen
  • 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.
mappings gebruiken voor niet-conforme velden

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.

Voorbeelden

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 Nameen department COID toe te wijzen aan EmployeeId, EmployeeNameen 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.

Databank


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.

Formatteren

{
  "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, FALSEof 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, userDetailsen userRoles. Zie Azure Static Web Apps-clientprincipaalgegevensvoor meer informatie.

Voorbeelden

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

Beperkingen

  • 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 actionscreate, read, updateen delete.
  • De syntaxis van de OData-expressie voor databasebeleid ondersteunt deze scenario's alleen.
    • Binaire operatoren, waaronder, maar niet beperkt tot; and, or, eq, gten lt. Zie BinaryOperatorKind voor meer informatie.
    • Unaire operators zoals de operatoren - (negate) en not. Zie UnaryOperatorKind voor meer informatie.
  • 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.

GraphQL (entiteiten)


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.

Formatteren

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

Eigenschappen

Eigenschap Vereist Type Verstek
enabled ❌ Nee booleaans Geen
type ❌ Nee tekenreeks of object Geen
operation ❌ Nee opsommingstekenreeks Geen

Voorbeelden

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

Type (GraphQL-entiteit)


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.

Formatteren

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

Eigenschappen

Eigenschap Vereist Type Verstek
singular ❌ Nee snaar Geen
plural ❌ Nee snaar N.b. (standaard: enkelvoud)

Voorbeelden

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

Bewerking (GraphQL-entiteit)


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.

Formatteren

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

Waarden

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

Voorbeelden

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.

Ingeschakeld (GraphQL-entiteit)


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.

Formatteren

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

REST (entiteiten)


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.

Formatteren

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

Eigenschappen

Eigenschap Vereist Type Verstek
enabled ✔️ Ja booleaans Waar
path ❌ Nee snaar /<entity-name>
methods ❌ Nee tekenreeksmatrix TOEVOEGEN

Voorbeelden

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

Ingeschakeld (REST-entiteit)


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.

Formatteren

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

Pad (REST-entiteit)


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

Formatteren

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

Voorbeelden

In dit voorbeeld wordt de Author entiteit weergegeven met behulp van het /auth-eindpunt.

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

Methoden (REST-entiteit)


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 methodsPOST.

Formatteren

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

Waarden

Hier volgt een lijst met toegestane waarden voor deze eigenschap:

Beschrijving
get HTTP GET-aanvragen beschikbaar maken
post HTTP POST-aanvragen beschikbaar maken

Voorbeelden

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

Toewijzingen (entiteiten)


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.

Formatteren

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

Voorbeelden

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 als id 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.

Relaties (entiteiten)


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

Formatteren

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

Eigenschappen

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

Voorbeelden

Wanneer u relaties overweegt, kunt u het beste de verschillen vergelijken tussen een-op-veel-, veel-op-een-en veel-op-veel-relaties.

Een-op-veel

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]!
}
Veel-op-een

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
}
Veel-op-veel

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

Kardinaliteit


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.

Waarden

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

Doelentiteit


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.

Bronvelden


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.

Doelvelden


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.

Object of entiteit koppelen


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.

Bronvelden koppelen


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.

Doelvelden koppelen


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.

Cache (entiteiten)


Ouder Eigenschap Type Vereist Verstek
entities.{entity}.cache enabled booleaans ❌ Nee Vals

Hiermee schakelt en configureert u caching voor de entiteit.

Formatteren

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

Eigenschappen

Eigenschap Vereist Type Verstek
enabled ❌ Nee booleaans Vals
ttl-seconds ❌ Nee geheel getal 5

Voorbeelden

In dit voorbeeld is cache ingeschakeld en verlopen de items na 30 seconden.

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

Ingeschakeld (cacheentiteit)


Ouder Eigenschap Type Vereist Verstek
entities.{entity}.cache enabled booleaans ❌ Nee Vals

Hiermee schakelt u caching in voor de entiteit.

Ondersteuning voor databaseobjecten

Objecttype Cacheondersteuning
Tafel ✅ Ja
Bekijken ✅ Ja
Opgeslagen procedure ✖️ Nee
Container ✖️ Nee

Ondersteuning voor HTTP-headers

Aanvraagheader Cacheondersteuning
no-cache ✖️ Nee
no-store ✖️ Nee
max-age ✖️ Nee
public ✖️ Nee
private ✖️ Nee
etag ✖️ Nee

Formatteren

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

Voorbeelden

In dit voorbeeld is cache uitgeschakeld.

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

TTL in seconden (cache-entiteit)


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.

Formatteren

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

Voorbeelden

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