Entities

Impostazioni di configurazione per le entità di database.

Health

Property	Description
`entities.entity-name.health.enabled`	Abilita i controlli di integrità per l'entità (endpoint REST e GraphQL)
`entities.entity-name.health.first`	Numero di righe restituite nella query di controllo integrità (intervallo: 1-500)
`entities.entity-name.health.threshold-ms`	Durata massima in millisecondi per la query di controllo integrità (min: 1)

Source

Property	Description
`entities.entity-name.source.type`	Tipo di oggetto: `table`, `view`o `stored-procedure`
`entities.entity-name.source.object`	Nome dell'oggetto di database
`entities.entity-name.source.parameters`	Parametri per stored procedure o funzioni
`entities.entity-name.source.key-fields`	Elenco di campi chiave primaria per le visualizzazioni
`entities.entity-name.mappings`	Esegue il mapping dei nomi dei campi dell'API alle colonne di database

REST

Property	Description
`entities.entity-name.rest.enabled`	Abilita REST per questa entità
`entities.entity-name.rest.path`	Route personalizzata per l'endpoint REST
`entities.entity-name.rest.methods`	Metodi REST consentiti: `get`, `post`, `put`, `patch`, `delete`

GraphQL

Property	Description
`entities.entity-name.graphql.type`	Nome del tipo o oggetto con `singular` e `plural`
`entities.entity-name.graphql.operation`	Tipo di operazione: `query` o `mutation`
`entities.entity-name.graphql.enabled`	Abilita GraphQL per questa entità

Permissions

Property	Description
`entities.entity-name.permissions[].role`	Stringa del nome del ruolo
`entities.entity-name.permissions[].actions`	Uno o più di: `create`, `read`, `update`, `delete`, `execute`

Relationships

Property	Description
`entities.entity-name.relationships.relationship-name.cardinality`	`one` o `many`
`entities.entity-name.relationships.relationship-name.target.entity`	Nome dell'entità di destinazione
`entities.entity-name.relationships.relationship-name.source.fields`	Campi di questa entità usata nella relazione
`entities.entity-name.relationships.relationship-name.target.fields`	Campi dall'entità di destinazione
`entities.entity-name.relationships.relationship-name.linking.object`	Oggetto Join utilizzato per le relazioni molti-a-molti
`entities.entity-name.relationships.relationship-name.linking.source.fields`	Campi dell'entità di origine usati nel join
`entities.entity-name.relationships.relationship-name.linking.target.fields`	Campi dell'entità di destinazione usati nel join

Cache

Property	Description
`entities.entity-name.cache.enabled`	Abilita la memorizzazione nella cache delle risposte per l'entità
`entities.entity-name.cache.ttl-seconds`	Durata della cache in secondi

Panoramica del formato

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

Origine (entità entity-name)

Parent	Property	Type	Required	Default
`entities.{entity-name}`	`source`	object	✔️ Sì	None

Dettagli dell'origine del database dell'entità.

Proprietà annidate

Parent	Property	Type	Required	Default
`entities.{entity-name}.source`	`object`	string	✔️ Sì	None
`entities.{entity-name}.source`	`type`	enum (`table`, `view`, `stored-procedure`)	✔️ Sì	None
`entities.{entity-name}.source`	`key-fields`	matrice di stringhe	✔️ Sì*	None
`entities.{entity-name}.source`	`parameters`	object	✔️ Sì**	None

key-fields è obbligatorio solo quando type è view. Il valore rappresenta le chiavi primarie.

** parameters è obbligatorio solo quando type è stored-procedure e solo per i parametri con valori predefiniti. Il tipo di dati del parametro viene dedotto. I parametri senza un valore predefinito possono essere omessi.

Tip

Se l'oggetto appartiene allo schema dbo, specificare lo schema è facoltativo. Inoltre, le parentesi quadre intorno ai nomi degli oggetti (ad esempio, dbo.Users vs. [dbo].[Users]) possono essere usate quando necessario.

Format

{
  "entities": {
    "{entity-name}": {
      "source": {
        "object": <string>,
        "type": <"view" | "stored-procedure" | "table">,
        "key-fields": [ <string> ], // primary keys of the view
        "parameters": { // only for option stored-procedure parameters
          "<parameter-name-1>": <default-value>
          "<parameter-name-2>": <default-value>
        }
      }
    }
  }
}

Autorizzazioni (entità entity-name)

Parent	Property	Type	Required	Default
`entities.permissions`	`role`	string	✔️ Sì	None

Stringa che specifica il nome del ruolo a cui si applicano le autorizzazioni.

Format

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "role": <"anonymous" | "authenticated" | "custom-role">
        }
      ]
    }
  }
}

Example

Questo esempio definisce il ruolo custom-role con solo read le autorizzazioni per l'entità User .

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

Esempi di utilizzo

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

using System.Net.Http;
using System.Net.Http.Headers;

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<your_access_token>");
client.DefaultRequestHeaders.Add("X-MS-API-ROLE", "custom-role");
var response = await client.GetAsync("https://localhost:5001/api/User");
// To read the response content:
// var content = await response.Content.ReadAsStringAsync();

const response = await fetch('https://localhost:5001/api/User', {
  headers: {
    "Authorization": "Bearer <your_access_token>",
    "X-MS-API-ROLE": "custom-role"
  }
});
// To read the response body as JSON:
// const data = await response.json();

import requests

headers = {
    "Authorization": "Bearer <your_access_token>",
    "X-MS-API-ROLE": "custom-role"
}
response = requests.get('https://localhost:5001/api/User', headers=headers)
# To print the response JSON:
print(response.json())

Azioni (entità entity-name per le autorizzazioni di matrice di stringhe)

Parent	Property	Type	Required	Default
`entities.permissions`	`actions`	oneOf [string, array]	✔️ Sì	None

Matrice di stringhe che descrive in dettaglio le operazioni consentite per il ruolo associato.

Action	Operazione SQL
`*`	Tutte le azioni
`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

* Attualmente in GraphQL sono supportate più operazioni.

Note

Per le stored procedure, l'azione con caratteri jolly (*) si espande solo all'azione execute. Per tabelle e viste, si espande fino a create, read, updatee delete.

Format

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "actions": [ <string> ]
        }
      ]
    }
  }
}

Example

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "actions": [ "*" ] // equivalent to create, read, update, delete
        }
      ]
    }
  }
}

Formato alternativo (solo stringa, quando `type=stored-procedure`)

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "actions": <string>
        }
      ]
    }
  }
}

Example

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "actions": "*" // equivalent to execute
        }
      ]
    }
  }
}

Azioni (entità entity-name delle autorizzazioni per le matrici di oggetti)

Parent	Property	Type	Required	Default
`entities.{entity-name}.permissions`	`actions`	matrice di stringhe	✔️ Sì	None

Matrice di oggetti che descrive in dettaglio le operazioni consentite per il ruolo associato.

Note

Per le stored procedure, l'azione con caratteri jolly (*) si espande solo execute. Per tabelle/viste, si espande fino a create, read, updatee delete.

Proprietà annidate

Parent	Property	Type	Required	Default
`entities.{entity-name}.permissions.actions[]`	`action`	string	✔️ Sì	None
`entities.{entity-name}.permissions.actions[]`	`fields`	object	❌ No	None
`entities.{entity-name}.permissions.actions[]`	`policy`	object	❌ No	None
`entities.{entity-name}.permissions.actions[].policy`	`database`	string	✔️ Sì	None

Format

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

Example

In questo modo si concede read l'autorizzazione a per l'entitàauditor, con restrizioni relative al campo e ai User criteri.

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

Note sui criteri

I criteri supportano operatori OData come eq.
I criteri supportano predicati composti usando and e or.
Supportato solo per le azioni: create, readupdate, e delete. (Non execute)
I criteri filtrano i risultati, ma non impediscono l'esecuzione di query nel database.
Il campo deve usare l'alias del campo, se mappato.

Tipo (entità GraphQL entity-name)

Parent	Property	Type	Required	Default
`entities.{entity-name}.graphql`	`type`	object	❌ No	{entity-name}

Imposta la convenzione di denominazione per un'entità all'interno dello schema GraphQL.

Format

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

Proprietà annidate

Parent	Property	Required	Type	Default
`entities.{entity-name}.graphql.type`	`singular`	❌ No	string	None
`entities.{entity-name}.graphql.type`	`plural`	❌ No	string	N/D (per impostazione predefinita è un valore singolare)

Example

Configuration

{
  "entities": {
    "User": {
      "graphql": {
        "type": {
          "singular": "User",
          "plural": "Users"
        }
      }
    }
  }
}

Query GraphQL

{
  Users {
    items {
      id
      name
      age
      isAdmin
    }
  }
}

Risposta graphQL

{
  "data": {
    "Users": {
      "items": [
        {
          "id": 1,
          "name": "Alice",
          "age": 30,
          "isAdmin": true
        },
        {
          "id": 2,
          "name": "Bob",
          "age": 25,
          "isAdmin": false
        }
        // ...
      ]
    }
  }
}

Operazione (entità GraphQL entity-name)

Parent	Property	Type	Required	Default
`entities.{entity-name}.graphql`	`operation`	stringa enumerazione	❌ No	mutation

Indica se l'operazione stored-procedure viene visualizzata in Query o Mutation.

Note

Quando {entity-name}.type è impostato su stored-procedure, viene creato automaticamente un nuovo tipo executeXXX GraphQL. Questa operation proprietà controlla la posizione di questo tipo nello schema GraphQL. Non c'è alcun impatto funzionale, solo l'igiene dello schema.

Format

{
  "entities": {
    "{entity-name}": {
      "graphql": {
        "operation": "query" | "mutation"
      }
    }
  }
}

Esempio: operazione

Quando operation è impostato su query

type Query {
  executeGetUserDetails(userId: Int!): GetUserDetailsResponse
}

Quando operation è impostato su mutation

type Mutation {
  executeGetUserDetails(userId: Int!): GetUserDetailsResponse
}

Abilitata (entità graphQL entity-name)

Parent	Property	Type	Required	Default
`entities.{entity-name}.graphql`	`enabled`	boolean	❌ No	True

Consente agli sviluppatori di includere in modo selettivo le entità nello schema GraphQL.

Format

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

REST (entità entity-name)

Parent	Property	Type	Required	Default
`entities.{entity-name}.rest`	`enabled`	boolean	❌ No	True
`entities.rest`	`path`	string	❌ No	`/{entity-name}`
`entities.{entity-name}.rest`	`methods`	matrice di stringhe	❌ No*	`POST`

* La methods proprietà è solo per stored-procedure gli endpoint.

Format

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

Mapping (entità entity-name)

Parent	Property	Type	Required	Default
`entities.{entity-name}`	`mappings`	object	❌ No	None

Abilita alias personalizzati o nomi esposti per i campi oggetto di database.

Important

Per le entità con GraphQL abilitato, il nome esposto configurato deve soddisfare i requisiti del nome GraphQL.

Format

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

Examples

Tabella di database

CREATE TABLE Books
(
  id INT,
  sku_title VARCHAR(50),
  sku_status VARCHAR(50),
)

Configuration

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

Cache (entità entity-name)

Parent	Property	Type	Required	Default
`entities.{entity-name}`	`cache`	object	❌ No	None

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

Proprietà annidate

Parent	Property	Type	Required	Default
`entities.{entity-name}.cache`	`enabled`	boolean	❌ No	False
`entities.{entity-name}.cache`	`ttl-seconds`	integer	❌ No	-

Format

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

Note

Se non specificato, ttl-seconds eredita il valore globale impostato in runtime.cache.

Example

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

Relazioni (entità entity-name)

Parent	Property	Type	Required	Default
`entities.{entity-name}`	`relationships`	object	❌ No	None

Configura il modo in cui le entità GraphQL sono correlate ad altre entità esposte. Per altre informazioni, vedere suddivisione delle relazioni del generatore di API dati.

Note

La relationship-name proprietà per ogni relazione deve essere univoca in tutte le relazioni per tale entità.

Proprietà annidate

Queste proprietà vengono usate in combinazioni diverse a seconda della cardinalità della relazione.

Parent	Property	Type	Required	Default
`entities.{entity-name}.relationships`	`cardinality`	string	✔️ Sì	None
`entities.{entity-name}.relationships`	`target.entity`	string	✔️ Sì	None
`entities.{entity-name}.relationships`	`target.fields`	matrice di stringhe	❌ No	None
`entities.{entity-name}.relationships`	`source.fields`	matrice di stringhe	❌ No	None
`entities.{entity-name}.relationships`	`linking.object`	string	❌ No	None
`entities.{entity-name}.relationships`	`linking.source.fields`	matrice di stringhe	❌ No	None
`entities.{entity-name}.relationships`	`linking.target.fields`	matrice di stringhe	❌ No	None

Format

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

Relationship	Cardinality	Example
one-to-many	`many`	Un'entità categoria può essere correlata a molte entità todo
many-to-one	`one`	Molte entità todo possono essere correlate a un'entità di categoria
many-to-many	`many`	Un'entità todo può essere correlata a molte entità utente e un'entità utente può essere correlata a molte entità todo

Esempio: cardinalità uno-a-uno

Ognuno Profile è correlato esattamente a un Useroggetto e ognuno User ha esattamente uno correlato Profile.

{
  "entities": {
    "User": {
      "relationships": {
        "user_profile": {
          "cardinality": "one",
          "target.entity": "Profile",
          "source.fields": [ "id" ],
          "target.fields": [ "user_id" ]
        }
      }
    },
    "Profile": {
      ...
    }
  }
}

Schema GraphQL

type User
{
  id: Int!
  ...
  profile: Profile
}

Command-line

dab update User \
  --relationship profile \
  --target.entity Profile \
  --cardinality one \
  --relationship.fields "id:user_id"

Esempio: cardinalità uno-a-molti

Un Category oggetto può avere una o più entità correlate Book , mentre ognuna Book può avere un oggetto correlato Category.

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

Schema GraphQL

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

Riga di comando

dab update Category \
  --relationship category_books \
  --target.entity Book \
  --cardinality many \
  --relationship.fields "id:category_id"

Esempio: cardinalità molti-a-uno

Molte Book entità possono avere uno correlato Category, mentre un Category può avere una o più voci correlate Book .

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

Schema GraphQL

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

Riga di comando

dab update Book \
  --relationship books_category \
  --target.entity "Category" \
  --cardinality one \
  --relationship.fields "category_id:id"

Esempio: cardinalità molti-a-molti

Molte Book entità possono avere molte entità correlate Author , mentre molte Author entità possono avere molte voci correlate Book .

Note

Questa relazione è possibile con una terza tabella, dbo.books_authors, a cui si fa riferimento come oggetto di collegamento.

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

Schema GraphQL

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

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

Riga di comando

dab update Book \
  --relationship books_authors \
  --target.entity "Author" \
  --cardinality many \
  --relationship.fields "id:id" \
  --linking.object "dbo.books_authors" \
  --linking.source.fields "book_id" \
  --linking.target.fields "author_id"

Integrità (entità entity-name)

Parent	Property	Type	Required	Default
`entities.{entity-name}`	`health`	object	❌ No	None

Abilita e configura i controlli di integrità per l'entità.

Proprietà annidate

Parent	Property	Type	Required	Default
`entities.{entity-name}.health`	`enabled`	boolean	❌ No	`true`
`entities.{entity-name}.health`	`first`	integer	❌ No	`100`
`entities.{entity-name}.health`	`threshold-ms`	integer	❌ No	`1000`

Example

{
  "entities": {
    "Book": {
      "health": {
        "enabled": true,
        "first": 3,
        "threshold-ms": 500
      }
    }
  }
}

Note

Il first valore deve essere minore o uguale all'impostazione runtime.pagination.max-page-size . I valori più piccoli consentono di completare i controlli di integrità più velocemente.

Important

Le stored procedure vengono escluse automaticamente dai controlli di integrità delle entità perché richiedono parametri e potrebbero non essere deterministici.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-09-24

Condividi tramite

Entities

Health

Source

REST

GraphQL

Permissions

Relationships

Cache

Panoramica del formato

Origine (entità entity-name)

Proprietà annidate

Format

Autorizzazioni (entità entity-name)

Format

Example

Esempi di utilizzo

Azioni (entità entity-name per le autorizzazioni di matrice di stringhe)

Format

Example

Formato alternativo (solo stringa, quando type=stored-procedure)

Example

Azioni (entità entity-name delle autorizzazioni per le matrici di oggetti)

Proprietà annidate

Format

Example

Note sui criteri

Tipo (entità GraphQL entity-name)

Format

Proprietà annidate

Example

Operazione (entità GraphQL entity-name)

Format

Esempio: operazione

Abilitata (entità graphQL entity-name)

Format

REST (entità entity-name)

Format

Mapping (entità entity-name)

Format

Examples

Cache (entità entity-name)

Proprietà annidate

Format

Example

Relazioni (entità entity-name)

Proprietà annidate

Format

Esempio: cardinalità uno-a-uno

Esempio: cardinalità uno-a-molti

Esempio: cardinalità molti-a-uno

Esempio: cardinalità molti-a-molti

Integrità (entità entity-name)

Proprietà annidate

Example

Commenti e suggerimenti

Risorse aggiuntive

Formato alternativo (solo stringa, quando `type=stored-procedure`)