Dataverse.Unmask 函数

适用于: 画布应用

请求单个Microsoft Dataverse记录的安全列的未屏蔽值。

Description

该 Dataverse.Unmask 函数以异步方式读取列,并返回具有列的 Power Fx 类型的单个值。 它不返回记录或表、更新源记录、更改掩码规则或替换应用中其他位置的掩码值。

Dataverse 强制实施用户的权限。 该函数不授予访问权限或绕过列级安全性。 若要读取未屏蔽的值,用户需要访问表和记录、列 读取 权限以及列安全配置文件中相应的 读取未屏蔽 权限。

在画布应用中将 Dataverse 表添加为数据源,并在该列上启用列级安全性。 若要配置掩码,请在托管环境中应用受支持的掩码规则。 安全列不一定具有掩码规则。 请参阅 列级安全性 并 创建和管理配置 、权限选项和支持的掩码规则类型的掩码规则。

Important

让管理员为方案选择适当的 读取未屏蔽 权限。 不要仅授予 “所有记录 ”以启用单记录示例。 使用非管理员帐户测试访问限制,因为列级安全性不会向系统管理员隐藏数据。

Syntax

Dataverse.Unmask( Record, Column )
  • 记录 - 必需。 保留其 Dataverse 记录标识的记录,并与一个 Dataverse 数据源完全关联。
  • 列 - 必需。 该记录上受保护支持的标量列的标识符。 提供列标识符,而不是包含列名称的文本表达式。

可以对 列使用有效的显示名称或逻辑名称。 在包含空格的显示名称周围使用单引号,例如 'Sensitive reference'。 双引号创建文本文本,不相等。 Power Apps将标识符解析为列的逻辑名称。

记录和列要求

如果所选库记录、 LookUp 返回的记录或存储在变量或集合中的记录,则可以使用它保留其 Dataverse 标识并与一个 Dataverse 源的关联。 构造具有相同字段值的匿名记录不会建立该标识。

不要将来自不同 Dataverse 表的记录分配给所使用的 Dataverse.Unmask同一记录变量。 此类变量与多个源相关联,并且被拒绝,即使表具有具有匹配名称的安全列也是如此。 使用单独的单源变量或调用。

必须保护目标列,并且具有受支持的标量类型。 不支持查找值、记录、表、文件、图像和非类型化列。 通过查找读取记录不同于取消屏蔽查阅值列。 有关支持的掩码方案,请参阅 掩码规则文档 ;公式类型接受不会确定可以为列配置掩码规则。

返回值和错误

结果具有与目标列相同的 Power Fx 类型。 例如,文本列返回文本,而不是包含文本的记录。

使用 IfError 处理失败的读取。 Dataverse 确定访问受限时的响应;不要假设每个权限拒绝都会生成 HTTP 错误。

Situation Behavior
该记录没有关联的 Dataverse 源或具有多个 Dataverse 源。 Power Apps Studio 拒绝记录参数。
该列未知、不安全或具有不受支持的类型。 Power Apps Studio 拒绝列参数。
非空记录在运行时没有有效的标识,或者无法解析其 Dataverse 源。 该函数返回无效记录错误。
Dataverse 请求失败。 该函数返回可以使用 IfError 处理的 Power Fx 错误。
成功的请求不返回行、省略请求的列或返回 null 值。 结果为空。

仅空白结果无法识别权限问题。 在将空白结果视为失败之前,请检查所选记录、其值和用户的访问权限。

Examples

这些示例使用具有名为'Sensitive reference'安全文本列的Customers演示 Dataverse 表。 将表添加为数据源、配置掩码规则,并将综合记录与具有相应权限的测试用户一起使用。 将表名和列名替换为你自己的名称。

读取所选记录

将库的 Items 属性设置为 Customers。 选中保存的记录后,此公式将请求其未屏蔽的引用:

Dataverse.Unmask( Gallery1.Selected, 'Sensitive reference' )

如果存储的值是 "REF-12345" 并且用户有权取消屏蔽读取它,则预期结果为文本 "REF-12345"。 公式不会更改读取 Gallery1.Selected.'Sensitive reference'的掩码值。

处理文本结果的错误

在要显示未屏蔽值的文本标签 的 Text 属性中使用以下公式:

IfError(
    Dataverse.Unmask( Gallery1.Selected, 'Sensitive reference' ),
    "Unable to show this value."
)

替换值是文本,因为 'Sensitive reference' 是文本列。 对于其他受支持的列类型,请在返回文本消息之前使用兼容的替换值或转换结果。 如果Error 处理错误,则不成功空结果。

有关完整的显示和隐藏交互,请参阅 “显示屏蔽的 Dataverse 列值”。

数据处理

重复评估可以重复使用缓存的结果,而不是发出新的网络请求。 不要依赖另一个评估来重新检查最近更改的权限。 隐藏控件不是授权边界,也不会清除缓存的值。

不要使用 SaveData 保留未屏蔽的值,将其写入日志,或将它们复制到不太受保护的数据源。 避免在屏幕截图或诊断附件中公开未屏蔽的数据。