Informazioni di riferimento sullo schema di configurazione di Generatore API dati

Articolo
05/30/2024

Il motore del generatore di API dati richiede un file di configurazione. Il file di configurazione di Generatore API dati offre un approccio strutturato e completo per configurare l'API, illustrando in dettaglio tutte le variabili di ambiente e le configurazioni specifiche dell'entità. Questo documento in formato JSON inizia con una $schema proprietà . Questa configurazione convalida il documento.

Le proprietà database-type e connection-string garantiscono una perfetta integrazione con i sistemi di database, dal database SQL di Azure all'API NoSQL di Cosmos DB.

Il file di configurazione può includere opzioni quali:

Informazioni di connessione e servizio di database
Opzioni di configurazione globali e di runtime
Set di entità esposte
Metodo di autenticazione
Regole di sicurezza necessarie per accedere alle identità
Regole di mapping dei nomi tra API e database
Relazioni tra entità che non possono essere dedotte
Funzionalità esclusive per servizi di database specifici

Panoramica della sintassi

Ecco una rapida suddivisione delle "sezioni" primarie in un file di configurazione.

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

Proprietà di primo livello

Ecco la descrizione delle proprietà di primo livello in un formato di tabella:

Proprietà	Descrizione
$schema	Specifica lo schema JSON per la convalida, assicurando che la configurazione sia conforme al formato richiesto.
origine dati	Contiene i dettagli sul tipo di database e sulla stringa di connessione, necessari per stabilire la connessione al database.
file di origine dati	Matrice facoltativa che specifica altri file di configurazione che potrebbero definire altre origini dati.
Runtime	Configura i comportamenti e le impostazioni di runtime, incluse le sottoproprietà per REST, GraphQL, host, cache e telemetria.
Entità	Definisce il set di entità (tabelle di database, viste e così via) esposte tramite l'API, inclusi i mapping, le autorizzazioni e le relazioni.

Configurazione di esempio

Ecco un file di configurazione di esempio che include solo le proprietà necessarie per una singola entità semplice. Questo esempio è progettato per illustrare uno scenario minimo.

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

Per un esempio di scenario più complesso, vedere la configurazione di esempio end-to-end.

Ambienti

Il file di configurazione di Generatore API dati può supportare scenari in cui è necessario supportare più ambienti, analogamente al appSettings.json file in ASP.NET Core. Il framework fornisce tre valori di ambiente comuni; Development, Staginge Production, ma è possibile scegliere di usare qualsiasi valore di ambiente scelto. L'ambiente usato da Generatore API dati deve essere configurato usando la DAB_ENVIRONMENT variabile di ambiente.

Si consideri un esempio in cui si vuole una configurazione di base e una configurazione specifica dello sviluppo. Questo esempio richiede due file di configurazione:

	Ambiente
dab-config.json	Base
dab-config. Development.json	Sviluppo

Per usare la configurazione specifica dello sviluppo, è necessario impostare la DAB_ENVIRONMENT variabile di ambiente su Development.

I file di configurazione specifici dell'ambiente sostituiscono i valori delle proprietà nel file di configurazione di base. In questo esempio, se il valore è impostato in entrambi i connection-string file, il valore di *. Development.json viene usato il file .

Fare riferimento a questa matrice per comprendere meglio quale valore viene usato a seconda della posizione in cui viene specificato (o non specificato) in entrambi i file.

	Specificato nella configurazione di base	Non specificato nella configurazione di base
Specificato nella configurazione dell'ambiente corrente	Ambiente corrente	Ambiente corrente
Non specificato nella configurazione dell'ambiente corrente	Base	Nessuno

Per un esempio dell'uso di più file di configurazione, vedere Usare Generatore API dati con ambienti.

Proprietà di configurazione

Questa sezione include tutte le possibili proprietà di configurazione disponibili per un file di configurazione.

SCHEMA

OBBLIGATORIO: ✔️ Sì

Ogni file di configurazione inizia con una $schema proprietà , specificando lo schema JSON per la convalida.

Format

{
  "$schema": "<string>"
}

Esempi

I file di schema sono disponibili per le versioni 0.3.7-alpha successive a URL specifici, assicurandosi di usare la versione corretta o lo schema più recente disponibile.

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

Sostituire VERSION-suffix con la versione desiderata.

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

La versione più recente dello schema è sempre disponibile in https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json.

Di seguito sono riportati alcuni esempi di valori di schema validi.

Versione	URI	Descrizione
0.3.7-alpha	`https://github.com/Azure/data-api-builder/releases/download/v0.3.7-alpha/dab.draft.schema.json`	Usa lo schema di configurazione da una versione alfa dello strumento.
0.10.23	`https://github.com/Azure/data-api-builder/releases/download/v0.10.23/dab.draft.schema.json`	Usa lo schema di configurazione per una versione stabile dello strumento.
Più recente	`https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json`	Usa la versione più recente dello schema di configurazione.

Nota

Le versioni del generatore di API dati precedenti alla versione 0.3.7-alpha possono avere un URI dello schema diverso.

Origine dati

OBBLIGATORIO: ✔️ Sì

La data-source sezione definisce il database e l'accesso al database tramite la stringa di connessione. Definisce anche le opzioni di database. La data-source proprietà configura le credenziali necessarie per connettersi al database di backup. La data-source sezione descrive la connettività del database back-end, specificando sia e database-typeconnection-string.

Formato

{
  "data-source": {
    "database-type": "...",
    "connection-string": "your-connection-string",
    
    // mssql-only
    "options": {
      "set-session-context": <true> (default) | <false>
    },
    
    // cosmosdb_nosql-only
    "options": {
      "database": "your-cosmosdb-database-name", 
      "container": "your-cosmosdb-container-name",
      "schema": "path-to-your-graphql-schema-file"
    }
  }
}

Proprietà

	Obbligatoria	Tipo
`database-type`	✔️ Sì	stringa di enumerazione
`connection-string`	✔️ Sì	string
`options`	❌ No	object

Tipo di database

OBBLIGATORIO: ✔️ Sì

Stringa di enumerazione utilizzata per specificare il tipo di database da utilizzare come origine dati.

Formato

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

Valori

La type proprietà indica il tipo di database back-end.

Tipo	Descrizione	Versione minima
`mssql`	database SQL di Azure	n/d
`mssql`	Istanza gestita di SQL di Azure	n/d
`mssql`	SQL Server	SQL 2016
`sqldw`	Azure SQL Data Warehouse	n/d
`postgresql`	PostgreSQL	v11
`mysql`	MySQL	v8
`cosmosdb_nosql`	Azure Cosmos DB for NoSQL	n/d
`cosmosdb_postgresql`	Azure Cosmos DB for PostgreSQL	n/d

Stringa di connessione

OBBLIGATORIO: ✔️ Sì

Valore stringa contenente una stringa di connessione valida per la connessione al servizio di database di destinazione. Stringa di connessione ADO.NET per connettersi al database back-end. Per altre informazioni, vedere ADO.NET stringhe di connessione.

Formato

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

Resilienza delle connessioni

Il generatore di API dati ritenta automaticamente le richieste di database dopo aver rilevato errori temporanei. La logica di ripetizione dei tentativi segue una strategia di backoff esponenziale in cui il numero massimo di tentativi è cinque. Durata del backoff dei tentativi dopo che le richieste successive vengono calcolate usando questa formula (presupponendo che il tentativo di ripetizione corrente sia r):

$r^2$

Usando questa formula, è possibile calcolare il tempo per ogni tentativo di ripetizione in secondi.

	Secondi
Primo	`2`
Secondo	`4`
Terzo	`8`
Quarto	`16`
Quinto	`32`

Azure SQL e SQL Server

Il generatore di API dati usa la SqlClient libreria per connettersi ad Azure SQL o SQL Server usando la stringa di connessione specificata nel file di configurazione. Un elenco di tutte le opzioni della stringa di connessione supportate è disponibile qui: Proprietà SqlConnection.ConnectionString.

Il generatore di API dati può anche connettersi al database di destinazione usando identità del servizio gestito.Data API builder can also connect to the target database using Managed Service Identities (MSI). Il DefaultAzureCredential definito nella Azure.Identity libreria viene usato per connettersi usando identità note quando non si specifica un nome utente o una password nella stringa di connessione. Per altre informazioni, vedere DefaultAzureCredential esempi.

Esempio

Il valore usato per la stringa di connessione dipende in gran parte dal servizio di database usato nello scenario. È sempre possibile scegliere di archiviare la stringa di connessione in una variabile di ambiente e accedervi usando la @env() funzione .

	Valore	Descrizione
Usare il valore stringa del database SQL di Azure	`Server=<server-address>;Database=<name-of-database>;User ID=<username>;Password=<password>;`	Stringa di connessione a un account del database SQL di Azure. Per altre informazioni, vedere Stringhe di connessione del database SQL di Azure.
Usare il valore stringa di Database di Azure per PostgreSQL	`Server=<server-address>;Database=<name-of-database>;Port=5432;User Id=<username>;Password=<password>;Ssl Mode=Require;`	Stringa di connessione a un account di Database di Azure per PostgreSQL. Per altre informazioni, vedere Stringhe di connessione di Database di Azure per PostgreSQL.
Usare il valore stringa di Azure Cosmos DB per NoSQL	`AccountEndpoint=<endpoint>;AccountKey=<key>;`	Stringa di connessione a un account Azure Cosmos DB per NoSQL. Per altre informazioni, vedere Stringhe di connessione di Azure Cosmos DB per NoSQL.
Usare il valore stringa di Database di Azure per MySQL	`Server=<server-address>;Database=<name-of-database>;User ID=<username>;Password=<password>;Sslmode=Required;SslCa=<path-to-certificate>;`	Stringa di connessione a un account di Database di Azure per MySQL. Per altre informazioni, vedere Stringhe di connessione di Database di Azure per MySQL.
Accedere alla variabile di ambiente	`@env('database-connection-string')`	Accedere a una variabile di ambiente dal computer locale. In questo esempio viene fatto riferimento alla `database-connection-string` variabile di ambiente.

Suggerimento

Come procedura consigliata, evitare di archiviare informazioni riservate nel file di configurazione. Quando possibile, usare @env() per fare riferimento alle variabili di ambiente. Per altre informazioni, vedere @env() funzione.

Questi esempi illustrano semplicemente come configurare ogni tipo di database. Lo scenario potrebbe essere univoco, ma questo esempio è un buon punto di partenza. Sostituire i segnaposto, myserverad esempio , myDataBasemylogin, e myPassword con i valori effettivi specifici dell'ambiente.

mssql
```
"data-source": {
  "database-type": "mssql",
  "connection-string": "$env('my-connection-string')",
  "options": {
    "set-session-context": true
  }
}
```
- Formato tipico della stringa di connessione: "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')"
}
```
- Formato tipico della stringa di connessione: "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')"
}
```
- Formato tipico della stringa di connessione: "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"
  }
}

Formato tipico della stringa di connessione: "AccountEndpoint=https://mycosmosdb.documents.azure.com:443/;AccountKey=myAccountKey;"

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

Nota

Le "opzioni" specificate, databasead esempio , containere schema sono specifiche per l'API NoSQL di Azure Cosmos DB anziché per l'API PostgreSQL. Per Azure Cosmos DB usando l'API PostgreSQL, le "opzioni" non includono database, containero schema come nell'installazione di NoSQL.

Opzioni

OBBLIGATORIO: ❌ No

Sezione facoltativa di parametri chiave-valore aggiuntivi per connessioni di database specifiche.

Format

{
  "data-source"{
    "options": {
        "<key>": "<value>"
    }
  }
}

Esempi

Indica se la options sezione è obbligatoria o meno dipende in gran parte dal servizio di database in uso.

	Valore	Descrizione
Abilitare `SESSION_CONTEXT` in AZURE SQL o SQL Server	`"set-session-context": false`	Per SQL di Azure e SQL Server, Il generatore di API dati può sfruttare la possibilità di `SESSION_CONTEXT` inviare metadati specificati dall'utente al database sottostante. Tali metadati sono disponibili per il generatore di API dati in virtù delle attestazioni presenti nel token di accesso. I `SESSION_CONTEXT` dati sono disponibili per il database durante la connessione al database fino alla chiusura della connessione. Per altre informazioni, vedere contesto della sessione.

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

File dell'origine dati

OBBLIGATORIO: ❌ No

Questa proprietà include i nomi dei file di configurazione di runtime che fanno riferimento a database aggiuntivi.

Formato

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

Considerazioni sul file di configurazione

La data-source proprietà in ogni file di configurazione è necessaria.
La entities proprietà in ogni file di configurazione è necessaria.
Viene usata solo l'impostazione del file runtime di configurazione di primo livello.
I file di configurazione a livello figlio possono anche identificare i file figlio.
I file di configurazione possono essere inseriti nelle sottocartelle come desiderato.
I nomi di entità devono essere univoci in tutti i file di configurazione.
Le relazioni tra i file di configurazione non sono supportate.

Problemi noti

Attualmente, i file di configurazione figlio sono supportati solo in GraphQL.
Attualmente, i file di configurazione figlio non supportano le variabili di ambiente.

Esempio

{
  "data-source-files": ["dab-config-two.json", "dab-config-three.json"]
}

Sottocartelle di riferimento se in uso:

{
  "data-source-files": ["myfolder/dab-config-two.json"]
}

Runtime

OBBLIGATORIO: ❌ No

La runtime sezione descrive le opzioni che influenzano il comportamento e le impostazioni di runtime per tutte le entità esposte.

Formato

{
  "runtime": {
    "rest": {
      "path": "/api" (default),
      "enabled": <true> (default) | <false>,
      "request-body-strict": <true> (default) | <false>
    },
    "graphql": {
      "path": "/graphql" (default),
      "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": -1, <integer; default: 100000>,
    "default-page-size": -1 | <integer; default: 100>
  },
  "telemetry": {
    "application-insights": {
      "connection-string": "<connection-string>",
      "enabled": <true> | <false> (default)
    }
  }
}

Proprietà

	Obbligatoria	Tipo
`rest`	❌ No	object
`graphql`	❌ No	object
`host`	❌ No	object
`cache`	❌ No	object

Esempio

Ecco un esempio di sezione runtime con più parametri predefiniti comuni specificati.

{
  "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": 100000,
      "default-page-size": 100
    },
    "telemetry": {
      "application-insights": {
        "connection-string": "<connection-string>",
        "enabled": true
      }
    }
  }
}

GraphQL (runtime)

OBBLIGATORIO: ❌ No

Questo oggetto definisce se GraphQL è abilitato e il nome[s] usato per esporre l'entità come tipo GraphQL. Questo oggetto è facoltativo e usato solo se il nome o le impostazioni predefinite non sono sufficienti. Questa sezione descrive le impostazioni globali per l'endpoint GraphQL.

Formato

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

Proprietà

	Obbligatoria	Tipo
`enabled`	❌ No	boolean
`path`	❌ No	string
`allow-introspection`	❌ No	boolean
`multiple-mutations`	❌ No	object

Abilitato (runtime GraphQL)

OBBLIGATORIO: ❌ No

Definisce se abilitare o disabilitare gli endpoint GraphQL a livello globale. Se disabilitato a livello globale, nessuna entità sarà accessibile tramite richieste GraphQL indipendentemente dalle singole impostazioni di entità.

Format

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

Esempi

In questo esempio l'endpoint GraphQL è disabilitato per tutte le entità.

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

Percorso (runtime GraphQL)

OBBLIGATORIO: ❌ No

Definisce il percorso URL in cui è disponibile l'endpoint GraphQL. Ad esempio, se questo parametro è impostato su /graphql, l'endpoint GraphQL viene esposto come /graphql. Per impostazione predefinita, il percorso è /graphql.

Importante

I percorsi secondari non sono consentiti per questa proprietà. Non è attualmente disponibile un valore del percorso personalizzato per l'endpoint GraphQL.

Format

{
  "runtime": {
    "graphql": {
      "path": "<string>"
    }
  }
}

Esempi

In questo esempio l'URI URI GraphQL radice è /query.

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

Consenti introspezione (runtime GraphQL)

OBBLIGATORIO: ❌ No

Questo flag booleano controlla la possibilità di eseguire query di introspezione dello schema nell'endpoint GraphQL. L'abilitazione dell'introspezione consente ai client di eseguire query sullo schema per informazioni sui tipi di dati disponibili, sui tipi di query che possono eseguire e sulle mutazioni disponibili.

Questa funzionalità è utile durante lo sviluppo per comprendere la struttura dell'API GraphQL e per gli strumenti che generano automaticamente query. Tuttavia, per gli ambienti di produzione, potrebbe essere disabilitato per nascondere i dettagli dello schema dell'API e migliorare la sicurezza. Per impostazione predefinita, l'introspezione è abilitata, consentendo l'esplorazione immediata e completa dello schema GraphQL.

Format

{
  "runtime": {
    "graphql": {
      "allow-introspection": "<boolean>"
    }
  }
}

Esempi

In questo esempio l'introspezione è disabilitata.

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

Più mutazioni (runtime GraphQL)

OBBLIGATORIO: ❌ No

Configura tutte le operazioni di mutazione multiple per il runtime GraphQL.

Nota

Per impostazione predefinita, più mutazioni non sono abilitate e devono essere configurate in modo esplicito per essere abilitate.

Formato

{
  "runtime": {
    "graphql": {
      "multiple-mutations": {
        "create": <object>
      }
    }
  }
}

Proprietà

	Obbligatoria	Tipo
`create`	❌ No	object

Più mutazioni : creare (runtime GraphQL)

OBBLIGATORIO: ❌ No

Configura più operazioni di creazione per il runtime GraphQL.

Formato

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

Proprietà

	Obbligatoria	Tipo
`enabled`	✔️ Sì	boolean

Esempio

In questo esempio sono abilitate più mutazioni per il runtime GraphQL. In particolare, l'operazione di creazione multipla è abilitata specificando un valore di true per la runtime.graphql.multiple-mutations.create.enabled proprietà.

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

REST (runtime)

OBBLIGATORIO: ❌ No

Questa sezione descrive le impostazioni globali per gli endpoint REST. Queste impostazioni fungono da impostazioni predefinite per tutte le entità, ma possono essere sostituite in base alle rispettive configurazioni.

Formato

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

Proprietà

	Obbligatoria	Tipo
`enabled`	❌ No	boolean
`path`	❌ No	string
`request-body-strict`	❌ No	boolean

Abilitato (runtime REST)

OBBLIGATORIO: ❌ No

Flag booleano che determina la disponibilità globale degli endpoint REST. Se disabilitato, non è possibile accedere alle entità tramite REST, indipendentemente dalle singole impostazioni di entità.

Format

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

Esempi

In questo esempio l'endpoint DELL'API REST è disabilitato per tutte le entità.

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

Percorso (runtime REST)

OBBLIGATORIO: ❌ No

Imposta il percorso URL per l'accesso a tutti gli endpoint REST esposti. Ad esempio, l'impostazione su path/api rende accessibile l'endpoint REST in /api/<entity>. I percorsi secondari non sono consentiti. Questo campo è facoltativo, con /api come impostazione predefinita.

Nota

Quando si distribuisce Il generatore di API dati usando App Web statiche (anteprima), il servizio di Azure inserisce automaticamente il sottopercorso /data-api aggiuntivo nell'URL. Questo comportamento garantisce la compatibilità con le funzionalità di App Web statiche esistenti. L'endpoint risultante sarà /data-api/api/<entity>. Questo è rilevante solo per le app Web statiche.

Importante

I percorsi secondari non sono consentiti per questa proprietà.

Format

{
  "runtime": {
    "rest": {
      "path": "<string>"
    }
  }
}

Esempi

In questo esempio l'URI dell'API REST radice è /data.

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

Suggerimento

Se si definisce un'entità Author , l'endpoint per questa entità sarà /data/Author.

Corpo della richiesta strict (runtime REST)

OBBLIGATORIO: ❌ No

Questo flag booleano determina se il corpo della richiesta per un'operazione di mutazione REST può contenere campi estranei. Per impostazione predefinita, il valore è true, ovvero i campi aggiuntivi nel corpo della richiesta generano un'eccezione BadRequest . Tuttavia, l'impostazione di questo flag su false consente agli utenti di includere campi aggiuntivi nel corpo della richiesta, che vengono ignorati. È importante notare che questo flag non influisce sulle richieste di query REST (GET), perché il corpo della richiesta viene sempre ignorato per le operazioni GET.

Nota

Questo flag non influisce sulle richieste HTTP GET all'endpoint dell'API REST. Il corpo della richiesta viene sempre ignorato per le operazioni GET.

Format

{
  "runtime": {
    "rest": {
      "request-body-strict": "<boolean>"
    }
  }
}

Esempi

In questo esempio la convalida rigorosa del corpo della richiesta è disabilitata.

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

Host (runtime)

OBBLIGATORIO: ❌ No

La host sezione all'interno della configurazione di runtime fornisce le impostazioni cruciali per l'ambiente operativo del generatore di API dati. Queste impostazioni includono modalità operative, configurazione CORS e dettagli di autenticazione.

Formato

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

Proprietà

	Obbligatoria	Tipo
`mode`	❌ No	stringa di enumerazione
`cors`	❌ No	object
`authentication`	❌ No	object

Esempio

Ecco un esempio di runtime configurato per l'hosting di sviluppo.

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

Modalità (runtime host)

OBBLIGATORIO: ❌ No

Definisce se il motore del generatore di API dati deve essere eseguito in development modalità o production . Il valore predefinito è production.

In genere, gli errori del database sottostanti vengono esposti in modo dettagliato impostando il livello predefinito di dettaglio per i log su Debug durante l'esecuzione nello sviluppo. Nell'ambiente di produzione il livello di dettaglio per i log è impostato su Error.

Suggerimento

È possibile eseguire l'override del livello di log predefinito usando dab start --LogLevel <level-of-detail>. Per altre informazioni, vedere le informazioni di riferimento sull'interfaccia della riga di comando.

Formato

{
  "runtime": {
    "host": {
      "mode": "<enum-string>"
    }
  }
}

Valori

Ecco un elenco di valori consentiti per questa proprietà:

	Descrizione
`production`	Usare quando si ospita nell'ambiente di produzione in Azure
`development`	Usare in fase di sviluppo nel computer locale

CORS (runtime host)

OBBLIGATORIO: ❌ No

Impostazioni CORS (Cross-Origin Resource Sharing) per l'host del motore del generatore di API dati.

Formato

{
  "runtime": {
    "host": {
      "cors": "<object>"
    }
  }
}

Proprietà

	Obbligatoria	Tipo
`allow-credentials`	❌ No	boolean
`origins`	❌ No	Matrice di stringhe

Consenti credenziali (runtime host)

OBBLIGATORIO: ❌ No

Se true, imposta l'intestazione Access-Control-Allow-Credentials CORS. Per impostazione predefinita, il valore è false.

Nota

Per altre informazioni sull'intestazione Access-Control-Allow-Credentials CORS, vedere Informazioni di riferimento su CORS per la documentazione Web MDN.

Formato

{
  "runtime": {
    "host": {
      "cors": {
        "allow-credentials": "<boolean>",
      }
    }
  }
}

Origini (runtime host)

OBBLIGATORIO: ❌ No

Imposta una matrice con un elenco di origini consentite per CORS. Questa impostazione consente il * carattere jolly per tutte le origini.

Format

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

Esempi

Ecco un esempio di host che consente CORS senza credenziali da tutte le origini.

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

Autenticazione (runtime host)

OBBLIGATORIO: ❌ No

Configura l'autenticazione per l'host Generatore API dati.

Formato

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "<enum-string>",
        "jwt": "<object>"
      }
    }
  }
}

Proprietà

	Obbligatoria	Tipo
`provider`	❌ No	stringa enumerazione
`jwt`	❌ No	object

Provider (runtime host)

OBBLIGATORIO: ❌ No

L'impostazione authentication.provider all'interno della host configurazione definisce il metodo di autenticazione usato dal generatore API dati. Determina come l'API convalida l'identità degli utenti o dei servizi che tentano di accedere alle risorse. Questa impostazione consente la flessibilità nella distribuzione e nell'integrazione supportando vari meccanismi di autenticazione personalizzati per diversi ambienti e requisiti di sicurezza.

Provider	Descrizione
`StaticWebApps` (impostazione predefinita)	Indica a Generatore API dati di cercare un set di intestazioni HTTP presenti solo quando viene eseguito all'interno di un ambiente App Web statiche.
`AppService`	Quando il runtime è ospitato in AppService di Azure con AppService Authentication abilitato e configurato (EasyAuth).
`AzureAd`	Microsoft Entra Identity deve essere configurato in modo che possa autenticare una richiesta inviata a Generatore API dati (l'app server). Per altre informazioni, vedere Autenticazione ID di Microsoft Entra.
`Simulator`	Provider di autenticazione configurabile che indica al motore generatore API dati di considerare tutte le richieste come autenticate. Per altre informazioni, vedere Autenticazione locale.

Formato

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "<enum-string>",
      }
    }
  }
}

Valori

Ecco un elenco di valori consentiti per questa proprietà:

	Descrizione
`StaticWebApps`	App Web statiche di Azure
`AppService`	Servizio app di Azure
`AzureAD`	Microsoft Entra ID
`Simulator`	Simulatore

Token Web JSON (runtime host)

OBBLIGATORIO: ❌ No

Se il provider di autenticazione è impostato su AzureAD (Microsoft Entra ID), questa sezione è necessaria per specificare il gruppo di destinatari e le autorità di certificazione per il token JWT (JSOn Web Tokens). Questi dati vengono usati per convalidare i token nel tenant di Microsoft Entra.

Obbligatorio se il provider di autenticazione è AzureAD per Microsoft Entra ID. Questa sezione deve specificare e audienceissuer per convalidare il token JWT ricevuto nel tenant previsto AzureAD per l'autenticazione.

Impostazione	Descrizione
audience	Identifica il destinatario previsto del token; in genere l'identificatore dell'applicazione registrato in Microsoft Entra Identity (o il provider di identità), assicurandosi che il token sia stato effettivamente rilasciato per l'applicazione.
autorità di certificazione	Specifica l'URL dell'autorità di emissione, ovvero il servizio token che ha rilasciato il JWT. Questo URL deve corrispondere all'URL dell'autorità di certificazione del provider di identità da cui è stato ottenuto il JWT, convalidando l'origine del token.

Formato

{
  "runtime": {
    "host": {
      "authentication": {
        "jwt": {
          "audience": "<string>",
          "issuer": "<string>"
        }
      }
    }
  }
}

Proprietà

	Obbligatoria	Tipo
`audience`	❌ No	string
`issuer`	❌ No	string

Esempio

Il Generatore API dati (DAB) offre supporto per l'autenticazione flessibile, integrazione con i server Microsoft Entra Identity e token Web JSON personalizzato (JWT). In questa immagine il server JWT rappresenta il servizio di autenticazione che rilascia token JWT ai client al termine dell'accesso. Il client passa quindi il token a DAB, che può interrogare le attestazioni e le proprietà.

Diagramma dei token Web JSON supportati in Generatore API dati.

Di seguito sono riportati esempi della proprietà in base a varie scelte dell'architettura host che è possibile effettuare nella soluzione.

App Web statiche di Azure

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

Con StaticWebApps, Generatore API dati prevede che app Web statiche di Azure autenticare la richiesta e l'intestazione X-MS-CLIENT-PRINCIPAL HTTP sia presente.

Servizio app di Azure

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

L'autenticazione viene delegata a un provider di identità supportato in cui è possibile rilasciare il token di accesso. Un token di accesso acquisito deve essere incluso con le richieste in ingresso a Generatore API dati. Generatore API dati convalida quindi tutti i token di accesso presentati, assicurandosi che Il generatore API dati fosse il pubblico previsto del 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"
   }
  }
 }
}

Simulatore (solo sviluppo)

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

Destinatari (runtime host)

OBBLIGATORIO: ❌ No

Destinatari per il token JWT.

Formato

{
  "runtime": {
    "host": {
      "authentication": {
        "jwt": {
          "audience": "<string>",
        }
      }
    }
  }
}

Autorità di certificazione (runtime host)

OBBLIGATORIO: ❌ No

Autorità di certificazione per il token JWT.

Formato

{
  "runtime": {
    "host": {
      "authentication": {
        "jwt": {
          "issuer": "<string>"
        }
      }
    }
  }
}

Paginazione (runtime)

OBBLIGATORIO: ❌ No

Configura i limiti dei risultati.

Formato

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

Proprietà

	Obbligatoria	Type	Predefinito
`max-page-size`	❌ No	numero intero	100,000
`default-page-size`	❌ No	numero intero	100

Esempio

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

Esempio di paginazione REST

Nell'esempio, se è stato rilasciato REST GET https://localhost:5001/api/books, il codice JSON risultante includerebbe un record nella value matrice perché le dimensioni della pagina sono state predefinite su 1. I risultati dell'esempio mostrano come i generatori di API dati vengono aggiunti nextLink ai risultati quando esiste una pagina successiva.

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

Si noti che l'opzione $after viene aggiunta allo stesso URL usato per eseguire query sull'endpoint. Questo valore speciale indica internamente l'ultimo record nella pagina corrente. Usando la stringa specificata come valore di $after restituirà automaticamente la pagina successiva dei dati.

Nota

È possibile che i dati della tabella sottostante siano stati modificati tra query. Non verrà generato un errore; illustra tuttavia perché il generatore api dati non ha il concetto di un numero di pagina. Le chiamate successive restituiscono la pagina successiva corretta, ma il numero di pagina potrebbe essere cambiato a causa delle modifiche ai dati. In questo modo, l'oggetto nextLink è letteralmente la pagina successiva dei dati, non il numero di pagina successivo.

Esempio di paginazione graphQL

Nell'esempio, se si esegue una query GraphQL, è necessario includere hasNextPage e endCursor usare la paginazione. Il motivo di questo requisito è che gli endpoint REST determinano la struttura dei payload, ma la query del consumer determina la struttura dei payload GraphQL. Con o senza questi valori, i risultati sono ancora limitati alle dimensioni predefinite della pagina. Una query sarà simile alla seguente:

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

I risultati di GraphQL includono hasNextPage e , endCursorche vengono usati per recuperare ulteriori pagine.

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

La query GraphQL successiva include il cursore come valore della after variabile nel modo seguente:

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

Uso $limit o first per modificare le dimensioni della pagina.

Sia REST che GraphQL possono includere rispettivamente una $limit variabile o first . Lo scopo di limit è limitare i risultati per una query specifica. Si consideri https://{server}/api/books?$limit=10tuttavia . Se limit , ad esempio, 10 quando la dimensione predefinita della pagina è 100, i risultati sono limitati a 10. Tuttavia, se limit è 200 quando la dimensione predefinita della pagina è 100, i risultati sono limitati a 200, un valore maggiore delle dimensioni predefinite della pagina.

Primo valore	Risultato
`-1`	Valore corrente dell'impostazione `max-page-size` . L'uso `-1` è utile quando il valore dell'impostazione `max-page-size` è sconosciuto al consumer. Generatore API dati sostituisce `-1` con il valore corrente di `max-page-size`.
`< max-page-size`	I risultati sono limitati al valore specificato.
`0`	Non valido. Viene restituita un'eccezione.
`< -1`	Non valido. Viene restituita un'eccezione.
`> max-page-size`	Non valido. Viene restituita un'eccezione.

Dimensioni massime della pagina (runtime di paginazione)

OBBLIGATORIO: ❌ No

Imposta il numero massimo di record di primo livello restituiti da una query REST o GraphQL.

Valori consentiti

valore	Risultato
`-1`	Questo valore viene predefinito per il valore massimo supportato.
`integer`	È supportato qualsiasi intero a 32 bit positivo.
`< -1`	Questa funzionalità non è supportata.
`= 0`	Questa funzionalità non è supportata.

Nota

Il valore massimo di un intero a 32 bit è 2.147.483.647. Questo è grande. In pratica, non esiste un limite universale rigoroso alle dimensioni di un payload dell'endpoint in uscita, ma diversi fattori possono limitare in modo efficace le dimensioni, tra cui la configurazione del server, la larghezza di banda e il timeout. Il generatore di API dati non conosce lo scenario, quindi questa impostazione è aperta alla configurazione da parte di ogni sviluppatore. Il massimo predefinito di 100.000 è già abbastanza aggressivo.

Dimensioni di pagina predefinite (runtime di paginazione)

OBBLIGATORIO: ❌ No

Imposta le dimensioni della pagina quando la paginazione è il numero di record di primo livello restituiti da una query REST o GraphQL.

Valori consentiti

valore	Risultato
`-1`	Questo valore viene predefinito per l'impostazione corrente `max-page-size` .
`integer`	Qualsiasi intero positivo minore dell'impostazione corrente `max-page-size` .
`< -1`	Questa funzionalità non è supportata.
`= 0`	Questa funzionalità non è supportata.

Cache (runtime)

OBBLIGATORIO: ❌ No

Abilita e configura la memorizzazione nella cache per l'intero runtime.

Formato

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

Proprietà

	Obbligatoria	Tipo
`enabled`	❌ No	boolean
`ttl-seconds`	❌ No	numero intero

Esempio

In questo esempio la cache è abilitata e gli elementi scadono dopo 30 secondi.

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

Abilitato (runtime cache)

OBBLIGATORIO: ❌ No

Abilita la memorizzazione nella cache a livello globale per tutte le entità. Il valore predefinito è false.

Format

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

Esempi

In questo esempio la cache è disabilitata.

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

TTL in secondi (runtime della cache)

OBBLIGATORIO: ❌ No

Configura il valore TTL (time-to-live) in secondi per gli elementi memorizzati nella cache. Dopo questo intervallo di tempo, gli elementi vengono eliminati automaticamente dalla cache. Il valore predefinito è 5 secondi.

Format

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

Esempi

In questo esempio la cache è abilitata a livello globale e tutti gli elementi scadono dopo 15 secondi.

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

Telemetria (runtime)

OBBLIGATORIO: ❌ No

Questa proprietà configura Application Insights per centralizzare i log API. Altre informazioni.

Entità

OBBLIGATORIO: ✔️ Sì

La entities sezione funge da core del file di configurazione, creando un bridge tra oggetti di database e i relativi endpoint API corrispondenti. Questa sezione esegue il mapping degli oggetti di database agli endpoint esposti. Questa sezione include anche il mapping delle proprietà e la definizione delle autorizzazioni. Ogni entità esposta viene definita in un oggetto dedicato. Il nome della proprietà dell'oggetto viene usato come nome dell'entità da esporre.

Questa sezione definisce il modo in cui ogni entità nel database è rappresentata nell'API, inclusi mapping delle proprietà e autorizzazioni. Ogni entità viene incapsulata all'interno della propria sottosezione, con il nome dell'entità che funge da chiave per riferimento in tutta la configurazione.

Formato

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "enabled": <true> (default) | <false>,
        "path": "/entity-path", (default <entity-name>)
        "methods": ["GET", "POST" (default)]
      },
      "graphql": {
        "enabled": <true> (default) | <false>,
        "type": {
          "singular": "myEntity",
          "plural": "myEntities"
        },
        "operation": "query" | "mutation" (default)
      },
      "source": {
        "object": "database-object-name",
        "type": "view" | "stored-procedure" | "table",
        "key-fields": ["field-name"],
        "parameters": {
          "parameter-name": "parameter-value"
        }
      },
      "mappings": {
        "database-field-name": "field-alias"
      },
      "relationships": {
        "relationship-name": {
          "cardinality": "one" | "many",
          "target.entity": "target-entity-name",
          "source.fields": ["source-field-name"],
          "target.fields": ["target-field-name"],
          "linking.object": "linking-object-name",
          "linking.source.fields": ["linking-source-field-name"],
          "linking.target.fields": ["linking-target-field-name"]
        }
      },
      "permissions": [
        {
          "role": "anonymous | authenticated | custom-role-name",
          "actions": ["create" | "read" | "update" | "delete" | "*"],
          "fields": {
            "include": ["field-name"],
            "exclude": ["field-name"]
          },
          "policy": {
            "database": "<Expression>"
          }
        }
      ]
    }
  }
}

Proprietà

	Obbligatoria	Tipo
`source`	✔️ Sì	object
`permissions`	✔️ Sì	array
`rest`	❌ No	object
`graphql`	❌ No	object
`mappings`	❌ No	object
`relationships`	❌ No	object
`cache`	❌ No	object

Esempio

Ad esempio, questo oggetto JSON indica a Generatore API dati di esporre un'entità GraphQL denominata Author e un endpoint REST raggiungibile tramite il /Author percorso. La dbo.authors tabella di database restituisce l'entità e la configurazione consente a chiunque di accedere all'endpoint in modo anonimo.

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

In questo esempio viene dichiarata l'entità User . Questo nome User viene usato ovunque nel file di configurazione in cui vengono fa riferimento le entità. In caso contrario, il nome dell'entità non è pertinente agli endpoint.

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

Source

OBBLIGATORIO: ✔️ Sì

La {entity}.source configurazione è fondamentale nella definizione della connessione tra l'entità esposta dall'API e il relativo oggetto di database sottostante. Questa proprietà specifica la tabella, la visualizzazione o la stored procedure di database rappresentata dall'entità, definendo un collegamento diretto per il recupero e la manipolazione dei dati.

Per scenari semplici, in cui l'entità esegue il mapping direttamente a una singola tabella o raccolta di database, la proprietà di origine richiede solo il nome di tale oggetto di database. Questa semplicità facilita la configurazione rapida per i casi d'uso comuni.

Formato

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

Proprietà

	Obbligatoria	Tipo
`object`	✔️ Sì	string
`type`	✔️ Sì	stringa enumerazione
`parameters`	❌ No	object
`key-fields`	❌ No	Matrice di stringhe

Esempio

In questo esempio viene illustrata la struttura più semplice per associare un'entità a una tabella di origine.

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

Ecco un exmaple di una relazione molti-a-molti.

Diagramma di una relazione molti-a-molti tra più tabelle di database

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

Todo Entità supportata da una stored procedure.
La type proprietà all'interno dell'origine è impostata su stored-procedure, che indica il tipo di oggetto di origine a cui viene mappata l'entità.
La object proprietà all'interno dell'origine è il nome della stored procedure nel database.

In questo esempio viene aggiunta anche la proprietà (facoltativa) mapping alla configurazione per l'entità "Todo". Specifica il modo in cui i campi nell'entità (Id, , Descriptione Completed) vengono mappati rispettivamente ai campi corrispondenti nell'origine dati sottostante o nei parametri della stored procedure (todo_id, todo_descriptionTitletodo_title, e , ).todo_completed Questo mapping garantisce che i dati corretti vengano passati tra l'entità e la stored procedure durante operazioni di creazione/aggiornamento.

Nell'esempio precedente viene usata la procedura SQL seguente.

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

@UserId: parametro obbligatorio senza un valore predefinito.
@Completed: parametro facoltativo. Se specificato, filtra i todos in base allo stato di completamento.
@CategoryName: parametro facoltativo. Se specificato, filtra il todos in base al nome della categoria.

Ecco un esempio per gli aggiornamenti usando una stored procedure.

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

In questo esempio viene impostato in modo esplicito il metodo HTTP per interagire con questa entità su POST come usare la proprietà del metodo.

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

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

Oggetto

OBBLIGATORIO: ✔️ Sì

Nome dell'oggetto database da usare.

Esempio

In questo esempio si object riferisce all'oggetto dbo.books nel database.

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

Tipo (entità)

OBBLIGATORIO: ✔️ Sì

La type proprietà identifica il tipo di oggetto di database dietro l'entità, che includono view, tablee stored-procedure. La type proprietà è obbligatoria e non esiste alcun valore predefinito.

Formato

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

Valori

Ecco un elenco di valori consentiti per questa proprietà:

	Descrizione
`table`	Rappresenta una tabella.
`stored-procedure`	Rappresenta una stored procedure.
`view`	Rappresenta una visualizzazione.

Esempio

In questo esempio, type indica che questa origine è una visualizzazione nel database. Questo valore influenza se sono necessari altri valori (ad esempio: key-fields).

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

Campi chiave

OBBLIGATORIO: ❌ No

L'impostazione {entity}.key-fields è necessaria per le entità supportate dalle visualizzazioni, quindi Generatore API dati sa come può identificare e restituire un singolo elemento, se necessario. Se type è impostato su view senza key-fields, il motore generatore API dati rifiuta l'avvio.

Importante

Questa proprietà è necessaria se il tipo di oggetto è un viewoggetto . Inoltre, questa proprietà è obbligatoria è il tipo di oggetto non è una table chiave primaria definita.

Format

{
  "entities" {
    "<entity-name>": {
      ...
      "type": "view",
      "key-fields": [ "<field-name>" ]
    }
  }
}

Esempi

In questo esempio viene usata la dbo.vw_category_details visualizzazione con category_id indicato come campo chiave.

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

Parametri

OBBLIGATORIO: ❌ No

L'impostazione {entity}.parameters è importante per le entità supportate dalle stored procedure, consentendo agli sviluppatori di specificare i parametri e i relativi valori predefiniti. I parametri garantiscono che, se alcuni parametri non vengono forniti all'interno di una richiesta HTTP, il sistema può tornare a questi valori predefiniti.

Importante

Questa proprietà è necessaria se il tipo di oggetto è un stored-procedureoggetto .

Format

{
  "entities" {
    "<entity-name>": {
      ...
      "type": "stored-procedure",
      "parameters": {
        "<parameter-name-1>" : "<default-value>",
        "<parameter-name-2>" : "<default-value>",
        "<parameter-name-3>" : "<default-value>"
      }
    }
  }
}

Esempi

In questo esempio viene richiamata la dbo.stp_get_bestselling_books stored procedure passando questi due parametri:

	Valore
`depth`	25
`list`	contoso-best-seller

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

Autorizzazioni

OBBLIGATORIO: ✔️ Sì

Questa sezione definisce chi può accedere all'entità correlata e quali azioni sono consentite. Le autorizzazioni sono definite in questa sezione in termini di ruoli. Le azioni vengono definite come operazioni CRUD tipiche, tra cui: create, read, updatee delete. La sezione permissions definisce chi (in termini di ruoli) può accedere all'entità correlata e a quali azioni. Le azioni sono le normali operazioni CRUD: create, , readupdate, delete.

Formato

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

Proprietà

	Obbligatoria	Tipo
`role`	✔️ Sì	string
`actions` (matrice di stringhe) o `actions` (matrice di oggetti)	✔️ Sì	matrice di oggetti o stringhe

Esempio

In questo esempio viene definito un ruolo anonimo con accesso a tutte le azioni possibili.

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

In alternativa, è possibile utilizzare un oggetto per definire l'azione con caratteri jolly.

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

È anche possibile combinare e associare azioni stringa e matrice di oggetti.

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

Ruolo anonimo Consentire agli utenti anonimi di leggere tutti i campi ad eccezione di secret-field. L'uso di "include": ["*"] con "exclude": ["secret-field"] nasconde secret-field efficacemente gli utenti anonimi consentendo l'accesso a tutti gli altri campi.

Ruolo autenticato Consentire agli utenti autenticati di leggere e aggiornare campi specifici, inclusi idin modo esplicito , titlee secret-field, ma quindi escludendo secret-field. Illustra l'inclusione esplicita e l'esclusione successiva di secret-field, che mostra la precedenza di exclude. Poiché secret-field è incluso ed escluso, finisce per essere inaccessibile, che corrisponde alla regola prevista di exclude avere la precedenza.

Ruolo autore Gli autori possono eseguire tutte le operazioni * su tutti i campi senza esclusioni. Il file indica "include": ["*"] che con una matrice vuota "exclude": [] concede l'accesso a tutti i campi, in quanto nessun campo viene escluso in modo esplicito.

Questa configurazione rappresenta l'impostazione predefinita se non viene specificato nulla.

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

È in effetti identico a:

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

Considerare anche la configurazione seguente:

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

La configurazione precedente specifica in modo efficace che nessun campo è incluso in modo esplicito ("include": [] è vuoto, a indicare che non sono consentiti campi) e che tutti i campi sono esclusi ("exclude": ["*"] usa il carattere jolly * per indicare tutti i campi).

Uso pratico: una configurazione di questo tipo potrebbe sembrare controintuitiva perché limita l'accesso a tutti i campi. Tuttavia, può essere usata in scenari in cui un ruolo può eseguire determinate azioni, ad esempio la creazione di un'entità, senza accedere ad alcun dato.

Lo stesso comportamento, ma con sintassi diversa, sarebbe:

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

L'installazione precedente tenta di specificare che devono essere inclusi solo i Id campi e Title , indicando anche che tutti i campi devono essere esclusi con il carattere jolly * nella exclude sezione. Un altro modo per esprimere la stessa logica sarebbe:

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

Data la regola generale che l'elenco exclude ha la precedenza sull'elenco include , specificando exclude: ["*"] in genere tutti i campi vengono esclusi, anche i campi elencati nella include sezione. Pertanto, a prima vista, questa configurazione potrebbe sembrare impedire che i campi siano accessibili, poiché la regola di esclusione è dominante.

Inverso: se lo scopo è concedere, accedere solo ai Id campi e Title , è più chiaro e più affidabile specificare solo tali campi nella include sezione e non usare exclude con un carattere jolly. In alternativa, è possibile modificare la logica delle autorizzazioni del sistema in modo da supportare in modo esplicito tali casi, presupponendo che si sia in controllo della progettazione. Ad esempio:

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

Ruolo

OBBLIGATORIO: ✔️ Sì

Stringa contenente il nome del ruolo a cui si applica l'autorizzazione definita. La role stringa contiene il nome del ruolo a cui si applica l'autorizzazione definita.

I ruoli impostano il contesto delle autorizzazioni in cui deve essere eseguita una richiesta. Per ogni entità definita nella configurazione di runtime, è possibile definire un set di ruoli e autorizzazioni associate che determinano come è possibile accedere all'entità negli endpoint REST e GraphQL. I ruoli non sono additivi. Per altre informazioni sui ruoli, vedere Autorizzazione.

Il generatore di API dati valuta le richieste nel contesto di un singolo ruolo:

Ruolo	Descrizione
`anonymous`	Non viene presentato alcun token di accesso
`authenticated`	Viene presentato un token di accesso valido
`<custom-role>`	Viene presentato un token di accesso valido e l'intestazione `X-MS-API-ROLE` HTTP è inclusa specificando un ruolo utente incluso anche nell'attestazione dei ruoli del token di accesso

Format

{
  "entities": {
    "entity-name": {
      "permissions": [
        {
          "role": "anonymous" | "authenticated" | "custom-role",
          "actions": [
            "create",
            "read",
            "update",
            "delete",
            "execute", // only when stored-procedure
            "*"
          ],
          "fields": {
            "include": ["field-name", "field-name"],
            "exclude": ["field-name", "field-name"]
          }
        }
      ]
    }
  }
}

Esempi

Questo esempio definisce un ruolo denominato reader con solo read le autorizzazioni per l'endpoint.

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

Azioni (matrice di stringhe)

OBBLIGATORIO: ✔️ Sì

Matrice di valori stringa che illustra in dettaglio le operazioni consentite per il ruolo associato. Per table gli oggetti di database e view , i ruoli possono essere configurati per usare qualsiasi combinazione di createazioni , read, updateo delete . Per le stored procedure, i ruoli possono avere solo l'azione execute . La actions matrice descrive in dettaglio le azioni consentite nel ruolo associato. Quando l'entità è una tabella o una vista, i ruoli possono essere configurati con una combinazione delle azioni: create, read, update, delete.

Azione	Operazione SQL
`*`	Carattere jolly, inclusa l'esecuzione
`create`	Inserire una o più righe
`read`	Selezionare una o più righe
`update`	Modificare una o più righe
`delete`	Eliminare una o più righe
`execute`	Esegue una stored procedure

Nota

Per le stored procedure, l'azione con caratteri jolly (*) si espande in un elenco che include solo l'azione execute . Per tabelle e viste, l'azione con caratteri jolly si espande in un elenco che include createle azioni , read, updatee delete .

Esempio

In questo esempio vengono concesse create le autorizzazioni e read al primo ruolo denominato contributor. Il secondo ruolo denominato auditor ha delete solo le autorizzazioni.

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

Di seguito è riportato un altro esempio.

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

Azioni (matrice di oggetti)

OBBLIGATORIO: ✔️ Sì

Nota

Formato

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

Proprietà

	Obbligatoria	Tipo
`action`	✔️ Sì	string
`fields`	❌ No	Matrice di stringhe
`policy`	❌ No	object

Esempio

In questo esempio viene concessa solo read l'autorizzazione al auditor ruolo. Il auditor ruolo può leggere solo dati specifici usando il predicato definito in policy.database. Il auditor ruolo è limitato anche nei campi che può essere letto usando la fields proprietà .

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

Azione

OBBLIGATORIO: ✔️ Sì

Specifica l'operazione specifica consentita nell'oggetto di database.

Valori

Ecco un elenco di valori consentiti per questa proprietà:

	Tabelle	Viste	Stored procedure	Descrizione
`create`	✔️ Sì	✔️ Sì	❌ No	Creare nuovi elementi
`read`	✔️ Sì	✔️ Sì	❌ No	Point read existing items (Lettura punti elementi esistenti)
`update`	✔️ Sì	✔️ Sì	❌ No	Aggiornare o sostituire gli elementi esistenti
`delete`	✔️ Sì	✔️ Sì	❌ No	Rimuovere gli elementi esistenti
`execute`	❌ No	❌ No	✔️ Sì	Eseguire operazioni a livello di codice

Esempio

Ecco un esempio in cui anonymous gli utenti possono accedere a execute una stored procedure specifica e read a una tabella specifica.

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

Campi

OBBLIGATORIO: ❌ No

Specifiche granulari per i campi specifici a cui è consentito l'accesso per l'oggetto di database. La configurazione del ruolo è un tipo di oggetto con due proprietà interne e includeexclude. Questi valori supportano la definizione granulare delle colonne di database (campi) a cui è consentito l'accesso nella sezione fields.

Format

{
  ...
  "entities": {
    "<entity-name>": {
      ...
      "permissions": [
        {
          {
            ...
            "fields": {
              "include": ["<field-name>"],
              "exclude": ["<field-name>"]
            }
          }
        }
      ]
    }
  }
}

Esempi

In questo esempio, il anonymous ruolo può leggere da tutti i campi tranne id, ma può usare tutti i campi durante la creazione di un elemento.

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

Includere ed escludere interagiscono. Il carattere jolly * nella include sezione indica tutti i campi. I campi annotati nella exclude sezione hanno la precedenza sui campi annotati nella include sezione . La definizione si traduce in includere tutti i campi ad eccezione del campo '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": []
            }
        }
    ]
}

Criteri

OBBLIGATORIO: ❌ No

La policy sezione, definita per action, definisce le regole di sicurezza a livello di elemento (criteri di database) che limitano i risultati restituiti da una richiesta. La sottosezione database indica l'espressione dei criteri di database valutata durante l'esecuzione della richiesta.

Formato

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

Proprietà

	Obbligatoria	Tipo
`database`	✔️ Sì	string

Descrizione

Criterio database : un'espressione simile a OData che viene convertita in un predicato di query valuta il database, inclusi operatori come eq, lte gt. Affinché i risultati vengano restituiti per una richiesta, il predicato di query della richiesta risolto da un criterio di database deve restituire true quando viene eseguito nel database.

Criteri elemento di esempio	Predicate
`@item.OwnerId eq 2000`	`WHERE Table.OwnerId = 2000`
`@item.OwnerId gt 2000`	`WHERE Table.OwnerId > 2000`
`@item.OwnerId lt 2000`	`WHERE Table.OwnerId < 2000`

È predicate un'espressione che restituisce TRUE o FALSE. I predicati vengono usati nelle condizioni di ricerca delle clausole WHERE e HAVING, nelle condizioni di join delle clausole FROM e in altri costrutti in cui è necessario un valore booleano. (Microsoft Learn Docs)

Criteri di database

È possibile usare due tipi di direttive per gestire i criteri di database durante la creazione di un'espressione di criteri di database:

Direttiva	Descrizione
`@claims`	Accedere a un'attestazione all'interno del token di accesso convalidato fornito nella richiesta
`@item`	Rappresenta un campo dell'entità per cui è definito il criterio del database

Nota

Quando è configurata l'autenticazione di App Web statiche di Azure (EasyAuth), è disponibile un numero limitato di tipi di attestazioni da usare nei criteri di database: identityProvider, userId, userDetailse userRoles. Per altre informazioni, vedere la documentazione relativa ai dati dell'entità client dell'app Web statica di Azure.

Ecco alcuni criteri di database di esempio:

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

Generatore API dati confronta il valore dell'attestazione UserId con il valore del campo OwnerIddel database . Il payload del risultato include solo i record che soddisfano sia i metadati della richiesta che l'espressione dei criteri di database.

Limitazioni

I criteri di database sono supportati per tabelle e viste. Le stored procedure non possono essere configurate con i criteri.

I criteri di database non impediscono l'esecuzione delle richieste all'interno del database. Questo comportamento è dovuto al fatto che vengono risolti come predicati nelle query generate passate al motore di database.

I criteri di database sono supportati solo per la creazione, la lettura, l'aggiornamento e l'eliminazioneactions. Poiché non è presente alcun predicato in una chiamata di stored procedure, non possono essere aggiunti.

Operatori simili a OData supportati

Operatore	Descrizione	Sintassi di esempio
`and`	AND logico	`"@item.status eq 'active' and @item.age gt 18"`
`or`	OR logico	`"@item.region eq 'US' or @item.region eq 'EU'"`
`eq`	Uguale a	`"@item.type eq 'employee'"`
`gt`	Maggiore di	`"@item.salary gt 50000"`
`lt`	Minore di	`"@item.experience lt 5"`

Per altre informazioni, vedere Operatori binari.

Operatore	Descrizione	Sintassi di esempio
`-`	Nega (numerico)	`"@item.balance lt -100"`
`not`	Negazione logica (NOT)	`"not @item.status eq 'inactive'"`

Per altre informazioni, vedere Operatori unari.

Restrizioni relative al nome del campo dell'entità

Regole: deve iniziare con una lettera o un carattere di sottolineatura (_), seguito da fino a 127 lettere, caratteri di sottolineatura (_) o cifre (0-9).
Impatto: i campi non aderendo a queste regole non possono essere usati direttamente nei criteri di database.
Soluzione: utilizzare la mappings sezione per creare alias per i campi che non soddisfano queste convenzioni di denominazione. I mapping assicurano che tutti i campi possano essere inclusi nelle espressioni dei criteri.

Uso di `mappings` campi non conformi

Se i nomi dei campi dell'entità non soddisfano le regole di sintassi OData o si vuole semplicemente eseguirne l'alias per altri motivi, è possibile definire gli alias nella mappings sezione della configurazione.

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

In questo esempio è field-1-name il nome del campo del database originale che non soddisfa le convenzioni di denominazione OData. La creazione di una mappa a field-1-name e field-1-alias consente di fare riferimento a questo campo nelle espressioni dei criteri di database senza problemi. Questo approccio non solo consente di aderire alle convenzioni di denominazione OData, ma migliora anche la chiarezza e l'accessibilità del modello di dati all'interno di endpoint GraphQL e RESTful.

Esempio

Prendere in considerazione un'entità denominata Employee all'interno di una configurazione dell'API dati che utilizza le direttive di attestazioni e elemento. Garantisce che l'accesso ai dati sia gestito in modo sicuro in base ai ruoli utente e alla proprietà dell'entità:

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

Definizione dell'entità: l'entità Employee è configurata per le interfacce REST e GraphQL, che indica che i dati possono essere sottoposti a query o manipolati tramite questi endpoint.

Configurazione origine: identifica l'oggetto HRUNITS nel database con employee NUM come campo chiave.

Mapping: gli alias vengono usati per eseguire il mapping employee NUMdi , employee Namee a EmployeeNameEmployeeId, e DepartmentIddepartment COID , rispettivamente, semplificando i nomi dei campi e offuscando potenzialmente i dettagli dello schema di database sensibili.

Applicazione criteri: la policy sezione applica un criterio di database usando un'espressione simile a OData. Questo criterio limita l'accesso ai dati agli utenti con il ruolo HR () o agli utenti le cui attestazioni corrispondono EmployeeId all'alias del campo nel database ().@claims.role eq 'HR'@claims.UserId eq @item.EmployeeIdUserId Garantisce che i dipendenti possano accedere solo ai propri record, a meno che non appartengano al reparto delle risorse umane. I criteri possono applicare la sicurezza a livello di riga in base alle condizioni dinamiche.

Database

OBBLIGATORIO: ✔️ Sì

Questa proprietà indica l'espressione di criteri di database valutata durante l'esecuzione della richiesta. La stringa di criteri è un'espressione OData tradotta in un predicato di query valutato dal database. Ad esempio, l'espressione @item.OwnerId eq 2000 di criteri viene tradotta nel predicato WHERE <schema>.<object-name>.OwnerId = 2000di query .

Nota

Un predicato è un'espressione che evalute in TRUE, FALSEo UNKNOWN. I predicati vengono usati in:

Condizione di ricerca delle WHERE clausole
Condizione di ricerca delle FROM clausole
Condizioni di join delle FROM clausole
Altri costrutti in cui è necessario un valore booleano.

Per altre informazioni, vedere predicati.

Per restituire i risultati per una richiesta, il predicato di query della richiesta risolto da un criterio di database deve essere valutato true durante l'esecuzione nel database.

È possibile usare due tipi di direttive per gestire i criteri di database quando si crea un'espressione di criteri di database:

	Descrizione
`@claims`	Accede a un'attestazione all'interno del token di accesso convalidato fornito nella richiesta
`@item`	Rappresenta un campo dell'entità per cui è definito il criterio di database

Nota

Un numero limitato di tipi di attestazione è disponibile per l'uso nei criteri di database quando è configurata l'autenticazione di App Web statiche di Azure (EasyAuth). Questi tipi di attestazione includono: identityProvider, userId, userDetailse userRoles. Per altre informazioni, vedere Dati dell'entità client app Web statiche di Azure.

Esempio

Ad esempio, un'espressione di criteri di base può valutare se un campo specifico è true all'interno della tabella. In questo esempio viene valutato se il soft_delete campo è false.

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

I predicati possono anche valutare sia claims i item tipi di direttiva che i tipi di direttiva. Questo esempio esegue il pull del campo dal token di accesso e lo confronta con il UserIdowner_id campo nella tabella di database di destinazione.

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

Limitazioni

I criteri di database sono supportati per tabelle e visualizzazioni. Le stored procedure non possono essere configurate con i criteri.
I criteri di database non possono essere usati per impedire l'esecuzione di una richiesta all'interno di un database. Questa limitazione è dovuta al fatto che i criteri di database vengono risolti come predicati di query nelle query di database generate. Il motore di database valuta infine queste query.
I criteri di database sono supportati solo per , actionscreateread, updatee delete.
La sintassi dell'espressione OData dei criteri di database supporta solo questi scenari.
- Operatori binari, inclusi, ma non limitati a; and, oreq, , gte lt. Per altre informazioni, vedere BinaryOperatorKind.
- Operatori unari, ad esempio i - (negati) e not gli operatori. Per altre informazioni, vedere UnaryOperatorKind.
I criteri di database hanno anche restrizioni correlate ai nomi dei campi.
- Nomi di campi di entità che iniziano con una lettera o un carattere di sottolineatura, seguiti dalla maggior parte di 127 lettere, caratteri di sottolineatura o cifre.
- Questo requisito è per specifica OData. Per altre informazioni, vedere OData Common Schema Definition Language.

Suggerimento

I campi che non sono conformi alle restrizioni indicate non possono essere a cui fare riferimento nei criteri di database. Come soluzione alternativa, configurare l'entità con una sezione mapping per assegnare alias conformi ai campi.

GraphQL (entità)

OBBLIGATORIO: ❌ No

Questo segmento fornisce l'integrazione di un'entità nello schema GraphQL. Consente agli sviluppatori di specificare o modificare valori predefiniti per l'entità in GraphQL. Questa configurazione garantisce che lo schema rifletta in modo accurato la struttura e le convenzioni di denominazione previste.

Formato

{
  "entities" {
    "<entity-name>": {
      ...
      "graphql": {
        "enabled": <true> (default) | <false>,
        "type": {
          "singular": "my-alternative-name",
          "plural": "my-alternative-name-pluralized"
        },
        "operation": "query" | "mutation" (default)
      },
    }
  }
}

{
  "entities": {
    "<string>": {
      "graphql": "<boolean>"
    }
  }
}

{
  "entities": {
    "<string>": {
      "graphql": {
        "enabled": "<boolean>",
        "type": "<string-or-object>",
        "operation": "<enum-string>"
      }
    }
  }
}

Proprietà

	Obbligatoria	Tipo
`enabled`	❌ No	boolean
`type`	❌ No	stringa o oggetto
`operation`	❌ No	stringa enumerazione

Esempio

Questi due esempi sono equivalenti a livello funzionale.

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

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

In questo esempio, l'entità definita è Book, che indica che si sta gestendo un set di dati correlati ai libri nel database. La configurazione per l'entità all'interno del Book segmento GraphQL offre una struttura chiara sulla modalità di rappresentazione e interazione con in uno schema GraphQL.

Proprietà abilitata: l'entità Book viene resa disponibile tramite GraphQL ("enabled": true), ovvero gli sviluppatori e gli utenti possono eseguire query o modificare i dati dei libri tramite le operazioni GraphQL.

Proprietà Type: l'entità è rappresentata con il nome singolare e il nome "Book""Books" plurale nello schema GraphQL. Questa distinzione garantisce che quando si esegue una query su un singolo libro o più libri, lo schema offre tipi denominati in modo intuitivo (Book per una singola voce, Books per un elenco), migliorando l'usabilità dell'API.

Proprietà Operation: l'operazione è impostata su "query", che indica che l'interazione primaria con l'entità Book tramite GraphQL deve essere eseguita una query (recupero) dei dati anziché modificarla (creazione, aggiornamento o eliminazione). Questa configurazione è allineata ai modelli di utilizzo tipici in cui i dati del libro sono più frequentemente letti rispetto alla modifica.

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

Tipo (entità GraphQL)

OBBLIGATORIO: ❌ No

Questa proprietà determina la convenzione di denominazione per un'entità all'interno dello schema GraphQL. Supporta sia i valori stringa scalari che i tipi di oggetto. Il valore dell'oggetto specifica le forme singolari e plurali. Questa proprietà fornisce un controllo granulare sulla leggibilità dello schema e sull'esperienza utente.

Formato

{
  "entities": {
    "<string>": {
      "graphql": {
        "type": "<string>"
      }
    }
  }
}

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

Proprietà

	Obbligatoria	Tipo
`singular`	❌ No	string
`plural`	❌ No	string

Esempio

Per un maggiore controllo sul tipo GraphQL, è possibile configurare la modalità di rappresentazione indipendente del nome singolare e plurale.

Se plural non è presente o omesso (ad esempio il valore scalare) Generatore API dati tenta di pluralizzare automaticamente il nome, seguendo le regole inglese per la pluralizzazione (ad esempio: https://engdic.org/singular-and-plural-noun-rules-definitions-examples)

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

È possibile specificare un nome di entità personalizzato usando il type parametro con un valore stringa. In questo esempio il motore differenzia automaticamente le varianti singolari e plurali di questo nome usando regole comuni in inglese per la pluralizzazione.

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

Se si sceglie di specificare i nomi in modo esplicito, usare le type.singular proprietà e type.plural . Questo esempio imposta in modo esplicito entrambi i nomi.

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

Entrambi gli esempi sono equivalenti a livello funzionale. Entrambi restituiscono lo stesso output JSON per una query GraphQL che usa il nome dell'entità bookauthors .

{
  bookauthors {
    items {
      first_name
      last_name
    }
  }
}

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

Operazione (entità GraphQL)

OBBLIGATORIO: ❌ No

Per le entità mappate alle stored procedure, la operation proprietà designa il tipo di operazione GraphQL (query o mutazione) in cui è accessibile la stored procedure. Questa impostazione consente l'organizzazione logica dello schema e l'adesione alle procedure consigliate graphQL, senza influire sulle funzionalità.

Nota

Un'entità viene specificata per essere una stored procedure impostando il valore della {entity}.type proprietà su stored-procedure. Nel caso di una stored procedure, viene creato automaticamente un nuovo tipo GraphQL executeXXX. Tuttavia, la operation proprietà consente allo sviluppatore di coerare la posizione di tale tipo in o mutationquery nelle parti dello schema. Questa proprietà consente l'hygene dello schema e non vi è alcun impatto funzionale indipendentemente dal operation valore.

Se mancante, il operation valore predefinito è mutation.

Formato

{
  "entities": {
    "<string>": {
      "graphql": {
        "operation": "<string-enum>"
      }
    }
  }
}

Valori

Ecco un elenco di valori consentiti per questa proprietà:

	Descrizione
`query`	La stored procedure sottostante viene esposta come query
`mutation`	La stored procedure sottostante viene esposta come mutazione

Esempio

Quando operation è mutation, lo schema GraphQL è simile al seguente:

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

Quando operation è query, lo schema GraphQL è simile al seguente:

Lo schema GraphQL è simile al seguente:

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

Nota

La operation proprietà riguarda solo il posizionamento dell'operazione nello schema GraphQL, non modifica il comportamento dell'operazione.

Abilitato (entità GraphQL)

OBBLIGATORIO: ❌ No

Abilita o disabilita l'endpoint GraphQL. Controlla se un'entità è disponibile tramite endpoint GraphQL. L'attivazione della enabled proprietà consente agli sviluppatori di esporre in modo selettivo le entità dallo schema GraphQL.

Formato

{
  "entities" {
    "<entity-name>": {
      ...
      "graphql": {
        ...
        "enabled": true | false
      }
    }
  }
}

REST (entità)

OBBLIGATORIO: ❌ No

La rest sezione del file di configurazione è dedicata all'ottimizzazione degli endpoint RESTful per ogni entità di database. Questa funzionalità di personalizzazione garantisce che l'API REST esposta corrisponda a requisiti specifici, migliorando sia le funzionalità di utilità che di integrazione. Risolve potenziali mancate corrispondenze tra le impostazioni posticipate predefinite e i comportamenti degli endpoint desiderati.

Formato

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "enabled": <true> (default) | <false>,
        "path": "/entity-path", (default <entity-name>)
        "methods": ["GET", "POST" (default)]
      },
      ...
    }
  }
}

Proprietà

	Obbligatoria	Tipo
`enabled`	✔️ Sì	boolean
`path`	❌ No	string
`methods`	❌ No	Matrice di stringhe

Esempio

Questi due esempi sono equivalenti a livello funzionale.

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

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

Ecco un altro esempio di configurazione REST per un'entità.

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

Abilitato (entità REST)

OBBLIGATORIO: ❌ No

Questa proprietà funge da interruttore per la visibilità delle entità all'interno dell'API REST. Impostando la proprietà su true o false, gli sviluppatori possono controllare l'accesso enabled a entità specifiche, abilitando un'area API personalizzata allineata ai requisiti di sicurezza e funzionalità dell'applicazione.

Se omesso o mancante, il valore predefinito di enabled è true.

Formato

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

Percorso (entità REST)

OBBLIGATORIO: ❌ No

La path proprietà specifica il segmento URI usato per accedere a un'entità tramite l'API REST. Questa personalizzazione consente percorsi endpoint più descrittivi o semplificati oltre il nome predefinito dell'entità, migliorando la navigabilità dell'API e l'integrazione lato client. Per impostazione predefinita, il percorso è /<entity-name>.

Format

{
  "entities" {
    "<entity-name>": {
      ...
      "rest": {
        ...
        "path": "/entity-path"
      }
    }
  }
}

Esempi

In questo esempio viene esposta l'entità usando l'endpoint Author/auth .

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

Metodi (entità REST)

OBBLIGATORIO: ❌ No

Applicabile in particolare alle stored procedure, la methods proprietà definisce i verbi HTTP ,ad esempio GET, POST, la procedura può rispondere. I metodi consentono un controllo preciso sulla modalità di esposizione delle stored procedure tramite l'API REST, garantendo la compatibilità con gli standard RESTful e le aspettative dei client. In questa sezione viene sottolineato l'impegno della piattaforma per la flessibilità e il controllo dello sviluppatore, consentendo una progettazione api precisa e intuitiva personalizzata in base alle esigenze specifiche di ogni applicazione.

Se omesso o mancante, il methods valore predefinito è POST.

Formato

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

Valori

Ecco un elenco di valori consentiti per questa proprietà:

	Descrizione
`get`	Espone le richieste HTTP GET
`post`	Espone richieste HTTP POST

Esempio

Questo esempio indica al motore che la stp_get_bestselling_authors stored procedure supporta HTTP GET solo le azioni.

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

Mapping (entità)

OBBLIGATORIO: ❌ No

La mappings sezione consente di configurare gli alias o i nomi esposti per i campi dell'oggetto di database. I nomi esposti configurati si applicano sia agli endpoint GraphQL che REST.

Importante

Per le entità con GraphQL abilitato, il nome esposto configurato deve soddisfare i requisiti di denominazione GraphQL. Per altre informazioni, vedere Specifica dei nomi GraphQL.

Format

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

Esempi

In questo esempio il sku_title campo dell'oggetto dbo.magazines di database viene esposto usando il nome title. Analogamente, il sku_status campo viene esposto come status in endpoint REST e GraphQL.

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

Ecco un altro esempio di mapping.

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

Mapping: l'oggetto mappings collega i campi di database (, , AuthorName) a nomi più intuitivi o standardizzati (BookIDid, BookTitletitle, author) usati esternamente. Questo aliasing serve diversi scopi:

Chiarezza e coerenza: consente l'uso di nomi chiari e coerenti nell'API, indipendentemente dallo schema del database sottostante. Ad esempio, BookID nel database viene rappresentato come id nell'API, rendendolo più intuitivo per gli sviluppatori che interagiscono con l'endpoint.
Conformità GraphQL: fornendo un meccanismo ai nomi dei campi alias, garantisce che i nomi esposti tramite l'interfaccia GraphQL siano conformi ai requisiti di denominazione GraphQL. L'attenzione ai nomi è importante perché GraphQL ha regole rigide sui nomi (ad esempio, senza spazi, deve iniziare con una lettera o un carattere di sottolineatura e così via). Ad esempio, se un nome di campo del database non soddisfa questi criteri, può essere aliasato a un nome conforme tramite mapping.
Flessibilità: questo aliasing aggiunge un livello di astrazione tra lo schema del database e l'API, consentendo le modifiche in una senza richiedere modifiche nell'altro. Ad esempio, una modifica del nome del campo nel database non richiede un aggiornamento alla documentazione dell'API o al codice lato client se il mapping rimane coerente.
Nome campo Offuscamento: il mapping consente l'offuscamento dei nomi dei campi, che consente di impedire agli utenti non autorizzati di dedurre informazioni sensibili sullo schema del database o sulla natura dei dati archiviati.
Protezione delle informazioni proprietarie: rinominando i campi, è anche possibile proteggere i nomi proprietari o la logica di business che potrebbero essere rilevati tramite i nomi di campo originali del database.

Relazioni (entità)

OBBLIGATORIO: ❌ No

Questa sezione esegue il mapping di un set di definizioni di relazione che mappano la modalità di correlazione delle entità ad altre entità esposte. Queste definizioni di relazione possono anche includere dettagli sugli oggetti di database sottostanti usati per supportare e applicare le relazioni. Gli oggetti definiti in questa sezione vengono esposti come campi GraphQL nell'entità correlata. Per altre informazioni, vedere Suddivisione delle relazioni tra generatori API dati.

Nota

Le relazioni sono rilevanti solo per le query GraphQL. Gli endpoint REST accedono solo a un'entità alla volta e non possono restituire tipi annidati.

La relationships sezione descrive come le entità interagiscono all'interno del generatore API dati, le associazioni dettagliate e il potenziale supporto del database per queste relazioni. La relationship-name proprietà per ogni relazione è necessaria e deve essere univoca in tutte le relazioni per una determinata entità. I nomi personalizzati garantiscono connessioni chiare, identificabili e mantengono l'integrità dello schema GraphQL generato da queste configurazioni.

Relazione	Cardinalità	Esempio
uno-a-molti	`many`	Un'entità categoria può essere correlata a molte entità todo
molti-a-uno	`one`	Molte entità todo possono essere correlate a un'entità di categoria
molti-a-molti	`many`	Un'entità todo può essere correlata a molte entità utente e un'entità utente può essere correlata a molte entità todo

Formato

{{
  "entities": {
    "entity-name": {
      ...
      "relationships": {
        "relationship-name": {
          "cardinality": "one" | "many",
          "target.entity": "target-entity-name",
          "source.fields": ["source-field-name"],
          "target.fields": ["target-field-name"],
          "linking.object": "linking-object-name",
          "linking.source.fields": ["linking-source-field-name"],
          "linking.target.fields": ["linking-target-field-name"]
        }
      }
    }
  }
}

Proprietà

	Obbligatoria	Tipo
`cardinality`	✔️ Sì	stringa enumerazione
`target.entity`	✔️ Sì	string
`source.fields`	❌ No	Matrice di stringhe
`target.fields`	❌ No	Matrice di stringhe
`linking.<object-or-entity>`	❌ No	string
`linking.source.fields`	❌ No	Matrice di stringhe
`linking.target.fields`	❌ No	Matrice di stringhe

Esempio

Quando si considerano le relazioni, è preferibile confrontare le differenze tra relazioni uno-a-molti, molti-a-uno e molte-a-molti.

Uno-a-molti

Si consideri innanzitutto un esempio di una relazione con l'entità esposta Category con una relazione uno-a-molti con l'entità Book . In questo caso, la cardinalità è impostata su many. Ogni Category entità può avere più entità correlate Book mentre ogni Book entità è associata solo a una singola Category entità.

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

In questo esempio l'elenco source.fields specifica il id campo dell'entità di origine (Category). Questo campo viene usato per connettersi all'elemento correlato nell'entità target . Al contrario, l'elenco target.fields specifica il category_id campo dell'entità di destinazione (Book). Questo campo viene usato per connettersi all'elemento correlato nell'entità source .

Con questa relazione definita, lo schema GraphQL risultante dovrebbe essere simile a questo esempio.

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

Molti-a-uno

Considerare quindi molti-a-uno che imposta la cardinalità su one. L'entità esposta Book può avere una singola entità correlata Category . L'entità Category può avere più entità correlate Book .

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

In questo caso, l'elenco source.fields specifica che il category_id campo dell'entità di origine () fa riferimento al id campo dell'entità di destinazione correlata (BookCategory). Inversamente, l'elenco target.fields specifica la relazione inversa. Con questa relazione, lo schema GraphQL risultante include ora un mapping da Libri a Categorie.

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

Molti-a-molti

Infine, viene definita una relazione molti-a-molti con una cardinalità di many e più metadati per definire quali oggetti di database vengono usati per creare la relazione nel database di backup. In questo caso, l'entità può avere più entità e al contrario l'entità BookAuthor può avere più AuthorBook entità.

{
  "entities": {
    "Book": {
      "relationships": {
        ...,
        "books_authors": {
          "cardinality": "many",
          "target.entity": "Author",
          "source.fields": [ "id" ],
          "target.fields": [ "id" ],
          "linking.object": "dbo.books_authors",
          "linking.source.fields": [ "book_id" ],
          "linking.target.fields": [ "author_id" ]
        }
      },
      "Category": {
        ...
      },
      "Author": {
        ...
      }
    }
  }
}

In questo esempio, e source.fieldstarget.fields entrambi indicano che la tabella delle relazioni usa l'identificatore primario () delle entità di origine (idBook) e di destinazione (Author). Il linking.object campo specifica che la relazione è definita nell'oggetto dbo.books_authors database. linking.source.fields Specifica inoltre che il book_id campo dell'oggetto di collegamento fa riferimento id al campo dell'entità Book e linking.target.fields specifica che il author_id campo dell'oggetto di collegamento fa riferimento al id campo dell'entitàAuthor.

Questo esempio può essere descritto usando uno schema GraphQL simile a questo esempio.

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

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

Cardinalità

OBBLIGATORIO: ✔️ Sì

Specifica se l'entità di origine corrente è correlata solo a una singola istanza dell'entità di destinazione o a più.

Valori

Ecco un elenco di valori consentiti per questa proprietà:

	Descrizione
`one`	L'origine si riferisce solo a un record dalla destinazione
`many`	L'origine può essere correlata a record zero-a-molti dalla destinazione

Entità di destinazione

OBBLIGATORIO: ✔️ Sì

Nome dell'entità definita altrove nella configurazione di destinazione della relazione.

Campi di origine

OBBLIGATORIO: ❌ No

Parametro facoltativo per definire il campo usato per il mapping nell'entità di origine usata per connettersi all'elemento correlato nell'entità di destinazione.

Suggerimento

Questo campo non è obbligatorio se è presente una restrizione della chiave esterna nel database tra i due oggetti di database che possono essere usati per dedurre automaticamente la relazione.

Campi di destinazione

OBBLIGATORIO: ❌ No

Parametro facoltativo per definire il campo usato per il mapping nell'entità di destinazione usata per connettersi all'elemento correlato nell'entità di origine.

Suggerimento

Questo campo non è obbligatorio se è presente una restrizione della chiave esterna nel database tra i due oggetti di database che possono essere usati per dedurre automaticamente la relazione.

Collegamento di oggetti o entità

OBBLIGATORIO: ❌ No

Per relazioni molti-a-molti, il nome dell'oggetto del database o dell'entità che contiene i dati necessari per definire una relazione tra due altre entità.

Collegamento di campi di origine

OBBLIGATORIO: ❌ No

Nome dell'oggetto di database o del campo di entità correlato all'entità di origine.

Collegamento di campi di destinazione

OBBLIGATORIO: ❌ No

Nome dell'oggetto di database o del campo di entità correlato all'entità di destinazione.

Cache (entità)

OBBLIGATORIO: ❌ No

Abilita e configura la memorizzazione nella cache per l'entità.

Formato

{
  "entities": {
    "<string>": {
      "cache": {
        "enabled": <true> | <false> (default),
        "ttl-seconds": (integer, default: 5)
      }
    }
  }
}

Proprietà

	Obbligatoria	Type	Predefinito
`enabled`	❌ No	boolean	`false`
`ttl-seconds`	❌ No	numero intero	`5`

Esempio

In questo esempio la cache è abilitata e gli elementi scadono dopo 30 secondi.

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

Abilitato (entità cache)

OBBLIGATORIO: ❌ No

Abilita la memorizzazione nella cache per l'entità. Il valore predefinito è false.

Format

{
  "entities": {
    "<string>": {
      "cache": {
        "enabled": "<boolean>"
      }
    }
  }
}

Esempi

In questo esempio la cache è disabilitata.

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

TTL in secondi (entità cache)

OBBLIGATORIO: ❌ No

Format

{
  "entities": {
    "<string>": {
      "cache": {
        "ttl-seconds": "<integer>"
      }
    }
  }
}

Esempi

In questo esempio la cache è abilitata e gli elementi scadono dopo 15 secondi.

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

Condividi tramite

Informazioni di riferimento sullo schema di configurazione di Generatore API dati

Panoramica della sintassi

Proprietà di primo livello

Configurazione di esempio

Ambienti

Proprietà di configurazione

SCHEMA

Format

Esempi

Origine dati

Formato

Proprietà

Tipo di database

Formato

Valori

Stringa di connessione

Formato

Resilienza delle connessioni

Azure SQL e SQL Server

Esempio

Opzioni

Format

Esempi

File dell'origine dati

Formato

Considerazioni sul file di configurazione

Problemi noti

Esempio

Runtime

Formato

Proprietà

Esempio

GraphQL (runtime)

Formato

Proprietà

Abilitato (runtime GraphQL)

Format

Esempi

Percorso (runtime GraphQL)

Format

Esempi

Consenti introspezione (runtime GraphQL)

Format

Esempi

Più mutazioni (runtime GraphQL)

Formato

Proprietà

Più mutazioni : creare (runtime GraphQL)

Formato

Proprietà

Esempio

REST (runtime)

Formato

Proprietà

Abilitato (runtime REST)

Format

Esempi

Percorso (runtime REST)

Format

Esempi

Corpo della richiesta strict (runtime REST)

Format

Esempi

Host (runtime)

Formato

Proprietà

Esempio

Modalità (runtime host)

Formato

Valori

CORS (runtime host)

Formato

Proprietà

Consenti credenziali (runtime host)

Formato

Origini (runtime host)

Format

Esempi

Autenticazione (runtime host)