Dataverse.Unmask 函數

適用於: 畫布應用

請求單一 Microsoft Dataverse 紀錄的安全欄位的未遮罩值。

Description

該 Dataverse.Unmask 函式非同步讀取欄位,並回傳一個欄位的 Power Fx 類型值。 它不會回傳記錄或資料表、更新來源記錄、更改遮罩規則,或替換應用程式其他遮罩值。

Dataverse 會強制執行使用者的權限。 這個函式不會授權存取或繞過欄位層級的安全。 要讀取未遮罩值,使用者需要存取資料表與記錄、欄位 讀取權限, 以及欄位安全設定檔中適當的 讀取解除防護 權限。

在你的畫布應用程式中將 Dataverse 表格加入為資料來源,並在該欄位啟用欄位層級的安全。 要設定遮蔽,請在受管理環境中套用支援的遮蔽規則。 安全柱不一定有遮罩規則。 請參閱欄位 層級安全性 及 建立與管理遮蔽規則 ,了解設定、權限選項及支援的遮罩規則類型。

Important

請你的管理員為該情境選擇適當的 Read unmasked 權限。 不要僅僅為了啟用單一紀錄範例而授予 所有紀錄 。 用非管理員帳號測試存取限制,因為欄位層級的安全不會對系統管理員隱藏資料。

Syntax

Dataverse.Unmask( Record, Column )
  • 紀錄 - 必備。 一個保留其 Dataverse 記錄身份,且只與一個 Dataverse 資料來源相關聯的紀錄。
  • 欄位 - 必填。 該紀錄上一個安全且支援的標量欄位識別碼。 請提供欄位識別碼,而非包含欄位名稱的文字表達式。

你可以使用有效的顯示名稱或邏輯名稱來表示 欄位。 在包含空格的顯示名稱周圍使用單引號,例如 'Sensitive reference'。 雙引號會直接創造文字,並不等同。 Power Apps 會將識別碼解析為欄位的邏輯名稱。

記錄與欄位要求

只要選取的圖庫紀錄、 LookUp 回傳的紀錄,或是存放在變數或集合中的紀錄,只要它仍保有 Dataverse 身份並與一個 Dataverse 來源有關聯,就可以使用。 建立一個欄位值相同的匿名紀錄並不能確立該身份。

不要將不同 Dataverse 資料表的紀錄指派到同一個由 Dataverse.UnmaskS 使用的紀錄變數。 此類變數會與多個來源相關聯,即使資料表的欄名相符,也會被拒絕。 使用獨立的單一來源變數或呼叫。

目標欄位必須是固定的,且有支援的純量類型。 查詢值、記錄、表格、檔案、影像和未打型欄位則不被支援。 透過查詢讀取記錄與揭露查找值欄位是不同的。 有關支援的遮罩情境,請參閱 遮蔽規則文件 ;公式型別接受並不代表可以為欄位設定遮罩規則。

回傳值與錯誤

結果的 Power FX 類型與目標欄位相同。 例如,文字欄位回傳的是文字,而非包含文字的記錄。

使用 IfError 來處理讀取失敗。 Dataverse 在存取受限時決定回應;不要以為每次拒絕權限都會產生 HTTP 錯誤。

Situation 行為
該紀錄沒有相關的 Dataverse 來源,或是有多個 Dataverse 來源。 Power Apps Studio 拒絕了記錄參數。
欄位為未知、無擔保或無支撐型。 Power Apps Studio 會拒絕欄位參數。
非空白記錄在執行時沒有有效的身份,或其 Dataverse 來源無法解析。 該函式會回傳一個無效記錄錯誤。
Dataverse 請求失敗。 這個函式會回傳一個 Power Fx 錯誤,你可以用 IfError 來處理。
成功請求不會回傳任何列、遺漏請求欄位或回傳空值。 結果是空白的。

僅有空白結果並不代表是權限問題。 在將空白結果視為失敗前,請檢查所選紀錄、其值及使用者的存取權限。

Examples

這些範例使用 Customers 一個具安全文字欄位 'Sensitive reference'的說明性資料表。 將資料表加入資料來源,設定遮罩規則,並與擁有適當權限的測試使用者使用合成紀錄。 把表格和欄位名稱換成你自己的。

閱讀精選紀錄

將畫廊的 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' 是文字欄位。 對於支援的不同欄位類型,請使用相容的替換值,或在回傳文字訊息前先轉換結果。 IfError 處理錯誤,而非成功的空白結果。

欲了解完整的揭示與隱藏互動,請參見「 揭露遮罩的 Dataverse 欄位值」。

資料處理

重複評估可以重複使用快取結果,而非重新提出網路請求。 不要指望再評估一次,重新檢查最近更改的權限。 隱藏控制項不是授權邊界,也不會清除快取值。

不要用 SaveData 持續保存未遮罩的值,寫入日誌,或複製到保護較弱的資料來源。 避免在截圖或診斷附件中暴露未掩蔽的資料。