Condividi tramite

add comando

Aggiungere una nuova definizione di entità a un file di configurazione di Generatore API dati esistente. È necessario avere già una configurazione creata con dab init. Usare dab update per modificare le entità dopo la creazione.

Suggerimento

Usare dab add per creare nuove entità e dab update per evolverle.

Sintassi

dab add <entity-name> [options]

Sguardo rapido

Opzione Riassunto
-c, --config Percorso del file di configurazione. Valore predefinito dab-config.json.

Sezione head

Opzione Riassunto
<entity-name> Argomento posizionale obbligatorio. Nome dell'entità logica.
-s, --source Obbligatorio. Nome dell'oggetto di database (tabella, vista o stored procedure).
--source.type Tipo di origine: table, view, stored-procedure (tabella predefinita).
--source.key-fields Campi chiave primaria per le visualizzazioni (delimitati da virgole).
--source.params Solo stored procedure. I valori predefiniti dei parametri sono param1:val1,param2:val2.

Sezione Cache

Opzione Riassunto
--cache.enabled Abilitare/disabilitare la memorizzazione nella cache per l'entità.
--cache.ttl Tempo di memorizzazione nella cache in secondi.
--description Descrizione in formato libero per l'entità.

Sezione Parametri

Opzione Riassunto
--parameters.name Solo stored procedure. Nomi di parametro (delimitati da virgole).
--parameters.description Solo stored procedure. Descrizioni dei parametri.
--parameters.required Solo stored procedure. Flag obbligatori dei parametri.
--parameters.default Solo stored procedure. Valori predefiniti dei parametri.

Sezione Campi

Opzione Riassunto
--fields.exclude Campi esclusi delimitati da virgole.
--fields.include Campi consentiti delimitati da virgole (* = all).
--fields.name Nomi di campo da descrivere (ripetibili o delimitati da virgole).
--fields.alias Alias di campo (delimitati da virgole, allineati a --fields.name).
--fields.description Descrizioni dei campi (delimitate da virgole, allineate a --fields.name).
--fields.primary-key Flag di chiave primaria (delimitati da virgole, allineati a --fields.name).

Sezione API

Opzione Riassunto
--graphql Esposizione graphQL: false, true, singularo singular:plural.
--graphql.operation Solo stored procedure. Query o Mutation (mutazione predefinita).
--rest Esposizione REST: false, trueo route personalizzata.
--rest.methods Solo stored procedure. Verbi consentiti: GET, POST, PUTPATCH, , DELETE. POST predefinito.
--mcp.dml-tools Abilitare/disabilitare gli strumenti DML (Data Manipulation Language) per l'entità nel protocollo MCP (Model Context Protocol). Valore predefinito true.
--mcp.custom-tool Solo stored procedure. Eseguire la registrazione come strumento MCP denominato.

Sezione Autorizzazioni

Opzione Riassunto
--permissions Obbligatorio. role:actions per un singolo ruolo.
--policy-database Filtro in stile OData applicato nella query del database.
--policy-request Criteri di richiesta valutati prima della chiamata al database.

<entity-name>

Nome logico dell'entità nella configurazione. Distinzione tra maiuscole e minuscole.

Esempi rapidi per tabelle, viste e stored procedure

Aggiungere una tabella

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

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

Aggiungere una stored procedure

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

Percorso del file di configurazione. Il valore predefinito è dab-config.json.

Example

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

-s, --source

Obbligatorio. Nome dell'oggetto di database: tabella, vista, contenitore o stored procedure.

Example

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

Configurazione risultante

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

--source.type

Tipo di oggetto di database. Impostazione predefinita: table.

Example

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

Configurazione risultante

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

--source.key-fields

Uno o più campi da usare come chiavi primarie. Le visualizzazioni non dispongono di chiavi primarie intrinseche, pertanto è necessario specificare i campi chiave in modo esplicito.

Example

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

Configurazione risultante

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

--source.params

Dizionario dei parametri e dei relativi valori predefiniti per le stored procedure. Usare il formatoparam1:val1,param2:val2.

Example

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

Configurazione risultante

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

Abilitare o disabilitare la memorizzazione nella cache.

Example

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

Configurazione risultante

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

--cache.ttl

Tempo di memorizzazione nella cache in secondi.

Example

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

Configurazione risultante

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

--description

Descrizione in formato libero dell'entità.

Annotazioni

Questa opzione è disponibile nell'interfaccia della 2.0.0-rc riga di comando. Il generatore di API dati 2.0 è attualmente in anteprima. Eseguire l'installazione 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"

Configurazione risultante

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

--parameters.name

Solo stored procedure. Elenco delimitato da virgole di nomi di parametri.

Annotazioni

Questa opzione è disponibile nell'interfaccia della 2.0.0-rc riga di comando. Il generatore di API dati 2.0 è attualmente in anteprima. Eseguire l'installazione 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"

Configurazione risultante

{
  "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 stored procedure. Elenco delimitato da virgole delle descrizioni dei parametri allineate a --parameters.name.

Annotazioni

Questa opzione è disponibile nell'interfaccia della 2.0.0-rc riga di comando. Il generatore di API dati 2.0 è attualmente in anteprima. Eseguire l'installazione 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 stored procedure. Elenco delimitato da virgole di true/false valori allineati a .--parameters.name

Annotazioni

Questa opzione è disponibile nell'interfaccia della 2.0.0-rc riga di comando. Il generatore di API dati 2.0 è attualmente in anteprima. Eseguire l'installazione 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 stored procedure. Elenco delimitato da virgole di valori predefiniti allineati a --parameters.name.

Annotazioni

Questa opzione è disponibile nell'interfaccia della 2.0.0-rc riga di comando. Il generatore di API dati 2.0 è attualmente in anteprima. Eseguire l'installazione 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

Elenco delimitato da virgole di campi da escludere.

Example

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

Configurazione risultante

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

--fields.include

Elenco delimitato da virgole di campi da esporre.

Example

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

Configurazione risultante

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

--fields.name

Nome della colonna del database da descrivere.

Annotazioni

Questa opzione è disponibile nell'interfaccia della 2.0.0-rc riga di comando. Il generatore di API dati 2.0 è attualmente in anteprima. Eseguire l'installazione 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"

Configurazione risultante

Annotazioni

Nella versione 2.0.0-rc corrente, l'interfaccia della riga di comando accetta --fields.name, --fields.alias, --fields.descriptione ma --fields.primary-key non rende ancora persistenti i metadati dei campi a livello di entità nel file di configurazione. Il team prevede di risolvere questo comportamento prima della disponibilità generale.

--fields.alias

Alias per il campo. Usare un elenco delimitato da virgole allineato a --fields.name.

Annotazioni

Questa opzione è disponibile nell'interfaccia della 2.0.0-rc riga di comando. Il generatore di API dati 2.0 è attualmente in anteprima. Eseguire l'installazione 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

Descrizione per il campo. Usare un elenco delimitato da virgole allineato a --fields.name.

Annotazioni

Questa opzione è disponibile nell'interfaccia della 2.0.0-rc riga di comando. Il generatore di API dati 2.0 è attualmente in anteprima. Eseguire l'installazione 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

Flag di chiave primaria per il campo. Usare un elenco delimitato da virgole di true/false valori allineati a .--fields.name

Annotazioni

Questa opzione è disponibile nell'interfaccia della 2.0.0-rc riga di comando. Il generatore di API dati 2.0 è attualmente in anteprima. Eseguire l'installazione 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"

Annotazioni

Nella versione 2.0.0-rc corrente, l'interfaccia della riga di comando accetta --fields.primary-key ma non rende ancora persistenti i metadati dei campi a livello di entità nel file di configurazione. Per specificare i campi chiave primaria per le visualizzazioni, usare --source.key-fields invece .

--graphql

Controllare l'esposizione di GraphQL.

Example

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

Configurazione risultante

{
  "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 stored procedure. Tipo di operazione GraphQL. Il valore predefinito è mutation.

Example

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

Configurazione risultante

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

Controllare l'esposizione REST.

Example

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

Configurazione risultante

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

--rest.methods

Solo stored procedure. Verbi HTTP consentiti per l'esecuzione: GET, POST, PUT, PATCH, DELETE. Il valore predefinito è POST. Ignorato per tabelle/viste.

Example

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

Configurazione risultante

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

--mcp.dml-tools

Abilitare o disabilitare gli strumenti DML per questa entità in MCP. Impostazione predefinita: true. Se impostato su false, l'entità viene esclusa dall'area degli strumenti MCP DML. Quando mcp viene omesso interamente, gli strumenti DML sono abilitati per impostazione predefinita.

Annotazioni

La funzionalità Generatore API dati 2.0 descritta in questa sezione è attualmente in anteprima e potrebbe cambiare prima della disponibilità generale. Per altre informazioni, vedere Novità della versione 2.0.

Example

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

Configurazione risultante

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

--mcp.custom-tool

Registrare un'entità stored procedure come strumento MCP denominato. Valido solo quando --source.type è stored-procedure. Quando true, DAB registra dinamicamente la procedura nella risposta MCP tools/list e gli agenti possono chiamarlo tramite tools/call.

Example

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

Configurazione risultante

{
  "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 è valido solo per le entità stored procedure. L'uso con le entità di tabella o vista genera un errore di convalida.

--permissions

Definisce le coppie role→actions.

--permissions non è ripetibile. Per aggiungere altri ruoli, eseguire dab add con un ruolo e quindi eseguire dab update per altri ruoli.

Example

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

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

--policy-database

Criteri a livello di database.

Example

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

Configurazione risultante

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

--policy-request

Criteri a livello di richiesta.

Example

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

Configurazione risultante

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

--help

Visualizza questa schermata della Guida.

Example

dab add \
  --help

--version

Visualizzare le informazioni sulla versione.

Example

dab add \
  --version
  • Last updated on