uip df 实体

“uip df实体”的语法和选项，可浏览和变异 Data Fabric 实体架构。

uip df entities 浏览和变异 Data Fabric 实体架构。实体是一种类型化的数据模型，即具有命名字段和类型的行形状。动词涵盖发现（ list 、 get ）、创作（ create 、 update ）和删除（ delete ）；记录级操作存在于uip df records中。

大纲

uip df entities list [--native-only] [--folder-key <key> | --include-folders]
uip df entities get <id> [--folder-key <key>]
uip df entities create <name> (-f <path> | --body <json>) [--folder-key <key>]
uip df entities update <id> (-f <path> | --body <json>) [-y --reason <text>] [--folder-key <key>]
uip df entities delete <id> -y --reason <text> [--folder-key <key>]

动词

动词	用途
list	列出实体。默认为租户级别的实体； --folder-key 作用域限定于一个文件夹，--include-folders 限定每个文件夹的实体以及租户级别的实体。
get	返回单个实体的架构（包括所有字段）。
create	根据 JSON 定义新建实体。
update	更新实体的元数据或架构 — 添加字段、更新字段元数据或删除字段（破坏性，需要 -y/--reason）。
delete	完全删除实体（具有破坏性，需要 -y/--reason）。

--folder-key、--native-only、--include-folders

--folder-key <key>（文件夹 GUID）将动词的作用域限定为文件夹级别实体，而不是租户。此设置适用于该组中的每个动词。在 list，它与 --include-folders 互斥（在一次调用中列出租户级别的实体以及每个文件夹的实体）。--native-only（仅在 list 上）筛选出联合实体 - 由外部连接器连接支持的实体（由非空的 externalFields 数组标识）。

uip df 实体列表

列出 Data Fabric 实体。

选项

短	长	值	默认	描述
—	--native-only	标记	关闭	仅显示原生实体；排除具有外部连接的联合实体。
—	--folder-key	键值	—	用于将列表的范围限定到特定文件夹的文件夹键值 (GUID)。与 --include-folders 互斥。
—	--include-folders	标记	关闭	列出租户级别的实体以及可以看到的每个文件夹中的实体。与 --folder-key 互斥。

示例

uip df entities list --native-only

uip df entities list --folder-key f1000000-0000-0000-0000-000000000001

数据形状（--输出 json）

{
  "Code": "EntityList",
  "Data": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "name": "Invoice",
      "displayName": "Invoice",
      "entityType": "Standard",
      "description": "Invoice records",
      "folderId": "f1000000-0000-0000-0000-000000000001",
      "isRbacEnabled": false,
      "fields": [
        { "id": "f1000000-0000-0000-0000-000000000001", "name": "amount" }
      ],
      "externalFields": []
    }
  ]
}

重要提示：

此处的Data行是原始 SDK 对象，采用驼峰式命名法——与下面的get响应不同， list不会采用帕斯卡拼写法命名字段名称，也不会改变有效负载的形状。每行的 folderId 都是在针对该实体的后续命令中作为 --folder-key 传递的值。

uip df 实体获取

返回单个实体的架构，包括所有字段。

参数

名称	必填	用途
<id>	是	实体 ID (UUID)。使用entities list查找。

选项

短	长	值	默认	描述
—	--folder-key	键值	—	对于文件夹范围内的实体，包含实体的文件夹的文件夹密钥 (GUID)。

示例

uip df entities get a1b2c3d4-0000-0000-0000-000000000001

数据形状（--输出 json）

{
  "Code": "EntitySchema",
  "Data": {
    "Id": "a1b2c3d4-0000-0000-0000-000000000001",
    "Name": "Invoice",
    "DisplayName": "Invoice",
    "EntityType": "Standard",
    "Description": "Invoice records",
    "IsRbacEnabled": false,
    "Fields": [
      {
        "Id": "f1000000-0000-0000-0000-000000000002",
        "Name": "amount",
        "DisplayName": "Amount",
        "FieldDataType": {
          "Name": "DECIMAL",
          "DecimalPrecision": 2,
          "MinValue": 0,
          "MaxValue": 999999
        },
        "IsRequired": true,
        "IsUnique": false,
        "IsEncrypted": false,
        "IsRbacEnabled": false,
        "IsPrimaryKey": false,
        "IsSystemField": false
      }
    ]
  }
}

与list不同，此响应遵循帕斯卡拼写法。字段的类型名称及其约束（DecimalPrecision、MinValue、MaxValue、LengthLimit 等，具体取决于类型，依此类推）实时嵌套在 FieldDataType 下，而不作为字段的平面属性。

uip df 实体创建

创建新实体。实体名称必须以字母开头，并且仅包含字母、数字和下划线。以直接方式 (--body) 或从文件中 (--file) 传递定义。

参数

名称	必填	用途
<name>	是	实体名称（以字母开头；仅限字母、数字和下划线）。

选项

短	长	值	默认	描述
-f	--file	路径	—	包含实体定义的 JSON 文件的路径（需要 fields 数组；displayName、description、isRbacEnabled、isAnalyticsEnabled 可选）。
—	--body	JSON	—	内联 JSON 实体定义，形式与 --file 相同。
—	--folder-key	键值	—	目标文件夹的文件夹密钥 (GUID)，用于创建文件夹范围的实体而不是租户级别的实体。

实体定义对象：

{
  "displayName": "Invoice",
  "description": "Invoice records",
  "isRbacEnabled": false,
  "fields": [
    { "name": "title", "type": "STRING" }
  ]
}

重要提示：

每个字段对象都需要name ，而不是fieldName — fieldName传递失败，并显示验证错误Each field must include a 'name' string 。此处也接受从 entities get 的输出（使用 Name/FieldDataType，帕斯卡拼写法）原义复制的字段对象，并自动标准化为此平面写入形状。

有效的type 值来自 SDK 的EntityFieldDataType ValidationError枚举，无效的类型将失败，并会列出完整的允许集合。除了简单的标量类型（STRING、DECIMAL、GUID、BOOLEAN、DATE、DATETIME 等）外，几种类型在字段对象上采用额外的必填属性：

类型	必需的额外属性
CHOICE_SET_SINGLE / CHOICE_SET_MULTIPLE	choiceSetId — 来自df choice-sets list UUID。
RELATIONSHIP	referenceEntityId （目标实体的 UUID，来自 entities list）和 referenceFieldId（目标实体上字段的 UUID，来自 entities get <target-id>）。当目标实体位于其他文件夹中时，可以选择使用 referenceFolderKey。
FILE	仅 name 和 type — 服务器自动关联内部附件引用。稍后使用uip df files upload填充该值。
MULTILINE_MAX	可选 lengthLimit（UTF-16 字节预算，1–131072；默认情况下大约 65,536 个字符）。不可筛选或可排序； records list/query 仅返回其大小标记 — 使用 records get 读取完整内容。由租户的 MultilineMax 功能标志进行门控。

无论哪个referenceFieldId配置了联接，记录上的RELATIONSHIP列始终存储目标记录的Id （UUID）。有关如何写入值，请参阅records insert 。

示例

uip df entities create Invoice --file ./invoice.entity.json

uip df entities create Invoice \
    --body '{"displayName":"Invoice","fields":[{"name":"amount","type":"DECIMAL"}]}'

# choice-set, relationship, file, and large-text fields
uip df entities create Expense \
    --body '{"displayName":"Expense","fields":[{"name":"category","type":"CHOICE_SET_SINGLE","choiceSetId":"c1d2e3f4-0000-0000-0000-000000000001","isRequired":true},{"name":"submitter","type":"RELATIONSHIP","referenceEntityId":"a1b2c3d4-0000-0000-0000-000000000010","referenceFieldId":"f1000000-0000-0000-0000-000000000100","isRequired":true},{"name":"receipt","type":"FILE"},{"name":"notes","type":"MULTILINE_MAX"}]}'

数据形状（--输出 json）

{
  "Code": "EntityCreated",
  "Data": { "ID": "a1b2c3d4-0000-0000-0000-000000000001" }
}

uip df 实体更新

更新实体的元数据或架构。正文接受 addFields、updateFields、removeFields、displayName、description 和 isAnalyticsEnabled/isRbacEnabled。实体 name 本身不可变 — 它不能包含在更新正文中。

参数

名称	必填	用途
<id>	是	实体 ID (UUID)。

选项

短	长	值	默认	描述
-f	--file	路径	—	包含更新选项的 JSON 文件的路径。
—	--body	JSON	—	内联 JSON 更新选项。
-y	--yes	标记	—	当removeFields为非空时为必填— 确认字段删除无法撤销。
—	--reason	text	—	当removeFields非空时为必填— 在响应中回显，以便调用者可以记录。
—	--folder-key	键值	—	对于文件夹范围内的实体，包含实体的文件夹的文件夹密钥 (GUID)。

• addFields — 新字段数组，平面写入形状（ name + type ，以及特定于类型的附加功能 — 请参阅上面的create部分）。从 entities get 复制的字段对象也会接受并规范化。
• updateFields — 由字段id （来自entities get ）设置密钥的数组，其中要更改的元数据属性（例如displayName 、 description 、 isRequired 、 isRbacEnabled 、 isEncrypted 、 isHiddenField 、 defaultValue 、约束）。不要在此处粘贴完整复制的字段对象 —传递 id 以及要更改的平面属性。updateFields 无法更改字段的 type 或其 isUnique 设置。
• removeFields — {"name": "<fieldName>"}对象数组，由名称而非 ID 标识。需要 -y/--yes 和 --reason "<text>" — 该操作将删除字段的存储值，并且无法撤销。
• 更新实体元数据（description、isRbacEnabled、isAnalyticsEnabled）时，需要在同一正文中包含 displayName（即使其未更改）— 如果不支持，请先使用 displayName 获取当前 entities get已经拥有了。

示例

# Add a field
uip df entities update a1b2c3d4-0000-0000-0000-000000000001 \
    --body '{"addFields":[{"name":"note","type":"STRING","lengthLimit":200}]}'

# Rename an existing field's display name
uip df entities update a1b2c3d4-0000-0000-0000-000000000001 \
    --body '{"updateFields":[{"id":"f1000000-0000-0000-0000-000000000002","displayName":"Amount (USD)","isRequired":true}]}'

# Remove a field — destructive, requires --yes and --reason
uip df entities update a1b2c3d4-0000-0000-0000-000000000001 \
    --body '{"removeFields":[{"name":"oldColumn"}]}' \
    --yes --reason "quarterly cleanup"

数据形状（--输出 json）

{
  "Code": "EntityUpdated",
  "Data": { "ID": "a1b2c3d4-0000-0000-0000-000000000001" }
}

当更新包含 removeFields 时，响应也会回显已删除的内容：

{
  "Code": "EntityUpdated",
  "Data": {
    "ID": "a1b2c3d4-0000-0000-0000-000000000001",
    "RemovedFields": ["oldColumn"],
    "Reason": "quarterly cleanup"
  }
}

uip df 实体删除

完全删除实体。此操作无法撤销，并且将删除实体的架构及其所有记录。

参数

名称	必填	用途
<id>	是	实体 ID (UUID)。

选项

短	长	值	默认	描述
-y	--yes	标记	—	必需。确认这是一个不可逆的操作。
—	--reason	text	—	必需。删除原因 — 在响应中回显，以便调用者可以记录。
—	--folder-key	键值	—	对于文件夹范围内的实体，包含实体的文件夹的文件夹密钥 (GUID)。

示例

uip df entities delete a1b2c3d4-0000-0000-0000-000000000001 \
    --yes --reason "test entity cleanup"

数据形状（--输出 json）

{
  "Code": "EntityDeleted",
  "Data": {
    "Id": "a1b2c3d4-0000-0000-0000-000000000001",
    "Reason": "test entity cleanup"
  }
}

相关内容

• uip df records — 管理这些实体拥有的行。
• uip df files — 记录上的文件附件。
• uip df choice-sets — 由CHOICE_SET_SINGLE / CHOICE_SET_MULTIPLE字段引用的选项集。
• uip vss generate — 从 Data Fabric 架构导出文件生成 TypeScript 类型。

另请参阅

• Data Fabric 工具概述
• 全局选项
• 退出代码