適用於: 畫布應用
請求單一 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 持續保存未遮罩的值,寫入日誌,或複製到保護較弱的資料來源。 避免在截圖或診斷附件中暴露未掩蔽的資料。