Dela via

Referens för konfigurationsschema för Data API Builder

  • Artikel

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 *.Development.json-filen om värdet connection-string 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
andra 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). 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.

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

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

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.

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.

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

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

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

Relaterat innehåll