註
Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。
重要
Microsoft Purview 敏感度標籤的匯入目前處於公開預覽階段,並受 Microsoft Azure 預覽版補充使用條款的約束。
有關此功能專屬的預覽條款,請參閱 預覽功能。
將 Microsoft Purview 敏感性標籤支援(預覽)新增至現有的 Foundry IQ(Azure AI 搜尋服務)索引管線。 設定標籤擷取,標註目標元資料欄位,並將這些值映射到每個索引文件或區塊。 Foundry IQ 會根據您的 Microsoft Purview 政策,使用索引標籤在查詢時強制執行文件層級存取權限。
此功能適用於以下資料來源:
本文中的三個欄位範例使用了已確認適用於 Microsoft 365 中 SharePoint 文件庫 (磁碟機) 檔案的中繼資料。 敏感度標籤匯入不支援 SharePoint list 項目或網站頁面。
先決條件
一個現有的資料來源與索引器,透過前一節連結的連接器指引進行配置。 如果你的管線為區塊建立索引,請先設定技能組和 索引投影,再新增標籤對應。
使用
purviewEnabled: true建立的目標索引,或計畫建立新的已啟用 Purview 的索引,並依照 步驟 4 所述將現有管線重新指向目標。在索引前,先設定 Microsoft Purview 敏感度標籤政策,並將其套用到文件上。
在您的 Microsoft Entra 租戶中擁有全域管理員或特權角色管理員角色,以授予 Foundry IQ 服務對 Purview API 與敏感度標籤的存取權。
Foundry IQ 服務與發出查詢的使用者必須位於同一 Microsoft Entra 租戶中。
使用來源文件,檔案類型同時由 Purview 敏感度標籤支援 ,且由 Foundry IQ 索引器支援。
請使用 REST API 版本 2026-11-01-preview 或等效的預覽 SDK 套件。
Foundry IQ 服務必須使用其系統指派的受控識別向 Microsoft Purview 驗證。 此功能不支援使用者指派的受管理身份。
限制
Azure 入口網站不支援這個功能。
不支援訪客帳戶及跨租戶查詢。
以下索引器功能不支援帶有敏感度標籤的文件。 如果你在技能集或索引器中使用這些功能,帶有敏感標籤的文件就不會被處理。
政策執行方式
敏感性標籤支援分為兩個階段:索引與查詢時強制執行。
索引
索引器擷取文件內容及敏感度標籤元資料。 在後續執行時,當偵測到文件標籤、內容或元資料的變更時,會更新索引值。
索引直到下一次成功執行索引器時,才會反映來源文件的標籤變更。
查詢時強制執行
在查詢時,Foundry IQ 會根據使用者的 Microsoft Entra ID 令牌與 Microsoft Purview 標籤政策,評估敏感度標籤並強制執行文件層級的存取控制。 只有授權在特定標籤下以 READ 使用權 存取內容的使用者,才能在搜尋結果中取得對應的文件。
關於查詢認證與授權需求,請參見 「查詢啟用敏感標籤的索引」。 如需了解行政調查和稽核行為,請參閱提升權限讀取。
1. 啟用 Foundry IQ 受控識別
為您的 Foundry IQ 服務啟用系統指派的管理識別碼。 索引器會利用服務自身的身分向 Microsoft Purview 驗證身分,並執行特EXTRACT權操作,包括讀取加密內容及安全分類。 在 步驟 3 中直接將所需角色指派給這個身份。
2. 在您的 Foundry IQ 服務中啟用 RBAC
在您的 Foundry IQ 服務上啟用基於角色的存取控制(RBAC)。 啟用 Purview 的索引需要 RBAC 認證以進行文件操作,包括內容索引與查詢。 如果其他服務操作依賴 API 金鑰,請同時啟用 RBAC 和 API 金鑰。 此配置不允許對啟用 Purview 的索引進行 API 金鑰文件操作。
3. 授予權限以擷取敏感性標籤
存取 Microsoft Purview 敏感性標籤元資料涉及高度特權的操作。 在分配權限前,請與您的資安或合規團隊合作,並透過組織治理流程取得批准。
核准後,請委託 全域管理員 或 特權角色管理員 ,將這些角色指派給 Foundry IQ 系統指派的管理身份:
- Content.SuperUser 用於標籤與內容擷取。
- UnifiedPolicy.Tenant.Read 用於 Purview 政策及標籤中繼資料存取。
使用 PowerShell 指派角色
僅將這些角色指派給 Foundry IQ 服務的 系統指派管理識別, 而非使用者指派的管理識別、獨立的應用程式服務主體或個別使用者帳戶。 PowerShell 腳本會自動從服務資源中取得管理身份物件 ID。
您的全域管理員或特權角色管理員應使用以下 PowerShell 腳本來授予所需的權限。 透過您核准的治理流程,取得管理員對已委派的 Microsoft Graph 權限範圍 AppRoleAssignment.ReadWrite.All 和 Application.Read.All 的同意。 僅靠租戶管理員角色無法提供這些代幣範圍。
安裝完以下段落所示的模組後,在同一個 PowerShell 會話中建立獨立的 Azure PowerShell 上下文,再執行剩餘指令。 使用 Connect-AzAccount 登入 Foundry IQ 服務的租戶,並使用 Set-AzContext 選擇正確的租戶與訂閱。 Azure 帳戶必須擁有讀取 Foundry IQ 服務資源的權限,例如 Reader 角色。
Connect-Entra 並未建立這個 Az 內容。
請將佔位符替換為您的實際租戶 ID、訂閱 ID、資源群組及 Foundry IQ 服務名稱。
Install-Module -Name Az -Scope CurrentUser
Install-Module -Name Microsoft.Entra -AllowClobber
Import-Module Az.Resources
Connect-Entra -TenantId "<tenantId>" `
-Scopes 'AppRoleAssignment.ReadWrite.All', 'Application.Read.All'
$resourceIdWithManagedIdentity = (
"/subscriptions/<subscriptionId>/resourceGroups/<resourceGroup>/" +
"providers/Microsoft.Search/searchServices/<searchServiceName>"
)
$managedIdentityObjectId = (Get-AzResource `
-ResourceId $resourceIdWithManagedIdentity).Identity.PrincipalId
# Microsoft Information Protection (MIP)
$MIPResourceSP = Get-EntraServicePrincipal `
-Filter "appID eq '870c4f2e-85b6-4d43-bdda-6ed9a579b725'"
New-EntraServicePrincipalAppRoleAssignment `
-ServicePrincipalId $managedIdentityObjectId `
-PrincipalId $managedIdentityObjectId `
-ResourceId $MIPResourceSP.Id `
-Id "8b2071cd-015a-4025-8052-1c0dba2d3f64"
# Microsoft Rights Management Services (MRMS) - policy read
$MRMSResourceSP = Get-EntraServicePrincipal `
-Filter "appID eq '00000012-0000-0000-c000-000000000000'"
New-EntraServicePrincipalAppRoleAssignment `
-ServicePrincipalId $managedIdentityObjectId `
-PrincipalId $managedIdentityObjectId `
-ResourceId $MRMSResourceSP.Id `
-Id "7347eb49-7a1a-43c5-8eac-a5cd1d1c7cf0"
參考資料:Connect-Entra、Get-AzResource、Get-EntraServicePrincipal、New-EntraServicePrincipalAppRoleAssignment 及 Microsoft Graph app-role assignment 權限。
腳本會在下列資源服務主體上為 Foundry IQ 服務的管理身份指派應用程式角色:
| App ID | 資源服務主體 |
|---|---|
870c4f2e-85b6-4d43-bdda-6ed9a579b725 |
Microsoft 資訊保護同步服務 |
00000012-0000-0000-c000-000000000000 |
Microsoft 權利管理服務 |
4. 設定索引以啟用 Purview 敏感性標籤
以下步驟的設定變更請使用 REST API 版本 2026-11-01-preview 。
重要
建立索引時,必須將 purviewEnabled 屬性設定為 true。 此設定為永久,之後無法修改。
如果你現有的索引沒有 purviewEnabled: true,建立一個新的 Purview 啟用索引,並將索引器和所有投影選擇器重新指向該索引。 你無法在現有索引上啟用這個屬性。
對於啟用 Purview 的索引,所有文件操作 API 僅支援 RBAC 認證。 API 金鑰存取僅限於索引結構檢索(list與get)。
在所有支援的敏感度標籤資料來源中,metadata_sensitivity_label 包含一個標籤 ID 作為 GUID 字串。 定義其目標索引欄位為 Edm.String,而非集合。 當文件未標註或故意跳過標籤擷取時,該值可能缺失或為空。
將這三個字串欄位加入目標索引。 如果區塊就是可搜尋文件,請將欄位加入區塊索引。
| 來源元資料欄位 | 目標索引欄位 | 類型與註解 |
|---|---|---|
metadata_sensitivity_label |
sensitivity_label_id |
Edm.String GUID;sensitivityLabelId: true、filterable: true、retrievable: true。 |
metadata_sensitivity_label_name |
sensitivity_label_name |
Edm.String 標籤名稱; sensitivityLabelName: true, retrievable: true。 |
metadata_source_document_id |
source_document_id |
Edm.String 稽核識別碼; sourceDocumentId: true, retrievable: true。 |
source_document_id 欄位可識別用於稽核的來源文件。 它不是搜尋索引鍵或投影父鍵。
警告
以下的 JSON 片段是配置 delta, 而非完整的 PUT 請求實體。 在提交請求前,將它們合併到完整的資源定義中。 建立或更新作業的 PUT 要求會取代該資源的定義。 保留現有欄位與陣列、映射、選項、選擇器、憑證及其他設定;不要用片段替換完整的定義或陣列。
索引建立屬性: 將此屬性包含在新索引的完整建立定義中。 如果現有索引已經包含該欄位,就保持不變。
{
"purviewEnabled": true
}
索引欄位新增: 將這些物件附加到完整索引定義陣 fields 列中,保留現有的結構與索引配置。
[
{
"name": "sensitivity_label_id",
"type": "Edm.String",
"filterable": true,
"retrievable": true,
"sensitivityLabelId": true
},
{
"name": "sensitivity_label_name",
"type": "Edm.String",
"retrievable": true,
"sensitivityLabelName": true
},
{
"name": "source_document_id",
"type": "Edm.String",
"retrievable": true,
"sourceDocumentId": true
}
]
參考資料:索引定義。
對於文件層級的對應,請遵循步驟 7。 對於子區塊,請依照步驟 6進行。
5. 設定資料來源
資料來源選項 delta:將sensitivityLabel加入您已設定的資料來源中的indexerPermissionOptions。 如果已經啟用其他權限選項,請保留它們並附加此選項,而非替換陣列。
{
"indexerPermissionOptions": ["sensitivityLabel"]
}
參考資料: 資料來源定義。
此選項可啟用標籤擷取。 它與 sensitivityLabelId、sensitivityLabelName 和 sourceDocumentId 索引欄位註解是不同的。 保留連接器現有的憑證、容器選擇和其他設定。
6. 在你的技能組中設定指數預測(如適用)
如果你的管線為區塊建立索引,就擴充它現有的索引投影選擇器。 將第 4 步 的欄位新增與 Purview 啟用的索引要求套用到區塊索引上。
投影映射新增內容: 將這些項目附加到 indexProjections.selectors 內相關選擇器的 mappings 陣列中。 這些新增項目並非完整的選取器或技能。
[
{
"name": "sensitivity_label_id",
"source": "/document/metadata_sensitivity_label"
},
{
"name": "sensitivity_label_name",
"source": "/document/metadata_sensitivity_label_name"
},
{
"name": "source_document_id",
"source": "/document/metadata_source_document_id"
}
]
參考:技能組定義。
保留選取器的 targetIndexName、parentKeyFieldName 和區塊 sourceContext,但在必要時可重新指定目標索引。 保留其他選擇器、內容與向量映射,以及現有的投影模式。 明確對應每個非索引鍵子欄位;上述三個新增項目並非完整的對應集合。
這些根級路徑會將父節點上的映射字串值複製到每個區塊上。 投影會產生子鍵與父項關聯以進行變更追蹤。 不要在投影或分塊索引器的 fieldMappings 中手動映射產生的鍵,例如 chunk_id 或 parent_id。
如果你的文字分割技能在 chunks 之下輸出原始字串,請使用 /document/chunks/* 作為選擇器的 sourceContext 和內容對應,而不是使用 /id 或 /text 子路徑。
使用 skipIndexingParentDocuments 時,直接索引器的 fieldMappings 不會填入子文件。 標籤-ID 投影是區塊層級查詢強制執行及相關標籤回應元資料所必需的。 關於回應處理,請參閱 在回應中檢查敏感度標籤中繼資料。
對於 雙索引的父子配置,使用 步驟7 中的直接映射來填充父索引,這些投影則填入子索引。 如需了解對應語意,請參閱審查欄位對應。
7. 設定索引器
每個來源文件對應一個搜尋文件時,可以直接將元資料對應加入現有索引器。 使用原始來源欄位名稱,不加 /document/ 前綴。
直接場域映射新增功能: 將這些項目附加到索引器陣 fieldMappings 列中。 保留其連接器金鑰映射、其他映射、資料來源與技能集連線、目標索引及設定,但必要時需改為指向新的索引。
[
{
"sourceFieldName": "metadata_sensitivity_label",
"targetFieldName": "sensitivity_label_id"
},
{
"sourceFieldName": "metadata_sensitivity_label_name",
"targetFieldName": "sensitivity_label_name"
},
{
"sourceFieldName": "metadata_source_document_id",
"targetFieldName": "source_document_id"
}
]
參考資料: 索引器定義。
對於區塊,保持現有索引器與其技能組的連結;步驟 6 中的選擇器映射會填充子元資料。
確認標籤匯入
將變更合併到完整資源定義後,若現有索引器已處理原始檔案,則進行 初始回填 。 啟用擷取、新增元資料欄位或重新定位管線,並不會讓未更改的檔案符合一般增量執行的條件。 要重新處理那些檔案,先 重置索引器,然後執行它。 重置會清除變更追蹤,隨後執行會重新處理所有原始文件;請將此工作負載納入考量。
如果檔案尚未編製索引,請不重設索引而執行索引子。 使用 Get Indexer Status 來確認執行成功,並檢查文件錯誤與警告。 已接受的執行要求並不代表已完成資料擷取。
使用已授權的查詢身分識別和查詢指南,驗證已知的標記文件及其區塊:
- 來自任何支援來源的已套用標籤檔案,都會在
sensitivity_label_id中填入 GUID 字串。 對於有標籤的 SharePoint 文件庫(磁碟機)檔案,也請在伴隨欄位中確認標籤名稱與原始文件稽核 ID;對於其他來源,請在該來源元資料可用時確認伴隨值。 - 未標註的文件,或故意跳過標籤擷取的文件,其標籤 ID 缺失或為空值。
- 每個子區塊都會繼承其父區塊上可用的映射元資料值,且產生的子與父鍵保持完整。
若缺少預期的元資料,請檢查執行錯誤與警告、第 5 步資料來源的擷取選項,以及第 6 和第 7 步的直接或投影映射。 確認回填已經處理了已知檔案。
為 後續增量刷新,執行或排程索引器以處理偵測到的來源變更;不要在每次重新整理標籤時都重置它。 來源標籤的變更在索引中不會顯示,直到成功執行索引程序處理後才會顯示。 如需定期重新整理,請參閱 為索引器排程。