在 Foundry IQ(Azure AI 搜尋服務)(預覽版)中保留 OneLake 權限

設定 OneLake 索引器或已編索引的 OneLake 知識來源,以保留 Microsoft OneLake 權限。 Foundry IQ(Azure AI 搜尋服務)會索引來源位置的中繼資料,而非使用者與群組 ACL,並使用 OneLake 在查詢時評估請求使用者的存取權。

本文補充了 OneLake 檔案 索引,並建立一個針對權限匯入的特定設定的 索引 OneLake 知識來源 。 管理 Microsoft Fabric 中的來源權限。

此預覽僅支援 Azure 公共雲。

Important

OneLake 權限擷取目前處於公開預覽階段,並受 Microsoft Azure 預覽補充使用條款的約束。

有關此功能專屬的預覽術語,請參閱 「預覽功能」。

有關連接外部資料來源時適用的術語,請參閱「外部資料來源」。

Prerequisites

設定 OneLake 索引器

對於直接管理的索引器管線,請將以下設定新增至 標準 OneLake 索引設定中。 這些設定是設定新增的,而非完整的建立請求。

  1. 在資料來源上設定 indexerPermissionOptions 以選取要匯入的來源位置元資料。 可分別選取 oneLakeParentFolders 和 oneLakeLakehouseId 以進行匯入。 以下 JSON 片段會選取兩者以進行具權限感知的擷取:

    {
      "indexerPermissionOptions": [
        "oneLakeParentFolders",
        "oneLakeLakehouseId"
      ]
    }
    
  2. 定義目標索引中的相應欄位。

    來源中繼資料 範例目標欄位 索引欄位類型 必填欄位配置
    metadata_onelake_parent_folders onelake_parent_folders Collection(Edm.String) filterable: true; permissionFilter: "oneLakeParentFolders"。
    metadata_onelake_lakehouse_id onelake_lakehouse_id Edm.String filterable: true; permissionFilter: "oneLakeLakehouseId"。
    metadata_onelake_is_shortcut metadata_onelake_is_shortcut Edm.Boolean 一個帶有 filterable: true 且沒有 permissionFilter 註解的頂層欄位。 保留此欄位名稱。

    湖屋 ID 用來識別已設定的來源湖屋,而不是捷徑的目標湖屋。

  3. 將索引的 permissionFilterOption 設定為 enabled,並將 oneLakeSecuritySource 設定為來源工作區與湖屋 ID:

    {
      "permissionFilterOption": "enabled",
      "oneLakeSecuritySource": {
        "fabricWorkspaceId": "<fabric-workspace-id>",
        "lakehouseId": "<lakehouse-id>"
      }
    }
    

不要用 OneLake 的權限選項取代 userIds 或 groupIds。 這些欄位代表來源位置,而非複製的使用者及群組 ACL 項目。

保留來源提供的數值。 不要用技能輸出、映射函數或從文件內容衍生的欄位來取代它們。

Project欄位到區塊中

當技能組建立區塊時,請透過 索引投影將三個中繼資料欄位全部映射到每個區塊上。 這些投影對應會直接填入區塊欄位;你不需要 indexer fieldMappings。

  1. 將前表中的三個欄位加入區塊索引中。 依照前面所述設定該索引 permissionFilterOption 與 oneLakeSecuritySource 。

  2. 將以下這個片段加入你的技能組合。 它使用標準區塊索引架構,搭配parent_id欄位和文字分割技能,該技能會產生/document/pages/*。 在調整範例時,請保留其他內容對應。

    {
      "indexProjections": {
        "selectors": [
          {
            "targetIndexName": "<chunk-index-name>",
            "parentKeyFieldName": "parent_id",
            "sourceContext": "/document/pages/*",
            "mappings": [
              {"name": "chunk", "source": "/document/pages/*"},
              {
                "name": "onelake_parent_folders",
                "source": "/document/metadata_onelake_parent_folders"
              },
              {
                "name": "onelake_lakehouse_id",
                "source": "/document/metadata_onelake_lakehouse_id"
              },
              {
                "name": "metadata_onelake_is_shortcut",
                "source": "/document/metadata_onelake_is_shortcut"
              }
            ]
          }
        ],
        "parameters": {"projectionMode": "skipIndexingParentDocuments"}
      }
    }
    

使用 skipIndexingParentDocuments,只寫區段。 每個已寫入的內容索引都需要三個中繼資料欄位。 直接從先前在每個內容投影中顯示的對應 /document/metadata_onelake_* 來源直接對應。

設定文件索引的欄位對應

對於非區塊擷取或獨立父索引,來源與目標名稱相符且類型相容時,會自動對應。 僅使用 索引子欄位對應 來重新命名這些元資料欄位,例如在範例結構描述中,將 metadata_onelake_parent_folders 重新命名為 onelake_parent_folders,並將 metadata_onelake_lakehouse_id 重新命名為 onelake_lakehouse_id。 未更改 metadata_onelake_is_shortcut 的名稱不需要明確的欄位對應。

在現有索引中新增權限欄位並不會將這些欄位填入已建立索引的文件中。 設定權限擷取後,重新 處理這些文件 以填充所需的中繼資料。

設定已索引的 OneLake 知識來源

當您建立索引的 OneLake 知識來源時,請在indexedOneLakeParameters.ingestionParameters.ingestionPermissionOptions中設定這兩個值:

{
  "ingestionPermissionOptions": [
    "oneLakeParentFolders",
    "oneLakeLakehouseId"
  ]
}

此 JSON 片段僅顯示權限設定。 與直接資料來源選項不同,這兩個值必須一併提供,才能進行受保護的索引 OneLake 匯入。 如需完整使用 2026-11-01-preview 兩種權限選項的 REST 建立範例,請參閱 「建立帶有 OneLake 權限保留的知識來源」。

知識來源會產生索引欄位、索引層級權限設定、欄位對應以及區塊投影。 您不需要分別設定這些產生的映射。

啟用 OneLake 權限擷取後,可省略 資產儲存、豐富快取及圖形擷取設定。

以請求使用者的身分進行查詢

使用現有的 ACL 查詢與測試流程,包括請求使用者的 x-ms-query-source-authorization 令牌。 針對 OneLake 權限感知要求,請使用 2026-11-01-preview,而非那些共用範例中的 API 版本。 對於知識庫,請遵循共用查詢時授權指引。 OneLake 不需要獨立的查詢協定。

搜尋會在已設定的 lakehouse 內,將請求使用者可讀的 OneLake 資料夾與索引的上層資料夾值進行比對。 與文件的直接父資料夾或祖先資料夾匹配,可以使該文件有資格被檢索。 來源權限仍會在 Fabric 中被管理。

對於 Files/teamA/reports/document.txt,索引資料夾的值為 ["Files", "Files/teamA", "Files/teamA/reports"]。 檔案名稱未包含在內。 階層結構包含已設定的匯入子資料夾上方的祖先。

路徑依 Lakehouse 為準,使用 / 分隔符號,且開頭或結尾都沒有斜線。 匹配是大小寫區分的。 依照提供的方式保留空格、Unicode 字元以及字面百分比字元;不要用 URI 解碼或以其他方式重寫這些中繼資料值。

考慮權限與路徑新鮮度

索引的來源位置與查詢時的存取資訊可能會在不同時間發生變化。 權限變更(包括撤銷)可能需要時間才能影響資料擷取;沒有固定的端到端新鮮度間隔。

查詢使用索引內容與查詢時授權;它們不會觸發索引器執行。 索引器通常在建立時執行,除非被停用,之後則按需或排程執行。 排定時間或執行請求並不是完成截止日期。 請參閱排程行為,以了解延遲或略過啟動的情況。

Stage 什麼會延遲變更
Fabric 與 OneLake 工作區角色、項目存取權及資料夾權限的傳播。
啟動索引器 排程與執行能力;排程或請求的執行可能不會立即開始。
索引器執行 處理時間、節流、重試或失敗的項目。
索引可用性 區塊投影、文件寫入與索引重新整理會影響更新內容與路徑元資料何時可搜尋。
要求者身分 權杖新鮮度及使用者角色或群組成員資格的變更。
查詢時存取 快取的 OneLake 存取資訊可持續反映先前權限,直到重新整理。 單靠新使用者令牌並不能清除快取資訊。

使用 索引器狀態與執行歷史 來檢查執行層級的開始與結束時間、錯誤、警告及失敗項目。 頂層 running 狀態表示索引器可用,可執行,而非執行正在進行中。 請檢查具代表性的文件與區塊,以確認所需的元資料。 成功執行擷取不代表 Fabric 傳播、使用者權杖及快取存取資訊也已重新整理。

在移動、重新命名、刪除或路徑重用後,檢查舊位置及新位置的舊記錄是否已過時。 較舊的索引內容可以持續與目前存取權變更的路徑相關聯。

在實體移除來源檔案之前,請先使用 OneLake 的軟刪除工作流程 。 如果來源檔案已經移除,請 手動刪除被遺棄的搜尋文件與區塊。

依照 執行與重設指引 ,重新處理仍然存在的檔案。 重設索引器不會刪除其已索引的文件,也不會重新整理查詢時的存取資訊。

在驗證權限變更時,請使用全新使用者權杖及共用 ACL 測試流程。 比較被允許的使用者與被拒絕的使用者,並在適用時檢查父文件和區塊兩者。 不要用擷取完成作為撤銷完成的衡量標準。

了解捷徑權限邊界

OneLake 權限感知擷取在本預覽中不支援捷徑。 由捷徑衍生的內容會被排除在結果之外,包括透過 OneLake-to-OneLake 及外部捷徑所到達的內容。 存取包含資料夾或捷徑目標,並不會因此允許擷取捷徑內容。

一般的 捷徑擷取支援 與權限感知擷取是分開的。

必填 metadata_onelake_is_shortcut 欄位用來區分捷徑衍生內容與直接檔案。 將其定義為頂層 Edm.Boolean 欄位,且 filterable: true 且沒有 permissionFilter 註解。 保留此欄位名稱及其來源提供的值。 缺少或為空值不會讓文件符合權限篩選結果的資格。 不要將此欄位替換為常數值,也不要從父資料夾存取中推斷它。

根據經過權限過濾的內容,所列的數量、分面、引用數以及依據資訊,並不是所有已索引內容的清單。

排除權限感知擷取問題

對於遺失的結果,請在使用共用查詢疑難排解指引前,先檢查下列來源特定條件:

  • 確認三個必填欄位的存在,並具備先前所示的類型與屬性。 對於區塊,請檢查每個投影的映射與來源路徑。
  • 檢查 Foundry IQ 服務的系統指派受控識別及其 Fabric 工作區 管理員 角色。
  • 檢查內容是否透過 shortcut 傳送。 Shortcut 排除是預覽限制,而非缺少父資料夾授權。
  • 在移動內容或變更權限後,檢查路徑的新鮮度、大小寫以及已設定的 lakehouse。
  • 如果 OneLake 的存取解析因驗證、分頁、無效回應或路徑解析而失敗,查詢會回傳錯誤,而非繼續執行不完整的存取資訊。 在重試之前,請先修正來源存取或設定。

Limitations

內建文字與嵌入技能支援 OneLake 權限匯入。 以下預覽限制適用:

  • 由捷徑衍生的內容會排除在權限感知檢索之外。 請參閱 捷徑權限邊界。
  • 啟用任一 OneLake 權限選項後,都不支援擴充快取、知識存放區及自訂 Web API 技能。
  • 聊天完成技能需要支援的 Microsoft 端點,以進行 OneLake 權限擷取;不支援自訂網域及 Azure API 管理 端點。 如果您同時啟用敏感度標籤匯入,聊天完成技能將不支援任何端點。