Entities

Ustawienia konfiguracji dla jednostek bazy danych.

Health

Description

Pola formularza

Source

REST

GraphQL

Permissions

Relationships

Cache

MCP

Omówienie formatu

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

Źródło (jednostki o nazwie jednostki)

Szczegóły źródła bazy danych jednostki.

Właściwości zagnieżdżone

* key-fields jest wymagany tylko wtedy, gdy type jest view i tablica fields nie jest używana. Wartość reprezentuje klucze podstawowe.

** parameters parametr jest wymagany tylko wtedy, gdy type parametr jest stored-procedure i tylko dla parametrów z wartościami domyślnymi. Typ danych parametru jest wnioskowany. Parametry bez wartości domyślnej można pominąć.

object-description jest opcjonalnym czytelnym dla człowieka opisem bazowego obiektu bazy danych. Ta wartość jest zwracana podczas odnajdywania narzędzi MCP, pomagając agentom sztucznej inteligencji zrozumieć przeznaczenie jednostki.

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 tablicy parametrów

W wersji zapoznawczej parameters języka DAB 2.0 obsługuje format tablicy ustrukturyzowanej z bardziej zaawansowanymi metadanymi. Każdy parametr jest obiektem o następujących właściwościach:

Przykład (format tablicy — preferowany)

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

Uprawnienia (jednostki o nazwie jednostki)

Określa nazwę roli, do której mają zastosowanie uprawnienia. Użyj ról systemowych (Anonymous, Authenticated) lub ról niestandardowych zdefiniowanych w dostawcy tożsamości.

Format

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

Example

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

Dziedziczenie roli

Język DAB 2.0 wprowadza dziedziczenie ról dla uprawnień jednostki. Gdy rola nie jest jawnie skonfigurowana dla jednostki, dziedziczy uprawnienia z szerszej roli przy użyciu następującego łańcucha:

named-role → authenticated → anonymous

• Jeśli authenticated jednostka nie jest skonfigurowana, dziedziczy ją z anonymousklasy .
• Jeśli nazwana rola nie jest skonfigurowana, dziedziczy ją z authenticatedelementu lub, anonymous jeśli authenticated jest również nieobecna.

Oznacza to, że można definiować uprawnienia raz na i anonymous każda szersza rola automatycznie uzyskuje ten sam dostęp bez konieczności duplikowania.

Example

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

W przypadku tej konfiguracji, anonymous, authenticatedi wszystkie nieskonfigurowane nazwane role mogą odczytywać Bookwszystkie . Użyj dab configure --show-effective-permissions polecenia , aby wyświetlić rozwiązane uprawnienia dla każdej jednostki po zastosowaniu dziedziczenia.

Akcje (string-array Permissions entity-name entities)

Tablica ciągów szczegółowo określa, jakie operacje są dozwolone dla skojarzonej roli.

* Wiele operacji jest obecnie obsługiwanych tylko w narzędziu GraphQL.

Format

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

Example

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

Format alternatywny (tylko ciąg, gdy type=stored-procedure)

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

Example

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

Akcje (jednostki uprawnień tablicy obiektów)

Tablica obiektów szczegółowo określa, jakie operacje są dozwolone dla skojarzonej roli.

Właściwości zagnieżdżone

Format

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

Example

To uprawnienie do read uprawnień do auditorUser jednostki z ograniczeniami pól i zasad.

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

Uwagi dotyczące zasad

Zasady bazy danych filtrują wyniki zapytań przy użyciu predykatów w stylu OData. Służy @item.<field> do odwołowania się do pól jednostki i @claims.<type> do wstrzykiwania uwierzytelnionych oświadczeń użytkowników.

Typ (jednostki jednostki GraphQL)

Ustawia konwencję nazewnictwa dla jednostki w schemacie GraphQL.

Format

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

Właściwości zagnieżdżone

* singular jest wymagany, gdy type jest określony jako obiekt. Gdy type jest to zwykły ciąg, ten ciąg jest używany jako nazwa pojedyncza.

Example

Configuration

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

Zapytanie GraphQL

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

Odpowiedź graphQL

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

Operacja (jednostki nazwy jednostki GraphQL)

Określa, stored-procedure czy operacja jest wyświetlana pod elementem Query lub Mutation.

Format

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

Przykład: operacja

Gdy operation jest ustawiona wartość query

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

Gdy operation jest ustawiona wartość mutation

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

Włączone (jednostki nazwy jednostki GraphQL)

Umożliwia deweloperom selektywne dołączanie jednostek do schematu GraphQL.

Format

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

REST (jednostki o nazwie jednostki)

* Właściwość methods dotyczy tylko stored-procedure punktów końcowych.

Format

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

Opis (jednostki o nazwie jednostki)

Opcjonalny czytelny dla człowieka opis jednostki. Ta wartość jest dostępna w wygenerowanej dokumentacji interfejsu API i jako komentarz w schemacie 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"
      }
    }
  }
}

Pola (jednostki o nazwie jednostki)

Definiuje metadane dla poszczególnych pól bazy danych, w tym aliasy, opisy i oznaczenia klucza podstawowego. Tablica fields zastępuje zarówno mappings (za pośrednictwem alias właściwości), jak i source.key-fields (za pośrednictwem primary-key właściwości) w pojedynczej, ujednoliconej strukturze.

Właściwości zagnieżdżone

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

W tym przykładzie id jest wyznaczony jako klucz podstawowy (zastępując potrzebę source.key-fields), a sku_title element i sku_status są aliasami jako title i status (zastępując potrzebę ).mappings

Mapowania (jednostki o nazwie jednostki)

Włącza niestandardowe aliasy lub uwidocznione nazwy dla pól obiektów bazy danych.

Format

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

Examples

Tabela bazy danych

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

Configuration

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

Pamięć podręczna (jednostki o nazwie jednostki)

Włącza i konfiguruje buforowanie dla jednostki.

Właściwości zagnieżdżone

Format

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

Właściwość level steruje warstwami pamięci podręcznej:

Example

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

Relacje (jednostki o nazwie jednostki)

Konfiguruje sposób, w jaki jednostki GraphQL są powiązane z innymi uwidocznionych jednostkami. Aby uzyskać więcej informacji, zobacz Podział relacji konstruktora interfejsu API danych.

Właściwości zagnieżdżone

Te właściwości są używane w różnych kombinacjach w zależności od kardynalności relacji.

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

Przykład: kardynalność jeden do jednego

Każda z nich jest powiązana z dokładnie jedną Profilewartością , a każda User z nich User ma dokładnie jeden powiązany element Profile.

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

Schemat GraphQL

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

Command-line

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

Przykład: kardynalność jeden do wielu

Element Category może mieć co najmniej jedną powiązaną Book jednostkę, a każda z nich Book może mieć jeden powiązany element Category.

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

Schemat GraphQL

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

Wiersz polecenia

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

Przykład: kardynalność wiele-do-jednego

Wiele Book jednostek może mieć jeden powiązany Categoryelement , a element Category może zawierać co najmniej jeden powiązany Book wpis.

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

Schemat GraphQL

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

Wiersz polecenia

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

Przykład: kardynalność wiele-do-wielu

Wiele Book jednostek może mieć wiele powiązanych Author jednostek, podczas gdy wiele Author jednostek może mieć wiele powiązanych Book wpisów.

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

Schemat GraphQL

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

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

Wiersz polecenia

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"

Kondycja (jednostki o nazwie jednostki)

Włącza i konfiguruje kontrole kondycji dla jednostki.

Właściwości zagnieżdżone

Example

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

MCP (jednostki o nazwie jednostki)

Kontroluje udział MCP w jednostce. Gdy mcP jest włączona globalnie, jednostki uczestniczą domyślnie. Użyj tej właściwości, aby zrezygnować lub włączyć niestandardowe narzędzia MCP dla jednostek procedur składowanej.

Format obiektu

Użyj formatu obiektu w celu uzyskania szczegółowej kontrolki:

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

Narzędzie niestandardowe (tylko procedury składowane)

W przypadku jednostek procedury składowanej ustaw wartość custom-tool na , aby true zarejestrować procedurę jako nazwane narzędzie MCP:

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

Przykłady interfejsu wiersza polecenia

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