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": {
    "User": {
      "source": "dbo.Users",
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["*"]
        }
      ]
    }
  }
}

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

Miljöer

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

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

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

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

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

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

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

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

Konfigurationsegenskaper

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

Schemat

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

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

Format

{
  "$schema": <string>
}

Exempel

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

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

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

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

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

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

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

Not

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

Datakälla

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

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

Format

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

Egenskaper

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

Databastyp

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

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

Format

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

Ange värden

Egenskapen type anger typen av serverdelsdatabas.

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

Anslutningssträng

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

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

Format

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

Anslutningsåterhämtning

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

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

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

Azure SQL och SQL Server

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

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

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

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

Exempel

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

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

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

Format

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

alternativ: { set-session-context: booleskt }

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.

Exempel på SQL-lagrad procedur:
CREATE PROC GetUser @userId INT AS
BEGIN
    -- Check if the current user has access to the requested userId
    IF SESSION_CONTEXT(N'user_role') = 'admin' 
        OR SESSION_CONTEXT(N'user_id') = @userId
    BEGIN
        SELECT Id, Name, Age, IsAdmin
        FROM Users
        WHERE Id = @userId;
    END
    ELSE
    BEGIN
        RAISERROR('Unauthorized access', 16, 1);
    END
END;
JSON-konfigurationsexempel:
{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')",
    "options": {
      "set-session-context": true
    }
  },
  "entities": {
    "User": {
      "source": {
        "object": "dbo.GetUser",
        "type": "stored-procedure",
        "parameters": {
          "userId": "number"
        }
      },
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["execute"]
        }
      ]
    }
  }
}

Förklaring:

  1. lagrad procedur (GetUser):

    • Proceduren kontrollerar SESSION_CONTEXT för att kontrollera om anroparen har rollen admin eller matchar den userId som angetts.
    • Obehörig åtkomst resulterar i ett fel.

  2. JSON-konfiguration:

    • set-session-context har aktiverats för att skicka användarmetadata från åtkomsttoken till databasen.
    • Egenskapen parameters mappar den userId parameter som krävs av den lagrade proceduren.
    • Blocket permissions garanterar att endast autentiserade användare kan köra den lagrade proceduren.

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

Följande visar hur du aktiverar och använder flera mutationer i GraphQL-körningen. I det här fallet är create-åtgärden konfigurerad för att tillåta skapandet av flera poster i en enda begäran genom att ange egenskapen runtime.graphql.multiple-mutations.create.enabled till true.

Konfigurationsexempel

Den här konfigurationen möjliggör flera create mutationer:

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

GraphQL-mutationsexempel

Med hjälp av ovanstående konfiguration skapar följande mutation flera User poster i en enda åtgärd:

mutation {
  createUsers(input: [
    { name: "Alice", age: 30, isAdmin: true },
    { name: "Bob", age: 25, isAdmin: false },
    { name: "Charlie", age: 35, isAdmin: true }
  ]) {
    id
    name
    age
    isAdmin
  }
}

REST (runtime)

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

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

Den här inställningen styr hur strikt begärandetexten för REST-mutationsåtgärder (t.ex. POST, PUT, PATCH) verifieras.

  • true (standard): Extra fält i begärandetexten som inte mappas till tabellkolumner orsakar ett BadRequest undantag.
  • false: Extra fält ignoreras och endast giltiga kolumner bearbetas.

Den här inställningen inte tillämpas på GET begäranden eftersom deras begärandetext alltid ignoreras.

Beteende med specifika kolumnkonfigurationer

  • Kolumner med värdet default() ignoreras under INSERT endast när värdet i nyttolasten är null. Kolumner med default() ignoreras inte under UPDATE oavsett nyttolastvärde.
  • Beräknade kolumner ignoreras alltid.
  • Automatiskt genererade kolumner ignoreras alltid.

Format

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

Exempel

CREATE TABLE Users (
    Id INT PRIMARY KEY IDENTITY,
    Name NVARCHAR(50) NOT NULL,
    Age INT DEFAULT 18,
    IsAdmin BIT DEFAULT 0,
    IsMinor AS IIF(Age <= 18, 1, 0)
);
Exempelkonfiguration
{
  "runtime": {
    "rest": {
      "request-body-strict": false
    }
  }
}
INSERT-beteende med request-body-strict: false

Begär nyttolast:

{
  "Id": 999,
  "Name": "Alice",
  "Age": null,
  "IsAdmin": null,
  "IsMinor": false,
  "ExtraField": "ignored"
}

resulterande Insert-instruktion:

INSERT INTO Users (Name) VALUES ('Alice');
-- Default values for Age (18) and IsAdmin (0) are applied by the database.
-- IsMinor is ignored because it’s a computed column.
-- ExtraField is ignored.
-- The database generates the Id value.

Svarsnyttolast:

{
  "Id": 1,          // Auto-generated by the database
  "Name": "Alice",
  "Age": 18,        // Default applied
  "IsAdmin": false, // Default applied
  "IsMinor": true   // Computed
}
UPPDATERA beteende med request-body-strict: false

Begär nyttolast:

{
  "Id": 1,
  "Name": "Alice Updated",
  "Age": null,     // explicitely set to 'null'
  "IsMinor": true, // ignored because computed
  "ExtraField": "ignored"
}

resulterande uppdateringsuttryck:

UPDATE Users
SET Name = 'Alice Updated', Age = NULL
WHERE Id = 1;
-- IsMinor and ExtraField are ignored.

Svarsnyttolast:

{
  "Id": 1,
  "Name": "Alice Updated",
  "Age": null,
  "IsAdmin": false,
  "IsMinor": false // Recomputed by the database (false when age is `null`)
}

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

Beteenden

  • Endast i development läge är Swagger tillgängligt.
  • Endast i development läge är Banana Cake Pop tillgänglig.

Maximal svarsstorlek (Runtime)

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

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

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

Tillåtna värden

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

Format

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

CORS (värdkörning)

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

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

Format

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

Egenskaper

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

Tillåt autentiseringsuppgifter (värdkörning)

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

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

Not

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

Format

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

Ursprung (värdkörning)

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

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

Format

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

Exempel

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

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

Autentisering (värdkörning)

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

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

Format

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

Egenskaper

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

autentisering och kundansvar

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

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

Provider (värdkörning)

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

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

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

Format

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

Värden

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

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

JSON-webbtoken (värdkörning)

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

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

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

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

Format

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

Egenskaper

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

Exempel

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

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

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

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

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

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

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

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

Målgrupp (värdkörning)

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

Målgrupp för JWT-token.

Format

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

Utfärdare (värdkörning)

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

Utfärdare för JWT-token.

Format

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

Sidnumrering (Runtime)

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

Konfigurerar sidnumreringsgränser för REST- och GraphQL-slutpunkter.

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

Exempelkonfiguration

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

Exempel på REST-sidnumrering

I det här exemplet returnerar en REST GET-begäran https://localhost:5001/api/users två poster i matrisen value eftersom default-page-size är inställt på 2. Om det finns fler resultat innehåller Data API Builder en nextLink i svaret. nextLink innehåller en $after parameter för att hämta nästa sida med data.

Begäran:
GET https://localhost:5001/api/users
Svar:
{
  "value": [
    {
      "Id": 1,
      "Name": "Alice",
      "Age": 30,
      "IsAdmin": true,
      "IsMinor": false
    },
    {
      "Id": 2,
      "Name": "Bob",
      "Age": 17,
      "IsAdmin": false,
      "IsMinor": true
    }
  ],
  "nextLink": "https://localhost:5001/api/users?$after=W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI=="
}

Med hjälp av nextLinkkan klienten hämta nästa uppsättning resultat.

GraphQL-sidnumreringsexempel

För GraphQL använder du fälten hasNextPage och endCursor för sidnumrering. De här fälten anger om fler resultat är tillgängliga och ger en markör för att hämta nästa sida.

Fråga:
query {
  users {
    items {
      Id
      Name
      Age
      IsAdmin
      IsMinor
    }
    hasNextPage
    endCursor
  }
}
Svar:
{
  "data": {
    "users": {
      "items": [
        {
          "Id": 1,
          "Name": "Alice",
          "Age": 30,
          "IsAdmin": true,
          "IsMinor": false
        },
        {
          "Id": 2,
          "Name": "Bob",
          "Age": 17,
          "IsAdmin": false,
          "IsMinor": true
        }
      ],
      "hasNextPage": true,
      "endCursor": "W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI=="
    }
  }
}

Om du vill hämta nästa sida tar du med värdet endCursor i nästa fråga:

Fråga med markör:
query {
  users(after: "W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI==") {
    items {
      Id
      Name
      Age
      IsAdmin
      IsMinor
    }
    hasNextPage
    endCursor
  }
}

Justera sidstorlek

BÅDE REST och GraphQL tillåter justering av antalet resultat per fråga med hjälp av $limit (REST) eller first (GraphQL).

$limit / first värde Uppförande
-1 Standardvärdet är max-page-size.
< max-page-size Begränsar resultatet till det angivna värdet.
0 eller < -1 Stöds inte.
> max-page-size Capped på max-page-size.
Exempel på REST-fråga:
GET https://localhost:5001/api/users?$limit=5
Exempel på GraphQL-fråga:
query {
  users(first: 5) {
    items {
      Id
      Name
      Age
      IsAdmin
      IsMinor
    }
  }
}

Maximal sidstorlek (sidnumreringskörning)

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

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

Tillåtna värden

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

Format

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

Standardstorlek för sidnumrering (sidnumreringskörning)

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

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

Tillåtna värden

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

Cache (körning)

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

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

Format

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

Egenskaper

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

Exempel

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

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

Aktiverad (cachekörning)

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

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

Format

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

Exempel

I det här exemplet är cachen inaktiverad.

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

TTL i sekunder (cachekörning)

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

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

Format

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

Exempel

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

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

Telemetri (körning)

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

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

Format

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

Application Insights (telemetrikörning)

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

Aktiverad (Application Insights-telemetri)

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

Anslutningssträng (Application Insights-telemetri)

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

Enheter

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

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

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

Format

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

Egenskaper

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

Exempel

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

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["*"]
        }
      ]
    }
  }
}

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": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table",
        "key-fields": ["Id"],
        "parameters": {} // only when source.type = stored-procedure
      },
      "rest": {
        "enabled": true,
        "path": "/users",
        "methods": [] // only when source.type = stored-procedure
      },
      "graphql": {
        "enabled": true,
        "type": {
          "singular": "User",
          "plural": "Users"
        },
        "operation": "query"
      },
      "mappings": {
        "id": "Id",
        "name": "Name",
        "age": "Age",
        "isAdmin": "IsAdmin"
      },
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"],  // "execute" only when source.type = stored-procedure
          "fields": {
            "include": ["id", "name", "age", "isAdmin"],
            "exclude": []
          },
          "policy": {
            "database": "@claims.userId eq @item.id"
          }
        },
        {
          "role": "admin",
          "actions": ["create", "read", "update", "delete"],
          "fields": {
            "include": ["*"],
            "exclude": []
          },
          "policy": {
            "database": "@claims.userRole eq 'UserAdmin'"
          }
        }
      ]
    }
  }
}

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 behöver källegenskapen endast namnet på det databasobjektet. Den här enkelheten underlättar snabb installation för vanliga användningsfall: "source": "dbo.User".

Format

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

Egenskaper

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

Exempel

1. Enkel tabellmappning:

Det här exemplet visar hur du associerar en User entitet med en källtabell dbo.Users.

SQL

CREATE TABLE dbo.Users (
  Id INT PRIMARY KEY,
  Name NVARCHAR(100),
  Age INT,
  IsAdmin BIT
);

Konfiguration

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      }
    }
  }
}

2. Exempel på lagrad procedur:

Det här exemplet visar hur du associerar en User entitet med en dbo.GetUsers.

SQL

CREATE PROCEDURE GetUsers 
     @IsAdmin BIT 
AS
SELECT Id, Name, Age, IsAdmin
FROM dbo.Users
WHERE IsAdmin = @IsAdmin;

Konfiguration

{
  "entities": {
    "User": {
      "source": {
        "type": "stored-procedure",
        "object": "GetUsers",
        "parameters": {
          "IsAdmin": "boolean"
        }
      },
      "mappings": {
        "Id": "id",
        "Name": "name",
        "Age": "age",
        "IsAdmin": "isAdmin"
      }
    }
  }
}

Egenskapen mappings är valfri för lagrade procedurer.

Objekt

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

Namnet på databasobjektet som ska användas. Om objektet tillhör dbo schema är det valfritt att ange schemat. Dessutom kan hakparenteser runt objektnamn (t.ex. [dbo].[Users] jämfört med dbo.Users) användas eller utelämnas.

Exempel

SQL

CREATE TABLE dbo.Users (
  Id INT PRIMARY KEY,
  Name NVARCHAR(100),
  Age INT,
  IsAdmin BIT
);

Konfiguration

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      }
    }
  }
}

alternativ notation utan schema och hakparenteser:

Om tabellen finns i dbo schema kan du utelämna schemat eller hakparenteserna:

{
  "entities": {
    "User": {
      "source": {
        "object": "Users",
        "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, inklusive view, tableoch stored-procedure. Den här egenskapen krävs och har inget standardvärde.

Format

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

Värden

Värde Beskrivning
table Representerar en tabell.
stored-procedure Representerar en lagrad procedur.
view Representerar en vy.

Exempel

1. Tabellexempel:

SQL

CREATE TABLE dbo.Users (
  Id INT PRIMARY KEY,
  Name NVARCHAR(100),
  Age INT,
  IsAdmin BIT
);

Konfiguration

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      }
    }
  }
}

2. Visa exempel:

SQL

CREATE VIEW dbo.AdminUsers AS
SELECT Id, Name, Age
FROM dbo.Users
WHERE IsAdmin = 1;

Konfiguration

{
  "entities": {
    "AdminUsers": {
      "source": {
        "object": "dbo.AdminUsers",
        "type": "view",
        "key-fields": ["Id"]
      },
      "mappings": {
        "Id": "id",
        "Name": "name",
        "Age": "age"
      }
    }
  }
}

Obs! Att ange key-fields är viktigt för vyer eftersom de saknar inbyggda primära nycklar.

3. Exempel på lagrad procedur:

SQL

CREATE PROCEDURE dbo.GetUsers (@IsAdmin BIT)
AS
SELECT Id, Name, Age, IsAdmin
FROM dbo.Users
WHERE IsAdmin = @IsAdmin;

Konfiguration

{
  "entities": {
    "User": {
      "source": {
        "type": "stored-procedure",
        "object": "GetUsers",
        "parameters": {
          "IsAdmin": "boolean"
        }
      }
    }
  }
}

Nyckelfält

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

Egenskapen {entity}.key-fields är särskilt nödvändig för entiteter som backas upp av vyer, så Data API Builder vet hur man identifierar och returnerar ett enda objekt. Om type är inställt på view utan att ange key-fields, vägrar motorn att starta. Den här egenskapen är tillåten med tabeller och lagrade procedurer, men den används inte i dessa fall.

Viktig

Den här egenskapen krävs om typen av objekt är en view.

Format

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

Exempel: Visa med nyckelfält

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

SQL

CREATE VIEW dbo.AdminUsers AS
SELECT Id, Name, Age
FROM dbo.Users
WHERE IsAdmin = 1;

Konfiguration

{
  "entities": {
    "AdminUsers": {
      "source": {
        "object": "dbo.AdminUsers",
        "type": "view",
        "key-fields": ["Id"]
      }
    }
  }
}

Parametrar

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

Egenskapen parameters i entities.{entity}.source används för entiteter som backas upp av lagrade procedurer. Det säkerställer korrekt mappning av parameternamn och datatyper som krävs enligt den lagrade proceduren.

Viktig

Egenskapen parameters krävs om objektets type är stored-procedure och parametern krävs.

Format

{
  "entities": {
    "<entity-name>": {
      "source": {
        "type": "stored-procedure",
        "parameters": {
          "<parameter-name-1>": <string | number | boolean>,
          "<parameter-name-2>": <string | number | boolean>
        }
      }
    }
  }
}
Exempel 1: Lagrad procedur utan parametrar

SQL

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

Konfiguration

{
  "entities": {
    "Users": {
      "source": {
        "object": "dbo.GetUsers",
        "type": "stored-procedure"
      }
    }
  }
}
Exempel 2: Lagrad procedur med parametrar

SQL

CREATE PROCEDURE dbo.GetUser (@userId INT) AS
SELECT Id, Name, Age, IsAdmin FROM dbo.Users
WHERE Id = @userId;

Konfiguration

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.GetUser",
        "type": "stored-procedure",
        "parameters": {
          "userId": "number"
        }
      }
    }
  }
}

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 när det gäller roller och CRUD-åtgärder: create, read, updateoch delete. Avsnittet permissions anger vilka roller som kan komma åt den relaterade entiteten och med vilka åtgärder.

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.
* Beviljar alla tillämpliga CRUD-åtgärder.

Exempel

Exempel 1: Anonym roll för användarentitet

I det här exemplet definieras den anonymous rollen med åtkomst till alla möjliga åtgärder på den User entiteten.

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

Exempel 2: Blandade åtgärder för anonym roll

Det här exemplet visar hur du blandar sträng- och objektmatrisåtgärder för den User entiteten.

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

Anonym roll: Tillåter anonyma användare att läsa alla fält utom ett hypotetiskt känsligt fält (t.ex. secret-field). Om du använder "include": ["*"] med "exclude": ["secret-field"] döljs secret-field samtidigt som åtkomst till alla andra fält tillåts.

Autentiserad roll: Tillåter autentiserade användare att läsa och uppdatera specifika fält. Om du till exempel uttryckligen inkluderar id, nameoch age men exkludering av isAdmin kan du visa hur undantag åsidosätter inkluderingar.

administratörsroll: Administratörer kan utföra alla åtgärder (*) på alla fält utan undantag. Om du anger "include": ["*"] med en tom "exclude": [] matris får du åtkomst till alla fält.

Den här konfigurationen:

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

är i praktiken identisk med:

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

Tänk också på den här konfigurationen:

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

Detta anger att inga fält uttryckligen inkluderas och att alla fält undantas, vilket vanligtvis begränsar åtkomsten helt.

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 utför vissa åtgärder (som att skapa en entitet) utan att komma åt någon av dess data.

Samma beteende, men med annan syntax, skulle vara:

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

Den här konfigurationen försöker endast inkludera Id och Name fält, men exkluderar alla fält på grund av jokertecknet i exclude.

Ett annat sätt att uttrycka samma logik är:

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

Med tanke på att exclude har företräde framför includeinnebär det att ange exclude: ["*"] innebär att alla fält undantas, även de i include. Vid första anblicken kan den här konfigurationen därför verka förhindra att fält blir tillgängliga.

Omvänd: Om avsikten är att endast bevilja åtkomst till Id och Name fält är det tydligare och mer tillförlitligt att endast ange dessa fält i avsnittet include utan att använda ett jokertecken för undantag:

"fields": {
  "include": ["Id", "Name"],
  "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. 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 via REST- och GraphQL-slutpunkter. Roller är inte additiva.

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 http-huvudet för X-MS-API-ROLE anger en roll som finns i token

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

I det här exemplet definieras en roll med namnet reader med endast read behörigheter för den User entiteten.

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

Du kan använda <custom-role> när en giltig åtkomsttoken visas och det X-MS-API-ROLE HTTP-huvudet ingår och ange en användarroll som också finns i anspråket för åtkomsttokens roller. Nedan visas exempel på GET-begäranden till den User entiteten, inklusive både auktoriseringsbärarens token och X-MS-API-ROLE-huvudet, i REST-slutpunktsbasen /api på localhost med olika språk.

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

Å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 använda valfri kombination av create, read, updateeller delete åtgärder. För lagrade procedurer kan roller bara ha åtgärden execute.

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 (*) endast till åtgärden execute. För tabeller och vyer expanderas den till create, read, updateoch delete.

Exempel

Det här exemplet ger create och read behörigheter till en roll med namnet contributor och delete behörigheter till en roll med namnet auditor på den User entiteten.

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

Ett annat exempel:

{
  "entities": {
    "User": {
      "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 åtgärdsobjekt som beskriver tillåtna åtgärder för den associerade rollen. För table- och view-objekt kan roller använda valfri kombination av create, read, updateeller delete. För lagrade procedurer tillåts endast execute.

Not

För lagrade procedurer expanderas åtgärden jokertecken (*) till endast execute. För tabeller/vyer expanderas den till create, read, updateoch delete.

Format

{
  "entities": {
    "<entity-name>": {
      "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 auditor roll för den User entiteten, med fält- och principbegränsningar.

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "auditor",
          "actions": [
            {
              "action": "read",
              "fields": {
                "include": ["*"],
                "exclude": ["last_login"]
              },
              "policy": {
                "database": "@item.IsAdmin eq false"
              }
            }
          ]
        }
      ]
    }
  }
}

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

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

Format

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

Exempel

Här är ett exempel där anonymous användare får execute en lagrad procedur och read från tabellen User.

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read"
            }
          ]
        }
      ]
    },
    "GetUser": {
      "source": {
        "object": "dbo.GetUser",
        "type": "stored-procedure",
        "parameters": {
          "userId": "number"
        }
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "execute"
            }
          ]
        }
      ]
    }
  }
}

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": "number"
        }
      },
      "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