Foundry IQ(Azure AI 搜尋服務)中用於篩除結果的安全性篩選器

Note

Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。

對於無法使用內建存取控制清單(ACL)支援的文件層級授權的搜尋解決方案,Foundry IQ(Azure AI 搜尋服務)支援建立篩選器,根據包含群組或使用者身份的字串來裁剪搜尋結果。

本文說明安全性篩選的模式,包含下列步驟:

  • 使用必要內容組合來源文件,包括用於儲存識別碼的字串
  • 在搜尋索引中建立主體識別碼的欄位
  • 將文件推送至搜尋索引以編製索引
  • 使用 search.in 篩選函式查詢索引

最後會提供實際操作學習的示範和範例連結。 建議您先檢閱本文以了解模式。

關於安全性篩選模式

安全性篩選模式會使用一般 OData 篩選來模擬文件層級授權,該篩選會根據包含或排除由安全性主體所組成的字串來包含或排除搜尋結果。 未經安全性主體的驗證或授權。 主體只是用於篩選條件運算式中的字串,可包含或排除搜尋結果中的文件。

此應用程式管理模式與 原生權限過濾不同。 您的應用程式必須驗證使用者、取得受信任的主體與授權值、對每個查詢套用篩選條件,並防止繞過。 無論是與權限相關的欄位名稱,還是文件金鑰,都無法證明相關內容已獲授權。 一般的內容與豐富內容產出並不自動被視為具權威性的授權。 對於 Blob 擷取,請檢視 文件身份與權限來源。

有數種方法能夠實現安全性篩選。 其中一種方式是透過複雜的相等運算式析取,例如 Id eq 'id1' or Id eq 'id2',依此類推。 此作法很容易發生錯誤且難以維護,若清單包含數以百計或千計的值,則會使查詢回應時間慢上數秒鐘。

如本文所述,針對安全性篩選使用 search.in 函式會是更好的解決方案。 如果您使用 search.in(Id, 'id1, id2, ...'),而不是使用相等運算式,就可以預期在 1 秒內得到回應。

必要條件

  • 包含群組或使用者身分識別的字串欄位,例如Microsoft Entra 物件識別碼。

  • 同一文件中的其他欄位應提供該群組或使用者可存取的內容。 在下列 JSON 文件中,"security_id" 欄位包含安全性篩選中使用的身分識別,如果呼叫者的身分識別碼合文件的“security_id”,則會包含姓名、薪資和婚姻狀況。

    {  
        "Employee-1": {  
            "employee_id": "100-1000-10-1-10000-1",
            "name": "Abram",   
            "salary": 75000,   
            "married": true,
            "security_id": "alphanumeric-object-id-for-employee-1"
        },
        "Employee-2": {  
            "employee_id": "200-2000-20-2-20000-2",
            "name": "Adams",   
            "salary": 75000,   
            "married": true,
            "security_id": "alphanumeric-object-id-for-employee-2"
        } 
    }  
    

建立安全性欄位

在搜尋索引的欄位集合中,您需要一個包含群組或使用者身分識別的欄位,類似於上一個範例中的虛構 "security_id" 欄位。

  1. 新增安全性欄位為 Collection(Edm.String)。

  2. 將欄位的 filterable 屬性設定為 true。

  3. 將欄位屬性 retrievable 設為 , false 這樣它就不會作為搜尋回應的一部分回傳。

  4. 索引都需要文件索引鍵。 "file_id" 欄位符合該需求。

  5. 索引也應包含可搜尋和可擷取的內容。 "file_name" 和 "file_description" 欄位在本例中代表這些欄位的用途。

    下列索引架構符合欄位需求。 您在 Foundry IQ 上索引的文件,應包含所有這些欄位的值,包括 group_ids。 當其安全性篩選條件包含 group_id2 或 group_id1 時,查詢會傳回帶有 file_namesecured_file_b 的文件。

    POST https://[search service].search.windows.net/indexes/securedfiles/docs/index?api-version=2026-10-01
    {
         "name": "securedfiles",  
         "fields": [
             {"name": "file_id", "type": "Edm.String", "key": true, "searchable": false },
             {"name": "file_name", "type": "Edm.String", "searchable": true },
             {"name": "file_description", "type": "Edm.String", "searchable": true },
             {"name": "group_ids", "type": "Collection(Edm.String)", "filterable": true, "retrievable": false }
         ]
     }
    

Note

設定 retrievable 為 false 防止 group_ids 在搜尋結果中作為文件的一部分被回傳。 它不是內容混淆或欄位層級的安全性機制。 在此模式中,文件層級授權是透過對每個查詢套用安全過濾器來強制執行的。 不要只依賴 retrievable 它來保護敏感資訊免受所有查詢功能或回應格式的影響。

使用 REST API 將資料推送至索引

使用提供每個欄位集合中欄位值的文件(包括安全性欄位的值)來填充您的搜尋索引。 Foundry IQ 並沒有提供專門填充安全欄位的 API 或功能。 不過,本文結尾所列的數個範例會說明填入此欄位的技巧。

在 Foundry IQ 中,載入資料的方法如下:

  • 透過單一推送或提取作業,匯入填滿所有欄位的文件(索引子)
  • 多個推送或提取作業。 只要次要匯入作業以正確的文件識別碼為目標,您就可以透過多個匯入來個別載入欄位。

下列範例顯示單一 HTTP POST 要求,傳送至索引 URL 端點的 docs 集合 (請參閱 文件 - 索引)。 HTTP 要求主體是要建立索引之文件的 JSON 呈現:

POST https://[search service].search.windows.net/indexes/securedfiles/docs/index?api-version=2026-10-01
{
    "value": [
        {
            "@search.action": "upload",
            "file_id": "1",
            "file_name": "secured_file_a",
            "file_description": "File access is restricted to Human Resources.",
            "group_ids": ["group_id1"]
        },
        {
            "@search.action": "upload",
            "file_id": "2",
            "file_name": "secured_file_b",
            "file_description": "File access is restricted to Human Resources and Recruiting.",
            "group_ids": ["group_id1", "group_id2"]
        },
        {
            "@search.action": "upload",
            "file_id": "3",
            "file_name": "secured_file_c",
            "file_description": "File access is restricted to Operations and Logistics.",
            "group_ids": ["group_id5", "group_id6"]
        }
    ]
}

若您需要透過群組清單更新現有文件,則可使用 merge 或 mergeOrUpload 動作:

{
    "value": [
        {
            "@search.action": "mergeOrUpload",
            "file_id": "3",
            "group_ids": ["group_id7", "group_id8", "group_id9"]
        }
    ]
}

在查詢中套用安全性篩選條件

若要根據 group_ids 存取權限調整文件,您應透過 group_ids/any(g:search.in(g, 'group_id1, group_id2,...')) 篩選條件發出搜尋查詢,其中 'group_id1, group_id2,...' 是搜尋要求簽發者的所屬群組。

group_ids 欄位包含其中一個指定識別碼的所有文件均符合此篩選條件。 如需使用 Foundry IQ 搜尋文件的完整詳細資訊,請參閱「搜尋文件」。

此範例示範如何使用 POST 要求來設定查詢。

發出 HTTP POST 要求,並在要求本文中指定篩選:

POST https://[service name].search.windows.net/indexes/securedfiles/docs/search?api-version=2026-10-01

{
   "filter":"group_ids/any(g:search.in(g, 'group_id1, group_id2'))"  
}

你應該找回其中group_ids包含"group_id1"或"group_id2"的文件。 換言之,您會取得發出請求者具有讀取權限的文件。

{
 [
   {
    "@search.score":1.0,
     "file_id":"1",
     "file_name":"secured_file_a",
   },
   {
     "@search.score":1.0,
     "file_id":"2",
     "file_name":"secured_file_b"
   }
 ]
}

下一步

本文說明根據使用者身分識別和函式 search.in() 篩選結果的模式。 您可以使用此函式傳入要求中使用者的主體識別碼,以比對與每個目標文件相關聯的主體識別碼。 處理搜尋要求時,search.in 函式會篩除那些使用者主體都沒有讀取權限的搜尋結果。 主體識別碼可代表安全性群組、角色等等,甚至可代表使用者的專屬身分識別。

如需更多範例、示範和影片: