Referens för konfigurationsschema för Data API Builder

Artikel
09/12/2024

Data-API-byggarens motor kräver en konfigurationsfil. Konfigurationsfilen för Data API Builder ger en strukturerad och omfattande metod för att konfigurera ditt API med information om allt från miljövariabler till entitetsspecifika konfigurationer. Det här JSON-formaterade dokumentet börjar med en $schema egenskap. Den här konfigurationen verifierar dokumentet.

Egenskaperna database-type och connection-string säkerställa sömlös integrering med databassystem, från Azure SQL Database till Cosmos DB NoSQL API.

Konfigurationsfilen kan innehålla alternativ som:

Information om databastjänst och anslutning
Konfigurationsalternativ för global och körning
Uppsättning exponerade entiteter
Autentiseringsmetod
Säkerhetsregler som krävs för åtkomst till identiteter
Regler för namnmappning mellan API och databas
Relationer mellan entiteter som inte kan härledas
Unika funktioner för specifika databastjänster

Syntaxöversikt

Här är en snabb uppdelning av de primära "avsnitten" i en konfigurationsfil.

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

Egenskaper på den översta nivån

Här är beskrivningen av egenskaperna på den översta nivån i tabellformat:

Egenskap	Beskrivning
$schema	Anger JSON-schemat för validering, vilket säkerställer att konfigurationen följer det format som krävs.
	Innehåller information om databastyp och anslutningssträngen, som krävs för att upprätta databasanslutningen.
	En valfri matris som anger andra konfigurationsfiler som kan definiera andra datakällor.
körning	Konfigurerar körningsbeteenden och inställningar, inklusive underegenskaper för REST, GraphQL, värd, cacheoch telemetri.
entiteter	Definierar uppsättningen entiteter (databastabeller, vyer osv.) som exponeras via API:et, inklusive deras mappningar, behörigheteroch relationer.

Exempelkonfigurationer

Här är en exempelkonfigurationsfil som bara innehåller nödvändiga egenskaper för en enkel entitet. Det här exemplet är avsett att illustrera ett minimalt scenario.

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

Ett exempel på ett mer komplext scenario finns i exempelkonfiguration från slutpunkt till slutpunkt.

Miljöer

Data API Builder-konfigurationsfilen kan stödja scenarier där du behöver stöd för flera miljöer, ungefär som den appSettings.json filen i ASP.NET Core. Ramverket innehåller tre vanliga miljövärden; Development, Stagingoch Production; men du kan välja att använda valfritt miljövärde som du väljer. Miljön som data-API-byggare använder måste konfigureras med hjälp av DAB_ENVIRONMENT miljövariabeln.

Tänk dig ett exempel där du vill ha en baslinjekonfiguration och en utvecklingsspecifik konfiguration. Det här exemplet kräver två konfigurationsfiler:

	Miljö
dab-config.json	Bas
dab-config.Development.json	Utveckling

Om du vill använda den utvecklingsspecifika konfigurationen måste du ange DAB_ENVIRONMENT miljövariabeln till Development.

Miljöspecifika konfigurationsfiler åsidosätter egenskapsvärden i baskonfigurationsfilen. I det här exemplet används värdet från connection-string-filen om värdet anges i båda filerna.

Se den här matrisen för att bättre förstå vilket värde som används beroende på var värdet anges (eller inte anges) i någon av filerna.

	anges i baskonfigurationen	Anges inte i baskonfigurationen
anges i den aktuella miljökonfigurationen	Aktuell miljö	Aktuell miljö
Anges inte i den aktuella miljökonfigurationen	Bas	Ingen

Ett exempel på hur du använder flera konfigurationsfiler finns i använda Data API Builder med miljöer.

Konfigurationsegenskaper

Det här avsnittet innehåller alla möjliga konfigurationsegenskaper som är tillgängliga för en konfigurationsfil.

Schemat

Förälder	Egenskap	Typ	Krävs	Standard
`$root`	`$schema`	sträng	✔️ Ja	Ingen

Varje konfigurationsfil börjar med en $schema-egenskap som anger JSON-schema för validering.

Format

{
  "$schema": <string>
}

Exempel

Schemafiler är tillgängliga för versioner 0.3.7-alpha och framåt på specifika URL:er, vilket säkerställer att du använder rätt version eller det senaste tillgängliga schemat.

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

Ersätt VERSION-suffix med den version du vill ha.

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

Den senaste versionen av schemat är alltid tillgänglig på https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json.

Här är några exempel på giltiga schemavärden.

Version	URI	Beskrivning
0.3.7-alfa	`https://github.com/Azure/data-api-builder/releases/download/v0.3.7-alpha/dab.draft.schema.json`	Använder konfigurationsschemat från en alfaversion av verktyget.
0.10.23	`https://github.com/Azure/data-api-builder/releases/download/v0.10.23/dab.draft.schema.json`	Använder konfigurationsschemat för en stabil version av verktyget.
Senaste	`https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json`	Använder den senaste versionen av konfigurationsschemat.

Not

Versioner av Data API-byggare före 0.3.7-alfa kan ha en annan schema-URI.

Datakälla

Förälder	Egenskap	Typ	Krävs	Standard
`$root`	`data-source`	sträng	✔️ Ja	Ingen

Avsnittet data-source definierar databasen och åtkomsten till databasen via anslutningssträngen. Den definierar även databasalternativ. Egenskapen data-source konfigurerar de autentiseringsuppgifter som krävs för att ansluta till bakgrundsdatabasen. Avsnittet data-source beskriver serverdelsdatabasanslutningen och anger både database-type och connection-string.

Format

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

Egenskaper

	Krävs	Typ
`database-type`	✔️ Ja	uppräkningssträng
`connection-string`	✔️ Ja	sträng
`options`	❌ Nej	objekt

Databastyp

Förälder	Egenskap	Typ	Krävs	Standard
`data-source`	`database-type`	uppräkningssträng	✔️ Ja	Ingen

En uppräkningssträng som används för att ange vilken typ av databas som ska användas som datakälla.

Format

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

Ange värden

Egenskapen type anger typen av serverdelsdatabas.

Typ	Beskrivning	Lägsta version
`mssql`	Azure SQL Database	Ingen
`mssql`	Azure SQL MI	Ingen
`mssql`	SQL Server	SQL 2016
`sqldw`	Azure SQL Data Warehouse	Ingen
`postgresql`	PostgreSQL	v11
`mysql`	MySQL	v8
`cosmosdb_nosql`	Azure Cosmos DB för NoSQL	Ingen
`cosmosdb_postgresql`	Azure Cosmos DB för PostgreSQL	Ingen

Anslutningssträng

Förälder	Egenskap	Typ	Krävs	Standard
`data-source`	`connection-string`	sträng	✔️ Ja	Ingen

Ett sträng värde som innehåller en giltig anslutningssträng för att ansluta till måldatabastjänsten. Den ADO.NET anslutningssträngen för att ansluta till serverdelsdatabasen. Mer information finns i ADO.NET anslutningssträngar.

Format

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

Anslutningsåterhämtning

Data API Builder försöker automatiskt skicka databasbegäranden igen efter att ha upptäckt tillfälliga fel. Logiken för återförsök följer en exponentiell backoff- strategi där det maximala antalet återförsök fem. Varaktigheten för återförsöksåterställning efter att efterföljande begäranden har beräknats med hjälp av den här formeln (förutsatt att det aktuella återförsöksförsöket är r): $r^2$

Med den här formeln kan du beräkna tiden för varje återförsök i sekunder.

	Sekunder
första	`2`
Second	`4`
tredje	`8`
fjärde	`16`
femte	`32`

Azure SQL och SQL Server

Data API Builder använder SqlClient-biblioteket för att ansluta till Azure SQL eller SQL Server med hjälp av anslutningssträngen som du anger i konfigurationsfilen. En lista över alla alternativ för anslutningssträngar som stöds finns här: SqlConnection.ConnectionString Property.

Data-API-byggare kan också ansluta till måldatabasen med hjälp av hanterade tjänstidentiteter (MSI) när Data API Builder finns i Azure. Den DefaultAzureCredential som definierats i Azure.Identity-biblioteket används för att ansluta med kända identiteter när du inte anger ett användarnamn eller lösenord i anslutningssträngen. Mer information finns i DefaultAzureCredential exempel.

Användartilldelad hanterad identitet (UMI): Lägg till -autentisering och användar-ID egenskaper i anslutningssträngen när du ersätter i klient-ID:t för den användartilldelade hanterade identiteten: Authentication=Active Directory Managed Identity; User Id=<UMI_CLIENT_ID>;.
System Assigned Managed Identity (SMI): Lägg till egenskapen Authentication och exkludera argumenten UserId och Password från anslutningssträngen: Authentication=Active Directory Managed Identity;. Avsaknaden av egenskaperna UserId och Password-anslutningssträngen signalerar att DAB autentiserar med hjälp av en systemtilldelad hanterad identitet.

Mer information om hur du konfigurerar en hanterad tjänstidentitet med Azure SQL eller SQL Server finns i Hanterade identiteter i Microsoft Entra för Azure SQL.

Exempel

Det värde som används för anslutningssträngen beror till stor del på den databastjänst som används i ditt scenario. Du kan alltid välja att lagra anslutningssträngen i en miljövariabel och komma åt den med hjälp av funktionen @env().

	Värde	Beskrivning
Använd Azure SQL Database-strängvärde	`Server=<server-address>;Database=<name-of-database>;User ID=<username>;Password=<password>;`	Anslutningssträng till ett Azure SQL Database-konto. Mer information finns i Azure SQL Database-anslutningssträngar.
Använd Azure Database for PostgreSQL-strängvärde	`Server=<server-address>;Database=<name-of-database>;Port=5432;User Id=<username>;Password=<password>;Ssl Mode=Require;`	Anslutningssträng till ett Azure Database for PostgreSQL-konto. Mer information finns i Azure Database for PostgreSQL-anslutningssträngar.
Använd Azure Cosmos DB för NoSQL-strängvärde	`AccountEndpoint=<endpoint>;AccountKey=<key>;`	Anslutningssträng till ett Azure Cosmos DB för NoSQL-konto. Mer information finns i Azure Cosmos DB för NoSQL-anslutningssträngar.
Använda Azure Database for MySQL-strängvärde	`Server=<server-address>;Database=<name-of-database>;User ID=<username>;Password=<password>;Sslmode=Required;SslCa=<path-to-certificate>;`	Anslutningssträng till ett Azure Database for MySQL-konto. Mer information finns i Anslutningssträngar för Azure Database for MySQL.
Access-miljövariabel	`@env('database-connection-string')`	Få åtkomst till en miljövariabel från den lokala datorn. I det här exemplet refereras miljövariabeln `database-connection-string`.

Dricks

Som bästa praxis bör du undvika att lagra känslig information i konfigurationsfilen. Använd om möjligt @env() för att referera till miljövariabler. Mer information finns i @env() funktion.

De här exemplen visar bara hur varje databastyp kan konfigureras. Ditt scenario kan vara unikt, men det här exemplet är en bra startpunkt. Ersätt platshållarna, till exempel myserver, myDataBase, myloginoch myPassword med de faktiska värden som är specifika för din miljö.

mssql
```
"data-source": {
  "database-type": "mssql",
  "connection-string": "$env('my-connection-string')",
  "options": {
    "set-session-context": true
  }
}
```
- Typiskt anslutningssträngsformat: "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')"
}
```
- Typiskt anslutningssträngsformat: "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')"
}
```
- Typiskt anslutningssträngsformat: "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"
  }
}

Typiskt anslutningssträngsformat: "AccountEndpoint=https://mycosmosdb.documents.azure.com:443/;AccountKey=myAccountKey;"

cosmosdb_postgresql
```
"data-source": {
  "database-type": "cosmosdb_postgresql",
  "connection-string": "$env('my-connection-string')"
}
```
- Typiskt anslutningssträngsformat: "Host=mycosmosdb.postgres.database.azure.com;Database=myDataBase;Username=mylogin@mycosmosdb;Password=myPassword;Port=5432;SSL Mode=Require;"

Not

De "alternativ" som anges, till exempel database, containeroch schema är specifika för Azure Cosmos DB:s NoSQL-API i stället för PostgreSQL-API:et. För Azure Cosmos DB med PostgreSQL-API:et skulle "alternativen" inte innehålla database, containereller schema som i NoSQL-konfigurationen.

Alternativ

Förälder	Egenskap	Typ	Krävs	Standard
`data-source`	`options`	objekt	❌ Nej	Ingen

Ett valfritt avsnitt med extra nyckel/värde-parametrar för specifika databasanslutningar.

Format

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

Exempel

Om det options avsnittet krävs eller inte beror till stor del på vilken databastjänst som används.

	Värde	Beskrivning
Aktivera `SESSION_CONTEXT` i Azure SQL eller SQL Server	`"set-session-context": false`	För Azure SQL och SQL Server kan Data API Builder dra nytta av `SESSION_CONTEXT` för att skicka användardefinierade metadata till den underliggande databasen. Sådana metadata är tillgängliga för Data API Builder på grund av de anspråk som finns i åtkomsttoken. `SESSION_CONTEXT` data är tillgängliga för databasen under databasanslutningen tills anslutningen stängs. Mer information finns i sessionskontext.

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

Datakällans filer

Förälder	Egenskap	Typ	Krävs	Standard
`$root`	`data-source-files`	strängmatris	❌ Nej	Ingen

Data API Builder har stöd för flera konfigurationsfiler för olika datakällor, där en har angetts som den översta fil som hanterar runtime inställningar. Alla konfigurationer delar samma schema, vilket gör att runtime inställningar i alla filer utan fel. Underordnade konfigurationer sammanfogas automatiskt, men cirkelreferenser bör undvikas. Entiteter kan delas upp i separata filer för bättre hantering, men relationer mellan entiteter måste finnas i samma fil.

diagram över flera konfigurationsfiler som refereras till som en matris i en enda konfigurationsfil.

Format

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

Överväganden för konfigurationsfil

Varje konfigurationsfil måste innehålla egenskapen data-source.
Varje konfigurationsfil måste innehålla egenskapen entities.
Inställningen runtime används endast från konfigurationsfilen på den översta nivån, även om den ingår i andra filer.
Underordnade konfigurationsfiler kan också innehålla egna underordnade filer.
Konfigurationsfiler kan ordnas i undermappar efter behov.
Entitetsnamn måste vara unika för alla konfigurationsfiler.
Relationer mellan entiteter i olika konfigurationsfiler stöds inte.

Exempel

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

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

Undermappssyntax stöds också:

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

Runtime

Förälder	Egenskap	Typ	Krävs	Standard
`$root`	`runtime`	objekt	✔️ Ja	Ingen

I avsnittet runtime beskrivs alternativ som påverkar körningsbeteendet och inställningarna för alla exponerade entiteter.

Format

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

Egenskaper

	Krävs	Typ
`rest`	❌ Nej	objekt
`graphql`	❌ Nej	objekt
`host`	❌ Nej	objekt
`cache`	❌ Nej	objekt

Exempel

Här är ett exempel på ett körningsavsnitt med flera vanliga standardparametrar angivna.

{
  "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 (körning)

Förälder	Egenskap	Typ	Krävs	Standard
`runtime`	`graphql`	objekt	❌ Nej	Ingen

Det här objektet definierar om GraphQL är aktiverat och namnet som används för att exponera entiteten som en GraphQL-typ. Det här objektet är valfritt och används endast om standardnamnet eller inställningarna inte räcker till. I det här avsnittet beskrivs de globala inställningarna för GraphQL-slutpunkten.

Format

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

Egenskaper

Egenskap	Krävs	Typ	Standard
`enabled`	❌ Nej	boolesk	Sann
`path`	❌ Nej	sträng	/graphql (standard)
`allow-introspection`	❌ Nej	boolesk	Sann
`multiple-mutations`	❌ Nej	objekt	{ create: { enabled: false } }

Aktiverad (GraphQL-körning)

Förälder	Egenskap	Typ	Krävs	Standard
`runtime.graphql`	`enabled`	boolesk	❌ Nej	Ingen

Definierar om GraphQL-slutpunkterna ska aktiveras eller inaktiveras globalt. Om de inaktiveras globalt skulle inga entiteter vara tillgängliga via GraphQL-begäranden oavsett enskilda entitetsinställningar.

Format

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

Exempel

I det här exemplet är GraphQL-slutpunkten inaktiverad för alla entiteter.

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

Djupgräns (GraphQL-körning)

Förälder	Egenskap	Typ	Krävs	Standard
`runtime.graphql`	`depth-limit`	heltal	❌ Nej	Ingen

Det maximala tillåtna frågedjupet för en fråga.

GraphQL:s möjlighet att hantera kapslade frågor baserat på relationsdefinitioner är en otrolig funktion som gör det möjligt för användare att hämta komplexa, relaterade data i en enda fråga. Men när användarna fortsätter att lägga till kapslade frågor ökar frågans komplexitet, vilket så småningom kan äventyra prestanda och tillförlitlighet för både databasen och API-slutpunkten. För att hantera den här situationen anger egenskapen runtime/graphql/depth-limit det maximala tillåtna djupet för en GraphQL-fråga (och mutation). Den här egenskapen gör det möjligt för utvecklare att hitta en balans, vilket gör det möjligt för användare att dra nytta av fördelarna med kapslade frågor samtidigt som de begränsar för att förhindra scenarier som kan äventyra systemets prestanda och kvalitet.

Exempel

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

Sökväg (GraphQL-körning)

Förälder	Egenskap	Typ	Krävs	Standard
`runtime.graphql`	`path`	sträng	❌ Nej	"/graphql"

Definierar URL-sökvägen där GraphQL-slutpunkten görs tillgänglig. Om den här parametern till exempel är inställd på /graphqlexponeras GraphQL-slutpunkten som /graphql. Som standard är sökvägen /graphql.

Viktig

Undersökvägar tillåts inte för den här egenskapen. Ett anpassat sökvägsvärde för GraphQL-slutpunkten är för närvarande inte tillgängligt.

Format

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

Exempel

I det här exemplet är rot-GraphQL-URI:n /query.

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

Tillåt introspektion (GraphQL-körning)

Förälder	Egenskap	Typ	Krävs	Standard
`runtime.graphql`	`allow-introspection`	boolesk	❌ Nej	Sann

Den här booleska flaggan styr möjligheten att utföra schema-introspektionsfrågor på GraphQL-slutpunkten. Genom att aktivera introspektion kan klienter fråga schemat efter information om vilka typer av data som är tillgängliga, vilka typer av frågor de kan utföra och vilka mutationer som är tillgängliga.

Den här funktionen är användbar under utvecklingen för att förstå strukturen för GraphQL-API:et och för verktyg som automatiskt genererar frågor. För produktionsmiljöer kan det dock inaktiveras för att dölja API:ets schemainformation och förbättra säkerheten. Som standard aktiveras introspektion, vilket möjliggör omedelbar och omfattande utforskning av GraphQL-schemat.

Format

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

Exempel

I det här exemplet är introspektionen inaktiverad.

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

Flera mutationer (GraphQL-körning)

Förälder	Egenskap	Typ	Krävs	Standard
`runtime.graphql`	`multiple-mutations`	objekt	❌ Nej	Ingen

Konfigurerar alla flera mutationsåtgärder för GraphQL-körningen.

Not

Som standard är flera mutationer inte aktiverade och måste uttryckligen konfigureras för att aktiveras.

Format

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

Egenskaper

	Krävs	Typ
`create`	❌ Nej	objekt

Flera mutationer – skapa (GraphQL-körning)

Förälder	Egenskap	Typ	Krävs	Standard
`runtime.graphql.multiple-mutations`	`create`	boolesk	❌ Nej	Falsk

Konfigurerar flera skapandeåtgärder för GraphQL-körningen.

Format

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

Egenskaper

Egenskap	Krävs	Typ	Standard
`enabled`	✔️ Ja	boolesk	Sann

Exempel

I det här exemplet aktiveras flera mutationer för GraphQL-körningen. Mer specifikt aktiveras åtgärden för flera skapande genom att ange värdet true för egenskapen runtime.graphql.multiple-mutations.create.enabled.

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

REST (runtime)

Förälder	Egenskap	Typ	Krävs	Standard
`runtime`	`rest`	objekt	❌ Nej	Ingen

I det här avsnittet beskrivs de globala inställningarna för REST-slutpunkterna. De här inställningarna fungerar som standardvärden för alla entiteter men kan åsidosättas per entitet i respektive konfiguration.

Format

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

Egenskaper

Egenskap	Krävs	Typ	Standard
`enabled`	❌ Nej	boolesk	Sann
`path`	❌ Nej	sträng	/Application Programming Interface
`request-body-strict`	❌ Nej	boolesk	Sann

Aktiverad (REST-körning)

Förälder	Egenskap	Typ	Krävs	Standard
`runtime.rest`	`enabled`	boolesk	❌ Nej	Ingen

En boolesk flagga som avgör den globala tillgängligheten för REST-slutpunkter. Om inaktiverad kan entiteter inte nås via REST, oavsett enskilda entitetsinställningar.

Format

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

Exempel

I det här exemplet är REST API-slutpunkten inaktiverad för alla entiteter.

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

Sökväg (REST-körning)

Förälder	Egenskap	Typ	Krävs	Standard
`runtime.rest`	`path`	sträng	❌ Nej	"/api"

Anger URL-sökvägen för åtkomst till alla exponerade REST-slutpunkter. Om du till exempel anger path till /api blir REST-slutpunkten tillgänglig på /api/<entity>. Undersökvägar är inte tillåtna. Det här fältet är valfritt, med /api som standard.

Not

När du distribuerar Data API Builder med Static Web Apps (förhandsversion) matar Azure-tjänsten automatiskt in ytterligare undersökväg /data-api till URL:en. Det här beteendet säkerställer kompatibilitet med befintliga funktioner för statisk webbapp. Den resulterande slutpunkten skulle vara /data-api/api/<entity>. Detta är endast relevant för Static Web Apps.

Format

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

Viktig

Användarens angivna undersökvägar tillåts inte för den här egenskapen.

Exempel

I det här exemplet är rest-API-rot-URI:n /data.

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

Dricks

Om du definierar en Author entitet blir slutpunkten för den här entiteten /data/Author.

Strikt begärandetext (REST-körning)

Förälder	Egenskap	Typ	Krävs	Standard
`runtime.rest`	`request-body-strict`	boolesk	❌ Nej	Sann

Den här booleska flaggan avgör om begärandetexten för en REST-mutationsåtgärd kan innehålla överflödiga fält. Som standard är värdet sant, vilket innebär att extra fält i begärandetexten resulterar i ett BadRequest undantag. Om du ställer in den här flaggan på false kan användarna dock inkludera extra fält i begärandetexten, som ignoreras. Det är viktigt att observera att den här flaggan inte påverkar REST-frågebegäranden (GET), eftersom begärandetexten alltid ignoreras för GET-åtgärder.

Not

Den här flaggan påverkar inte HTTP GET-begäranden till REST API-slutpunkten. Begärandetexten ignoreras alltid för GET-åtgärder.

Format

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

Exempel

I det här exemplet inaktiveras verifiering av strikt begärandetext.

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

Värd (körning)

Förälder	Egenskap	Typ	Krävs	Standard
`runtime`	`host`	objekt	❌ Nej	Ingen

Avsnittet host i körningskonfigurationen innehåller inställningar som är avgörande för driftmiljön för data-API-byggaren. De här inställningarna omfattar driftlägen, CORS-konfiguration och autentiseringsinformation.

Format

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

Egenskaper

Egenskap	Krävs	Typ	Standard
`mode`	❌ Nej	uppräkningssträng	produktion
`cors`	❌ Nej	objekt	Ingen
`authentication`	❌ Nej	objekt	Ingen

Exempel

Här är ett exempel på en körning som konfigurerats för utvecklingsvärd.

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

Läge (värdkörning)

Förälder	Egenskap	Typ	Krävs	Standard
`runtime.host`	`mode`	sträng	❌ Nej	"produktion"

Definierar om data-API-buildermotorn ska köras i development eller production läge. Standardvärdet är production.

Vanligtvis exponeras de underliggande databasfelen i detalj genom att ange standardnivån för information för loggar till Debug när de körs under utveckling. I produktion är detaljnivån för loggar inställd på Error.

Dricks

Standardloggnivån kan åsidosättas ytterligare med hjälp av dab start --LogLevel <level-of-detail>. Mer information finns i cli-referens (kommandoradsgränssnitt).

Format

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

Värden

Här är en lista över tillåtna värden för den här egenskapen:

	Beskrivning
`production`	Använd när du är värd i produktion i Azure
`development`	Använda under utveckling på lokal dator

Maximal svarsstorlek (Runtime)

Förälder	Egenskap	Typ	Krävs	Standard
`runtime.host`	`max-response-size-mb`	heltal	❌ Nej	158

Anger den maximala storleken (i megabyte) för ett givet resultat. Med den här inställningen kan användarna konfigurera mängden data som värdplattformens minne kan hantera när data strömmas från de underliggande datakällorna.

När användare begär stora resultatuppsättningar kan det belasta databasen och data-API-byggaren. För att åtgärda detta gör max-response-size-mb att utvecklare kan begränsa den maximala svarsstorleken, mätt i megabyte, som dataströmmar från datakällan. Den här gränsen baseras på den totala datastorleken, inte antalet rader. Eftersom kolumner kan variera i storlek kan vissa kolumner (t.ex. text, binär, XML eller JSON) innehålla upp till 2 GB vardera, vilket gör enskilda rader potentiellt mycket stora. Den här inställningen hjälper utvecklare att skydda sina slutpunkter genom att begränsa svarsstorlekarna och förhindra systemöverbelastningar samtidigt som flexibiliteten för olika datatyper bibehålls.

Tillåtna värden

Värde	Resultat
`null`	Standardvärdet är 158 mb om det tas bort eller uttryckligen anges till `null`.
`integer`	Alla positiva 32-bitars heltal stöds.
`< 0`	Stöds inte. Valideringsfel inträffar om värdet är mindre än 1 MB.

Format

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

CORS (värdkörning)

Förälder	Egenskap	Typ	Krävs	Standard
`runtime.host`	`cors`	objekt	❌ Nej	Ingen

CORS-inställningar (Cross-Origin Resource Sharing) för Data API Builder-motorns värd.

Format

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

Egenskaper

	Krävs	Typ
`allow-credentials`	❌ Nej	boolesk
`origins`	❌ Nej	strängmatris

Tillåt autentiseringsuppgifter (värdkörning)

Förälder	Egenskap	Typ	Krävs	Standard
`runtime.host.cors`	`allow-credentials`	boolesk	❌ Nej	Falsk

Om det är sant anger du Access-Control-Allow-Credentials CORS-rubrik.

Not

Mer information om Access-Control-Allow-Credentials CORS-huvudet finns i MDN Web Docs CORS-referens.

Format

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

Ursprung (värdkörning)

Förälder	Egenskap	Typ	Krävs	Standard
`runtime.host.cors`	`origins`	strängmatris	❌ Nej	Ingen

Anger en matris med en lista över tillåtna ursprung för CORS. Den här inställningen tillåter * jokertecken för alla ursprung.

Format

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

Exempel

Här är ett exempel på en värd som tillåter CORS utan autentiseringsuppgifter från alla ursprung.

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

Autentisering (värdkörning)

Förälder	Egenskap	Typ	Krävs	Standard
`runtime.host`	`authentication`	objekt	❌ Nej	Ingen

Konfigurerar autentisering för Data API Builder-värden.

Format

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

Egenskaper

Egenskap	Krävs	Typ	Standard
`provider`	❌ Nej	uppräkningssträng	StaticWebApps
`jwt`	❌ Nej	objekt	Ingen

autentisering och kundansvar

Data-API-byggare är utformad för att fungera inom en bredare säkerhetspipeline och det finns viktiga steg att konfigurera innan begäranden bearbetas. Det är viktigt att förstå att Data API Builder inte autentiserar den direkta anroparen (till exempel ditt webbprogram) utan snarare slutanvändaren, baserat på en giltig JWT-token som tillhandahålls av en betrodd identitetsprovider (till exempel Entra-ID). När en begäran når data-API-byggare förutsätter den att JWT-token är giltig och kontrollerar den mot alla krav som du har konfigurerat, till exempel specifika anspråk. Auktoriseringsregler tillämpas sedan för att avgöra vad användaren kan komma åt eller ändra.

När auktoriseringen har godkänts kör Data API Builder begäran med det konto som anges i anslutningssträngen. Eftersom det här kontot ofta kräver utökade behörigheter för att hantera olika användarbegäranden är det viktigt att minimera dess åtkomsträttigheter för att minska risken. Vi rekommenderar att du skyddar din arkitektur genom att konfigurera en Private Link mellan klientwebbappen och API-slutpunkten och genom att härda datorn som är värd för Data API-byggare. Dessa åtgärder bidrar till att säkerställa att din miljö förblir säker, skyddar dina data och minimerar sårbarheter som kan utnyttjas för åtkomst, ändring eller utfiltrering av känslig information.

Provider (värdkörning)

Förälder	Egenskap	Typ	Krävs	Standard
`runtime.host.authentication`	`provider`	sträng	❌ Nej	"StaticWebApps"

Inställningen authentication.provider i konfigurationen host definierar den autentiseringsmetod som används av data-API-byggaren. Den avgör hur API:et verifierar identiteten för användare eller tjänster som försöker komma åt dess resurser. Den här inställningen möjliggör flexibilitet i distribution och integrering genom att stödja olika autentiseringsmekanismer som är skräddarsydda för olika miljöer och säkerhetskrav.

Familjeförsörjare	Beskrivning
`StaticWebApps`	Instruerar Data API-byggare att söka efter en uppsättning HTTP-huvuden som endast finns när de körs i en Static Web Apps-miljö.
`AppService`	När körningen körs i Azure AppService med AppService-autentisering aktiverad och konfigurerad (EasyAuth).
`AzureAd`	Microsoft Entra-identiteten måste konfigureras så att den kan autentisera en begäran som skickas till Data API-byggare ("Serverappen"). Mer information finns i Microsoft Entra ID-autentisering.
`Simulator`	En konfigurerbar autentiseringsprovider som instruerar Data API Builder-motorn att behandla alla begäranden som autentiserade. Mer information finns i lokal autentisering.

Format

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

Värden

Här är en lista över tillåtna värden för den här egenskapen:

	Beskrivning
`StaticWebApps`	Azure Static Web Apps
`AppService`	Azure App Service
`AzureAD`	Microsoft Entra-ID
`Simulator`	Simulator

JSON-webbtoken (värdkörning)

Förälder	Egenskap	Typ	Krävs	Standard
`runtime.host.authentication`	`jwt`	objekt	❌ Nej	Ingen

Om autentiseringsprovidern är inställd på AzureAD (Microsoft Entra-ID) måste det här avsnittet ange målgruppen och utfärdarna för JSOn-webbtoken (JWT). Dessa data används för att verifiera token mot din Microsoft Entra-klientorganisation.

Krävs om autentiseringsprovidern är AzureAD för Microsoft Entra-ID. Det här avsnittet måste ange audience och issuer för att verifiera den mottagna JWT-token mot den avsedda AzureAD klientorganisationen för autentisering.

Inställning	Beskrivning
publik	Identifierar den avsedda mottagaren av token. vanligtvis programmets identifierare registrerad i Microsoft Entra Identity (eller din identitetsprovider), vilket säkerställer att token verkligen har utfärdats för ditt program.
utfärdare	Anger den utfärdande utfärdarens URL, vilket är den tokentjänst som utfärdade JWT. Den här URL:en ska matcha identitetsproviderns utfärdar-URL som JWT hämtades från, vilket validerar tokens ursprung.

Format

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

Egenskaper

Egenskap	Krävs	Typ	Standard
`audience`	❌ Nej	sträng	Ingen
`issuer`	❌ Nej	sträng	Ingen

Exempel

Data API Builder (DAB) erbjuder stöd för flexibel autentisering, integrering med Microsoft Entra Identity och anpassade JSON Web Token-servrar (JWT). I den här avbildningen representerar JWT Server- den autentiseringstjänst som utfärdar JWT-token till klienter vid lyckad inloggning. Klienten skickar sedan token till DAB, som kan förhöra dess anspråk och egenskaper.

Diagram över stöd för JSON-webbtoken i Data API Builder.

Följande är exempel på egenskapen host med olika arkitekturval som du kan göra i din lösning.

Azure Static Web Apps

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

Med StaticWebAppsförväntar sig Data API Builder att Azure Static Web Apps autentiserar begäran och att X-MS-CLIENT-PRINCIPAL HTTP-huvud finns.

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

Autentisering delegeras till en identitetsprovider som stöds där åtkomsttoken kan utfärdas. En förvärvad åtkomsttoken måste ingå i inkommande begäranden till Data API Builder. Data API Builder verifierar sedan alla presenterade åtkomsttoken, vilket säkerställer att Data API Builder var den avsedda målgruppen för token.

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 (endast utveckling)

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

Målgrupp (värdkörning)

Förälder	Egenskap	Typ	Krävs	Standard
`runtime.host.authentication.jwt`	`audience`	sträng	❌ Nej	Ingen

Målgrupp för JWT-token.

Format

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

Utfärdare (värdkörning)

Förälder	Egenskap	Typ	Krävs	Standard
`runtime.host.authentication.jwt`	`issuer`	sträng	❌ Nej	Ingen

Utfärdare för JWT-token.

Format

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

Sidnumrering (Runtime)

Förälder	Egenskap	Typ	Krävs	Standard
`runtime`	`pagination`	objekt	❌ Nej	Ingen

Konfigurerar sidnumreringsgränser.

Format

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

Egenskaper

Egenskap	Krävs	Typ	Standard
`max-page-size`	❌ Nej	heltal	100,000
`default-page-size`	❌ Nej	heltal	100

Exempel

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

EXEMPEL på REST-sidnumrering

I det här exemplet skulle utfärdandet av REST GET-https://localhost:5001/api/books returnera en post i matrisen value eftersom default-page-size har angetts till 1. Om det finns fler resultat lägger Data API Builder till en nextLink i svaret. nextLink innehåller en $after parameter för att hämta nästa sida med data.

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

Med hjälp av nextLink ser du till att nästa uppsättning resultat returneras, även om data har ändrats mellan frågor.

GraphQL-sidnumreringsexempel

För GraphQL använder du fälten hasNextPage och endCursor för sidnumrering. Dessa krävs för att hämta nästa uppsättning resultat. Utan dem är frågan fortfarande begränsad till standardsidans storlek.

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

Svaret innehåller fälten hasNextPage och endCursor:

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

Om du vill hämta nästa sida tar du med markörens värde i nästa fråga:

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

Använda $limit eller first för att ändra sidstorleken:

REST och GraphQL stöder båda en $limit eller first parameter för att justera antalet resultat per fråga. Till exempel begränsar https://{server}/api/books?$limit=10 resultatet till 10 poster, vilket överskrider default-page-size. Om $limit överskrider max-page-sizebegränsas resultatet till max-page-size.

Första värdet	Resultat
`-1`	Standardinställningen för aktuell `max-page-size`.
`< max-page-size`	Begränsar resultatet till det angivna värdet.
`0`	Stöds inte.
`< -1`	Stöds inte.
`> max-page-size`	Stöds inte.

Maximal sidstorlek (sidnumreringskörning)

Förälder	Egenskap	Typ	Krävs	Standard
`runtime.pagination`	`max-page-size`	Int	❌ Nej	100,000

Anger det maximala antalet poster på den översta nivån som returneras av REST eller GraphQL. Om en användare begär mer än max-page-sizebegränsas resultatet till max-page-size.

Tillåtna värden

Värde	Resultat
`-1`	Standardvärdet är det högsta värde som stöds.
`integer`	Alla positiva 32-bitars heltal stöds.
`< -1`	Stöds inte.
`0`	Stöds inte.

Format

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

Standardstorlek för sidnumrering (sidnumreringskörning)

Förälder	Egenskap	Typ	Krävs	Standard
`runtime.pagination`	`default-page-size`	Int	❌ Nej	100

Anger standardantalet för poster på den översta nivån som returneras när sidnumrering är aktiverat, men ingen explicit sidstorlek anges.

Tillåtna värden

Värde	Resultat
`-1`	Standardinställningen för aktuell `max-page-size`.
`integer`	Alla positiva heltal som är mindre än det aktuella `max-page-size`.
`< -1`	Stöds inte.
`0`	Stöds inte.

Cache (körning)

Förälder	Egenskap	Typ	Krävs	Standard
`runtime`	`cache`	objekt	❌ Nej	Ingen

Aktiverar och konfigurerar cachelagring för hela körningen.

Format

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

Egenskaper

Egenskap	Krävs	Typ	Standard
`enabled`	❌ Nej	boolesk	Ingen
`ttl-seconds`	❌ Nej	heltal	5

Exempel

I det här exemplet är cachen aktiverad och objekten upphör att gälla efter 30 sekunder.

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

Aktiverad (cachekörning)

Förälder	Egenskap	Typ	Krävs	Standard
`runtime.cache`	`enabled`	boolesk	❌ Nej	Falsk

Aktiverar cachelagring globalt för alla entiteter. Standardvärdet är false.

Format

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

Exempel

I det här exemplet är cachen inaktiverad.

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

TTL i sekunder (cachekörning)

Förälder	Egenskap	Typ	Krävs	Standard
`runtime.cache`	`ttl-seconds`	heltal	❌ Nej	5

Konfigurerar TTL-värdet (time-to-live) i sekunder för cachelagrade objekt. Efter den här tiden rensas objekt automatiskt från cacheminnet. Standardvärdet är 5 sekunder.

Format

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

Exempel

I det här exemplet aktiveras cachen globalt och alla objekt upphör att gälla efter 15 sekunder.

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

Telemetri (körning)

Förälder	Egenskap	Typ	Krävs	Standard
`runtime`	`telemetry`	objekt	❌ Nej	Ingen

Den här egenskapen konfigurerar Application Insights för att centralisera API-loggar. Läs mer.

Format

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

Application Insights (telemetrikörning)

Förälder	Egenskap	Typ	Krävs	Standard
`runtime.telemetry`	`application-insights`	objekt	✔️ Ja	Ingen

Aktiverad (Application Insights-telemetri)

Förälder	Egenskap	Typ	Krävs	Standard
`runtime.telemetry.application-insights`	`enabled`	boolesk	❌ Nej	Sann

Anslutningssträng (Application Insights-telemetri)

Förälder	Egenskap	Typ	Krävs	Standard
`runtime.telemetry.application-insights`	`connection-string`	sträng	✔️ Ja	Ingen

Enheter

Förälder	Egenskap	Typ	Krävs	Standard
`$root`	`entities`	objekt	✔️ Ja	Ingen

Avsnittet entities fungerar som kärnan i konfigurationsfilen och etablerar en brygga mellan databasobjekt och motsvarande API-slutpunkter. Det här avsnittet mappar databasobjekt till exponerade slutpunkter. Det här avsnittet innehåller även egenskapsmappning och behörighetsdefinition. Varje exponerad entitet definieras i ett dedikerat objekt. Objektets egenskapsnamn används som namnet på den entitet som ska exponeras.

Det här avsnittet definierar hur varje entitet i databasen representeras i API:et, inklusive egenskapsmappningar och behörigheter. Varje entitet kapslas in i sitt eget underavsnitt, där entitetens namn fungerar som referensnyckel i hela konfigurationen.

Format

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

Egenskaper

	Krävs	Typ
`source`	✔️ Ja	objekt
`permissions`	✔️ Ja	samling
`rest`	❌ Nej	objekt
`graphql`	❌ Nej	objekt
`mappings`	❌ Nej	objekt
`relationships`	❌ Nej	objekt
`cache`	❌ Nej	objekt

Exempel

Det här JSON-objektet instruerar till exempel Data API Builder att exponera en GraphQL-entitet med namnet Author och en REST-slutpunkt som kan nås via sökvägen /Author. Den dbo.authors databastabellen stöder entiteten och konfigurationen gör att vem som helst kan komma åt slutpunkten anonymt.

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

I det här exemplet deklareras den User entiteten. Det här namnet User används var som helst i konfigurationsfilen där entiteter refereras. Annars är entitetsnamnet inte relevant för slutpunkterna.

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

Källa

Förälder	Egenskap	Typ	Krävs	Standard
`entities.{entity}`	`source`	objekt	✔️ Ja	Ingen

Konfigurationen {entity}.source ansluter den API-exponerade entiteten och dess underliggande databasobjekt. Den här egenskapen anger den databastabell, vy eller lagrade procedur som entiteten representerar och upprättar en direktlänk för datahämtning och manipulering.

För enkla scenarier, där entiteten mappar direkt till en enskild databastabell eller samling, behöver källegenskapen endast namnet på det databasobjektet. Den här enkelheten underlättar snabb installation för vanliga användningsfall.

Format

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

Egenskaper

	Krävs	Typ
`object`	✔️ Ja	sträng
`type`	✔️ Ja	uppräkningssträng
`parameters`	❌ Nej	objekt
`key-fields`	❌ Nej	strängmatris

Exempel

Det här exemplet visar den enklaste strukturen för att associera en entitet med en källtabell.

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

Här är en exmaple av en många-till-många-relation.

diagram över en många-till-många-relation mellan flera databastabeller

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

Den Todo entitet som backas upp av en lagrad procedur.
Egenskapen type i källan är inställd på stored-procedure, vilket anger vilken typ av källobjekt entiteten mappas till.
Egenskapen object i källan är namnet på den lagrade proceduren i databasen.

I det här exemplet läggs även egenskapen (valfritt) mapping till i konfigurationen för entiteten "Todo". Den anger hur fälten i entiteten (Id, Title, Descriptionoch Completed) mappas till motsvarande fält i den underliggande datakällan eller lagrade procedureparametrar (todo_id, todo_title, todo_descriptionrespektive todo_completed). Den här mappningen säkerställer att rätt data skickas mellan entiteten och den lagrade proceduren under åtgärderna för att skapa/uppdatera.

I föregående exempel används följande SQL-procedur.

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

@UserId: Obligatorisk parameter utan standardvärde.
@Completed: Valfri parameter. Om det tillhandahålls filtreras todosen efter deras slutförandestatus.
@CategoryName: Valfri parameter. Om det tillhandahålls filtreras todosen efter kategorinamn.

Här är ett exempel på uppdateringar med hjälp av en lagrad procedur.

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

I det här exemplet anges uttryckligen HTTP-metoden för interaktion med den här entiteten till POST med hjälp av metodegenskapen.

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

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

Objekt

Förälder	Egenskap	Typ	Krävs	Standard
`entities.{entity}.source`	`object`	sträng	✔️ Ja	Ingen

Namnet på databasobjektet som ska användas.

Exempel

I det här exemplet refererar object till det dbo.books objektet i databasen.

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

Typ (entiteter)

Förälder	Egenskap	Typ	Krävs	Standard
`entities.{entity}.source`	`type`	sträng	✔️ Ja	Ingen

Egenskapen type identifierar typen av databasobjekt bakom entiteten, bland annat view, tableoch stored-procedure. Egenskapen type krävs och det finns inget standardvärde.

Format

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

Värden

Här är en lista över tillåtna värden för den här egenskapen:

	Beskrivning
`table`	Representerar en tabell.
`stored-procedure`	Representerar en lagrad procedur.
`view`	Representerar en vy.

Exempel

I det här exemplet anger type att den här källan är en vy i databasen. Det här värdet påverkar om andra värden (till exempel key-fields) krävs.

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

Nyckelfält

Förälder	Egenskap	Typ	Krävs	Standard
`entities.{entity}.source`	`key-fields`	strängmatris	❌ Nej	Ingen

Inställningen {entity}.key-fields är nödvändig för entiteter som backas upp av vyer, så data-API-byggare vet hur den kan identifiera och returnera ett enskilt objekt om det behövs. Om type är inställt på view utan key-fieldsvägrar data-API-buildermotorn att starta.

Viktig

Den här egenskapen krävs om typen av objekt är en view. Den här egenskapen krävs också är typen av objekt är en table utan att någon primärnyckel har definierats.

Format

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

Exempel

I det här exemplet används vyn dbo.vw_category_details med category_id som anges som nyckelfält.

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

Parametrar

Förälder	Egenskap	Typ	Krävs	Standard
`entities.{entity}.source`	`parameters`	objekt	❌ Nej	Ingen

Inställningen {entity}.source.parameters är viktig för entiteter som backas upp av lagrade procedurer, vilket gör det möjligt för utvecklare att ange parametrar och deras standardvärden. Parametrar ser till att om vissa parametrar inte tillhandahålls i en HTTP-begäran kan systemet återgå till dessa fördefinierade värden.

Viktig

Den här egenskapen krävs om typen av objekt är en stored-procedure.

Format

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

Exempel

Det här exemplet anropar den dbo.stp_get_bestselling_books lagrade proceduren som skickar in följande två parametrar:

	Värde
`depth`	25
`list`	contoso-best-sellers

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

Behörigheter

Förälder	Egenskap	Typ	Krävs	Standard
`entities.{entity}`	`permissions`	objekt	✔️ Ja	Ingen

Det här avsnittet definierar vem som kan komma åt den relaterade entiteten och vilka åtgärder som tillåts. Behörigheter definieras i det här avsnittet när det gäller roller. Åtgärder definieras som vanliga CRUD-åtgärder, inklusive: create, read, updateoch delete. Avsnittet permissions definierar vem (när det gäller roller) som kan komma åt den relaterade entiteten och använda vilka åtgärder. Åtgärder är de vanliga CRUD-åtgärderna: create, read, update, delete.

Format

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

Handling	Beskrivning
`create`	Tillåter att du skapar en ny post i entiteten.
`read`	Tillåter läsning eller hämtning av poster från entiteten.
`update`	Tillåter uppdatering av befintliga poster i entiteten.
`delete`	Tillåter borttagning av poster från entiteten.
`execute`	Tillåter körning av en lagrad procedur eller åtgärd som är relaterad till entiteten.
`*`	Beviljar alla tillämpliga CRUD-åtgärder

Exempel

I det här exemplet definieras en anonym roll med åtkomst till alla möjliga åtgärder.

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

Du kan också blanda och matcha sträng- och objektmatrisåtgärder.

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

Anonym roll Tillåt anonyma användare att läsa alla fält utom secret-field. Användningen av "include": ["*"] med "exclude": ["secret-field"] döljer effektivt secret-field från anonyma användare samtidigt som åtkomst till alla andra fält tillåts.

Autentiserad roll Tillåt autentiserade användare att läsa och uppdatera specifika fält, uttryckligen inklusive id, titleoch secret-field, men sedan exkluderas secret-field. Visar explicit inkludering och efterföljande exkludering av secret-field, som visar prioriteten för exclude. Eftersom secret-field både ingår och exkluderas blir det otillgängligt, vilket matchar den avsedda regeln för exclude som har företräde.

Författare roll Författare kan utföra alla åtgärder * på alla fält utan undantag. Filen anger "include": ["*"] med en tom "exclude": [] matris ger åtkomst till alla fält, eftersom inga fält uttryckligen undantas.

Den här konfigurationen representerar standardvärdet om inget har angetts.

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

Det är i praktiken identiskt med:

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

Tänk också på följande konfiguration:

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

Den tidigare konfigurationen anger i praktiken att inga fält uttryckligen inkluderas ("include": [] är tom, vilket indikerar att inga fält tillåts) och att alla fält är exkluderade ("exclude": ["*"] använder jokertecknet * för att ange alla fält).

Praktisk användning: En sådan konfiguration kan verka kontraintuitiv eftersom den begränsar åtkomsten till alla fält. Den kan dock användas i scenarier där en roll kan utföra vissa åtgärder , till exempel att skapa en entitet, utan att komma åt någon av dess data.

Samma beteende, men med annan syntax, skulle vara:

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

Den tidigare konfigurationen försöker ange att endast fälten Id och Title ska inkluderas, samtidigt som alla fält ska undantas med jokertecknet * i avsnittet exclude. Ett annat sätt att uttrycka samma logik är:

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

Med tanke på den allmänna regeln att exclude-listan har företräde framför listan include innebär det vanligtvis att alla fält undantas om du anger exclude: ["*"], även de fält som anges i avsnittet include. Vid första anblicken kan den här konfigurationen därför verka förhindra att några fält blir tillgängliga, eftersom exkluderingsregeln är dominerande.

Omvänd: Om avsikten är att bevilja, endast åtkomst till fälten Id och Title, är det tydligare och mer tillförlitligt att endast ange de fälten i avsnittet include och inte använda exclude med jokertecken. Du kan också justera systemets behörighetslogik för att uttryckligen hantera sådana fall, förutsatt att du har kontroll över dess design. Till exempel:

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

Egenskaper

	Krävs	Typ
`role`	✔️ Ja	sträng
`actions` (strängmatris) eller `actions` (objektmatris)	✔️ Ja	objekt- eller strängmatris

Roll

Förälder	Egenskap	Typ	Krävs	Standard
`entities.permissions`	`role`	sträng	✔️ Ja	Ingen

Sträng som innehåller namnet på den roll som den definierade behörigheten gäller för. Strängen role innehåller namnet på den roll som den definierade behörigheten gäller för.

Roller anger behörighetskontexten där en begäran ska köras. För varje entitet som definieras i körningskonfigurationen kan du definiera en uppsättning roller och associerade behörigheter som avgör hur entiteten kan nås i både REST- och GraphQL-slutpunkterna. Roller är inte additiva. Mer information om roller finns i auktorisering.

Data API Builder utvärderar begäranden i kontexten för en enda roll:

Roll	Beskrivning
`anonymous`	Ingen åtkomsttoken visas
`authenticated`	En giltig åtkomsttoken visas
`<custom-role>`	En giltig åtkomsttoken visas och `X-MS-API-ROLE` HTTP-huvudet ingår som anger en användarroll som också ingår i åtkomsttokens rollanspråk

Format

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

Exempel

Det här exemplet definierar en roll med namnet reader med endast read behörigheter på slutpunkten.

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

Åtgärder (strängmatris)

Förälder	Egenskap	Typ	Krävs	Standard
`entities.permissions`	`actions`	oneOf [sträng, matris]	✔️ Ja	Ingen

En matris med strängvärden som beskriver vilka åtgärder som tillåts för den associerade rollen. För table- och view databasobjekt kan roller konfigureras för att använda valfri kombination av create, read, updateeller delete åtgärder. För lagrade procedurer kan roller bara ha åtgärden execute. Den actions matrisen beskriver vilka åtgärder som tillåts för den associerade rollen. När entiteten antingen är en tabell eller vy kan roller konfigureras med en kombination av åtgärderna: create, read, update, delete.

Handling	SQL-åtgärd
`*`	Jokertecken, inklusive körning
`create`	Infoga en eller flera rader
`read`	Markera en eller flera rader
`update`	Ändra en eller flera rader
`delete`	Ta bort en eller flera rader
`execute`	Kör en lagrad procedur

Not

För lagrade procedurer expanderas åtgärden jokertecken (*) till en lista som endast innehåller åtgärden execute. För tabeller och vyer expanderas jokerteckenåtgärden till en lista som innehåller åtgärderna create, read, updateoch delete.

Exempel

Det här exemplet ger create och read behörigheter till den första rollen med namnet contributor. Den andra rollen med namnet auditor har bara delete behörigheter.

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

Här är ett annat exempel.

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

Åtgärder (objektmatris)

Förälder	Egenskap	Typ	Krävs	Standard
`entities.permissions`	`actions`	strängmatris	✔️ Ja	Ingen

Not

Format

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

Egenskaper

Egenskap	Krävs	Typ	Standard
`action`	✔️ Ja	sträng	Ingen
`fields`	❌ Nej	strängmatris	Ingen
`policy`	❌ Nej	objekt	Ingen

Exempel

Det här exemplet ger endast read behörighet till rollen auditor. Rollen auditor kan bara läsa specifika data med hjälp av predikatet som definieras i policy.database. Den auditor rollen är också begränsad i vilka fält den kan eller inte kan läsa med hjälp av egenskapen fields.

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

Handling

Förälder	Egenskap	Typ	Krävs	Standard
`entities.permissions.actions[]`	`action`	sträng	✔️ Ja	Ingen

Anger den specifika åtgärd som tillåts för databasobjektet.

Värden

Här är en lista över tillåtna värden för den här egenskapen:

	Tabeller	Visningar	Lagrade procedurer	Beskrivning
`create`	✔️ Ja	✔️ Ja	❌ Nej	Skapa nya objekt
`read`	✔️ Ja	✔️ Ja	❌ Nej	Punktläsning av befintliga objekt
`update`	✔️ Ja	✔️ Ja	❌ Nej	Uppdatera eller ersätta befintliga objekt
`delete`	✔️ Ja	✔️ Ja	❌ Nej	Ta bort befintliga objekt
`execute`	❌ Nej	❌ Nej	✔️ Ja	Köra programmatiska åtgärder

Format

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

Exempel

Här är ett exempel där anonymous användare får execute en specifik lagrad procedur och read en specifik tabell.

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

Fält

Förälder	Egenskap	Typ	Krävs	Standard
`entities.permissions.actions[]`	`fields`	objekt	❌ Nej	Ingen

Detaljerade specifikationer för vilka specifika fält som tillåts åtkomst för databasobjektet. Rollkonfiguration är en objekttyp med två interna egenskaper, include och exclude. Dessa värden stöder detaljerad definition av vilka databaskolumner (fält) som tillåts åtkomst i avsnittet fields.

Format

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

Exempel

I det här exemplet kan anonymous-rollen läsa från alla fält utom id, men kan använda alla fält när du skapar ett objekt.

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

Inkludera och exkludera arbete tillsammans. Jokertecknet * i avsnittet include anger alla fält. Fälten som anges i avsnittet exclude har företräde framför fält som anges i avsnittet include. Definitionen översätts till inkludera alla fält förutom fältet "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": []
            }
        }
    ]
}

Politik

Förälder	Egenskap	Typ	Krävs	Standard
`entities.{entity}.permissions.actions[]`	`policy`	objekt	❌ Nej	Ingen

Avsnittet policy, som definieras per action, definierar säkerhetsregler på objektnivå (databasprinciper) som begränsar de resultat som returneras från en begäran. Underavsnittet database anger det databasprinciputtryck som utvärderas under körningen av begäran.

Format

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

Egenskaper

Egenskap	Krävs	Typ	Standard
`database`	✔️ Ja	sträng	Ingen

Beskrivning

Principen database: ett OData-liknande uttryck som översätts till en fråga som predikar databasen utvärderas, inklusive operatorer som eq, ltoch gt. För att resultat ska returneras för en begäran måste begärans frågepredikat som matchas från en databasprincip utvärderas till true när den körs mot databasen.

Exempel på objektprincip	Predikat
`@item.OwnerId eq 2000`	`WHERE Table.OwnerId = 2000`
`@item.OwnerId gt 2000`	`WHERE Table.OwnerId > 2000`
`@item.OwnerId lt 2000`	`WHERE Table.OwnerId < 2000`

En predicate är ett uttryck som utvärderas till TRUE eller FALSE. Predikat används i sökvillkoret för WHERE-satser och HAVING-satser, kopplingsvillkoren för FROM-satser och andra konstruktioner där ett booleskt värde krävs. (Microsoft Learn Docs)

Databasprincip

Två typer av direktiv kan användas för att hantera databasprinciper när du skapar ett databasprinciputtryck:

Direktiv	Beskrivning
`@claims`	Få åtkomst till ett anspråk i den verifierade åtkomsttoken som anges i begäran
`@item`	Representerar ett fält i den entitet som databasprincipen har definierats för

Not

När Azure Static Web Apps-autentisering (EasyAuth) har konfigurerats är ett begränsat antal anspråkstyper tillgängliga för användning i databasprinciper: identityProvider, userId, userDetailsoch userRoles. Mer information finns i dokumentationen om klientobjekt i Azure Static Web Apps dokumentation.

Här följer några exempel på databasprinciper:

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

Data API Builder jämför värdet för det UserId anspråket med värdet för databasfältet OwnerId. Resultatnyttolasten innehåller endast poster som uppfyller både begärandemetadata och databasprinciputtrycket.

Begränsningar

Databasprinciper stöds för tabeller och vyer. Lagrade procedurer kan inte konfigureras med principer.

Databasprinciper förhindrar inte att begäranden körs i databasen. Det här beteendet beror på att de matchas som predikat i de genererade frågor som skickas till databasmotorn.

Databasprinciper stöds bara för actionsskapa, läsa, uppdateraoch ta bort. Eftersom det inte finns något predikat i ett lagrat proceduranrop kan de inte läggas till.

OData-liknande operatorer som stöds

Operatör	Beskrivning	Exempelsyntax
`and`	Logiskt OCH	`"@item.status eq 'active' and @item.age gt 18"`
`or`	Logiskt ELLER	`"@item.region eq 'US' or @item.region eq 'EU'"`
`eq`	Motsvarar	`"@item.type eq 'employee'"`
`gt`	Större än	`"@item.salary gt 50000"`
`lt`	Mindre än	`"@item.experience lt 5"`

Mer information finns i binära operatorer.

Operatör	Beskrivning	Exempelsyntax
`-`	Negate (numerisk)	`"@item.balance lt -100"`
`not`	Logisk negate (NOT)	`"not @item.status eq 'inactive'"`

Mer information finns i unary operatorer.

Begränsningar för entitetsfältnamn

Regler: Måste börja med en bokstav eller understreck (_), följt av upp till 127 bokstäver, understreck (_), eller siffror (0-9).
Effekt: Fält som inte följer dessa regler kan inte användas direkt i databasprinciper.
Solution: Använd avsnittet mappings för att skapa alias för fält som inte uppfyller dessa namngivningskonventioner. mappningar säkerställer att alla fält kan inkluderas i principuttryck.

Använda `mappings` för icke-konforma fält

Om namn på entitetsfält inte uppfyller OData-syntaxreglerna eller om du bara vill ge dem alias av andra skäl kan du definiera alias i avsnittet mappings i konfigurationen.

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

I det här exemplet är field-1-name det ursprungliga databasfältnamnet som inte uppfyller OData-namngivningskonventionerna. Om du skapar en karta för att field-1-name och field-1-alias kan det här fältet refereras till i databasprinciputtryck utan problem. Den här metoden hjälper inte bara till att följa OData-namngivningskonventionerna, utan förbättrar även tydligheten och tillgängligheten för din datamodell inom både GraphQL- och RESTful-slutpunkter.

Exempel

Överväg en entitet med namnet Employee i en data-API-konfiguration som använder både anspråks- och objektdirektiv. Det säkerställer att dataåtkomst hanteras på ett säkert sätt baserat på användarroller och entitetsägarskap:

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

Entitetsdefinition: Den Employee entiteten har konfigurerats för REST- och GraphQL-gränssnitt, vilket anger att dess data kan efterfrågas eller manipuleras via dessa slutpunkter.

Source Configuration: Identifierar HRUNITS i databasen med employee NUM som nyckelfält.

Mappningar: Alias används för att mappa employee NUM, employee Nameoch department COID till EmployeeId, EmployeeNamerespektive DepartmentId, vilket förenklar fältnamn och potentiellt döljer känslig information om databasschema.

Principprogram: Avsnittet policy tillämpar en databasprincip med ett OData-liknande uttryck. Den här principen begränsar dataåtkomsten till användare med HR-rollen (@claims.role eq 'HR') eller till användare vars UserId anspråk matchar EmployeeId – fältaliaset – i databasen (@claims.userId eq @item.EmployeeId). Det säkerställer att anställda endast kan komma åt sina egna poster om de inte tillhör HR-avdelningen. Principer kan framtvinga säkerhet på radnivå baserat på dynamiska villkor.

Databas

Förälder	Egenskap	Typ	Krävs	Standard
`entities.{entity}.permissions.actions.policy`	`database`	objekt	✔️ Ja	Ingen

Format

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

Den här egenskapen anger det databasprinciputtryck som utvärderas under körningen av begäran. Principsträngen är ett OData-uttryck som översätts till en fråga som beräknas av databasen. Principuttrycket @item.OwnerId eq 2000 översätts till frågepredikatet WHERE <schema>.<object-name>.OwnerId = 2000.

Not

Ett predikat är ett uttryck som utvärderas till TRUE, FALSEeller UNKNOWN. Predikat används i:

Sökvillkoret för WHERE-satser
Sökvillkoret för FROM-satser
Anslutningsvillkoren för FROM-satser
Andra konstruktioner där ett booleskt värde krävs.

Mer information finns i predikat.

För att resultat ska returneras för en begäran måste begärans frågepredikat som matchas från en databasprincip utvärderas till true när den körs mot databasen.

Två typer av direktiv kan användas för att hantera databasprincipen när du skapar ett databasprinciputtryck:

	Beskrivning
`@claims`	Får åtkomst till ett anspråk inom den verifierade åtkomsttoken som anges i begäran
`@item`	Representerar ett fält i den entitet som databasprincipen har definierats för

Not

Ett begränsat antal anspråkstyper är tillgängliga för användning i databasprinciper när Azure Static Web Apps-autentisering (EasyAuth) har konfigurerats. Dessa anspråkstyper är: identityProvider, userId, userDetailsoch userRoles. Mer information finns i Azure Static Web Apps-klientens huvuddata.

Exempel

Ett grundläggande principuttryck kan till exempel utvärdera om ett visst fält är sant i tabellen. Det här exemplet utvärderar om fältet soft_delete är false.

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

Predikat kan också utvärdera både claims och item direktivtyper. Det här exemplet hämtar fältet UserId från åtkomsttoken och jämför det med fältet owner_id i måldatabastabellen.

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

Begränsningar

Databasprinciper stöds för tabeller och vyer. Lagrade procedurer kan inte konfigureras med principer.
Databasprinciper kan inte användas för att förhindra att en begäran körs i en databas. Den här begränsningen beror på att databasprinciper löses som frågepredikat i de genererade databasfrågorna. Databasmotorn utvärderar slutligen dessa frågor.
Databasprinciper stöds endast för actionscreate, read, updateoch delete.
Databasprincipens OData-uttryckssyntax stöder endast dessa scenarier.
- Binära operatorer inklusive, men inte begränsat till; and, or, eq, gtoch lt. Mer information finns i BinaryOperatorKind.
- Unary-operatorer som operatorerna - (negate) och not. Mer information finns i UnaryOperatorKind.
Databasprinciper har också begränsningar relaterade till fältnamn.
- Entitetsfältnamn som börjar med en bokstav eller ett understreck följt av högst 127 bokstäver, understreck eller siffror.
- Det här kravet är enligt OData-specifikationen. Mer information finns i OData Common Schema Definition Language.

Dricks

Fält som inte överensstämmer med de nämnda begränsningarna kan inte refereras till i databasprinciper. Som en lösning konfigurerar du entiteten med ett mappningsavsnitt för att tilldela överensstämmande alias till fälten.

GraphQL (entiteter)

Förälder	Egenskap	Typ	Krävs	Standard
`entities.{entity}`	`graphql`	objekt	❌ Nej	Ingen

Det här segmentet tillhandahåller integrering av en entitet i GraphQL-schemat. Det gör att utvecklare kan ange eller ändra standardvärden för entiteten i GraphQL. Den här konfigurationen säkerställer att schemat korrekt återspeglar den avsedda strukturen och namngivningskonventionerna.

Format

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

Egenskaper

Egenskap	Krävs	Typ	Standard
`enabled`	❌ Nej	boolesk	Ingen
`type`	❌ Nej	sträng eller objekt	Ingen
`operation`	❌ Nej	uppräkningssträng	Ingen

Exempel

Dessa två exempel är funktionellt likvärdiga.

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

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

I det här exemplet är den definierade entiteten Book, vilket indikerar att vi hanterar en uppsättning data som är relaterade till böcker i databasen. Konfigurationen för den Book entiteten inom GraphQL-segmentet ger en tydlig struktur för hur den ska representeras och interageras med i ett GraphQL-schema.

Aktiverad egenskap: Entiteten Book görs tillgänglig via GraphQL ("enabled": true), vilket innebär att utvecklare och användare kan fråga eller mutera bokdata via GraphQL-åtgärder.

Type property: Entiteten representeras med det unika namnet "Book" och pluralnamnet "Books" i GraphQL-schemat. Den här skillnaden säkerställer att schemat erbjuder intuitivt namngivna typer (Book för en enda post, Books för en lista) när du frågar efter en enda bok eller flera böcker, vilket förbättrar API:ets användbarhet.

Egenskapen Operation: Åtgärden är inställd på "query", vilket anger att den primära interaktionen med den Book entiteten via GraphQL är avsedd att köra frågor mot (hämta) data i stället för att mutera (skapa, uppdatera eller ta bort) den. Den här konfigurationen överensstämmer med vanliga användningsmönster där bokdata läses oftare än ändras.

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

Typ (GraphQL-entitet)

Förälder	Egenskap	Typ	Krävs	Standard
`entities.{entity}.graphql`	`type`	oneOf [sträng, objekt]	❌ Nej	{entity-name}

Den här egenskapen dikterar namngivningskonventionen för en entitet i GraphQL-schemat. Den stöder både skalära strängvärden och objekttyper. Objektvärdet anger singular- och pluralformerna. Den här egenskapen ger detaljerad kontroll över schemats läsbarhet och användarupplevelse.

Format

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

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

Egenskaper

Egenskap	Krävs	Typ	Standard
`singular`	❌ Nej	sträng	Ingen
`plural`	❌ Nej	sträng	N/A (standard: singular)

Exempel

Om du vill ha ännu större kontroll över GraphQL-typen kan du konfigurera hur singular- och pluralnamnet representeras oberoende av varandra.

Om plural saknas eller utelämnas (till exempel skalärt värde) försöker data-API-byggare att pluralisera namnet automatiskt genom att följa de engelska reglerna för pluralisering (till exempel: https://engdic.org/singular-and-plural-noun-rules-definitions-examples)

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

Ett anpassat entitetsnamn kan anges med hjälp av parametern type med ett strängvärde. I det här exemplet skiljer motorn automatiskt mellan singular- och pluralvarianterna av det här namnet med hjälp av vanliga engelska regler för pluralisering.

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

Om du väljer att uttryckligen ange namnen använder du egenskaperna type.singular och type.plural. I det här exemplet anges uttryckligen båda namnen.

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

Båda exemplen är funktionellt likvärdiga. Båda returnerar samma JSON-utdata för en GraphQL-fråga som använder bookauthors entitetsnamn.

{
  bookauthors {
    items {
      first_name
      last_name
    }
  }
}

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

Åtgärd (GraphQL-entitet)

Förälder	Egenskap	Typ	Krävs	Standard
`entities.{entity}.graphql`	`operation`	uppräkningssträng	❌ Nej	Ingen

För entiteter som mappas till lagrade procedurer anger egenskapen operation GraphQL-åtgärdstyp (fråga eller mutation) där den lagrade proceduren är tillgänglig. Den här inställningen möjliggör logisk organisation av schemat och efterlevnad av bästa praxis för GraphQL, utan att påverka funktionaliteten.

Not

En entitet har angetts som en lagrad procedur genom att ange {entity}.type egenskapsvärdet till stored-procedure. När det gäller en lagrad procedur skapas automatiskt en ny GraphQL-typ executeXXX. Med egenskapen operation kan utvecklaren dock dela upp platsen för den typen i antingen mutation eller query delar av schemat. Den här egenskapen tillåter schemahygene och det finns ingen funktionspåverkan oavsett operation värde.

Om det saknas är standardvärdet operationmutation.

Format

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

Värden

Här är en lista över tillåtna värden för den här egenskapen:

	Beskrivning
`query`	Den underliggande lagrade proceduren exponeras som en fråga
`mutation`	Den underliggande lagrade proceduren exponeras som en mutation

Exempel

När operation är mutationskulle GraphQL-schemat likna:

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

När operation är queryskulle GraphQL-schemat likna:

GraphQL-schemat skulle likna:

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

Not

Egenskapen operation handlar bara om placeringen av åtgärden i GraphQL-schemat, den ändrar inte åtgärdens beteende.

Aktiverad (GraphQL-entitet)

Förälder	Egenskap	Typ	Krävs	Standard
`entities.{entity}.graphql`	`enabled`	boolesk	❌ Nej	Sann

Aktiverar eller inaktiverar GraphQL-slutpunkten. Styr om en entitet är tillgänglig via GraphQL-slutpunkter. Genom att växla enabled-egenskapen kan utvecklare selektivt exponera entiteter från GraphQL-schemat.

Format

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

REST (entiteter)

Förälder	Egenskap	Typ	Krävs	Standard
`entities.{entity}`	`rest`	objekt	❌ Nej	Ingen

Det rest avsnittet i konfigurationsfilen är dedikerat för att finjustera RESTful-slutpunkterna för varje databasentitet. Den här anpassningsfunktionen säkerställer att det exponerade REST API:et matchar specifika krav, vilket förbättrar både dess verktygs- och integreringsfunktioner. Den åtgärdar potentiella matchningar mellan standardinställningar och önskade slutpunktsbeteenden.

Format

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

Egenskaper

Egenskap	Krävs	Typ	Standard
`enabled`	✔️ Ja	boolesk	Sann
`path`	❌ Nej	sträng	`/<entity-name>`
`methods`	❌ Nej	strängmatris	FÅ

Exempel

Dessa två exempel är funktionellt likvärdiga.

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

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

Här är ett annat exempel på en REST-konfiguration för en entitet.

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

Aktiverad (REST-entitet)

Förälder	Egenskap	Typ	Krävs	Standard
`entities.{entity}.rest`	`enabled`	boolesk	❌ Nej	Sann

Den här egenskapen fungerar som en växlingsknapp för synligheten för entiteter i REST-API:et. Genom att ange egenskapen enabled till true eller falsekan utvecklare styra åtkomsten till specifika entiteter, vilket möjliggör en anpassad API-yta som överensstämmer med kraven på programsäkerhet och funktioner.

Format

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

Sökväg (REST-entitet)

Förälder	Egenskap	Typ	Krävs	Standard
`entities.rest`	`path`	sträng	❌ Nej	Ingen

Egenskapen path anger det URI-segment som används för att komma åt en entitet via REST-API:et. Den här anpassningen möjliggör mer beskrivande eller förenklade slutpunktssökvägar utöver standardentitetsnamnet, vilket förbättrar API-navigeringen och integreringen på klientsidan. Som standard är sökvägen /<entity-name>.

Format

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

Exempel

I det här exemplet exponeras den Author entiteten med hjälp av /auth-slutpunkten.

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

Metoder (REST-entitet)

Förälder	Egenskap	Typ	Krävs	Standard
`entities.{entity}.rest`	`methods`	strängmatris	❌ Nej	Ingen

Den methods egenskapen gäller specifikt för lagrade procedurer och definierar vilka HTTP-verb (till exempel GET, POST) som proceduren kan svara på. Metoder ger exakt kontroll över hur lagrade procedurer exponeras via REST-API:et, vilket säkerställer kompatibilitet med RESTful-standarder och klientförväntningar. Det här avsnittet understryker plattformens engagemang för flexibilitet och utvecklarkontroll, vilket möjliggör exakt och intuitiv API-design som är anpassad efter de specifika behoven i varje program.

Om det utelämnas eller saknas är standardvärdet methodsPOST.

Format

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

Värden

Här är en lista över tillåtna värden för den här egenskapen:

	Beskrivning
`get`	Exponerar HTTP GET-begäranden
`post`	Exponerar HTTP POST-begäranden

Exempel

Det här exemplet instruerar motorn att den stp_get_bestselling_authors lagrade proceduren endast stöder HTTP GET åtgärder.

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

Mappningar (entiteter)

Förälder	Egenskap	Typ	Krävs	Standard
`entities.{entity}`	`mappings`	objekt	❌ Nej	Ingen

Avsnittet mappings gör det möjligt att konfigurera alias eller exponerade namn för databasobjektfält. De konfigurerade exponerade namnen gäller för både GraphQL- och REST-slutpunkterna.

Viktig

För entiteter med GraphQL aktiverat måste det konfigurerade exponerade namnet uppfylla GraphQL-namngivningskraven. Mer information finns i GraphQL-namnspecifikationen.

Format

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

Exempel

I det här exemplet exponeras fältet sku_title från databasobjektet dbo.magazines med namnet title. På samma sätt exponeras fältet sku_status som status i både REST- och GraphQL-slutpunkter.

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

Här är ett annat exempel på mappningar.

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

Mappningar: Det mappings objektet länkar databasfälten (BookID, BookTitle, AuthorName) till mer intuitiva eller standardiserade namn (id, title, author) som används externt. Det här aliaset har flera syften:

Tydlighet och Konsekvens: Det gör det möjligt att använda tydlig och konsekvent namngivning i API:et, oavsett det underliggande databasschemat. Till exempel representeras BookID i databasen som id i API:et, vilket gör det mer intuitivt för utvecklare som interagerar med slutpunkten.
GraphQL Compliance: Genom att tillhandahålla en mekanism för aliasfältnamn säkerställer det att namnen som exponeras via GraphQL-gränssnittet uppfyller kraven för GraphQL-namngivning. Uppmärksamhet på namn är viktigt eftersom GraphQL har strikta regler för namn (till exempel inga blanksteg, måste börja med en bokstav eller understreck osv.). Om ett databasfältnamn till exempel inte uppfyller dessa villkor kan det aliaseras till ett kompatibelt namn via mappningar.
Flexibilitet: Den här aliaseringen lägger till ett abstraktionslager mellan databasschemat och API:et, vilket möjliggör ändringar i det ena utan att kräva ändringar i det andra. En fältnamnsändring i databasen kräver till exempel ingen uppdatering av API-dokumentationen eller koden på klientsidan om mappningen förblir konsekvent.
Fältnamn Fördunkling: Mappning möjliggör fördunkling av fältnamn, vilket kan hjälpa till att förhindra obehöriga användare från att härleda känslig information om databasschemat eller typen av data som lagras.
Skydda upphovsrättsskyddad information: Genom att byta namn på fält kan du också skydda egna namn eller affärslogik som kan antydas via databasens ursprungliga fältnamn.

Relationer (entiteter)

Förälder	Egenskap	Typ	Krävs	Standard
`entities.{entity}`	`relationships`	objekt	❌ Nej	Ingen

Det här avsnittet mappar innehåller en uppsättning relationsdefinitioner som mappar hur entiteter är relaterade till andra exponerade entiteter. Dessa relationsdefinitioner kan också innehålla information om de underliggande databasobjekt som används för att stödja och framtvinga relationerna. Objekt som definierats i det här avsnittet exponeras som GraphQL-fält i den relaterade entiteten. Mer information finns i Data API builder relationsuppdelning.

Not

Relationer är bara relevanta för GraphQL-frågor. REST-slutpunkter får endast åtkomst till en entitet i taget och kan inte returnera kapslade typer.

I avsnittet relationships beskrivs hur entiteter interagerar i data-API-byggaren, med information om associationer och potentiellt databasstöd för dessa relationer. Egenskapen relationship-name för varje relation krävs och måste vara unik för alla relationer för en viss entitet. Anpassade namn säkerställer tydliga, identifierbara anslutningar och upprätthåller integriteten för GraphQL-schemat som genereras från dessa konfigurationer.

Förhållande	Kardinalitet	Exempel
en-till-många	`many`	En kategorientitet kan relatera till många att göra-entiteter
många-till-en	`one`	Många att göra-entiteter kan relatera till en kategorientitet
många-till-många	`many`	En att göra-entitet kan relatera till många användarentiteter, och en användarentitet kan relatera till många att göra-entiteter

Format

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

Egenskaper

Egenskap	Krävs	Typ	Standard
`cardinality`	✔️ Ja	uppräkningssträng	Ingen
`target.entity`	✔️ Ja	sträng	Ingen
`source.fields`	❌ Nej	strängmatris	Ingen
`target.fields`	❌ Nej	strängmatris	Ingen
`linking.<object-or-entity>`	❌ Nej	sträng	Ingen
`linking.source.fields`	❌ Nej	strängmatris	Ingen
`linking.target.fields`	❌ Nej	strängmatris	Ingen

Exempel

När du överväger relationer är det bäst att jämföra skillnaderna mellan en-till-många-, många-till-en-och många-till-många- relationer.

En-till-många

Först ska vi överväga ett exempel på en relation med den exponerade Category entiteten har en en-till-många- relation med den Book entiteten. Här är kardinaliteten inställd på many. Varje Category kan ha flera relaterade Book entiteter medan varje Book entitet endast är associerad med en enda Category entitet.

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

I det här exemplet anger listan source.fields fältet id för källentiteten (Category). Det här fältet används för att ansluta till det relaterade objektet i den target entiteten. Omvänt anger target.fields-listan category_id fältet för målentiteten (Book). Det här fältet används för att ansluta till det relaterade objektet i den source entiteten.

Med den här relationen definierad bör det resulterande exponerade GraphQL-schemat likna det här exemplet.

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

Många-till-en

Överväg sedan många-till-en- som anger kardinaliteten till one. Den exponerade Book entiteten kan ha en enda relaterad Category entitet. Den Category entiteten kan ha flera relaterade Book entiteter.

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

Här anger listan source.fields att fältet category_id för källentiteten (Book) refererar till fältet id för den relaterade målentiteten (Category). Omvänt anger listan target.fields invertera relationen. Med den här relationen innehåller det resulterande GraphQL-schemat nu en mappning tillbaka från Böcker till Kategorier.

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

Många-till-många

Slutligen definieras en många-till-många- relation med kardinaliteten many och fler metadata för att definiera vilka databasobjekt som används för att skapa relationen i databasen. Här kan den Book entiteten ha flera Author entiteter och omvänt kan den Author entiteten ha flera Book entiteter.

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

I det här exemplet anger både source.fields och target.fields att relationstabellen använder den primära identifieraren (id) för både källentiteterna (Book) och mål (Author). Fältet linking.object anger att relationen definieras i dbo.books_authors-databasobjektet. Dessutom anger linking.source.fields att det book_id fältet i länkobjektet refererar till fältet id för den Book entiteten och linking.target.fields anger att fältet author_id i länkobjektet refererar till fältet id i den Author entiteten.

Det här exemplet kan beskrivas med ett GraphQL-schema som liknar det här exemplet.

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

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

Kardinalitet

Förälder	Egenskap	Typ	Krävs	Standard
`entities.{entity}.relationships`	`cardinality`	sträng	✔️ Ja	Ingen

Anger om den aktuella källentiteten endast är relaterad till en enda instans av målentiteten eller flera.

Värden

Här är en lista över tillåtna värden för den här egenskapen:

	Beskrivning
`one`	Källan relaterar endast till en post från målet
`many`	Källan kan relatera till noll-till-många-poster från målet

Målentitet

Förälder	Egenskap	Typ	Krävs	Standard
`entities.{entity}.relationships`	`target.entity`	sträng	✔️ Ja	Ingen

Namnet på entiteten som definierats någon annanstans i den konfiguration som är målet för relationen.

Källfält

Förälder	Egenskap	Typ	Krävs	Standard
`entities.{entity}.relationships`	`source.fields`	samling	❌ Nej	Ingen

En valfri parameter för att definiera det fält som används för mappning i källa entitet som används för att ansluta till det relaterade objektet i målentiteten.

Dricks

Det här fältet krävs inte om det finns en sekundärnyckel begränsning i databasen mellan de två databasobjekt som kan användas för att härleda relationen automatiskt.

Målfält

Förälder	Egenskap	Typ	Krävs	Standard
`entities.{entity}.relationships`	`target.fields`	samling	❌ Nej	Ingen

En valfri parameter för att definiera det fält som används för mappning i mål entitet som används för att ansluta till det relaterade objektet i källentiteten.

Dricks

Det här fältet krävs inte om det finns en sekundärnyckel begränsning i databasen mellan de två databasobjekt som kan användas för att härleda relationen automatiskt.

Länka objekt eller entitet

Förälder	Egenskap	Typ	Krävs	Standard
`entities.{entity}.relationships`	`linking.object`	sträng	❌ Nej	Ingen

För många-till-många-relationer, namnet på databasobjektet eller entiteten som innehåller de data som krävs för att definiera en relation mellan två andra entiteter.

Länka källfält

Förälder	Egenskap	Typ	Krävs	Standard
`entities.{entity}.relationships`	`linking.source.fields`	samling	❌ Nej	Ingen

Namnet på databasobjektet eller entitetsfältet som är relaterat till källentiteten.

Länka målfält

Förälder	Egenskap	Typ	Krävs	Standard
`entities.{entity}.relationships`	`linking.target.fields`	samling	❌ Nej	Ingen

Namnet på databasobjektet eller entitetsfältet som är relaterat till målentiteten.

Cacheminne (entiteter)

Förälder	Egenskap	Typ	Krävs	Standard
`entities.{entity}.cache`	`enabled`	boolesk	❌ Nej	Falsk

Aktiverar och konfigurerar cachelagring för entiteten.

Format

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

Egenskaper

Egenskap	Krävs	Typ	Standard
`enabled`	❌ Nej	boolesk	Falsk
`ttl-seconds`	❌ Nej	heltal	5

Exempel

I det här exemplet är cachen aktiverad och objekten upphör att gälla efter 30 sekunder.

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

Aktiverad (cacheentitet)

Förälder	Egenskap	Typ	Krävs	Standard
`entities.{entity}.cache`	`enabled`	boolesk	❌ Nej	Falsk

Aktiverar cachelagring för entiteten.

Stöd för databasobjekt

Objekttyp	Cachestöd
Bord	✅ Ja
Utsikt	✅ Ja
Lagrad procedur	✖️ Nej
Behållare	✖️ Nej

Stöd för HTTP-sidhuvud

Begärandehuvud	Cachestöd
`no-cache`	✖️ Nej
`no-store`	✖️ Nej
`max-age`	✖️ Nej
`public`	✖️ Nej
`private`	✖️ Nej
`etag`	✖️ Nej

Format

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

Exempel

I det här exemplet är cachen inaktiverad.

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

TTL i sekunder (cacheentitet)

Förälder	Egenskap	Typ	Krävs	Standard
`entities.cache`	`ttl-seconds`	heltal	❌ Nej	5

Konfigurerar TTL-värdet (time-to-live) i sekunder för cachelagrade objekt. Efter den här tiden rensas objekt automatiskt från cacheminnet. Standardvärdet är 5 sekunder.

Format

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

Exempel

I det här exemplet är cachen aktiverad och objekten upphör att gälla efter 15 sekunder. När den utelämnas ärver den här inställningen den globala inställningen eller standardinställningen.

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

Dela via

Referens för konfigurationsschema för Data API Builder

Syntaxöversikt

Egenskaper på den översta nivån

Exempelkonfigurationer

Miljöer

Konfigurationsegenskaper

Schemat

Format

Exempel

Datakälla

Format

Egenskaper

Databastyp

Format

Ange värden

Anslutningssträng

Format

Anslutningsåterhämtning

Azure SQL och SQL Server

Exempel

Alternativ

Format

Exempel

Datakällans filer

Format

Överväganden för konfigurationsfil

Exempel

Runtime

Format

Egenskaper

Exempel

GraphQL (körning)

Format

Egenskaper

Aktiverad (GraphQL-körning)

Format

Exempel

Djupgräns (GraphQL-körning)

Exempel

Sökväg (GraphQL-körning)

Format

Exempel

Tillåt introspektion (GraphQL-körning)

Format

Exempel

Flera mutationer (GraphQL-körning)

Format

Egenskaper

Flera mutationer – skapa (GraphQL-körning)

Format

Egenskaper

Exempel

REST (runtime)

Format

Egenskaper

Aktiverad (REST-körning)

Format

Exempel

Sökväg (REST-körning)

Format

Exempel

Strikt begärandetext (REST-körning)

Format

Exempel

Värd (körning)

Format

Egenskaper

Exempel

Läge (värdkörning)

Format

Värden

Maximal svarsstorlek (Runtime)

Tillåtna värden

Format

CORS (värdkörning)

Format

Egenskaper

Tillåt autentiseringsuppgifter (värdkörning)

Format