Entities

Konfigurationseinstellungen für Datenbankentitäten.

Health

Description

Felder

Source

REST

GraphQL

Permissions

Relationships

Cache

MCP

Formatübersicht

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

Quelle (Entitätsnamenentitäten)

Die Datenbankquelldetails der Entität.

Verschachtelte Eigenschaften

* key-fields ist nur erforderlich, wenn typeview das fields Array nicht verwendet wird. Der Wert stellt die Primärschlüssel dar.

** parameters ist nur erforderlich, wenn type und stored-procedure nur für Parameter mit Standardwerten. Der Datentyp des Parameters wird abgeleitet. Parameter ohne Standard können weggelassen werden.

object-description ist eine optionale, lesbare Beschreibung des zugrunde liegenden Datenbankobjekts. Dieser Wert wird während der MCP-Toolermittlung angezeigt und hilft KI-Agents, den Zweck der Entität zu verstehen.

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

Parameterarrayformat

Unterstützt in der DAB 2.0-Vorschau parameters ein strukturiertes Arrayformat mit umfangreicheren Metadaten. Jeder Parameter ist ein Objekt mit den folgenden Eigenschaften:

Beispiel (Arrayformat – bevorzugt)

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

Berechtigungen (Entitätsnamenentitäten)

Gibt den Rollennamen an, für den Berechtigungen gelten. Verwenden Sie Systemrollen (Anonymous, ) oder benutzerdefinierte Rollen, Authenticateddie in Ihrem Identitätsanbieter definiert sind.

Format

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

Example

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

Rollenvererbung

DAB 2.0 führt die Rollenvererbung für Entitätsberechtigungen ein. Wenn eine Rolle nicht explizit für eine Entität konfiguriert ist, erbt sie Berechtigungen von einer breiteren Rolle mithilfe der folgenden Kette:

named-role → authenticated → anonymous

• Wenn authenticated sie nicht für eine Entität konfiguriert ist, erbt sie von anonymous.
• Wenn eine benannte Rolle nicht konfiguriert ist, erbt sie von authenticatedoder von anonymous , wenn authenticated sie ebenfalls nicht vorhanden ist.

Dies bedeutet, dass Sie Berechtigungen einmal anonymous für und jede breitere Rolle automatisch denselben Zugriff erhält, ohne dass Duplizierung erforderlich ist.

Example

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

Mit dieser Konfiguration anonymousauthenticatedkönnen alle nicht konfigurierten benannten Rollen gelesen Bookwerden. Hiermit dab configure --show-effective-permissions werden die aufgelösten Berechtigungen für jede Entität angezeigt, nachdem die Vererbung angewendet wurde.

Aktionen (Entitätsentitäten mit Zeichenfolgenarrayberechtigungen)

Ein Zeichenfolgenarray, das angibt, welche Vorgänge für die zugeordnete Rolle zulässig sind.

* Mehrere Vorgänge werden derzeit nur in GraphQL unterstützt.

Format

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

Example

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

Alternatives Format (nur Zeichenfolge, wenn type=stored-procedure)

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

Example

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

Aktionen (Entitäten mit Objektarrayberechtigungen)

Ein Objektarray, das angibt, welche Vorgänge für die zugeordnete Rolle zulässig sind.

Verschachtelte Eigenschaften

Format

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

Example

Dadurch wird die Berechtigung für read die auditor Entität mit Feld- und Richtlinieneinschränkungen gewährtUser.

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

Richtliniennotizen

Datenbankrichtlinien filtern Abfrageergebnisse mithilfe von OData-Prädikaten. Dient @item.<field> zum Verweisen auf Entitätsfelder und @claims.<type> zum Einfügen authentifizierter Benutzeransprüche.

Typ (GraphQL-Entitätennamentitäten)

Legt die Benennungskonvention für eine Entität im GraphQL-Schema fest.

Format

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

Verschachtelte Eigenschaften

* singular ist erforderlich, wenn type sie als Objekt angegeben wird. Wenn type es sich um eine einfache Zeichenfolge handelt, wird diese Zeichenfolge als Singularname verwendet.

Example

Configuration

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

GraphQL-Abfrage

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

GraphQL-Antwort

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

Vorgang (GraphQL-Entitätennamentitäten)

Legt fest, ob der stored-procedure Vorgang unter dem oder dem QueryMutation.

Format

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

Beispiel: Vorgang

Wann operation ist auf query

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

Wann operation ist auf mutation

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

Aktiviert (GraphQL-Entitätennamentitäten)

Ermöglicht Entwicklern selektiv das Einschließen von Entitäten im GraphQL-Schema.

Format

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

REST (Entitätsnamenentitäten)

* Die methods Eigenschaft gilt nur für stored-procedure Endpunkte.

Format

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

Beschreibung (Entitätsnamentitäten)

Eine optionale, vom Menschen lesbare Beschreibung der Entität. Dieser Wert wird in der generierten API-Dokumentation und als Kommentar im GraphQL-Schema angezeigt.

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

Felder (Entitätsnamenentitäten)

Definiert Metadaten für einzelne Datenbankfelder, einschließlich Aliase, Beschreibungen und Primärschlüsselbezeichnungen. Das fields Array ersetzt sowohl (über die mappings Eigenschaft) als alias auch source.key-fields (über die primary-key Eigenschaft) in einer einzigen, einheitlichen Struktur.

Verschachtelte Eigenschaften

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 diesem Beispiel id wird als Primärschlüssel (ersetzt die Notwendigkeit source.key-fields) angegeben, während sku_title und sku_status als aliased als title und status (ersetzt die Notwendigkeit mappings).

Zuordnungen (Entitätsnamenentitäten)

Aktiviert benutzerdefinierte Aliase oder offengelegte Namen für Datenbankobjektfelder.

Format

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

Examples

Datenbanktabelle

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ätsnamenentitäten)

Aktiviert und konfiguriert die Zwischenspeicherung für die Entität.

Verschachtelte Eigenschaften

Format

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

Die level Eigenschaft steuert, welche Cacheebenen verwendet werden:

Example

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

Beziehungen (Entitätsnamenentitäten)

Konfiguriert, wie GraphQL-Entitäten mit anderen verfügbar gemachten Entitäten verknüpft sind. Weitere Informationen finden Sie unter Aufschlüsselung von Daten-API-Generator-Beziehungen.

Verschachtelte Eigenschaften

Diese Eigenschaften werden je nach Beziehungskardinalität in unterschiedlichen Kombinationen verwendet.

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

Beispiel: 1:1-Kardinalität

Jeder Profile ist mit genau einem Userverknüpften , und jeder User hat genau ein verwandtes .Profile

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

GraphQL-Schema

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

Command-line

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

Beispiel: 1:n-Kardinalität

A Category kann eine oder mehrere verwandte Book Entitäten aufweisen, während jedes Book eine verwandte CategoryEntität aufweisen kann.

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

GraphQL-Schema

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

Befehlszeile

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

Beispiel: n:1-Kardinalität

Viele Book Entitäten können eine verwandte CategoryEntität haben, während eine Category oder mehrere verwandte Book Einträge enthalten kann.

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

GraphQL-Schema

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

Befehlszeile

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

Beispiel: n:n-Kardinalität

Viele Book Entitäten können viele verwandte Author Entitäten haben, während viele Author Entitäten viele verwandte Book Einträge enthalten können.

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

GraphQL-Schema

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

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

Befehlszeile

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ät (Entitätsnamentitäten)

Aktiviert und konfiguriert Integritätsprüfungen für die Entität.

Verschachtelte Eigenschaften

Example

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

MCP (Entitätsnamenentitäten)

Steuert die MCP-Teilnahme für die Entität. Wenn MCP global aktiviert ist, nehmen Entitäten standardmäßig teil. Verwenden Sie diese Eigenschaft, um sich abzumelden oder benutzerdefinierte MCP-Tools für Entitäten gespeicherter Prozeduren zu aktivieren.

Objektformat

Verwenden Sie das Objektformat für granulare Steuerung:

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

Benutzerdefiniertes Tool (nur gespeicherte Prozeduren)

Legen Sie für Entitäten für gespeicherte Prozeduren fest, custom-tool dass true die Prozedur als benanntes MCP-Tool registriert werden soll:

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

CLI-Beispiele

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