Compartilhar via

add comando

Adicione uma nova definição de entidade a um arquivo de configuração existente do construtor de API de Dados. Você já deve ter uma configuração criada com dab init. Use dab update para modificar entidades após a criação.

Dica

Use dab add para criar novas entidades e dab update evoluí-las.

Sintaxe

dab add <entity-name> [options]

Olhar rápido

Opção Resumo
-c, --config Caminho do arquivo de configuração. Padrão dab-config.json.

Seção Cabeçalho

Opção Resumo
<entity-name> Argumento posicional necessário. Nome da entidade lógica.
-s, --source Obrigatório Nome do objeto de banco de dados (tabela, exibição ou procedimento armazenado).
--source.type Tipo de origem: table, view, stored-procedure (tabela padrão).
--source.key-fields Campos de chave primária para exibições (separados por vírgulas).
--source.params Somente procedimentos armazenados. Valores de parâmetro padrão como param1:val1,param2:val2.

Seção Cache

Opção Resumo
--cache.enabled Habilitar/desabilitar o cache para a entidade.
--cache.ttl Tempo de vida útil do cache em segundos.
--description Descrição de formulário livre para a entidade.

Seção Parâmetros

Opção Resumo
--parameters.name Somente procedimentos armazenados. Nomes de parâmetro (separados por vírgulas).
--parameters.description Somente procedimentos armazenados. Descrições de parâmetro.
--parameters.required Somente procedimentos armazenados. Sinalizadores necessários para parâmetros.
--parameters.default Somente procedimentos armazenados. Valores padrão do parâmetro.

Seção Campos

Opção Resumo
--fields.exclude Campos excluídos separados por vírgulas.
--fields.include Campos permitidos separados por vírgulas (* = todos).
--fields.name Nomes de campo a serem descritos (repetíveis ou separados por vírgulas).
--fields.alias Aliases de campo (separados por vírgulas, alinhados a --fields.name).
--fields.description Descrições de campo (separadas por vírgula, alinhadas a --fields.name).
--fields.primary-key Sinalizadores de chave primária (separados por vírgula, alinhados a --fields.name).

Seção API

Opção Resumo
--graphql Exposição do GraphQL: false, , true, singularou singular:plural.
--graphql.operation Somente procedimentos armazenados. Query ou Mutation (mutação padrão).
--rest Exposição REST: false, trueou rota personalizada.
--rest.methods Somente procedimentos armazenados. Verbos permitidos: GET, , POST, PUT, PATCH. DELETE POST padrão.
--mcp.dml-tools Habilitar/desabilitar ferramentas de DML (linguagem de manipulação de dados) para entidade no Protocolo de Contexto de Modelo (MCP). Padrão true.
--mcp.custom-tool Somente procedimentos armazenados. Registre-se como uma ferramenta MCP nomeada.

Seção Permissões

Opção Resumo
--permissions Obrigatório role:actions para uma única função.
--policy-database Filtro no estilo OData aplicado na consulta de banco de dados.
--policy-request Política de solicitação avaliada antes da chamada de banco de dados.

<entity-name>

Nome lógico da entidade em configuração. Diferencia maiúsculas de minúsculas.

Exemplos rápidos para tabelas, exibições e procedimentos armazenados

Adicionar uma tabela

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

Adicionar uma exibição

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"

Adicionar um procedimento armazenado

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

Caminho do arquivo de configuração. O padrão é dab-config.json.

Example

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

-s, --source

Obrigatório Nome do objeto de banco de dados: tabela, exibição, contêiner ou procedimento armazenado.

Example

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

Configuração resultante

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

--source.type

Tipo de objeto de banco de dados. Padrão: table.

Example

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

Configuração resultante

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

--source.key-fields

Um ou mais campos a serem usados como chaves primárias. As exibições não têm chaves primárias intrínsecas, portanto, você deve especificar campos de chave explicitamente.

Example

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

Configuração resultante

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

--source.params

Dicionário de parâmetros e seus valores padrão para procedimentos armazenados. Use o formato param1:val1,param2:val2.

Example

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

Configuração resultante

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

Habilitar ou desabilitar o cache.

Example

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

Configuração resultante

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

--cache.ttl

Tempo de vida útil do cache em segundos.

Example

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

Configuração resultante

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

--description

Descrição de texto livre da entidade.

Observação

Essa opção está disponível na 2.0.0-rc CLI. O Construtor de API de Dados 2.0 está atualmente em versão prévia. Instalar com 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"

Configuração resultante

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

--parameters.name

Somente procedimentos armazenados. Lista separada por vírgulas de nomes de parâmetros.

Observação

Essa opção está disponível na 2.0.0-rc CLI. O Construtor de API de Dados 2.0 está atualmente em versão prévia. Instalar com 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"

Configuração resultante

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

Somente procedimentos armazenados. Lista separada por vírgulas de descrições de parâmetro alinhadas a --parameters.name.

Observação

Essa opção está disponível na 2.0.0-rc CLI. O Construtor de API de Dados 2.0 está atualmente em versão prévia. Instalar com 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

Somente procedimentos armazenados. Lista separada por vírgulas de true/false valores alinhados a --parameters.name.

Observação

Essa opção está disponível na 2.0.0-rc CLI. O Construtor de API de Dados 2.0 está atualmente em versão prévia. Instalar com 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

Somente procedimentos armazenados. Lista separada por vírgulas de valores padrão alinhados a --parameters.name.

Observação

Essa opção está disponível na 2.0.0-rc CLI. O Construtor de API de Dados 2.0 está atualmente em versão prévia. Instalar com 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

Lista separada por vírgulas de campos a serem excluídos.

Example

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

Configuração resultante

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

--fields.include

Lista separada por vírgulas de campos a serem expostos.

Example

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

Configuração resultante

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

--fields.name

Nome da coluna de banco de dados a ser descrita.

Observação

Essa opção está disponível na 2.0.0-rc CLI. O Construtor de API de Dados 2.0 está atualmente em versão prévia. Instalar com 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"

Configuração resultante

Observação

Na versão atual do 2.0.0-rc, a CLI aceita--fields.name, --fields.alias--fields.descriptione --fields.primary-key ainda não persiste metadados de campo no nível da entidade para o arquivo de configuração. A equipe espera resolver esse comportamento antes da GA.

--fields.alias

Alias para o campo. Use uma lista separada por vírgulas alinhada a --fields.name.

Observação

Essa opção está disponível na 2.0.0-rc CLI. O Construtor de API de Dados 2.0 está atualmente em versão prévia. Instalar com 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

Descrição do campo. Use uma lista separada por vírgulas alinhada a --fields.name.

Observação

Essa opção está disponível na 2.0.0-rc CLI. O Construtor de API de Dados 2.0 está atualmente em versão prévia. Instalar com 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

Sinalizador de chave primária para o campo. Use uma lista separada por vírgulas de true/false valores alinhados a --fields.name.

Observação

Essa opção está disponível na 2.0.0-rc CLI. O Construtor de API de Dados 2.0 está atualmente em versão prévia. Instalar com 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"

Observação

Na versão atual do 2.0.0-rc, a CLI aceita --fields.primary-key , mas ainda não persiste metadados de campo no nível da entidade para o arquivo de configuração. Para especificar campos de chave primária para exibições, use --source.key-fields em vez disso.

--graphql

Controlar a exposição do GraphQL.

Example

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

Configuração resultante

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

--graphql.operation

Somente procedimentos armazenados. Tipo de operação GraphQL. O padrão é mutation.

Example

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

Configuração resultante

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

Controlar a exposição rest.

Example

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

Configuração resultante

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

--rest.methods

Somente procedimentos armazenados. Verbos HTTP permitidos para execução: GET, , POST, PUT, PATCH, DELETE. O padrão é POST. Ignorado para tabelas/exibições.

Example

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

Configuração resultante

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

--mcp.dml-tools

Habilite ou desabilite as ferramentas DML para essa entidade no MCP. Padrão: true. Quando definido como false, a entidade é excluída da superfície da ferramenta DML do MCP. Quando mcp é omitido inteiramente, as ferramentas DML são habilitadas por padrão.

Observação

A funcionalidade do Construtor de API de Dados 2.0 descrita nesta seção está atualmente em versão prévia e pode ser alterada antes da disponibilidade geral. Para obter mais informações, consulte o que há de novo na versão 2.0.

Example

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

Configuração resultante

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

--mcp.custom-tool

Registre uma entidade de procedimento armazenado como uma ferramenta MCP nomeada. Válido somente quando --source.type for stored-procedure. Quando trueo DAB registra dinamicamente o procedimento na resposta mcp tools/list e os agentes podem chamá-lo por meio tools/callde .

Example

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

Configuração resultante

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

Importante

--mcp.custom-tool é válido apenas para entidades de procedimento armazenado. Usá-lo com entidades de tabela ou exibição causa um erro de validação.

--permissions

Define pares role→actions.

--permissions não é repetível. Para adicionar mais funções, execute dab add com uma função e execute dab update para obter mais funções.

Example

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

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

--policy-database

Política no nível do banco de dados.

Example

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

Configuração resultante

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

--policy-request

Política no nível da solicitação.

Example

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

Configuração resultante

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

--help

Exibir esta tela de ajuda.

Example

dab add \
  --help

--version

Exibir informações de versão.

Example

dab add \
  --version
  • Last updated on