Entities

Impostazioni di configurazione per le entità di database.

Health

Description

Fields

Source

REST

GraphQL

Permissions

Relationships

Cache

MCP

Panoramica del formato

{
  "entities": {
    "{entity-name}": {
      "description": <string>,
      "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>,
        "object-description": <string>,
        "type": "view" | "stored-procedure" | "table",
        "key-fields": [<string>], // DEPRECATED: use fields[].primary-key
        "parameters": [ // array format (preferred)
          {
            "name": "<parameter-name>",
            "required": <boolean>,
            "default": <value>,
            "description": "<string>"
          }
        ]
      },
      "fields": [
        {
          "name": "<database-field-name>",
          "alias": "<api-exposed-name>",
          "description": "<string>",
          "primary-key": <boolean>
        }
      ],
      "mappings": { // DEPRECATED: use fields[].alias
        "<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>
          }
        }
      ],
      "cache": {
        "enabled": <boolean>,
        "ttl-seconds": <integer>,
        "level": "L1" | "L1L2" // default: "L1L2"
      },
      "mcp": {
        "dml-tools": <boolean>,       // default: true
        "custom-tool": <boolean>      // stored-procedure only; default: false
      }
    }
  }
}

Origine (entità entity-name)

Dettagli dell'origine del database dell'entità.

Proprietà annidate

* key-fields è obbligatorio solo quando type è view e la fields matrice non viene usata. 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.

object-description è una descrizione facoltativa leggibile dell'oggetto di database sottostante. Questo valore viene visualizzato durante l'individuazione degli strumenti MCP, consentendo agli agenti di intelligenza artificiale di comprendere lo scopo dell'entità.

Format

{
  "entities": {
    "{entity-name}": {
      "source": {
        "object": <string>,
        "object-description": <string>,
        "type": <"view" | "stored-procedure" | "table">,
        "key-fields": [ <string> ], // DEPRECATED: use fields[].primary-key
        "parameters": [ // array format (preferred)
          {
            "name": "<parameter-name>",
            "required": <boolean>,
            "default": <value>,
            "description": "<string>"
          }
        ]
      }
    }
  }
}

Formato matrice parametri

Nell'anteprima parameters di DAB 2.0 supporta un formato di matrice strutturato con metadati più avanzati. Ogni parametro è un oggetto con le proprietà seguenti:

Esempio (formato matrice- preferito)

{
  "entities": {
    "GetBookById": {
      "source": {
        "type": "stored-procedure",
        "object": "dbo.get_book_by_id",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "default": null,
            "description": "The unique identifier of the book"
          }
        ]
      }
    }
  }
}

Autorizzazioni (entità entity-name)

Specifica il nome del ruolo a cui si applicano le autorizzazioni. Usare i ruoli di sistema (Anonymous, Authenticated) o i ruoli personalizzati definiti nel provider di identità.

Format

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "role": <"Anonymous" | "Authenticated" | "custom-role">,
          "actions": [ <string> ]
        }
      ]
    }
  }
}

Example

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

Ereditarietà dei ruoli

DAB 2.0 introduce l'ereditarietà dei ruoli per le autorizzazioni di entità. Quando un ruolo non è configurato in modo esplicito per un'entità, eredita le autorizzazioni da un ruolo più ampio usando la catena seguente:

named-role → authenticated → anonymous

• Se authenticated non è configurato per un'entità, eredita da anonymous.
• Se un ruolo denominato non è configurato, eredita da authenticatedo da anonymous se authenticated è assente.

Ciò significa che è possibile definire le autorizzazioni una sola volta su anonymous e ogni ruolo più ampio ottiene automaticamente lo stesso accesso, senza la duplicazione necessaria.

Example

{
  "entities": {
    "Book": {
      "source": "dbo.books",
      "permissions": [
        { "role": "anonymous", "actions": [ "read" ] }
      ]
    }
  }
}

Con questa configurazione, anonymous, authenticatede qualsiasi ruolo denominato non configurato può leggere Booktutti . Usare dab configure --show-effective-permissions per visualizzare le autorizzazioni risolte per ogni entità dopo l'applicazione dell'ereditarietà.

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

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

* Attualmente in GraphQL sono supportate più operazioni.

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)

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

Proprietà annidate

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 di database filtrano i risultati delle query usando predicati in stile OData. Usare @item.<field> per fare riferimento a campi di entità e @claims.<type> per inserire attestazioni utente autenticate.

Tipo (entità GraphQL 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

* singular è obbligatorio quando type viene specificato come oggetto . Quando type è una stringa normale, tale stringa viene usata come nome 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)

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

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)

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)

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

Format

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

Descrizione (entità entity-name)

Descrizione facoltativa leggibile dell'entità. Questo valore viene illustrato nella documentazione dell'API generata e come commento nello schema GraphQL.

Format

{
  "entities": {
    "{entity-name}": {
      "description": "<string>"
    }
  }
}

Example

{
  "entities": {
    "Book": {
      "description": "Represents a book in the catalog with title, author, and pricing information.",
      "source": {
        "object": "dbo.books",
        "type": "table"
      }
    }
  }
}

Campi (entità entity-name)

Definisce i metadati per i singoli campi di database, inclusi alias, descrizioni e designazioni di chiave primaria. La fields matrice sostituisce ( mappings tramite la alias proprietà) e source.key-fields (tramite la primary-key proprietà ) in una singola struttura unificata.

Proprietà annidate

Format

{
  "entities": {
    "{entity-name}": {
      "fields": [
        {
          "name": "<database-field-name>",
          "alias": "<api-exposed-name>",
          "description": "<string>",
          "primary-key": <boolean>
        }
      ]
    }
  }
}

Example

{
  "entities": {
    "Book": {
      "source": {
        "object": "dbo.books",
        "type": "table"
      },
      "fields": [
        {
          "name": "id",
          "description": "Unique book identifier",
          "primary-key": true
        },
        {
          "name": "sku_title",
          "alias": "title",
          "description": "The display title of the book"
        },
        {
          "name": "sku_status",
          "alias": "status"
        }
      ]
    }
  }
}

In questo esempio viene id designato come chiave primaria (sostituendo la necessità di source.key-fields), mentre sku_title e sku_status vengono aliasati come title e status (sostituendo la necessità di mappings).

Mapping (entità entity-name)

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

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)

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

Proprietà annidate

Format

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

La level proprietà controlla quali livelli di cache vengono usati:

Example

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

Relazioni (entità entity-name)

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.

Proprietà annidate

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

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

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 .

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

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

Proprietà annidate

Example

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

MCP (entità entity-name)

Controlla la partecipazione MCP per l'entità. Quando MCP è abilitato a livello globale, le entità partecipano per impostazione predefinita. Utilizzare questa proprietà per rifiutare esplicitamente o per abilitare strumenti MCP personalizzati per le entità stored procedure.

Formato oggetto

Usare il formato dell'oggetto per il controllo granulare:

{
  "entities": {
    "Book": {
      "mcp": {
        "dml-tools": true
      }
    }
  }
}

Strumento personalizzato (solo stored procedure)

Per le entità stored procedure, impostare su custom-tooltrue per registrare la procedura come strumento MCP denominato:

{
  "entities": {
    "GetBookById": {
      "source": {
        "type": "stored-procedure",
        "object": "dbo.get_book_by_id"
      },
      "mcp": {
        "custom-tool": true
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["execute"]
        }
      ]
    }
  }
}

Esempi dell'interfaccia della riga di comando

dab add Book --source books --permissions "anonymous:*" --mcp.dml-tools true

dab add GetBookById --source dbo.get_book_by_id --source.type stored-procedure --permissions "anonymous:execute" --mcp.custom-tool true