add 命令

將新的實體定義新增至現有的資料 API 產生器組態檔。 您必須已經使用 建立的組態 dab init。 用於 dab update 在建立後修改圖元。

小提示

用於 dab add 建立新實體，並 dab update 進化它們。

語法

dab add <entity-name> [options]

快速瀏覽

Option 總結
-c, --config 組態檔路徑。 預設 dab-config.json。

頭部部分

Option 總結
<entity-name> 必要的位置引數。 邏輯實體名稱。
-s, --source 必須的。 資料庫物件名稱 （資料表、檢視或預存程序）。
--source.type 來源類型： table、 view、 stored-procedure （預設資料表）。
--source.key-fields 視圖的主要鍵欄位（逗號分隔）。
--source.params 僅限預存程序。 預設參數值為 param1:val1,param2:val2。

快取區段

Option 總結
--cache.enabled 啟用/停用實體的快取。
--cache.ttl 快取存留時間 （以秒為單位）。
--description 實體的自由格式描述。

參數區段

Option 總結
--parameters.name 僅限預存程序。 參數名稱（逗號分隔）。
--parameters.description 僅限預存程序。 參數描述。
--parameters.required 僅限預存程序。 參數需要標記。
--parameters.default 僅限預存程序。 參數預設值。

田野區

Option 總結
--fields.exclude 以逗號分隔的排除欄位。
--fields.include 以逗號分隔的允許欄位 （* = all）。
--fields.name 欄位名稱可描述（可重複或逗號分隔）。
--fields.alias 欄位別名（逗號分隔，對齊至 --fields.name）。
--fields.description 場描述（逗號分隔，對齊於 --fields.name）。
--fields.primary-key 主鍵旗標（逗號分隔，對齊於 --fields.name）。

API 章節

Option 總結
--graphql GraphQL 曝光： false、 true、 singular或 singular:plural。
--graphql.operation 僅限預存程序。 Query 或 Mutation （預設突變）。
--rest REST 暴露： false、 true或自訂路由。
--rest.methods 僅限預存程序。 允許的動詞：GET， POST， ， PUTPATCHDELETE， ， 。 預設 POST。
--mcp.dml-tools 在模型情境協定（MCP）中啟用/停用實體的資料操作語言（DML）工具。 預設 true。
--mcp.custom-tool 僅限預存程序。 註冊為一個命名的 MCP 工具。

許可章節

Option 總結
--permissions 必須的。 role:actions 只是一個角色。
--policy-database 資料庫查詢中套用 OData 式過濾器。
--policy-request 請求在資料庫呼叫前評估政策。

<entity-name>

配置中實體的邏輯名稱。區分大小寫。

表格、檢視與儲存程序的快速範例

新增數據表

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

新增檢視

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"

新增儲存程序

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

組態檔路徑。 預設值為 dab-config.json。

Example

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

-s, --source

必須的。 資料庫物件名稱：資料表、檢視表、容器或儲存程序。

Example

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

產生的設定

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

--source.type

資料庫物件的類型。 預設值：table。

Example

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

產生的設定

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

--source.key-fields

一個或多個欄位作為主鍵。 視圖缺乏內在主鍵，因此必須明確指定鍵欄位。

Example

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

產生的設定

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

--source.params

參數字典及其儲存程序的預設值。 請使用 param1:val1,param2:val2 格式。

Example

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

產生的設定

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

啟用或停用快取。

Example

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

產生的設定

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

--cache.ttl

快取存留時間 （以秒為單位）。

Example

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

產生的設定

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

--description

實體的自由文字描述。

備註

此選項可在 2.0.0-rc CLI 中提供。 Data API 建構器 2.0 目前處於預覽階段。 安裝時用 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"

產生的設定

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

--parameters.name

僅限預存程序。 參數名稱的逗號分隔列表。

備註

此選項可在 2.0.0-rc CLI 中提供。 Data API 建構器 2.0 目前處於預覽階段。 安裝時用 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"

產生的設定

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

僅限預存程序。 參數描述的逗號分隔列表對齊於 --parameters.name。

備註

此選項可在 2.0.0-rc CLI 中提供。 Data API 建構器 2.0 目前處於預覽階段。 安裝時用 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

僅限預存程序。 以逗號分隔的數值列表 true/false ，對齊於 --parameters.name。

備註

此選項可在 2.0.0-rc CLI 中提供。 Data API 建構器 2.0 目前處於預覽階段。 安裝時用 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

僅限預存程序。 以逗號分隔的預設值列表，對齊於 --parameters.name。

備註

此選項可在 2.0.0-rc CLI 中提供。 Data API 建構器 2.0 目前處於預覽階段。 安裝時用 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

要排除的欄位以逗號分隔的清單。

Example

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

產生的設定

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

--fields.include

要公開的欄位以逗號分隔的清單。

Example

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

產生的設定

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

--fields.name

要描述的資料庫欄位名稱。

備註

此選項可在 2.0.0-rc CLI 中提供。 Data API 建構器 2.0 目前處於預覽階段。 安裝時用 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"

產生的設定

備註

在目前的 2.0.0-rc 版本中，CLI 接受 --fields.name、 --fields.alias、 --fields.description， --fields.primary-key 但尚未將實體層級的欄位元資料持久化到設定檔。 團隊預期在 GA 前解決此行為。

--fields.alias

田野的別名。 使用一個逗號分隔的清單，對齊於 --fields.name。

備註

此選項可在 2.0.0-rc CLI 中提供。 Data API 建構器 2.0 目前處於預覽階段。 安裝時用 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

該領域的描述。 使用一個逗號分隔的清單，對齊於 --fields.name。

備註

此選項可在 2.0.0-rc CLI 中提供。 Data API 建構器 2.0 目前處於預覽階段。 安裝時用 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

田野的主鍵旗幟。 使用一個逗號分隔的值清單true/false，對齊於 。--fields.name

備註

此選項可在 2.0.0-rc CLI 中提供。 Data API 建構器 2.0 目前處於預覽階段。 安裝時用 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"

備註

在目前的 2.0.0-rc 版本中，CLI 接受 --fields.primary-key 但尚未持久化實體層級欄位元資料到設定檔。 若要指定視圖的主鍵欄位，請使用--source.key-fields

--graphql

控制 GraphQL 曝光。

Example

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

產生的設定

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

--graphql.operation

僅限預存程序。 GraphQL 作業類型。 預設值為 mutation。

Example

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

產生的設定

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

控制 REST 暴露。

Example

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

產生的設定

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

--rest.methods

僅限預存程序。 允許執行的 HTTP 動詞有：GET， POST， PUTPATCHDELETE 預設為 POST。 對於資料表/檢視會忽略。

Example

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

產生的設定

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

--mcp.dml-tools

在 MCP 中啟用或停用該實體的 DML 工具。 預設值：true。 當 設定為 false時，該實體會被排除在 MCP DML 工具表面之外。 當 mcp 完全省略時，DML 工具預設會啟用。

備註

本節所述的資料API建構器2.0功能目前處於預覽階段，可能會在正式推出前有所變動。 欲了解更多資訊，請參閱 2.0 版本的新內容。

Example

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

產生的設定

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

--mcp.custom-tool

將儲存程序實體註冊為命名的 MCP 工具。 僅當 --source.type 為 時 stored-procedure有效。 當 true時，DAB 會動態登錄 MCP tools/list 回應中的程序，代理程式可透過 tools/call呼叫。

Example

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

產生的設定

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

這很重要

--mcp.custom-tool 僅適用於儲存程序實體。 使用表格或檢視實體會導致驗證錯誤。

--permissions

定義角色→動作配對。

--permissions 無法重複。 想增加更多角色，先先跑 dab add 一個角色，再跑 dab update 去爭取更多角色。

Example

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

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

--policy-database

資料庫層級原則。

Example

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

產生的設定

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

--policy-request

要求層級原則。

Example

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

產生的設定

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

--help

顯示此說明畫面。

Example

dab add \
  --help

--version

顯示版本資訊。

Example

dab add \
  --version
  • Last updated on