add kommando`

Lägg till en ny entitetsdefinition i en befintlig konfigurationsfil för Data API Builder. Du måste redan ha en konfiguration skapad med dab init. Använd dab update för att ändra entiteter efter skapandet.

Tips/Råd

Använd dab add för att skapa nya entiteter och dab update för att utveckla dem.

Syntax

dab add <entity-name> [options]

Snabbblick

Option Sammanfattning
-c, --config Konfigurationsfilsökväg. Standard dab-config.json.

Huvudsektion

Option Sammanfattning
<entity-name> Obligatoriskt positionsargument. Namn på logisk entitet.
-s, --source Obligatoriskt. Databasobjektnamn (tabell, vy eller lagrad procedur).
--source.type Källtyp: table, view, stored-procedure (standardtabell).
--source.key-fields Primära nyckelfält för vyer (kommaavgränsade).
--source.params Endast lagrade procedurer. Standardparametervärden som param1:val1,param2:val2.

Cacheavsnitt

Option Sammanfattning
--cache.enabled Aktivera/inaktivera cachelagring för entitet.
--cache.ttl Cachelagrade time-to-live i sekunder.
--description Beskrivning av fritt formulär för entitet.

Avsnittet Parametrar

Option Sammanfattning
--parameters.name Endast lagrade procedurer. Parameternamn (kommaavgränsade).
--parameters.description Endast lagrade procedurer. Parameterbeskrivningar.
--parameters.required Endast lagrade procedurer. Obligatoriska parameterflaggor.
--parameters.default Endast lagrade procedurer. Parameterstandardvärden.

Fältavsnitt

Option Sammanfattning
--fields.exclude Kommaavgränsade exkluderade fält.
--fields.include Kommaavgränsade tillåtna fält (* = alla).
--fields.name Fältnamn som ska beskrivas (repeterbara eller kommaavgränsade).
--fields.alias Fältalias (kommaavgränsade, justerade till --fields.name).
--fields.description Fältbeskrivningar (kommaavgränsade, justerade till --fields.name).
--fields.primary-key Primärnyckelflaggor (kommaavgränsade, justerade till --fields.name).

API-avsnitt

Option Sammanfattning
--graphql GraphQL-exponering: false, true, singulareller singular:plural.
--graphql.operation Endast lagrade procedurer. Query eller Mutation (standardmutation).
--rest REST-exponering: false, trueeller anpassad väg.
--rest.methods Endast lagrade procedurer. Tillåtna verb: GET, POST, PUT, PATCH, DELETE. Standard-POST.
--mcp.dml-tools Aktivera/inaktivera verktyg för datamanipuleringsspråk (DML) för entitet i MCP (Model Context Protocol). Standard true.
--mcp.custom-tool Endast lagrade procedurer. Registrera dig som ett namngivet MCP-verktyg.

Avsnittet Behörigheter

Option Sammanfattning
--permissions Obligatoriskt. role:actions för en enda roll.
--policy-database OData-formatfilter som används i databasfrågan.
--policy-request Begärandeprincip utvärderas före databasanrop.

<entity-name>

Logiskt namn på entiteten i konfigurationen. Skiftlägeskänsligt.

Snabbexempel för tabeller, vyer och lagrade procedurer

Lägga till en tabell

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

Lägg till en vy

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"

Lägga till en lagrad procedur

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

Konfigurationsfilsökväg. Standard är dab-config.json.

Example

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

-s, --source

Obligatoriskt. Namnet på databasobjektet: tabell, vy, container eller lagrad procedur.

Example

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

Resulterande konfiguration

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

--source.type

Typ av databasobjekt. Förvald: table.

Example

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

Resulterande konfiguration

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

--source.key-fields

Ett eller flera fält som ska användas som primära nycklar. Vyer saknar inbyggda primära nycklar, så du måste uttryckligen ange nyckelfält.

Example

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

Resulterande konfiguration

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

--source.params

Ordlista över parametrar och deras standardvärden för lagrade procedurer. Använd formatet param1:val1,param2:val2.

Example

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

Resulterande konfiguration

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

Aktivera eller inaktivera cachelagring.

Example

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

Resulterande konfiguration

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

--cache.ttl

Cachelagrade time-to-live i sekunder.

Example

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

Resulterande konfiguration

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

--description

Beskrivning av entiteten i fritext.

Anmärkning

Det här alternativet är tillgängligt i 2.0.0-rc CLI. Data API Builder 2.0 är för närvarande i förhandsversion. Installera med 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"

Resulterande konfiguration

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

--parameters.name

Endast lagrade procedurer. Kommaavgränsad lista med parameternamn.

Anmärkning

Det här alternativet är tillgängligt i 2.0.0-rc CLI. Data API Builder 2.0 är för närvarande i förhandsversion. Installera med 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"

Resulterande konfiguration

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

Endast lagrade procedurer. Kommaavgränsad lista över parameterbeskrivningar som är justerade till --parameters.name.

Anmärkning

Det här alternativet är tillgängligt i 2.0.0-rc CLI. Data API Builder 2.0 är för närvarande i förhandsversion. Installera med 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

Endast lagrade procedurer. Kommaavgränsad lista med true/false värden som är justerade till .--parameters.name

Anmärkning

Det här alternativet är tillgängligt i 2.0.0-rc CLI. Data API Builder 2.0 är för närvarande i förhandsversion. Installera med 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

Endast lagrade procedurer. Kommaavgränsad lista med standardvärden som är justerade till --parameters.name.

Anmärkning

Det här alternativet är tillgängligt i 2.0.0-rc CLI. Data API Builder 2.0 är för närvarande i förhandsversion. Installera med 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

Kommaavgränsad lista över fält som ska undantas.

Example

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

Resulterande konfiguration

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

--fields.include

Kommaavgränsad lista över fält som ska exponeras.

Example

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

Resulterande konfiguration

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

--fields.name

Namnet på den databaskolumn som ska beskrivas.

Anmärkning

Det här alternativet är tillgängligt i 2.0.0-rc CLI. Data API Builder 2.0 är för närvarande i förhandsversion. Installera med 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"

Resulterande konfiguration

Anmärkning

I den aktuella versionen av 2.0.0-rc accepterar --fields.nameCLI , --fields.alias, --fields.descriptionoch --fields.primary-key men bevarar ännu inte fältmetadata på entitetsnivå till konfigurationsfilen. Teamet förväntar sig att lösa det här beteendet före GA.

--fields.alias

Alias för fältet. Använd en kommaavgränsad lista som är justerad till --fields.name.

Anmärkning

Det här alternativet är tillgängligt i 2.0.0-rc CLI. Data API Builder 2.0 är för närvarande i förhandsversion. Installera med 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

Beskrivning av fältet. Använd en kommaavgränsad lista som är justerad till --fields.name.

Anmärkning

Det här alternativet är tillgängligt i 2.0.0-rc CLI. Data API Builder 2.0 är för närvarande i förhandsversion. Installera med 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

Primärnyckelflagga för fältet. Använd en kommaavgränsad lista med true/false värden som är justerade till .--fields.name

Anmärkning

Det här alternativet är tillgängligt i 2.0.0-rc CLI. Data API Builder 2.0 är för närvarande i förhandsversion. Installera med 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"

Anmärkning

I den aktuella versionen av 2.0.0-rc accepterar CLI men bevarar ännu inte fältmetadata på entitetsnivå till konfigurationsfilen --fields.primary-key . Om du vill ange primärnyckelfält för vyer använder du --source.key-fields i stället.

--graphql

Kontrollera GraphQL-exponering.

Example

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

Resulterande konfiguration

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

--graphql.operation

Endast lagrade procedurer. GraphQL-åtgärdstyp. Standard är mutation.

Example

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

Resulterande konfiguration

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

Kontrollera REST-exponering.

Example

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

Resulterande konfiguration

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

--rest.methods

Endast lagrade procedurer. HTTP-verb som tillåts för körning: GET, POST, PUT, PATCH, DELETE. Standardvärdet är POST. Ignoreras för tabeller/vyer.

Example

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

Resulterande konfiguration

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

--mcp.dml-tools

Aktivera eller inaktivera DML-verktyg för den här entiteten i MCP. Förvald: true. När den är inställd falsepå undantas entiteten från MCP DML-verktygsytan. När mcp utelämnas helt aktiveras DML-verktyg som standard.

Anmärkning

Funktionerna i Data API Builder 2.0 som beskrivs i det här avsnittet är för närvarande i förhandsversion och kan komma att ändras före allmän tillgänglighet. Mer information finns i Nyheter i version 2.0.

Example

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

Resulterande konfiguration

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

--mcp.custom-tool

Registrera en lagrad procedurentitet som ett namngivet MCP-verktyg. Gäller endast när --source.type är stored-procedure. När trueregistrerar DAB dynamiskt proceduren i MCP-svaret tools/list och agenter kan anropa den via tools/call.

Example

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

Resulterande konfiguration

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

Viktigt!

--mcp.custom-tool är endast giltigt för entiteter med lagrad procedur. Om du använder den med tabell- eller vyentiteter uppstår ett valideringsfel.

--permissions

Definierar par för roll→actions.

--permissions är inte repeterbar. Om du vill lägga till fler roller kör du dab add med en roll och kör dab update sedan för fler roller.

Example

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

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

--policy-database

Princip på databasnivå.

Example

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

Resulterande konfiguration

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

--policy-request

Princip på begäransnivå.

Example

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

Resulterande konfiguration

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

--help

Visa den här hjälpskärmen.

Example

dab add \
  --help

--version

Visa versionsinformation.

Example

dab add \
  --version
  • Last updated on