Udostępnij za pośrednictwem

add polecenie

Dodaj nową definicję jednostki do istniejącego pliku konfiguracji konstruktora interfejsu API danych. Musisz mieć już utworzoną konfigurację za pomocą dab initpolecenia . Użyj polecenia dab update , aby zmodyfikować jednostki po utworzeniu.

Wskazówka

Użyj dab add polecenia , aby utworzyć nowe jednostki i dab update rozwijać je.

Składnia

dab add <entity-name> [options]

Szybki rzut oka

Option Podsumowanie
-c, --config Ścieżka pliku konfiguracji. Wartość domyślna dab-config.json.

Sekcja główna

Option Podsumowanie
<entity-name> Wymagany argument pozycyjny. Nazwa jednostki logicznej.
-s, --source To jest wymagane. Nazwa obiektu bazy danych (tabela, widok lub procedura składowana).
--source.type Typ źródła: table, , viewstored-procedure(tabela domyślna).
--source.key-fields Pola klucza podstawowego dla widoków (rozdzielane przecinkami).
--source.params Tylko procedury składowane. Domyślne wartości parametrów jako param1:val1,param2:val2.

Sekcja pamięci podręcznej

Option Podsumowanie
--cache.enabled Włączanie/wyłączanie buforowania dla jednostki.
--cache.ttl Czas wygaśnięcia pamięci podręcznej w sekundach.
--description Dowolny opis jednostki.

Sekcja Parametrów

Option Podsumowanie
--parameters.name Tylko procedury składowane. Nazwy parametrów (rozdzielane przecinkami).
--parameters.description Tylko procedury składowane. Opisy parametrów.
--parameters.required Tylko procedury składowane. Wymagane flagi parametru.
--parameters.default Tylko procedury składowane. Wartości domyślne parametru.

Sekcja Pola

Option Podsumowanie
--fields.exclude Wykluczone pola rozdzielone przecinkami.
--fields.include Pola dozwolone rozdzielone przecinkami (* = wszystkie).
--fields.name Nazwy pól do opisania (powtarzalne lub rozdzielane przecinkami).
--fields.alias Aliasy pól (rozdzielone przecinkami, wyrównane do --fields.name).
--fields.description Opisy pól (rozdzielone przecinkami, wyrównane do --fields.namewartości ).
--fields.primary-key Flagi klucza podstawowego (rozdzielane przecinkami, wyrównane do --fields.nameelementu ).

Sekcja interfejsu API

Option Podsumowanie
--graphql Ekspozycja graphQL: false, true, singularlub singular:plural.
--graphql.operation Tylko procedury składowane. Query lub Mutation (mutacja domyślna).
--rest Ekspozycja REST: false, truelub trasa niestandardowa.
--rest.methods Tylko procedury składowane. Dozwolone czasowniki: GET, , POSTPUT, PATCH, DELETE. Domyślny post.
--mcp.dml-tools Włącz/wyłącz narzędzia języka manipulowania danymi (DML) dla jednostki w protokole MCP (Model Context Protocol). Wartość domyślna true.
--mcp.custom-tool Tylko procedury składowane. Zarejestruj się jako nazwane narzędzie MCP.

Sekcja Uprawnień

Option Podsumowanie
--permissions To jest wymagane. role:actions dla jednej roli.
--policy-database Filtr w stylu OData zastosowany w zapytaniu bazy danych.
--policy-request Zażądaj oceny zasad przed wywołaniem bazy danych.

<entity-name>

Logiczna nazwa jednostki w konfiguracji. Uwzględniana wielkość liter.

Krótkie przykłady tabel, widoków i procedur składowanych

Dodawanie tabeli

dab add Book \
  --source dbo.Books \
  --source.type table \
  --permissions "anonymous:read" \
  --description "Example for managing book inventory"

Dodawanie widoku

dab add BookView \
  --source dbo.MyView \
  --source.type view \
  --source.key-fields "id,region" \
  --permissions "anonymous:read" \
  --description "Example for managing book inventory from view"

Dodawanie procedury składowanej

dab add BookProc \
  --source dbo.MyProc \
  --source.type stored-procedure \
  --parameters.name "year,active" \
  --parameters.required "false,false" \
  --parameters.default "2024,true" \
  --permissions "anonymous:execute" \
  --graphql.operation query \
  --description "Example for executing a stored procedure"

-c, --config

Ścieżka pliku konfiguracji. Wartość domyślna to dab-config.json.

Example

dab add Book \
  --config ./dab-config.mssql.json \
  --source dbo.Books \
  --permissions "anonymous:read"

-s, --source

To jest wymagane. Nazwa obiektu bazy danych: tabela, widok, kontener lub procedura składowana.

Example

dab add Book \
  --source dbo.Books \
  --permissions "anonymous:read"

Wynikowa konfiguracja

{
  "entities": {
    "Book": {
      "source": {
        "type": "table",
        "object": "dbo.Books"
      },
      "permissions": [
        { "role": "anonymous", "actions": [ { "action": "read" } ] }
      ]
    }
  }
}

--source.type

Typ obiektu bazy danych. Wartość domyślna: table.

Example

dab add Book \
  --source dbo.Books \
  --source.type table \
  --permissions "anonymous:read"

Wynikowa konfiguracja

{
  "entities": {
    "Book": {
      "source": {
        "type": "table",
        "object": "dbo.Books"
      },
      "permissions": [
        { "role": "anonymous", "actions": [ { "action": "read" } ] }
      ]
    }
  }
}

--source.key-fields

Co najmniej jedno pole do użycia jako klucze podstawowe. Widoki nie mają wewnętrznych kluczy podstawowych, dlatego należy jawnie określić pola kluczy.

Example

dab add BookView \
  --source dbo.MyView \
  --source.type view \
  --source.key-fields "id,region" \
  --permissions "anonymous:read"

Wynikowa konfiguracja

{
  "entities": {
    "BookView": {
      "source": {
        "object": "dbo.MyView",
        "type": "view",
        "key-fields": [ "id", "region" ]
      },
      "permissions": [
        { "role": "anonymous", "actions": [ { "action": "read" } ] }
      ]
    }
  }
}

--source.params

Słownik parametrów i ich wartości domyślnych dla procedur składowanych. Użyj formatu param1:val1,param2:val2.

Example

dab add BookProc \
  --source dbo.MyProc \
  --source.type stored-procedure \
  --source.params "year:2024,active:true" \
  --permissions "anonymous:execute"

Wynikowa konfiguracja

{
  "entities": {
    "BookProc": {
      "source": {
        "object": "dbo.MyProc",
        "type": "stored-procedure",
        "parameters": [
          { "name": "year", "required": false, "default": "2024" },
          { "name": "active", "required": false, "default": "True" }
        ]
      },
      "permissions": [
        { "role": "anonymous", "actions": [ { "action": "execute" } ] }
      ]
    }
  }
}

--cache.enabled

Włącz lub wyłącz buforowanie.

Example

dab add Book \
  --source dbo.Books \
  --permissions "anonymous:read" \
  --cache.enabled true

Wynikowa konfiguracja

{
  "entities": {
    "Book": {
      "source": {
        "type": "table",
        "object": "dbo.Books"
      },
      "permissions": [
        { "role": "anonymous", "actions": [ { "action": "read" } ] }
      ],
      "cache": {}
    }
  }
}

--cache.ttl

Czas wygaśnięcia pamięci podręcznej w sekundach.

Example

dab add Book \
  --source dbo.Books \
  --permissions "anonymous:read" \
  --cache.ttl 300

Wynikowa konfiguracja

{
  "entities": {
    "Book": {
      "source": {
        "type": "table",
        "object": "dbo.Books"
      },
      "permissions": [
        { "role": "anonymous", "actions": [ { "action": "read" } ] }
      ],
      "cache": {
        "ttl-seconds": 300
      }
    }
  }
}

--description

Dowolny tekst opisu jednostki.

Uwaga / Notatka

Ta opcja jest dostępna w interfejsie 2.0.0-rc wiersza polecenia. Konstruktor interfejsu API danych 2.0 jest obecnie w wersji zapoznawczej. Zainstaluj za pomocą polecenia dotnet tool install microsoft.dataapibuilder --version 2.0.0-rc --prerelease.

Example

dab add Book \
  --source dbo.Books \
  --permissions "anonymous:read" \
  --description "Entity for managing book inventory"

Wynikowa konfiguracja

{
  "entities": {
    "Book": {
      "source": {
        "type": "table",
        "object": "dbo.Books"
      },
      "permissions": [
        { "role": "anonymous", "actions": [ { "action": "read" } ] }
      ],
      "description": "Entity for managing book inventory"
    }
  }
}

--parameters.name

Tylko procedury składowane. Rozdzielona przecinkami lista nazw parametrów.

Uwaga / Notatka

Ta opcja jest dostępna w interfejsie 2.0.0-rc wiersza polecenia. Konstruktor interfejsu API danych 2.0 jest obecnie w wersji zapoznawczej. Zainstaluj za pomocą polecenia dotnet tool install microsoft.dataapibuilder --version 2.0.0-rc --prerelease.

Example

dab add GetOrdersByDateRange \
  --source dbo.usp_GetOrdersByDateRange \
  --source.type stored-procedure \
  --permissions "authenticated:execute" \
  --description "Retrieves all orders placed within a specified date range" \
  --parameters.name "StartDate,EndDate,CustomerID" \
  --parameters.description "Beginning of date range (inclusive),End of date range (inclusive),Optional customer ID filter" \
  --parameters.required "true,true,false" \
  --parameters.default ",,null"

Wynikowa konfiguracja

{
  "entities": {
    "GetOrdersByDateRange": {
      "description": "Retrieves all orders placed within a specified date range",
      "source": {
        "object": "dbo.usp_GetOrdersByDateRange",
        "type": "stored-procedure",
        "parameters": [
          {
            "name": "StartDate",
            "required": true,
            "default": "",
            "description": "Beginning of date range (inclusive)"
          },
          {
            "name": "EndDate",
            "required": true,
            "default": "",
            "description": "End of date range (inclusive)"
          },
          {
            "name": "CustomerID",
            "required": false,
            "default": "null",
            "description": "Optional customer ID filter"
          }
        ]
      },
      "permissions": [
        {
          "role": "authenticated",
          "actions": [
            {
              "action": "execute"
            }
          ]
        }
      ]
    }
  }
}

--parameters.description

Tylko procedury składowane. Rozdzielona przecinkami lista opisów parametrów wyrównana do --parameters.name.

Uwaga / Notatka

Ta opcja jest dostępna w interfejsie 2.0.0-rc wiersza polecenia. Konstruktor interfejsu API danych 2.0 jest obecnie w wersji zapoznawczej. Zainstaluj za pomocą polecenia dotnet tool install microsoft.dataapibuilder --version 2.0.0-rc --prerelease.

Example

dab add GetOrdersByDateRange \
  --source dbo.usp_GetOrdersByDateRange \
  --source.type stored-procedure \
  --permissions "authenticated:execute" \
  --parameters.name "StartDate,EndDate" \
  --parameters.description "Beginning of date range (inclusive),End of date range (inclusive)"

--parameters.required

Tylko procedury składowane. Rozdzielona przecinkami lista true/false wartości wyrównanych do .--parameters.name

Uwaga / Notatka

Ta opcja jest dostępna w interfejsie 2.0.0-rc wiersza polecenia. Konstruktor interfejsu API danych 2.0 jest obecnie w wersji zapoznawczej. Zainstaluj za pomocą polecenia dotnet tool install microsoft.dataapibuilder --version 2.0.0-rc --prerelease.

Example

dab add GetOrdersByDateRange \
  --source dbo.usp_GetOrdersByDateRange \
  --source.type stored-procedure \
  --permissions "authenticated:execute" \
  --parameters.name "StartDate,EndDate" \
  --parameters.required "true,true"

--parameters.default

Tylko procedury składowane. Rozdzielona przecinkami lista wartości domyślnych wyrównana do --parameters.name.

Uwaga / Notatka

Ta opcja jest dostępna w interfejsie 2.0.0-rc wiersza polecenia. Konstruktor interfejsu API danych 2.0 jest obecnie w wersji zapoznawczej. Zainstaluj za pomocą polecenia dotnet tool install microsoft.dataapibuilder --version 2.0.0-rc --prerelease.

Example

dab add GetOrdersByDateRange \
  --source dbo.usp_GetOrdersByDateRange \
  --source.type stored-procedure \
  --permissions "authenticated:execute" \
  --parameters.name "CustomerID" \
  --parameters.default "null"

--fields.exclude

Rozdzielona przecinkami lista pól do wykluczenia.

Example

dab add Book \
  --source dbo.Books \
  --permissions "anonymous:read" \
  --fields.exclude "internal_flag,secret_note"

Wynikowa konfiguracja

{
  "entities": {
    "Book": {
      "source": { "type": "table", "object": "dbo.Books" },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "fields": {
                "exclude": [ "internal_flag", "secret_note" ]
              }
            }
          ]
        }
      ]
    }
  }
}

--fields.include

Rozdzielona przecinkami lista pól do uwidocznienia.

Example

dab add Book \
  --source dbo.Books \
  --permissions "anonymous:read" \
  --fields.include "id,title,price"

Wynikowa konfiguracja

{
  "entities": {
    "Book": {
      "source": { "type": "table", "object": "dbo.Books" },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "fields": {
                "exclude": [],
                "include": [ "id", "title", "price" ]
              }
            }
          ]
        }
      ]
    }
  }
}

--fields.name

Nazwa kolumny bazy danych do opisania.

Uwaga / Notatka

Ta opcja jest dostępna w interfejsie 2.0.0-rc wiersza polecenia. Konstruktor interfejsu API danych 2.0 jest obecnie w wersji zapoznawczej. Zainstaluj za pomocą polecenia dotnet tool install microsoft.dataapibuilder --version 2.0.0-rc --prerelease.

Example

dab add Products \
  --source dbo.Products \
  --permissions "anonymous:*" \
  --fields.name "ProductID,ProductName" \
  --fields.alias "product_id,product_name" \
  --fields.description "Unique identifier for each product,Display name of the product" \
  --fields.primary-key "true,false"

Wynikowa konfiguracja

Uwaga / Notatka

W bieżącej wersji 2.0.0-rc interfejs wiersza polecenia akceptuje --fields.namewartości , --fields.alias--fields.description, i--fields.primary-key, ale nie utrwala jeszcze metadanych pól na poziomie jednostki do pliku konfiguracji. Zespół spodziewa się rozwiązać to zachowanie przed ga.

--fields.alias

Alias pola. Użyj listy rozdzielanej przecinkami wyrównanej do --fields.name.

Uwaga / Notatka

Ta opcja jest dostępna w interfejsie 2.0.0-rc wiersza polecenia. Konstruktor interfejsu API danych 2.0 jest obecnie w wersji zapoznawczej. Zainstaluj za pomocą polecenia dotnet tool install microsoft.dataapibuilder --version 2.0.0-rc --prerelease.

Example

dab add Products \
  --source dbo.Products \
  --permissions "anonymous:*" \
  --fields.name "ProductID" \
  --fields.alias "product_id"

--fields.description

Opis pola. Użyj listy rozdzielanej przecinkami wyrównanej do --fields.name.

Uwaga / Notatka

Ta opcja jest dostępna w interfejsie 2.0.0-rc wiersza polecenia. Konstruktor interfejsu API danych 2.0 jest obecnie w wersji zapoznawczej. Zainstaluj za pomocą polecenia dotnet tool install microsoft.dataapibuilder --version 2.0.0-rc --prerelease.

Example

dab add Products \
  --source dbo.Products \
  --permissions "anonymous:*" \
  --fields.name "ProductID" \
  --fields.description "Unique identifier"

--fields.primary-key

Flaga klucza podstawowego dla pola. Użyj rozdzielanej przecinkami listy true/false wartości wyrównanych do .--fields.name

Uwaga / Notatka

Ta opcja jest dostępna w interfejsie 2.0.0-rc wiersza polecenia. Konstruktor interfejsu API danych 2.0 jest obecnie w wersji zapoznawczej. Zainstaluj za pomocą polecenia dotnet tool install microsoft.dataapibuilder --version 2.0.0-rc --prerelease.

Example

dab add Products \
  --source dbo.Products \
  --permissions "anonymous:*" \
  --fields.name "ProductID" \
  --fields.primary-key "true"

Uwaga / Notatka

W bieżącej wersji 2.0.0-rc interfejs wiersza polecenia akceptuje --fields.primary-key , ale nie utrwala jeszcze metadanych pola na poziomie jednostki do pliku konfiguracji. Aby określić pola klucza podstawowego dla widoków, użyj --source.key-fields zamiast tego.

--graphql

Kontrolowanie ekspozycji GraphQL.

Example

dab add Book \
  --source dbo.Books \
  --permissions "anonymous:read" \
  --graphql book:books

Wynikowa konfiguracja

{
  "entities": {
    "Book": {
      "source": { "type": "table", "object": "dbo.Books" },
      "permissions": [
        { "role": "anonymous", "actions": [ { "action": "read" } ] }
      ],
      "graphql": {
        "enabled": true,
        "type": {
          "singular": "book",
          "plural": "books"
        }
      }
    }
  }
}

--graphql.operation

Tylko procedury składowane. Typ operacji GraphQL. Wartość domyślna to mutation.

Example

dab add BookProc \
  --source dbo.MyProc \
  --source.type stored-procedure \
  --permissions "admin:execute" \
  --graphql.operation Query

Wynikowa konfiguracja

{
  "entities": {
    "BookProc": {
      "source": { "type": "stored-procedure", "object": "dbo.MyProc" },
      "permissions": [
        { "role": "admin", "actions": [ { "action": "execute" } ] }
      ],
      "graphql": {
        "enabled": true,
        "operation": "query",
        "type": {
          "singular": "BookProc",
          "plural": "BookProcs"
        }
      }
    }
  }
}

--rest

Kontrolowanie ekspozycji REST.

Example

dab add Book \
  --source dbo.Books \
  --permissions "anonymous:read" \
  --rest BooksApi

Wynikowa konfiguracja

{
  "entities": {
    "Book": {
      "source": { "type": "table", "object": "dbo.Books" },
      "permissions": [
        { "role": "anonymous", "actions": [ { "action": "read" } ] }
      ],
      "rest": {
        "enabled": true,
        "path": "/BooksApi"
      }
    }
  }
}

--rest.methods

Tylko procedury składowane. Czasowniki HTTP dozwolone do wykonywania: GET, , POST, PUTPATCH, . DELETE Domyślnie jest to POST. Ignorowane dla tabel/widoków.

Example

dab add BookProc \
  --source dbo.MyProc \
  --source.type stored-procedure \
  --permissions "admin:execute" \
  --rest true \
  --rest.methods GET,POST

Wynikowa konfiguracja

{
  "entities": {
    "BookProc": {
      "source": { "type": "stored-procedure", "object": "dbo.MyProc" },
      "permissions": [
        { "role": "admin", "actions": [ { "action": "execute" } ] }
      ],
      "rest": {
        "enabled": true,
        "methods": [ "get", "post" ]
      }
    }
  }
}

--mcp.dml-tools

Włącz lub wyłącz narzędzia DML dla tej jednostki w programie MCP. Wartość domyślna: true. Gdy jest ustawiona wartość false, jednostka jest wykluczona z powierzchni narzędzia MCP DML. W przypadku mcp całkowitego pominięcia narzędzia DML są domyślnie włączone.

Uwaga / Notatka

Funkcja narzędzia Data API Builder 2.0 opisana w tej sekcji jest obecnie dostępna w wersji zapoznawczej i może ulec zmianie przed ogólną dostępnością. Aby uzyskać więcej informacji, zobacz Co nowego w wersji 2.0.

Example

dab add Book \
  --source dbo.Books \
  --permissions "anonymous:read" \
  --mcp.dml-tools true

Wynikowa konfiguracja

{
  "entities": {
    "Book": {
      "source": {
        "type": "table",
        "object": "dbo.Books"
      },
      "permissions": [
        { "role": "anonymous", "actions": [ { "action": "read" } ] }
      ],
      "mcp": {
        "dml-tools": true
      }
    }
  }
}

--mcp.custom-tool

Zarejestruj jednostkę procedury składowanej jako nazwane narzędzie MCP. Prawidłowy tylko wtedy, gdy --source.type ma wartość stored-procedure. Gdy trueprogram DAB dynamicznie rejestruje procedurę w odpowiedzi MCP tools/list , a agenci mogą wywołać ją za pomocą metody tools/call.

Example

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

Wynikowa konfiguracja

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

Ważna

--mcp.custom-tool jest prawidłowy tylko w przypadku jednostek procedury składowanej. Użycie jej z tabelą lub wyświetlaniem jednostek powoduje błąd weryfikacji.

--permissions

Definiuje pary ról→akcje.

--permissions nie jest powtarzalny. Aby dodać więcej ról, uruchom polecenie dab add z jedną rolą, a następnie uruchom dab update polecenie w celu uzyskania większej liczby ról.

Example

dab add Book \
  --source dbo.Books \
  --permissions "anonymous:read"

dab update Book \
  --permissions "authenticated:create,read,update,delete"

--policy-database

Zasady na poziomie bazy danych.

Example

dab add Book \
  --source dbo.Books \
  --permissions "anonymous:read" \
  --policy-database "region eq 'US'"

Wynikowa konfiguracja

{
  "entities": {
    "Book": {
      "source": { "type": "table", "object": "dbo.Books" },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "region eq 'US'"
              }
            }
          ]
        }
      ]
    }
  }
}

--policy-request

Zasady na poziomie żądania.

Example

dab add Book \
  --source dbo.Books \
  --permissions "anonymous:read" \
  --policy-request "@claims.role == 'admin'"

Wynikowa konfiguracja

{
  "entities": {
    "Book": {
      "source": { "type": "table", "object": "dbo.Books" },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "policy": {
                "request": "@claims.role == 'admin'"
              }
            }
          ]
        }
      ]
    }
  }
}

--help

Wyświetl ten ekran pomocy.

Example

dab add \
  --help

--version

Wyświetl informacje o wersji.

Example

dab add \
  --version
  • Last updated on