Команда add

Добавьте новое определение сущности в существующий файл конфигурации построителя данных. У вас уже должна быть конфигурация, созданная с dab initпомощью . Используется dab update для изменения сущностей после создания.

Подсказка

Используется dab add для создания новых сущностей и dab update их развития.

Синтаксис

dab add <entity-name> [options]

Краткий обзор

Вариант Сводка
-c, --config Путь к файлу конфигурации. dab-config.jsonпо умолчанию.

Раздел "Головка"

Вариант Сводка
<entity-name> Обязательный позиционный аргумент. Имя логической сущности.
-s, --source Обязательное. Имя объекта базы данных (таблица, представление или хранимая процедура).
--source.type Тип источника: table, viewstored-procedure (таблица по умолчанию).
--source.key-fields Поля первичного ключа для представлений (разделенные запятыми).
--source.params Хранимые процедуры только. Значения параметров по умолчанию .param1:val1,param2:val2

Раздел кэша

Вариант Сводка
--cache.enabled Включение и отключение кэширования для сущности.
--cache.ttl Кэшируйте время в секундах.
--description Описание свободной формы для сущности.

Раздел параметров

Вариант Сводка
--parameters.name Хранимые процедуры только. Имена параметров (разделенные запятыми).
--parameters.description Хранимые процедуры только. Описания параметров.
--parameters.required Хранимые процедуры только. Обязательные флаги параметра.
--parameters.default Хранимые процедуры только. Значения по умолчанию параметра.

Раздел "Поля"

Вариант Сводка
--fields.exclude Разделенные запятыми поля.
--fields.include Разрешенные поля с разделим запятыми (* = все).
--fields.name Имена полей для описания (повторяемые или разделенные запятыми).
--fields.alias Псевдонимы полей (разделенные запятыми, выровнены по краю --fields.name).
--fields.description Описания полей (разделенные запятыми, выровненные по краю --fields.name).
--fields.primary-key Флаги первичного ключа (разделенные запятыми, выровнены по краю --fields.name).

Раздел API

Вариант Сводка
--graphql Экспозиция GraphQL: false, true, singularили singular:plural.
--graphql.operation Хранимые процедуры только. Query или Mutation (мутация по умолчанию).
--rest Экспозиция REST: false, trueили настраиваемый маршрут.
--rest.methods Хранимые процедуры только. Допустимые команды: GET, POST, PUTPATCH, DELETE. По умолчанию POST.
--mcp.dml-tools Включение и отключение средств языка обработки данных (DML) для сущности в протоколе контекста модели (MCP). trueпо умолчанию.
--mcp.custom-tool Хранимые процедуры только. Зарегистрируйтесь как именованное средство MCP.

Раздел "Разрешения"

Вариант Сводка
--permissions Обязательное. role:actions для одной роли.
--policy-database Фильтр в стиле OData, применяемый в запросе к базе данных.
--policy-request Политика запроса, вычисляемая перед вызовом базы данных.

<entity-name>

Логическое имя сущности в конфигурации. Учитывает регистр.

Краткие примеры таблиц, представлений и хранимых процедур

Добавление таблицы

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

Добавить представление

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"

Добавление хранимой процедуры

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

Путь к файлу конфигурации. По умолчанию — dab-config.json.

Example

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

-s, --source

Обязательное. Имя объекта базы данных: таблица, представление, контейнер или хранимая процедура.

Example

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

Результирующая конфигурация

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

--source.type

Тип объекта базы данных. По умолчанию: table.

Example

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

Результирующая конфигурация

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

--source.key-fields

Одно или несколько полей для использования в качестве первичных ключей. Представления не имеют встроенных первичных ключей, поэтому необходимо явно указать поля ключей.

Example

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

Результирующая конфигурация

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

--source.params

Словарь параметров и их значения по умолчанию для хранимых процедур. Используйте формат param1:val1,param2:val2.

Example

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

Результирующая конфигурация

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

Включение или отключение кэширования.

Example

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

Результирующая конфигурация

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

--cache.ttl

Кэшируйте время в секундах.

Example

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

Результирующая конфигурация

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

--description

Описание сущности без текста.

Замечание

Этот параметр доступен в интерфейсе командной 2.0.0-rc строки. Построитель данных 2.0 в настоящее время находится в предварительной версии. Установите с 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"

Результирующая конфигурация

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

--parameters.name

Хранимые процедуры только. Разделенный запятыми список имен параметров.

Замечание

Этот параметр доступен в интерфейсе командной 2.0.0-rc строки. Построитель данных 2.0 в настоящее время находится в предварительной версии. Установите с 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"

Результирующая конфигурация

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

Хранимые процедуры только. Разделенный запятыми список описаний параметров, выровненных по значению --parameters.name.

Замечание

Этот параметр доступен в интерфейсе командной 2.0.0-rc строки. Построитель данных 2.0 в настоящее время находится в предварительной версии. Установите с 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

Хранимые процедуры только. Разделенный запятыми список значенийtrue/false, выровненных по значению.--parameters.name

Замечание

Этот параметр доступен в интерфейсе командной 2.0.0-rc строки. Построитель данных 2.0 в настоящее время находится в предварительной версии. Установите с 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

Хранимые процедуры только. Разделенный запятыми список значений по умолчанию, выровненных по --parameters.nameумолчанию.

Замечание

Этот параметр доступен в интерфейсе командной 2.0.0-rc строки. Построитель данных 2.0 в настоящее время находится в предварительной версии. Установите с 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

Разделенный запятыми список полей, которые необходимо исключить.

Example

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

Результирующая конфигурация

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

--fields.include

Разделенный запятыми список полей для предоставления.

Example

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

Результирующая конфигурация

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

--fields.name

Имя столбца базы данных для описания.

Замечание

Этот параметр доступен в интерфейсе командной 2.0.0-rc строки. Построитель данных 2.0 в настоящее время находится в предварительной версии. Установите с 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"

Результирующая конфигурация

Замечание

В текущем выпуске 2.0.0-rc интерфейс командной строки принимает --fields.name, --fields.alias--fields.descriptionи --fields.primary-key пока не сохраняет метаданные поля уровня сущности в файле конфигурации. Команда ожидает устранить это поведение до общедоступной версии.

--fields.alias

Псевдоним поля. Используйте разделенный запятыми список.--fields.name

Замечание

Этот параметр доступен в интерфейсе командной 2.0.0-rc строки. Построитель данных 2.0 в настоящее время находится в предварительной версии. Установите с 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

Описание поля. Используйте разделенный запятыми список.--fields.name

Замечание

Этот параметр доступен в интерфейсе командной 2.0.0-rc строки. Построитель данных 2.0 в настоящее время находится в предварительной версии. Установите с 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

Флаг первичного ключа для поля. Используйте разделенный запятыми список значенийtrue/false, выровненных по значению.--fields.name

Замечание

Этот параметр доступен в интерфейсе командной 2.0.0-rc строки. Построитель данных 2.0 в настоящее время находится в предварительной версии. Установите с 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"

Замечание

В текущем выпуске 2.0.0-rc CLI принимает --fields.primary-key , но пока не сохраняет метаданные поля уровня сущности в файле конфигурации. Чтобы указать поля первичного ключа для представлений, используйте --source.key-fields вместо этого.

--graphql

Управление экспозицией GraphQL.

Example

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

Результирующая конфигурация

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

--graphql.operation

Хранимые процедуры только. Тип операции GraphQL. По умолчанию — mutation.

Example

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

Результирующая конфигурация

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

Управление экспозицией REST.

Example

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

Результирующая конфигурация

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

--rest.methods

Хранимые процедуры только. Http-команды, разрешенные для выполнения: GET, POST, PUT, PATCHDELETE. По умолчанию используется POST. Игнорируется для таблиц и представлений.

Example

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

Результирующая конфигурация

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

--mcp.dml-tools

Включите или отключите средства DML для этой сущности в MCP. По умолчанию: true. Если задано значение false, сущность исключается из области инструментов MCP DML. Если mcp опущено полностью, средства DML включены по умолчанию.

Замечание

Функции построителя данных 2.0, описанные в этом разделе, находятся в предварительной версии и могут измениться до общедоступной доступности. Дополнительные сведения см. в статье "Новые возможности" версии 2.0.

Example

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

Результирующая конфигурация

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

--mcp.custom-tool

Зарегистрируйте сущность хранимой процедуры в качестве именованного средства MCP. Допустимо только в том stored-procedureслучае--source.type. Когда trueDAB динамически регистрирует процедуру в ответе MCP tools/list и агенты могут вызывать ее через tools/call.

Example

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

Результирующая конфигурация

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

Это важно

--mcp.custom-tool допустимо только для сущностей хранимой процедуры. Использование его с сущностями таблицы или представления приводит к ошибке проверки.

--permissions

Определяет пары ролей→actions.

--permissions не повторяется. Чтобы добавить дополнительные роли, запустите dab add с одной ролью, а затем запустите dab update для дополнительных ролей.

Example

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

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

--policy-database

Политика уровня базы данных.

Example

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

Результирующая конфигурация

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

--policy-request

Политика уровня запроса.

Example

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

Результирующая конфигурация

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

--help

Отобразите этот экран справки.

Example

dab add \
  --help

--version

Отображение сведений о версии.

Example

dab add \
  --version
  • Last updated on