Entities

Paramètres de configuration pour les entités de base de données.

Health

Description

Fields

Source

REST

GraphQL

Permissions

Relationships

Cache

MCP

Vue d’ensemble du format

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

Source (entités de nom d’entité)

Détails de la source de base de données de l’entité.

Propriétés imbriquées

* key-fields n’est nécessaire que lorsque typeview le fields tableau n’est pas utilisé. La valeur représente les clés primaires.

** parameters n’est nécessaire que lorsque type c’est stored-procedure et uniquement pour les paramètres avec des valeurs par défaut. Le type de données du paramètre est déduit. Les paramètres sans valeur par défaut peuvent être omis.

object-description est une description facultative lisible par l’homme de l’objet de base de données sous-jacent. Cette valeur est exposée pendant la découverte d’outils MCP, ce qui aide les agents IA à comprendre l’objectif de l’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>"
          }
        ]
      }
    }
  }
}

Format du tableau de paramètres

Dans la préversion de DAB 2.0, parameters prend en charge un format de tableau structuré avec des métadonnées plus riches. Chaque paramètre est un objet avec les propriétés suivantes :

Exemple (format de tableau , préféré)

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

Autorisations (entités de nom d’entité)

Spécifie le nom du rôle auquel s’appliquent les autorisations. Utilisez des rôles système (Anonymous, Authenticated) ou des rôles personnalisés définis dans votre fournisseur d’identité.

Format

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

Example

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

Héritage de rôle

DAB 2.0 introduit l’héritage des rôles pour les autorisations d’entité. Lorsqu’un rôle n’est pas configuré explicitement pour une entité, il hérite des autorisations d’un rôle plus large à l’aide de la chaîne suivante :

named-role → authenticated → anonymous

• S’il authenticated n’est pas configuré pour une entité, il hérite de anonymous.
• Si un rôle nommé n’est pas configuré, il hérite ou authenticateds’il anonymousauthenticated est également absent.

Cela signifie que vous pouvez définir des autorisations une fois sur anonymous et chaque rôle plus large obtient automatiquement le même accès, sans duplication requise.

Example

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

Avec cette configuration, anonymous, authenticatedet tout rôle nommé non configuré peut tous lire Book. Permet dab configure --show-effective-permissions de voir les autorisations résolues pour chaque entité après l’application de l’héritage.

Actions (entités entity-name d’autorisations de tableau de chaînes)

Tableau de chaînes détaillant les opérations autorisées pour le rôle associé.

* Actuellement, plusieurs opérations sont uniquement prises en charge dans GraphQL.

Format

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

Example

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

Autre format (chaîne uniquement, quand type=stored-procedure)

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

Example

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

Actions (entités entity-name d’autorisations de tableau d’objets)

Tableau d’objets détaillant les opérations autorisées pour le rôle associé.

Propriétés imbriquées

Format

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

Example

Cela accorde read l’autorisation à auditor l’entité User , avec des restrictions de champ et de stratégie.

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

Notes de stratégie

Les stratégies de base de données filtrent les résultats des requêtes à l’aide de prédicats de style OData. Permet @item.<field> de référencer des champs d’entité et @claims.<type> d’injecter des revendications utilisateur authentifiées.

Type (entités de nom d’entité GraphQL)

Définit la convention d’affectation de noms pour une entité dans le schéma GraphQL.

Format

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

Propriétés imbriquées

* singular est obligatoire lorsqu’il type est spécifié en tant qu’objet. Lorsqu’il type s’agit d’une chaîne simple, cette chaîne est utilisée comme nom singulier.

Example

Configuration

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

Requête GraphQL

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

Réponse GraphQL

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

Opération (entités de nom d’entité GraphQL)

Indique si l’opération stored-procedure apparaît sous le Query ou Mutation.

Format

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

Exemple : opération

Quand operation est défini sur query

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

Quand operation est défini sur mutation

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

Activé (entités de nom d’entité GraphQL)

Permet aux développeurs d’inclure de manière sélective des entités dans le schéma GraphQL.

Format

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

REST (entités de nom d’entité)

* La methods propriété est uniquement destinée aux stored-procedure points de terminaison.

Format

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

Description (entités de nom d’entité)

Description facultative lisible par l’homme de l’entité. Cette valeur est exposée dans la documentation de l’API générée et en tant que commentaire dans le schéma 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"
      }
    }
  }
}

Champs (entités de nom d’entité)

Définit les métadonnées des champs de base de données individuels, y compris les alias, les descriptions et les désignations de clé primaire. Le fields tableau remplace les deux mappings (via la alias propriété) et source.key-fields (via la primary-key propriété) dans une structure unifiée unique.

Propriétés imbriquées

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

Dans cet exemple, id est désigné comme clé primaire (en remplaçant la nécessité), source.key-fieldstandis sku_title qu’elle sku_status est alias et titlestatus (remplacement de la nécessité).mappings

Mappages (entités de nom d’entité)

Active les alias personnalisés ou les noms exposés pour les champs d’objet de base de données.

Format

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

Examples

Table de base de données

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és de nom d’entité)

Active et configure la mise en cache de l’entité.

Propriétés imbriquées

Format

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

La propriété contrôle les level niveaux de cache utilisés :

Example

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

Relations (entités de nom d’entité)

Configure la façon dont les entités GraphQL sont liées à d’autres entités exposées. Pour plus d’informations, consultez répartition des relations du générateur d’API de données.

Propriétés imbriquées

Ces propriétés sont utilisées dans différentes combinaisons en fonction de la cardinalité de relation.

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

Exemple : cardinalité un-à-un

Chacun Profile est lié à exactement un User, et chacun User a exactement un associé Profile.

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

Schéma GraphQL

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

Command-line

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

Exemple : cardinalité un-à-plusieurs

Un Category peut avoir une ou plusieurs entités associées Book , tandis que chacun Book peut avoir un associé Category.

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

Schéma GraphQL

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

Ligne de commande

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

Exemple : cardinalité plusieurs-à-un

De nombreuses Book entités peuvent avoir une entité associée Category, tandis qu’une Category ou plusieurs entrées associées peuvent être associées Book .

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

Schéma GraphQL

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

Ligne de commande

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

Exemple : cardinalité plusieurs-à-plusieurs

De nombreuses Book entités peuvent avoir de nombreuses entités associées Author , tandis que de nombreuses Author entités peuvent avoir de nombreuses entrées associées 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": {
        ...
      }
    }
  }
}

Schéma GraphQL

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

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

Ligne de commande

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"

Intégrité (entités de nom d’entité)

Active et configure les vérifications d’intégrité pour l’entité.

Propriétés imbriquées

Example

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

MCP (entités de nom d’entité)

Contrôle la participation MCP pour l’entité. Lorsque MCP est activé globalement, les entités participent par défaut. Utilisez cette propriété pour désactiver ou activer des outils MCP personnalisés pour les entités de procédure stockée.

Format d’objet

Utilisez le format d’objet pour le contrôle granulaire :

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

Outil personnalisé (procédures stockées uniquement)

Pour les entités de procédure stockée, définissez custom-tooltrue pour inscrire la procédure en tant qu’outil MCP nommé :

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

Exemples CLI

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