update 命令

更新資料 API 產生器組態檔中的現有實體定義。 使用此指令來調整現有實體的原始元資料、權限、曝光（REST/GraphQL）、政策、快取、關係、映射及描述性元資料。

小提示

用於 dab add 建立新實體，並 dab update 進化它們。 管理欄位元資料時，請使用 --fields.name 、 --fields.alias--fields.description、 --fields.primary-key和 。

語法

dab update <entity-name> [options]

快速瀏覽

Option 總結
<entity-name> 必要的位置引數。 邏輯實體名稱。
-s, --source 來源資料表、檢視或儲存程序的名稱。
-m, --map 資料庫欄位與公開名稱之間的對應。
--permissions 格式中 role:actions 的角色與行動。
--description 取代實體描述。
-c, --config 組態檔的路徑。 如果省略，則預設解析度會套用。
--help 顯示說明畫面。
--version 顯示版本資訊。

緩存

Option 總結
--cache.enabled 啟用或停用實體快取。
--cache.ttl 快取存留時間 （以秒為單位）。

Fields

Option 總結
--fields.exclude 以逗號分隔的排除欄位清單。
--fields.include 以逗號分隔的包含欄位清單 （* = all）。

欄位中繼資料

Option 總結
--fields.name 要描述的資料庫欄位名稱。
--fields.alias 田野的別名。
--fields.description 該領域的描述。
--fields.primary-key 將此欄位設為主鍵。

GraphQL

Option 總結
--graphql GraphQL 曝光： false、 true、 singular或 singular:plural。
--graphql.operation 僅限預存程序： query 或 mutation （預設突變）。

權限和政策

Option 總結
--permissions role:actions 只是一個角色。 多次跑多個角色。
--policy-database 在資料庫查詢中注入 OData 式過濾器。
--policy-request 預資料庫請求篩選器。

關係

Option 總結
--relationship 關係名稱。 與關聯性選項搭配使用。
--cardinality 關係基數： one 或 many。
--target.entity 目標實體名稱。
--linking.object 連結物件用於多對多。
--linking.source.fields 連結指向來源的物件欄位。
--linking.target.fields 連結指向目標的物件欄位。
--relationship.fields 直接關係的欄位對應。

REST

Option 總結
--rest REST 公開： false、 true或自訂路徑。
--rest.methods 僅限預存程序。 取代允許的 HTTP 動詞。

映射

Option 總結
-m, --map 資料庫欄位與公開名稱之間的對應。

MCP

Option 總結
--mcp.dml-tools 啟用或停用此實體的 MCP DML 工具。
--mcp.custom-tool 啟用 MCP 自訂工具（僅限儲存程序）。

來源

Option 總結
-s, --source 基礎資料庫物件名稱。
--source.type 來源類型： table、 view或 stored-procedure。
--source.params 儲存程序的預設參數值。
--source.key-fields 檢視或資料表的主鍵欄位。

參數（儲存程序）

Option 總結
--parameters.name 參數名稱的逗號分隔列表。
--parameters.description 參數描述的逗號分隔列表。
--parameters.required 必要旗標的逗號分隔清單。
--parameters.default 以逗號分隔的預設值清單。

--cache.enabled

啟用或停用此實體的快取。

Example

dab update \
  Book \
  --cache.enabled true

產生的設定

{
  "entities": {
    "Book": {
      "cache": {}
    }
  }
}

備註

當快取啟用（預設值）時，CLI 會寫入一個空 cache 物件。 該 "enabled" 性質僅在設定為 false時明確出現。

--cache.ttl

設定快取存留時間 （以秒為單位）。 只有在啟用快取時才有效。

Example

dab update \
  Book \
  --cache.ttl 600

產生的設定

{
  "entities": {
    "Book": {
      "cache": {
        "ttl-seconds": 600
      }
    }
  }
}

備註

當快取被停用時，提供 TTL（存活時間）在快取啟用前不會生效。

--description

取代實體描述。

備註

此選項可在 2.0.0-rc CLI 中提供。 Data API 建構器 2.0 目前處於預覽階段。 安裝時用 dotnet tool install microsoft.dataapibuilder --version 2.0.0-rc --prerelease.

Example

dab update \
  Book \
  --description "Updated description"

產生的設定

{
  "entities": {
    "Book": {
      "description": "Updated description"
    }
  }
}

--fields.exclude

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

Example

dab update \
  Book \
  --permissions "anonymous:read" \
  --fields.exclude "internal_flag,secret_note"

產生的設定

{
  "entities": {
    "Book": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "fields": {
                "exclude": [ "internal_flag", "secret_note" ]
              }
            }
          ]
        }
      ]
    }
  }
}

--fields.include

要包含的欄位清單以逗號分隔。 * 包括所有欄位。 取代現有的包含清單。

Example

dab update \
  Book \
  --permissions "anonymous:read" \
  --fields.include "id,title,author"

產生的設定

{
  "entities": {
    "Book": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "fields": {
                "exclude": [],
                "include": [ "id", "title", "author" ]
              }
            }
          ]
        }
      ]
    }
  }
}

--graphql

控制 GraphQL 曝光。

Example

dab update \
  Book \
  --graphql book:books

產生的設定

{
  "entities": {
    "Book": {
      "graphql": {
        "enabled": true,
        "type": {
          "singular": "book",
          "plural": "books"
        }
      }
    }
  }
}

--graphql.operation

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

Example

dab update \
  RunReport \
  --graphql.operation query

產生的設定

{
  "entities": {
    "RunReport": {
      "graphql": {
        "operation": "query"
      }
    }
  }
}

備註

會忽略表格或視圖的供應 --graphql.operation 。

--permissions

新增或更新單一角色及其動作的權限。

你可以 dab update 執行多次（每個角色一次）來新增多個角色。

Example

dab update \
  Book \
  --permissions "anonymous:read"

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

產生的設定

{
  "entities": {
    "Book": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read"
            }
          ]
        },
        {
          "role": "authenticated",
          "actions": [
            { "action": "create" },
            { "action": "read" },
            { "action": "update" }
          ]
        }
      ]
    }
  }
}

備註

若指定角色已存在，其動作會被更新;否則，該角色會被加入。

--policy-database

附加於資料庫查詢的 OData 式過濾器。

Example

dab update \
  Book \
  --permissions "anonymous:read" \
  --policy-database "region eq 'US'"

產生的設定

{
  "entities": {
    "Book": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "region eq 'US'"
              }
            }
          ]
        }
      ]
    }
  }
}

--policy-request

在叫用資料庫之前評估的要求層級原則。

Example

dab update \
  Book \
  --permissions "anonymous:read" \
  --policy-request "@claims.role == 'admin'"

產生的設定

{
  "entities": {
    "Book": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "policy": {
                "request": "@claims.role == 'admin'"
              }
            }
          ]
        }
      ]
    }
  }
}

--relationship

定義或更新關係。 與其他關係選項搭配使用。

Example

dab update \
  User \
  --relationship profile \
  --target.entity Profile \
  --cardinality one \
  --relationship.fields "id:user_id"

產生的設定

{
  "entities": {
    "User": {
      "relationships": {
        "profile": {
          "cardinality": "one",
          "target.entity": "Profile",
          "source.fields": [ "id" ],
          "target.fields": [ "user_id" ],
          "linking.source.fields": [],
          "linking.target.fields": []
        }
      }
    }
  }
}

--cardinality

關係的基數。 與 --relationship 搭配使用。

Example

dab update \
  User \
  --relationship profile \
  --target.entity Profile \
  --cardinality one \
  --relationship.fields "id:user_id"

--target.entity

關係的目標實體名稱。 與 --relationship 搭配使用。

Example

dab update \
  User \
  --relationship profile \
  --target.entity Profile \
  --cardinality one \
  --relationship.fields "id:user_id"

--linking.object

只有多對多。 作為連結物件的資料庫物件名稱。

Example

dab update \
  Book \
  --relationship books_authors \
  --target.entity Author \
  --cardinality many \
  --relationship.fields "id:id" \
  --linking.object dbo.books_authors \
  --linking.source.fields book_id \
  --linking.target.fields author_id

--linking.source.fields

只有多對多。 以逗號分隔的連結物件欄位清單，指向來源實體。

Example

dab update \
  Book \
  --relationship books_authors \
  --target.entity Author \
  --cardinality many \
  --relationship.fields "id:id" \
  --linking.object dbo.books_authors \
  --linking.source.fields book_id \
  --linking.target.fields author_id

--linking.target.fields

只有多對多。 以逗號分隔的連結物件欄位清單，指向目標實體。

Example

dab update \
  Book \
  --relationship books_authors \
  --target.entity Author \
  --cardinality many \
  --relationship.fields "id:id" \
  --linking.object dbo.books_authors \
  --linking.source.fields book_id \
  --linking.target.fields author_id

--relationship.fields

直接關係的冒號分隔欄位對應。

該 --relationship.fields 值為逗號分隔的雙對列表 sourceField:targetField 。

Example

dab update \
  User \
  --relationship profile \
  --target.entity Profile \
  --cardinality one \
  --relationship.fields "id:user_id"

產生的設定

{
  "entities": {
    "User": {
      "relationships": {
        "profile": {
          "cardinality": "one",
          "target.entity": "Profile",
          "source.fields": [ "id" ],
          "target.fields": [ "user_id" ],
          "linking.source.fields": [],
          "linking.target.fields": []
        }
      }
    }
  }
}

--rest

控制 REST 暴露。

Example

dab update \
  Book \
  --rest BooksApi

產生的設定

{
  "entities": {
    "Book": {
      "rest": {
        "enabled": true,
        "path": "/BooksApi"
      }
    }
  }
}

--rest.methods

僅限預存程序。 取代允許的 HTTP 方法。 預設為 POST。

Example

dab update \
  RunReport \
  --rest true \
  --rest.methods GET,POST

產生的設定

{
  "entities": {
    "RunReport": {
      "rest": {
        "enabled": true,
        "methods": [ "get", "post" ]
      }
    }
  }
}

備註

停用 REST 時提供 --rest.methods 沒有任何效果。

-s, --source

更新基礎資料庫物件。

Example

dab update \
  Book \
  --source dbo.Books

產生的設定

{
  "entities": {
    "Book": {
      "source": {
        "object": "dbo.Books",
        "type": "table"
      }
    }
  }
}

--source.type

變更來源物件類型。

備註

視圖需要 --source.key-fields。 若未指定鍵欄位，則 view 會產生錯誤。

Example

dab update \
  Book \
  --source.type view \
  --source.key-fields "id"

產生的設定

{
  "entities": {
    "Book": {
      "source": {
        "type": "view",
        "object": "Book"
      },
      "fields": [
        {
          "name": "id",
          "primary-key": true
        }
      ]
    }
  }
}

--source.params

僅限預存程序。 預設參數值以 name:value 成對形式。

Example

dab update \
  RunReport \
  --source.params "startDate:2024-01-01,endDate:2024-12-31"

產生的設定

{
  "entities": {
    "RunReport": {
      "source": {
        "type": "stored-procedure",
        "parameters": [
          {
            "name": "startDate",
            "required": false,
            "default": "2024-01-01"
          },
          {
            "name": "endDate",
            "required": false,
            "default": "2024-12-31"
          }
        ]
      }
    }
  }
}

--source.key-fields

指定主鍵欄位，適用於沒有推斷鍵的視圖或資料表。

Example

dab update \
  Book \
  --source.type view \
  --source.key-fields "id"

產生的設定

{
  "entities": {
    "Book": {
      "source": {
        "type": "view",
        "object": "Book"
      },
      "fields": [
        {
          "name": "id",
          "primary-key": true
        }
      ]
    }
  }
}

備註

檢視總是需要鍵欄位。 該 --source.key-fields 選項會將元素加入 fields 陣列，且 "primary-key": true。

-m, --map

指定資料庫欄位名稱與暴露的 REST/GraphQL 欄位名稱之間的對應。

Example

dab update \
  Book \
  --map "id:bookId,title:bookTitle"

產生的設定

{
  "entities": {
    "Book": {
      "fields": [
        {
          "name": "id",
          "alias": "bookId",
          "primary-key": false
        },
        {
          "name": "title",
          "alias": "bookTitle",
          "primary-key": false
        }
      ]
    }
  }
}

備註

這個--map選項會在陣列中建立帶有fields屬性設定的項目alias。

--parameters.name

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

備註

此選項可在 2.0.0-rc CLI 中提供。 Data API 建構器 2.0 目前處於預覽階段。 安裝時用 dotnet tool install microsoft.dataapibuilder --version 2.0.0-rc --prerelease.

小提示

要定義儲存程序參數，請使用 --parameters.name 、 --parameters.description--parameters.required、 --parameters.default和 。

Example

dab update \
  GetOrdersByDateRange \
  --parameters.name "StartDate,EndDate" \
  --parameters.required "true,true" \
  --parameters.description "Beginning of date range,End of date range"

產生的設定

{
  "entities": {
    "GetOrdersByDateRange": {
      "source": {
        "parameters": [
          {
            "name": "StartDate",
            "description": "Beginning of date range",
            "required": true
          },
          {
            "name": "EndDate",
            "description": "End of date range",
            "required": true
          }
        ]
      }
    }
  }
}

--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 update \
  GetOrdersByDateRange \
  --parameters.name "StartDate,EndDate" \
  --parameters.description "Beginning of date range,End of date range"

--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 update \
  GetOrdersByDateRange \
  --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 update \
  GetOrdersByDateRange \
  --parameters.name "CustomerID" \
  --parameters.default "null"

--fields.name

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

備註

此選項可在 2.0.0-rc CLI 中提供。 Data API 建構器 2.0 目前處於預覽階段。 安裝時用 dotnet tool install microsoft.dataapibuilder --version 2.0.0-rc --prerelease.

Example

dab update \
  Products \
  --fields.name Id \
  --fields.primary-key true \
  --fields.description "Product Id"

產生的設定

{
  "entities": {
    "Products": {
      "fields": [
        {
          "name": "Id",
          "description": "Product Id",
          "primary-key": true
        }
      ]
    }
  }
}

--fields.alias

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

備註

此選項可在 2.0.0-rc CLI 中提供。 Data API 建構器 2.0 目前處於預覽階段。 安裝時用 dotnet tool install microsoft.dataapibuilder --version 2.0.0-rc --prerelease.

小提示

使用 --fields.alias with --fields.name 來定義暴露欄位名稱。

Example

dab update \
  Products \
  --fields.name "Id,Title" \
  --fields.alias "product_id,product_title"

--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 update \
  Products \
  --fields.name Id \
  --fields.description "Product Id"

--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.

小提示

使用 --fields.primary-key 來 --fields.name 定義沒有推斷鍵的視圖或表格的主鍵欄位。

Example

dab update \
  SalesSummary \
  --fields.name "year,region" \
  --fields.primary-key "true,true"

產生的設定

{
  "entities": {
    "SalesSummary": {
      "fields": [
        {
          "name": "year",
          "primary-key": true
        },
        {
          "name": "region",
          "primary-key": true
        }
      ]
    }
  }
}

--mcp.dml-tools

啟用或停用 MCP DML（資料操作語言）工具以支援此實體。 預設值為 true。

備註

此選項可在 2.0.0-rc CLI 中提供。 Data API 建構器 2.0 目前處於預覽階段。 安裝時用 dotnet tool install microsoft.dataapibuilder --version 2.0.0-rc --prerelease.

Example

dab update \
  Book \
  --mcp.dml-tools false

產生的設定

{
  "entities": {
    "Book": {
      "mcp": {
        "dml-tools": false
      }
    }
  }
}

備註

使用 --mcp.dml-tools 時，設定 mcp 為物件形式，使配置明確。

--mcp.custom-tool

僅限預存程序。 啟用此實體的 MCP 自訂工具。 預設值為 false。

備註

此選項可在 2.0.0-rc CLI 中提供。 Data API 建構器 2.0 目前處於預覽階段。 安裝時用 dotnet tool install microsoft.dataapibuilder --version 2.0.0-rc --prerelease.

Example

dab update \
  RunReport \
  --mcp.custom-tool true

產生的設定

{
  "entities": {
    "RunReport": {
      "mcp": {
        "custom-tool": true
      }
    }
  }
}

-c, --config

組態檔的路徑。

Example

dab update \
  Book \
  --description "Updated description" \
  --config dab-config.json

--help

顯示說明畫面。

Example

dab update --help

--version

顯示版本資訊。

Example

dab update --version

這很重要

變更來源類型可能會使其他屬性失效。 例如，視圖始終需要索引鍵欄位;預存程序無法定義索引鍵欄位。

  • Last updated on