Partager via

Commande add

Ajoutez une nouvelle définition d’entité à un fichier de configuration existant du générateur d’API de données. Vous devez déjà avoir une configuration créée avec dab init. Permet dab update de modifier des entités après la création.

Conseil / Astuce

Permet dab add de créer de nouvelles entités et dab update de les faire évoluer.

Syntaxe

dab add <entity-name> [options]

Aperçu rapide

Choix Résumé
-c, --config Chemin du fichier de configuration. dab-config.jsonpar défaut .

Section de la tête

Choix Résumé
<entity-name> Argument positionnel obligatoire. Nom de l’entité logique.
-s, --source Obligatoire. Nom de l’objet de base de données (table, vue ou procédure stockée).
--source.type Type de source : table, view, stored-procedure (table par défaut).
--source.key-fields Champs de clé primaire pour les vues (séparés par des virgules).
--source.params Procédures stockées uniquement. Valeurs de paramètre par défaut en tant que param1:val1,param2:val2.

Section Cache

Choix Résumé
--cache.enabled Activez/désactivez la mise en cache pour l’entité.
--cache.ttl Durée de vie du cache en secondes.
--description Description de formulaire libre pour l’entité.

Section Paramètres

Choix Résumé
--parameters.name Procédures stockées uniquement. Noms de paramètres (séparés par des virgules).
--parameters.description Procédures stockées uniquement. Descriptions des paramètres.
--parameters.required Procédures stockées uniquement. Indicateurs requis pour les paramètres.
--parameters.default Procédures stockées uniquement. Valeurs par défaut des paramètres.

Section Champs

Choix Résumé
--fields.exclude Champs exclus séparés par des virgules.
--fields.include Champs autorisés séparés par des virgules (* = all).
--fields.name Noms de champs à décrire (séparés par des virgules ou reproductibles).
--fields.alias Alias de champ (séparés par des virgules, alignés sur --fields.name).
--fields.description Descriptions des champs (séparées par des virgules, alignées sur --fields.name).
--fields.primary-key Indicateurs de clé primaire (séparés par des virgules, alignés sur --fields.name).

Section API

Choix Résumé
--graphql Exposition GraphQL : false, , truesingularou singular:plural.
--graphql.operation Procédures stockées uniquement. Query ou Mutation (mutation par défaut).
--rest Exposition REST : false, ou trueitinéraire personnalisé.
--rest.methods Procédures stockées uniquement. Verbes autorisés : GET, , POSTPUT, PATCH, DELETE. POST par défaut.
--mcp.dml-tools Activer/désactiver les outils DML (Data Manipulation Language) pour l’entité dans le protocole MCP (Model Context Protocol). truepar défaut .
--mcp.custom-tool Procédures stockées uniquement. Inscrivez-vous en tant qu’outil MCP nommé.

Section Autorisations

Choix Résumé
--permissions Obligatoire. role:actions pour un seul rôle.
--policy-database Filtre de style OData appliqué dans la requête de base de données.
--policy-request Stratégie de requête évaluée avant l’appel de base de données.

<entity-name>

Nom logique de l’entité dans la configuration. Respect de la casse.

Exemples rapides pour les tables, les vues et les procédures stockées

Ajouter une table

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

Ajouter une vue

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"

Ajouter une procédure stockée

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

Chemin du fichier de configuration. La valeur par défaut est dab-config.json.

Example

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

-s, --source

Obligatoire. Nom de l’objet de base de données : table, vue, conteneur ou procédure stockée.

Example

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

Configuration résultante

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

--source.type

Type d’objet de base de données. Par défaut : table.

Example

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

Configuration résultante

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

--source.key-fields

Un ou plusieurs champs à utiliser comme clés primaires. Les vues ne disposent pas de clés primaires intrinsèques. Vous devez donc spécifier explicitement les champs de clé.

Example

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

Configuration résultante

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

--source.params

Dictionnaire de paramètres et leurs valeurs par défaut pour les procédures stockées. Utilisez le format param1:val1,param2:val2.

Example

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

Configuration résultante

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

Activez ou désactivez la mise en cache.

Example

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

Configuration résultante

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

--cache.ttl

Durée de vie du cache en secondes.

Example

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

Configuration résultante

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

--description

Description de texte libre de l’entité.

Note

Cette option est disponible dans l’interface 2.0.0-rc CLI. Data API Builder 2.0 est actuellement en préversion. Installer avec 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"

Configuration résultante

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

--parameters.name

Procédures stockées uniquement. Liste séparée par des virgules des noms de paramètres.

Note

Cette option est disponible dans l’interface 2.0.0-rc CLI. Data API Builder 2.0 est actuellement en préversion. Installer avec 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"

Configuration résultante

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

Procédures stockées uniquement. Liste séparée par des virgules des descriptions de paramètres alignées sur --parameters.name.

Note

Cette option est disponible dans l’interface 2.0.0-rc CLI. Data API Builder 2.0 est actuellement en préversion. Installer avec 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

Procédures stockées uniquement. Liste séparée par des virgules des true/false valeurs alignées sur --parameters.name.

Note

Cette option est disponible dans l’interface 2.0.0-rc CLI. Data API Builder 2.0 est actuellement en préversion. Installer avec 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

Procédures stockées uniquement. Liste séparée par des virgules des valeurs par défaut alignées sur --parameters.name.

Note

Cette option est disponible dans l’interface 2.0.0-rc CLI. Data API Builder 2.0 est actuellement en préversion. Installer avec 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

Liste séparée par des virgules des champs à exclure.

Example

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

Configuration résultante

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

--fields.include

Liste de champs séparés par des virgules à exposer.

Example

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

Configuration résultante

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

--fields.name

Nom de la colonne de base de données à décrire.

Note

Cette option est disponible dans l’interface 2.0.0-rc CLI. Data API Builder 2.0 est actuellement en préversion. Installer avec 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"

Configuration résultante

Note

Dans la version actuelle de la version 2.0.0-rc, l’interface CLI accepte --fields.name, --fields.alias--fields.descriptionet --fields.primary-key ne conserve pas encore les métadonnées de champ au niveau de l’entité dans le fichier de configuration. L’équipe s’attend à résoudre ce comportement avant la disponibilité générale.

--fields.alias

Alias du champ. Utilisez une liste séparée par des virgules alignée sur --fields.name.

Note

Cette option est disponible dans l’interface 2.0.0-rc CLI. Data API Builder 2.0 est actuellement en préversion. Installer avec 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

Description du champ. Utilisez une liste séparée par des virgules alignée sur --fields.name.

Note

Cette option est disponible dans l’interface 2.0.0-rc CLI. Data API Builder 2.0 est actuellement en préversion. Installer avec 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

Indicateur de clé primaire pour le champ. Utilisez une liste séparée par des virgules de true/false valeurs alignées sur --fields.name.

Note

Cette option est disponible dans l’interface 2.0.0-rc CLI. Data API Builder 2.0 est actuellement en préversion. Installer avec 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"

Note

Dans la version actuelle de la version 2.0.0-rc, l’interface CLI accepte --fields.primary-key mais ne conserve pas encore les métadonnées de champ au niveau de l’entité dans le fichier de configuration. Pour spécifier les champs de clé primaire pour les vues, utilisez --source.key-fields à la place.

--graphql

Contrôler l’exposition GraphQL.

Example

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

Configuration résultante

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

--graphql.operation

Procédures stockées uniquement. Type d’opération GraphQL. La valeur par défaut est mutation.

Example

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

Configuration résultante

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

Contrôler l’exposition REST.

Example

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

Configuration résultante

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

--rest.methods

Procédures stockées uniquement. Verbes HTTP autorisés pour l’exécution : GET, , POSTPUT, PATCH, DELETE. La valeur par défaut est POST. Ignoré pour les tables/vues.

Example

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

Configuration résultante

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

--mcp.dml-tools

Activez ou désactivez les outils DML pour cette entité dans MCP. Par défaut : true. Lorsque la valeur est définie false, l’entité est exclue de l’aire de l’outil DML MCP. Lorsqu’il mcp est omis entièrement, les outils DML sont activés par défaut.

Note

La fonctionnalité 2.0 du Générateur d’API de données décrite dans cette section est actuellement en préversion et peut changer avant la disponibilité générale. Pour plus d’informations, consultez Nouveautés de la version 2.0.

Example

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

Configuration résultante

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

--mcp.custom-tool

Inscrivez une entité de procédure stockée en tant qu’outil MCP nommé. Valide uniquement quand est --source.typestored-procedure. Quand true, DAB inscrit dynamiquement la procédure dans la réponse MCP tools/list et les agents peuvent l’appeler via tools/call.

Example

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

Configuration résultante

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

Important

--mcp.custom-tool est valide uniquement pour les entités de procédure stockée. L’utilisation de celui-ci avec des entités de table ou d’affichage provoque une erreur de validation.

--permissions

Définit des paires role→actions.

--permissions n’est pas reproductible. Pour ajouter d’autres rôles, exécutez-le dab add avec un rôle, puis exécutez-le dab update pour plus de rôles.

Example

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

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

--policy-database

Stratégie au niveau de la base de données.

Example

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

Configuration résultante

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

--policy-request

Stratégie au niveau de la demande.

Example

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

Configuration résultante

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

--help

Affichez cet écran d’aide.

Example

dab add \
  --help

--version

Affichez les informations de version.

Example

dab add \
  --version
  • Last updated on