Compartir a través de

Comando add

Agregue una nueva definición de entidad a un archivo de configuración de Data API Builder existente. Ya debe tener una configuración creada con dab init. Use dab update para modificar las entidades después de la creación.

Sugerencia

Use dab add para crear nuevas entidades y dab update para evolucionarlas.

Syntax

dab add <entity-name> [options]

Vista rápida

Opción Resumen
-c, --config Ruta de acceso del archivo de configuración. El valor predeterminado es dab-config.json.

Sección principal

Opción Resumen
<entity-name> Argumento posicional requerido. Nombre de entidad lógica.
-s, --source Obligatorio. Nombre del objeto de base de datos (tabla, vista o procedimiento almacenado).
--source.type Tipo de origen: table, view, stored-procedure (tabla predeterminada).
--source.key-fields Campos de clave principal para vistas (separados por comas).
--source.params Solo procedimientos almacenados. Valores de parámetro predeterminados como param1:val1,param2:val2.

Sección caché

Opción Resumen
--cache.enabled Habilite o deshabilite el almacenamiento en caché para la entidad.
--cache.ttl Tiempo de vida en caché en segundos.
--description Descripción de forma libre para la entidad.

Sección Parámetros

Opción Resumen
--parameters.name Solo procedimientos almacenados. Nombres de parámetro (separados por comas).
--parameters.description Solo procedimientos almacenados. Descripciones de parámetros.
--parameters.required Solo procedimientos almacenados. Marcas necesarias para parámetros.
--parameters.default Solo procedimientos almacenados. Valores predeterminados del parámetro.

Sección Campos

Opción Resumen
--fields.exclude Campos excluidos separados por comas.
--fields.include Campos permitidos separados por comas (* = todos).
--fields.name Nombres de campo que se describen (repetibles o separados por comas).
--fields.alias Alias de campo (separados por comas, alineados con --fields.name).
--fields.description Descripciones de campo (separadas por comas, alineadas con --fields.name).
--fields.primary-key Marcas de clave principales (separadas por comas, alineadas con --fields.name).

Sección DE API

Opción Resumen
--graphql Exposición de GraphQL: false, true, singularo singular:plural.
--graphql.operation Solo procedimientos almacenados. Query o Mutation (mutación predeterminada).
--rest Exposición de REST: false, trueo ruta personalizada.
--rest.methods Solo procedimientos almacenados. Verbos permitidos: GET, POST, PUT, PATCH, DELETE. POST predeterminado.
--mcp.dml-tools Habilite o deshabilite las herramientas del lenguaje de manipulación de datos (DML) para la entidad en el Protocolo de contexto de modelo (MCP). El valor predeterminado es true.
--mcp.custom-tool Solo procedimientos almacenados. Regístrese como una herramienta MCP con nombre.

Sección Permisos

Opción Resumen
--permissions Obligatorio. role:actions para un solo rol.
--policy-database Filtro de estilo OData aplicado en la consulta de base de datos.
--policy-request Directiva de solicitud evaluada antes de llamar a la base de datos.

<entity-name>

Nombre lógico de la entidad en la configuración. Distingue mayúsculas de minúsculas.

Ejemplos rápidos de tablas, vistas y procedimientos almacenados

Agregar una tabla

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

Agregar una vista

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"

Adición de un procedimiento almacenado

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

Ruta de acceso del archivo de configuración. El valor predeterminado es dab-config.json.

Example

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

-s, --source

Obligatorio. Nombre del objeto de base de datos: tabla, vista, contenedor o procedimiento almacenado.

Example

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

Configuración resultante

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

--source.type

Tipo de objeto de base de datos. Predeterminado: table.

Example

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

Configuración resultante

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

--source.key-fields

Uno o varios campos que se van a usar como claves principales. Las vistas carecen de claves principales intrínsecas, por lo que debe especificar explícitamente campos de clave.

Example

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

Configuración resultante

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

--source.params

Diccionario de parámetros y sus valores predeterminados para los procedimientos almacenados. Use el 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"

Configuración 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

Habilite o deshabilite el almacenamiento en caché.

Example

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

Configuración resultante

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

--cache.ttl

Tiempo de vida en caché en segundos.

Example

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

Configuración resultante

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

--description

Descripción de texto libre de la entidad.

Nota:

Esta opción está disponible en la 2.0.0-rc CLI. Data API Builder 2.0 está actualmente en versión preliminar. Instale con 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"

Configuración resultante

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

--parameters.name

Solo procedimientos almacenados. Lista separada por comas de nombres de parámetros.

Nota:

Esta opción está disponible en la 2.0.0-rc CLI. Data API Builder 2.0 está actualmente en versión preliminar. Instale con 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"

Configuración 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

Solo procedimientos almacenados. Lista separada por comas de descripciones de parámetros alineadas con --parameters.name.

Nota:

Esta opción está disponible en la 2.0.0-rc CLI. Data API Builder 2.0 está actualmente en versión preliminar. Instale con 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

Solo procedimientos almacenados. Lista separada por comas de true/false valores alineados con .--parameters.name

Nota:

Esta opción está disponible en la 2.0.0-rc CLI. Data API Builder 2.0 está actualmente en versión preliminar. Instale con 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

Solo procedimientos almacenados. Lista separada por comas de valores predeterminados alineados con --parameters.name.

Nota:

Esta opción está disponible en la 2.0.0-rc CLI. Data API Builder 2.0 está actualmente en versión preliminar. Instale con 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 comas de campos que se van a excluir.

Example

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

Configuración 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 comas de campos que se van a exponer.

Example

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

Configuración resultante

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

--fields.name

Nombre de la columna de base de datos que se va a describir.

Nota:

Esta opción está disponible en la 2.0.0-rc CLI. Data API Builder 2.0 está actualmente en versión preliminar. Instale con 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"

Configuración resultante

Nota:

En la versión actual de 2.0.0-rc, la CLI acepta , --fields.alias, --fields.descriptiony --fields.primary-key pero aún no conserva los metadatos --fields.namede campo de nivel de entidad en el archivo de configuración. El equipo espera resolver este comportamiento antes de la disponibilidad general.

--fields.alias

Alias para el campo. Use una lista separada por comas alineada con --fields.name.

Nota:

Esta opción está disponible en la 2.0.0-rc CLI. Data API Builder 2.0 está actualmente en versión preliminar. Instale con 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

Descripción del campo. Use una lista separada por comas alineada con --fields.name.

Nota:

Esta opción está disponible en la 2.0.0-rc CLI. Data API Builder 2.0 está actualmente en versión preliminar. Instale con 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

Marca de clave principal para el campo. Use una lista separada por comas de true/false valores alineados con .--fields.name

Nota:

Esta opción está disponible en la 2.0.0-rc CLI. Data API Builder 2.0 está actualmente en versión preliminar. Instale con 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"

Nota:

En la versión actual de 2.0.0-rc, la CLI acepta pero aún no conserva los metadatos --fields.primary-key de campo de nivel de entidad en el archivo de configuración. Para especificar los campos de clave principal para las vistas, use --source.key-fields en su lugar.

--graphql

Controlar la exposición de GraphQL.

Example

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

Configuración 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

Solo procedimientos almacenados. Tipo de operación GraphQL. El valor predeterminado es mutation.

Example

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

Configuración 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 la exposición de REST.

Example

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

Configuración resultante

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

--rest.methods

Solo procedimientos almacenados. Verbos HTTP permitidos para la ejecución: GET, POST, PUT, PATCH, DELETE. El valor predeterminado es POST. Se omite para las tablas o vistas.

Example

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

Configuración 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 o deshabilite las herramientas DML para esta entidad en MCP. Predeterminado: true. Cuando se establece en false, la entidad se excluye de la superficie de herramientas de MCP DML. Cuando mcp se omite por completo, las herramientas DML están habilitadas de forma predeterminada.

Nota:

La funcionalidad de Data API Builder 2.0 descrita en esta sección se encuentra actualmente en versión preliminar y podría cambiar antes de la disponibilidad general. Para obtener más información, consulte Novedades de la versión 2.0.

Example

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

Configuración resultante

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

--mcp.custom-tool

Registre una entidad de procedimiento almacenado como una herramienta MCP con nombre. Válido solo cuando --source.type es stored-procedure. Cuando true, DAB registra dinámicamente el procedimiento en la respuesta mcP tools/list y los agentes pueden llamarlo a través de tools/call.

Example

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

Configuración 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 solo es válido para las entidades de procedimiento almacenado. Su uso con entidades de tabla o vista provoca un error de validación.

--permissions

Define pares role→actions.

--permissions no se puede repetir. Para agregar más roles, ejecute dab add con un rol y, a continuación, ejecute dab update para más roles.

Example

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

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

--policy-database

Directiva de nivel de base de datos.

Example

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

Configuración resultante

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

--policy-request

Directiva de nivel de solicitud.

Example

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

Configuración resultante

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

--help

Muestra esta pantalla de ayuda.

Example

dab add \
  --help

--version

Mostrar información de versión.

Example

dab add \
  --version
  • Last updated on