註
Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。
重要
本文中標示為(預覽)的功能或特性目前處於公開預覽狀態,並受 Microsoft Azure 預覽版補充使用條款的約束。
有關 Foundry IQ(Azure AI 搜尋服務)專屬的預覽條款,請參閱預覽功能。
有關連接外部資料來源時適用的術語,請參閱「外部資料來源」。
Microsoft 365 中的 SharePoint 索引器 會將檔案、清單項目及新式網站頁面匯入 Foundry IQ。 它已隨 2026-10-01 REST API 正式推出。 本文使用該版本進行設定步驟,後續說明行為與情境。
關於支援文件的版面感知擷取及分塊,請參閱 在 Foundry IQ 中擷取並豐富 SharePoint 文件。 使用知識來源 API 以簡化設定,或直接設定索引器和技能集以獲得更多控制。
在 Foundry IQ 中,索引器會從資料來源擷取可搜尋的資料與元資料。 Microsoft 365 索引器中的 SharePoint 提供以下功能:
- 索引一個或多個文件函式庫的檔案與元資料。
- 為SharePoint 清單及其項目欄位值建立索引,其中每個清單欄都可作為欄位對應的來源欄位。
- 索引 ASPX網站頁面 (現代網站頁面)。
- 使用
allSiteContent容器值,在單一索引器中為混合的 SharePoint 內容(文件庫、清單和網站頁面)建立索引。 - 當
includeSubsites=true資料來源查詢中設定為 時,會索引跨子網站的內容。 - 以累加方式建立索引,僅擷取新增和已變更的檔案、清單項目、頁面及中繼資料。
- 自動偵測已刪除內容。 檔案、清單項目或頁面的刪除會在下一次索引器執行時被移除,對應的搜尋文件也會從索引中移除。
- 自動從索引文件中擷取文字及正規化影像。 你也可以選擇加入更深入的 AI 強化技能,例如光學字元辨識(OCR)或實體辨識。
- 支援 文件層級的權限匯入。 請參閱連結文章,了解支援的權限子集、群組解析及權限同步。
- 支援查詢時擷取及接受 Microsoft Purview 敏感度標籤。 此功能目前還在預覽階段。
先決條件
Foundry IQ,基礎定價方案或更高。
Microsoft 365 雲端服務中的 SharePoint(OneDrive 不是受支援的資料來源)。
Visual Studio Code 搭配 REST Client 擴充功能,用於設定與執行索引器管線。
選擇你的權限設定
在第三 步建立應用程式註冊前,請先在下表中確認你的情境。 請注意所需的 Microsoft Graph 權限、SharePoint API 權限以及憑證類型。 接著,請依照本文後面連結的步驟來應用這些步驟。
| 劇本 | Microsoft Graph 權限 | SharePoint API 權限 | Credential | 申請 |
|---|---|---|---|---|
| 僅編製文件庫索引,無 ACL 擷取 |
Files.Read.All,Sites.Read.All(應用程式)或委派對應項目 |
沒有 | 用戶端秘密(應用程式)或裝置程式碼(委派) | 步驟 3, 步驟 6 |
| 索引清單、ASPX 頁面或混合內容(無 ACL 擷取) |
Files.Read.All、Sites.Read.All(application) |
沒有 | 用戶端秘密或聯邦憑證 | 步驟 3 |
| SharePoint 網站群組的 ACL 匯入或查詢時解析 | 請參閱 ACL 權限矩陣。 | 請參閱 ACL 權限矩陣。 | 請參閱 ACL 權限矩陣。 | ACL 情境下的權限 |
設定權限時,請考慮以下資訊:
- 委派權限只適用於小型測試,且不支援 ACL 擷取。
- 聯邦憑證是推薦的無秘密認證方式。 涵蓋索引器驗證和查詢時的 SharePoint 群組解析。
- 使用
Sites.Selected時,先明確授權應用程式對每個目標SharePoint網站的存取權限,再進行索引。 Microsoft Entra ID 的管理員同意Sites.Selected本身並不授權該應用程式存取網站內容。 你也必須在每個目標網站分配權限。 如果你在沒有明確授權網站權限的情況下將網站加入資料來源,索引器就會失敗。 使用Sites.Selected時,請參閱「授予網站存取權限」
應用程式的擷取權限不會建立終端使用者的查詢權限。 在面向使用者的權限篩選應用程式中,會由 Authorization 向 Search 驗證呼叫者身分,同時 x-ms-query-source-authorization 提供使用者的權限內容。 請參閱 查詢時權限強制執行。
應用程式權杖代表的是應用程式本身,而非已登入的使用者。 Microsoft 身分識別平台 on-behalf-of 流程僅支援使用者主體。 不要用僅應用程式的令牌作為該流程的使用者聲明。
支援的文件格式
Microsoft 365 索引器的 SharePoint 可以從以下文件格式中擷取文字:
- CSV(參見 CSV 塊狀索引)
- EML
- EPUB
- GZ
- HTML
- JSON(參見 索引 JSON blobs)
- KML(用於地理表現的 XML)
- Markdown
- Microsoft Office 格式:DOCX/DOC/DOCM、XLSX/XLSM、PPTX/PPT/PPTM、MSG(Outlook 電子郵件)、XML(2003 及 2006 WORD XML)
- 開放文件格式:ODT、ODS、ODP
- 純文字檔案(另見 索引純文字)
- RTF
- XML
- ZIP
限制與考量
以下是此功能的限制:
OneNote筆記本檔案不支援。
增量索引限制:
重新命名 SharePoint 資料夾會破壞增量索引。 重新命名的資料夾會被視為新內容。
索引器即使文件內容未變,也能重新處理先前已編入索引的文件。 這種行為是刻意設計的,有助於避免遺漏變更並維護資料完整性。 重新處理可能發生在來源系統暫時性錯誤的復原期間,或 Microsoft 365 處理程序更新 SharePoint 中繼資料時。 這些內部事件可能無法透過面向客戶的文件屬性看見。
根據你的管線配置,重處理可能會再次啟動下游服務,包括 AI 豐富化與嵌入生成。 在規劃索引時間、容量與成本時,將這些額外處理納入考量。 有關疑難排解,請參閱「了解同步重試」。
安全限制:
從 Foundry IQ 到 SharePoint Online 的連線使用公開端點。 SharePoint Online 並非受支援的共用私人連結目標,因此此來源無法提供私人外送連線。 您的應用程式仍可透過輸入私人端點連線至 Search。 請參閱「 入站與出站網路流量」。
不支援啟用 Microsoft Entra ID條件存取的租戶。
不支援使用者加密檔案及受密碼保護的 ZIP 檔案。 不過,如果加密內容受到Microsoft Purview 敏感標籤保護,且啟用了設定以保留並尊重這些標籤(預覽),即可允許。
文件層級的存取權限支援 SharePoint 權限模型中的一部分。 SharePoint ACL 的擷取與篩選功能已正式推出,並支援 REST API
2026-10-01。 詳情與設定請參見 SharePoint ACL 設定文件。 關於每種情境所需的權限,請參見 「選擇你的權限設定」。
當網站上下文欄位標記為 時,SharePoint 群組 權限解析有
sharepointSiteUrl: true的限制。 此限制並不適用於所有權限設定。 如果您需要跨越多個網站的 SharePoint 群組 權限,請評估獨立的索引與已索引的知識來源。 請參閱「規劃 SharePoint 群組 權限的拓撲」。文件庫、清單與現代頁面來源各自擁有獨立的 索引範圍預設值。 這些計算計算的是選取的來源,而非單一檔案、清單項目或頁面。
以下是使用此功能時的一些考量:
若要在 Foundry IQ 中不建立 SharePoint 內容索引的情況下擷取資料,請考慮 遠端 SharePoint 知識來源(預覽版)。 它使用 Copilot Retrieval API 代表使用者查詢 SharePoint 的文字內容。 將此選項與 SharePoint 架構選擇中的索引及自訂匯入方法進行比較。
如果您需要建立自訂 Copilot/RAG 應用程式或 AI Agent,在生產環境中與 SharePoint 資料聊天,請考慮先直接透過 Microsoft Copilot Studio 建置。 如果 Copilot Studio 不符合你的需求,請考慮:
建立一個自訂連接器,包含 SharePoint webhooks,呼叫 Microsoft 圖形 API 將資料匯出到 Azure Blob 容器,然後使用 Azure blob indexer 進行增量索引。
建立您自己的Azure Logic Apps工作流程,同時使用 Azure Logic Apps SharePoint 連接器與 Foundry IQ 連接器。 Foundry IQ 連接器在正式推出後即可取得。 以 Azure 入口網站精靈 產生的工作流程作為起點,然後在 Azure Logic Apps designer 中自訂,加入你需要的轉換步驟。 Foundry IQ 精靈所建立的工作流程是消費工作流程。 對於生產工作負載,請切換到 標準邏輯應用程式的工作流程 ,以利用其額外的企業功能。
無論你選擇哪種方式,無論是用 SharePoint webhook 建立自訂連接器,還是建立 Azure Logic Apps 工作流程,務必實施強而有力的安全措施。 這些措施包括設定防火牆、保留來源使用者權限,並在查詢時遵循這些權限設定。 你也應該定期審核並監控你的管道。
對於 SharePoint ACL 擷取作業,支援巢狀於 SharePoint 群組內的 Microsoft Entra 群組,最多支援五個巢狀層級。 另有獨立的站點層級主體限制。 如需了解設定需求與該限制,請參閱 「支援的群組關係」。
規劃您的索引拓撲
對於直接設定的管線,各資源有不同的職責:
| Resource | 責任 |
|---|---|
| Microsoft Entra 應用程式與 SharePoint 網站授權 | 授權對所選內容的擷取存取權限。 使用 Sites.Selected 時,請為每個選取的網站授與存取權限。 |
| 數據源 | 定義連線並選取網站、文件庫、清單、頁面或資料夾。 選擇不會授予存取權限。 |
| Indexer | 讀取一個資料來源,並在 targetIndexName 中命名一個目標索引。 多個選取的網站不會自動建立多個目標索引。 |
| 搜尋索引 | 定義欄位並儲存可搜尋的內容、元資料及用於檢索的權限欄位。 |
| 搜尋索引知識來源與知識庫 | 可選擇性地公開已填充的索引以供代理式擷取。 這些擷取資源不會取代索引設定或使用者的文件權限。 |
例如:
| 劇本 | 資源配置 |
|---|---|
| 一個擁有多個文件庫或資料夾的網站 | 在單一資料來源中選擇所需的函式庫或資料夾,並在內容共享目標結構與處理需求時使用單一索引器。 |
| 預設端點為 A 的選取站點 B 與 C | 使用 跨站查詢設定,授權對 B 與 C 的存取權,並透過一個索引器寫入至一個目標索引。 當權限篩選需要時,保留原始站點上下文。 |
| 需要獨立架構、處理排程或治理的內容 | 請使用分開的索引管線與索引。 針對代理檢索,透過搜尋索引知識來源揭露每個索引,並在其限制範圍內將來源指派至知識庫。 |
索引器的單一 targetIndexName 與索引 投影不同,後者可以將強化的子文件傳送到其他索引。 每個可搜尋的區塊必須保留所需的權限欄位及原始站點上下文。 請依照 ACL 映射與投影指引操作。
新增寫入同一索引的索引器不會增加 SharePoint 群組 網站 URL 限制。 請依照現有的 分區指引 來處理該權限流程。
如果您偏好服務管理的匯入方式,請建立已索引的 SharePoint 知識來源,而非分別設定這些索引資源。 有關架構與擁有權選項,請參閱 SharePoint 架構選擇。
在 Microsoft 365 索引器中設定 SharePoint
使用 2026-10-01 REST API 設定 Microsoft 365 中的 SharePoint 索引器。
(可選)步驟 1:啟用系統指派的管理身份
啟用系統指派的受控識別,以自動偵測 Foundry IQ 服務所佈建所在的 Microsoft Entra 租用戶。
如果 SharePoint 網站與 Foundry IQ 服務位於同一 Microsoft Entra 租戶中,請執行此步驟。 如果他們在不同的 Microsoft Entra 租戶中,可以跳過這個步驟。 該身分識別用於租戶識別。 如果你想在 連接字串 裡放 Microsoft Entra 租戶 ID,也可以跳過這個步驟。 若要使用系統指派或使用者指派的管理身份來進行無秘密索引,請以 無秘密認證來設定應用程式權限。
選擇 儲存後,您會收到指派給 Foundry IQ 服務的物件 ID。
步驟 2:決定索引器需要哪些權限
關於涵蓋 ACL 與非 ACL 情境的決策矩陣,請參見 「選擇你的權限設定」。 如果您選擇委派權限,使用者委派的權杖每 75 分鐘到期一次,到期後需要使用 執行索引器 手動進行索引。 僅建議在小型測試作業中使用授權權限。
步驟 3:建立 Microsoft Entra 應用程式註冊
Microsoft 365 索引器的 SharePoint 使用 Microsoft Entra 應用程式進行認證。 在設定應用程式的權限和憑證之前,先建立應用程式註冊。
登入 Azure 入口網站。
搜尋或導航至 Microsoft Entra ID。
在 概覽 頁面,選擇 + 新增>應用程式註冊。
- 輸入你的應用程式名稱。
- 選擇 僅限單一租戶- 租戶名稱。
- 跳過URI指定步驟。 不需要重定向 URI。
- 選擇 登記。
從左側窗格選擇 「管理>API 權限」。
選擇 + 新增權限,然後選擇 Microsoft Graph。
如果你的索引器使用 Application API 權限,請選擇 應用程式權限。
標準索引時,選擇:
Files.Read.AllSites.Read.All
如果您啟用 ACL 匯入,所需的權限取決於您所建立的項目類型(文件庫檔案、清單項目、ASPX 頁面)及群組類型(Microsoft Entra 與 SharePoint 網站群組)。 在完成此步驟前,請參考 「依 ACL 授權」情境。 關於跨情境的摘要,請參見 「選擇你的權限設定」。
使用應用程式權限表示索引器在服務環境中存取 SharePoint 網站。 因此,當你執行索引器時,它能存取 SharePoint 租戶中的所有內容,這需要租戶管理員的審核。 驗證也需要用戶端秘密或無秘密設定。 關於建立認證機制,本文後面的「 僅適用於應用程式 API 權限的可用認證方法」將詳細說明。
如果你的索引器使用委派 API 權限,請選擇 委派權限,然後選擇:
Files.Read.AllSites.Read.AllUser.Read
委派權限允許搜尋用戶端以目前使用者的安全身份連接 SharePoint。
選取 為租用戶名稱授予管理員同意。
使用應用程式 API 權限時,必須取得租戶管理員同意。 有些租戶被鎖定,授權 API 權限也必須租戶管理員同意。 若符合任一條件,租戶管理員必須在建立索引器前,先同意此 Microsoft Entra 應用程式。
從左側窗格選擇 「管理>認證(預覽)」。
在「Redirect URI」設定標籤中,選擇 + 新增 Redirect URI。
- 選取 行動和桌面應用程式。
- 選取
https://login.microsoftonline.com/common/oauth2/nativeclient重新導向 URI。 - 選擇 設定。
在 設定 標籤中,啟用 允許公開客戶端流程 切換,然後選擇 儲存。
根據你的解決方案需求設定索引器 認證方法 。
使用 Sites.Selected 時授予網站存取權限
如果你使用 Sites.Selected 設定應用程式註冊,請先完成以下步驟,再執行索引子。 在 Microsoft Entra ID 中,管理員同意Sites.Selected只允許應用程式使用有範圍的 SharePoint 權限。 除非你另外分配網站權限,否則不會授予任何網站存取權限。
在 Microsoft Entra ID:將
Sites.Selected新增至應用程式註冊,並授予管理員同意。 在你的案例所需的 API 介面下新增權限,例如 Microsoft Graph;而在 ACL 擷取案例中,則為 SharePoint。在 SharePoint 中:為應用程式指派每個目標網站的權限角色。 對於內容的索引,至少要給予閱讀權限。
要授權網站,請使用 Microsoft Graph。 請將
{siteId}替換為您的網站 ID:POST https://graph.microsoft.com/v1.0/sites/{siteId}/permissions Content-Type: application/json { "roles": ["read"], "grantedToIdentities": [ { "application": { "id": "<application-client-id>", "displayName": "<application-display-name>" } } ] }若要使用 PnP PowerShell 授予相同權限:
Grant-PnPEntraIDAppSitePermission ` -AppId "<application-client-id>" ` -DisplayName "<application-display-name>" ` -Site "https://<tenant>.sharepoint.com/sites/<site-name>" ` -Permissions Read
僅適用於應用程式 API 權限的認證方法
為了驗證 Microsoft Entra 應用程式的應用程式權限,索引器會使用用戶端秘密或無秘密設定。
使用用戶端祕密
這些指令會設定應用程式使用用戶端秘密來認證索引器,使其能從 SharePoint 匯入資料。
從左側選單選擇 「憑證與秘密」 ,然後選擇 「用戶端秘密」 和 「新客戶端秘密」。
在跳出的選單中,輸入新用戶端憑證的描述。 必要時調整有效期限。 如果秘密過期,你需要重新建立它並更新索引器。
新的用戶端密鑰會出現在密鑰列表中。 一旦你離開頁面,秘密就看不見了,所以用複製按鈕複製該值並存到安全位置。
使用無秘密認證取得應用程式權杖
使用聯邦憑證登入,無需客戶端秘密。 Microsoft Entra 信任受控識別以取得應用程式權杖,因此索引子可以從 SharePoint 擷取資料,而不需儲存祕密。 下一節將逐步說明如何設定管理身份。
配置註冊的應用程式以使用受管理的身分識別
根據您的情境需求,建立(或選擇)使用者指派的受控識別,並指派給您的 Foundry IQ 服務,或系統指派的受控識別。
擷取 物件(主體)ID。 在建立資料來源時,將此值作為憑證設定的一部分。
從左側選單選擇「 憑證與秘密 」。
在 聯邦憑證中選擇+ 新增憑證。
在 聯邦憑證情境 下,選擇 「管理身份」。
選擇受管理身份:選擇步驟 1 中建立的受管理身份。
新增你的憑證名稱並選擇 儲存。
步驟 4:建立資料來源
在剩餘步驟中,請使用 API 版本為 2026-10-01 的 REST 用戶端。
資料來源指定要索引哪些資料、憑證及政策,以有效識別資料變更(新增、修改或刪除的列)。 同一 Foundry IQ 服務中的多個索引器可以使用相同的資料來源。
對於 SharePoint 索引,資料來源必須具備以下必要的屬性:
- name 是資料來源在您的 Foundry IQ 服務內的唯一名稱。
- 類型 必須為 "sharepoint"。 此值區分大小寫。
-
認證資訊提供 SharePoint 端點及應用程式獲准用來要求 Microsoft Entra 權杖的驗證方式。 端點SharePoint範例為
https://[your-tenant-name].sharepoint.com/teams/MySharePointSite。 你可以透過 SharePoint 網站的首頁,從瀏覽器複製網址來取得端點。 請檢視 連接字串 格式以取得支援的語法。 - container 會選取要索引的文件庫、清單或網站頁面。 其屬性 控制哪些文件要被索引。
若要建立資料來源,請呼叫「建立資料來源」。
這裡有一個資料來源定義範例,適用於帶有應用程式秘密或系統指派管理身份的憑證。
POST https://[service name].search.windows.net/datasources?api-version=2026-10-01
Content-Type: application/json
api-key: [admin key]
{
"name" : "sharepoint-datasource",
"type" : "sharepoint",
"credentials" : { "connectionString" : "[connection-string]" },
"container" : { "name" : "defaultSiteLibrary", "query" : null }
}
聯邦憑證配置需要FederatedCredentialApplicationId在 連接字串 中。 該值依身份類型而異:
-
系統指派的管理識別:設定
FederatedCredentialApplicationId為服務的系統指派管理識別應用程式(用戶端)ID。 省略封鎖identity。 -
使用者指派的管理身份:以使用者指派的受管理身分資源路徑填入
identity區塊。 將FederatedCredentialApplicationId設定為使用者指派之受控身分識別自身的應用程式 (用戶端) 識別碼。
註
ApplicationId 和 FederatedCredentialApplicationId 是不同的值。
ApplicationId是您註冊的 Entra 擷取應用程式,持有 SharePoint 權限。
FederatedCredentialApplicationId 是受管理身份本身的應用程式(用戶端)ID,也就是用其令牌證明該管理身份身份的實體。
POST https://[service name].search.windows.net/datasources?api-version=2026-10-01
Content-Type: application/json
api-key: [admin key]
{
"name" : "sharepoint-datasource",
"type" : "sharepoint",
"credentials" : { "connectionString" : "[connection-string]" },
"container" : { "name" : "defaultSiteLibrary", "query" : null },
"identity": {
"@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
"userAssignedIdentity": "/subscriptions/[Azure subscription ID]/resourceGroups/[resource-group]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[user-assigned managed identity]"
}
}
連接字串格式
連接字串 的格式會根據索引器使用的是委派的 API 權限或應用程式 API 權限而改變。
委派 API 權限連接字串格式
SharePointOnlineEndpoint=[SharePoint site URL];ApplicationId=[Microsoft Entra application ID];TenantId=[SharePoint site's Microsoft Entra tenant ID]應用程式 API 權限與應用程式秘密連接字串格式
SharePointOnlineEndpoint=[SharePoint site URL];ApplicationId=[Microsoft Entra application ID];ApplicationSecret=[Microsoft Entra application client secret];TenantId=[SharePoint site's Microsoft Entra tenant ID]使用無密碼(同盟身分識別憑證)連線字串格式的應用程式 API 權限:
SharePointOnlineEndpoint=[SharePoint site URL];ApplicationId=[Microsoft Entra application ID];FederatedCredentialApplicationId=[managed identity's application (client) ID];TenantId=[SharePoint site's Microsoft Entra tenant ID]
下表描述每個連接字串欄位。
| Field | Required | 描述 |
|---|---|---|
SharePointOnlineEndpoint |
Yes | 預設 SharePoint 網站 URL(例如,https://[your-tenant-name].sharepoint.com)。 容器 useQuery 可以選取同一租戶中的其他網站。 請參閱 「從其他網站選擇內容」。 |
ApplicationId |
Yes | 資料擷取應用程式的 Microsoft Entra 應用程式(用戶端)ID。 必須是有效的 GUID。 |
TenantId |
Optional | 擁有 SharePoint 網站之租戶的 Microsoft Entra 租戶 ID(GUID) 這個租戶不一定是與 Foundry IQ 服務相關聯的 Microsoft Entra 租戶。 當 SharePoint 網站與 Foundry IQ 服務位於不同的 Microsoft Entra 租用單位時,為必要條件。 |
ApplicationSecret |
Conditional | 擷取應用程式的用戶端祕密。 用於基於秘密的認證。 |
FederatedCredentialApplicationId |
條件式(聯邦身份憑證) | Microsoft Entra 應用程式(客戶端)ID 用於驗證受管理身份。 必須是有效的 GUID。 對於系統指派的受控身分識別,請使用該身分識別的應用程式 (用戶端) 識別碼。 對於使用者指派的管理身份,請使用該身份本身的應用程式(用戶端)ID。 若為跨租用戶的使用者指派受控身分識別,且在federatedIdentityClientId區塊中設定了identity,請使用多租用戶應用程式的用戶端識別碼。 |
重要
FederatedCredentialApplicationId 和 ApplicationSecret 互斥。 將它們結合的連接字串會在資料來源建立或更新時被拒絕。
設定權限時,請考慮以下資訊:
為了向下相容,SharePoint 索引器仍接受連接字串中的
FederatedCredentialObjectId(擷取應用程式上同盟識別憑證的物件 ID/主體 ID),因此現有的資料來源無須變更即可繼續運作。 針對新的與已更新的資料來源,請使用FederatedCredentialApplicationId。
要取得 TenantId,請開啟擁有該 SharePoint 網站的租戶的 Microsoft Entra 系統管理中心,並從概覽中複製租戶 ID。
你可以從object (principal) ID」的部分取得受管理身份。
設定權限時,請考慮以下資訊:
如果 SharePoint 網站與 Foundry IQ 服務位於同一 Microsoft Entra 租戶且已啟用系統指派的管理身份,則不必包含
TenantId在 連接字串 中。 如果它們位於不同的 Microsoft Entra 租戶中,您必須包含TenantId。
以下範例展示了以以下 FederatedCredentialApplicationId方式建立的資料來源:
系統指派的受控識別與同盟認證:
POST https://[service name].search.windows.net/datasources?api-version=2026-10-01
Content-Type: application/json
api-key: [admin key]
{
"name": "sharepoint-ds",
"type": "sharepoint",
"credentials": {
"connectionString": "SharePointOnlineEndpoint=https://[your-tenant-name].sharepoint.com;ApplicationId=[Microsoft Entra application ID];TenantId=[SharePoint site's Microsoft Entra tenant ID];FederatedCredentialApplicationId=[system-assigned managed identity's application (client) ID]"
},
"container": { "name": "defaultSiteLibrary" }
}
使用者指派的受控識別,搭配同盟憑證(單一租用戶):
{
"name": "sharepoint-uami-fed",
"type": "sharepoint",
"credentials": {
"connectionString": "SharePointOnlineEndpoint=https://[your-tenant-name].sharepoint.com;ApplicationId=[Microsoft Entra application ID];TenantId=[SharePoint site's Microsoft Entra tenant ID];FederatedCredentialApplicationId=[user-assigned managed identity application (client) ID]"
},
"container": { "name": "defaultSiteLibrary" },
"identity": {
"@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
"userAssignedIdentity": "/subscriptions/[subscription-id]/resourceGroups/[resource-group]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[uami-name]"
}
}
註
對於使用者指派的受管理身份, FederatedCredentialApplicationId 必須等於該受管理身份的應用程式(客戶端)ID,而非擷取應用程式的ID(ApplicationId)。 如果你省略了該 identity 區塊,索引器會退回到系統指派的管理身份。
跨租用戶使用者指派受控識別搭配同盟認證(進階):
使用此設定前,請確保使用者指派的管理身份已設定為聯邦身份憑證,且該憑證信任多租戶的 Microsoft Entra 應用程式。 關於設定步驟,請參見 「以管理身份設定註冊應用程式」。
{
"name": "sharepoint-uami-crosstenantfed",
"type": "sharepoint",
"credentials": {
"connectionString": "SharePointOnlineEndpoint=https://[your-tenant-name].sharepoint.com;ApplicationId=[Microsoft Entra application ID];TenantId=[SharePoint site's Microsoft Entra tenant ID];FederatedCredentialApplicationId=[multitenant app client ID]"
},
"container": { "name": "defaultSiteLibrary" },
"identity": {
"@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
"userAssignedIdentity": "/subscriptions/[subscription-id]/resourceGroups/[resource-group]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[uami-name]",
"federatedIdentityClientId": "[multi-tenant app client ID]"
}
}
當使用者指派的管理身份本身與多租戶 Microsoft Entra 應用程式聯合時,請使用跨租戶使用者指派的管理身份設定。 在這種情況下,在區塊中federatedIdentityClientId設定identity為多租戶應用程式的客戶端 ID,並在 連接字串 中設定FederatedCredentialApplicationId為同一多租戶應用程式的客戶端 ID。 在此情況下,將 FederatedCredentialApplicationId 設為使用者指派受控識別本身的客戶端 ID 會導致驗證失敗。
如果您的索引器使用 SharePoint ACL 設定,或保留並尊重 Microsoft Purview 敏感度標籤(預覽),請在建立索引器前先檢視相關文章。 每個功能都有特定的資料來源、索引和技能組設定步驟。
步驟五:建立索引
索引指定文件中的欄位、屬性及其他塑造搜尋體驗的結構。
若要建立索引,請呼叫 「建立索引」:
POST https://[service name].search.windows.net/indexes?api-version=2026-10-01
Content-Type: application/json
api-key: [admin key]
{
"name" : "sharepoint-index",
"fields": [
{ "name": "id", "type": "Edm.String", "key": true, "searchable": false },
{ "name": "metadata_spo_item_name", "type": "Edm.String", "key": false, "searchable": true, "filterable": false, "sortable": false, "facetable": false },
{ "name": "metadata_spo_item_path", "type": "Edm.String", "key": false, "searchable": false, "filterable": false, "sortable": false, "facetable": false },
{ "name": "metadata_spo_item_content_type", "type": "Edm.String", "key": false, "searchable": false, "filterable": true, "sortable": false, "facetable": true },
{ "name": "metadata_spo_item_last_modified", "type": "Edm.DateTimeOffset", "key": false, "searchable": false, "filterable": false, "sortable": true, "facetable": false },
{ "name": "metadata_spo_item_size", "type": "Edm.Int64", "key": false, "searchable": false, "filterable": false, "sortable": false, "facetable": false },
{ "name": "content", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false }
]
}
重要
Microsoft 365 索引器中由 SharePoint 索引器填充的索引中,鍵欄位依據資料來源中的容器類型而異:
- 對於文件庫內容(
defaultSiteLibrary、allSiteLibraries或useQuery,且設有文件庫或資料夾篩選器),請使用metadata_spo_site_library_item_id。 如果資料來源中沒有某個鍵欄位,metadata_spo_site_library_item_id會自動映射到該鍵欄位。 - 對於列表、頁面或混合內容(
allSiteLists、 、 或allSitePages),請使用allSiteContentmetadata_spo_site_asset_item_id。 自動對應不適用於此欄位。 定義一個明確的fieldMappings項目,將metadata_spo_site_asset_item_id對應至您的索引鍵欄位。
在將這些關鍵欄位映射到你的索引base64Encode欄位時,套用id映射功能。
步驟六:建立索引器
索引器將資料來源與目標搜尋索引連結,並提供自動資料更新的排程。 建立資料來源和索引後,再建立索引器。
要建立索引器:
傳送 建立索引器 請求:
POST https://[service name].search.windows.net/indexers?api-version=2026-10-01 Content-Type: application/json api-key: [admin key] { "name" : "sharepoint-indexer", "dataSourceName" : "sharepoint-datasource", "targetIndexName" : "sharepoint-index", "parameters": { "batchSize": null, "maxFailedItems": null, "maxFailedItemsPerBatch": null, "configuration": { "indexedFileNameExtensions" : ".pdf, .docx", "excludedFileNameExtensions" : ".png, .jpg", "dataToExtract": "contentAndMetadata" } }, "fieldMappings" : [ { "sourceFieldName" : "metadata_spo_site_library_item_id", "targetFieldName" : "id", "mappingFunction" : { "name" : "base64Encode" } } ] }對於使用
allSiteLists、allSitePages或allSiteContent容器值的資料來源,請用 mapmetadata_spo_site_asset_item_id代替metadata_spo_site_library_item_id。文件庫範例僅包含
.pdf和.docx檔案。 調整 檔案類型篩選條件 ,以符合您打算索引的內容。使用應用程式權限時,你可以在索引器初始執行時查詢索引,但只有已被索引的項目會返回結果。 等候執行完成以取得完整涵蓋範圍。 此步驟剩餘的指示僅適用於委派權限。
當您首次建立索引器時,建立索引器 的請求會等待您完成下一步。 您必須致電 「取得索引器狀態 」取得連結並輸入您的新裝置代碼。
GET https://[service name].search.windows.net/indexers/sharepoint-indexer/status?api-version=2026-10-01 Content-Type: application/json api-key: [admin key]如果你在 10 分鐘內沒有呼叫 「Get Indexer Status 」,程式碼就會過期,你必須重新建立 資料來源。
複製「 取得索引器狀態 」回應中的裝置登入代碼。 裝置登入代碼可在「errorMessage」中找到。
{ "lastResult": { "status": "transientFailure", "errorMessage": "To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code <CODE> to authenticate." } }輸入錯誤訊息中包含的代碼。
Microsoft 365 中的 SharePoint 索引器會以已登入使用者的身分存取 SharePoint 內容。 在這個步驟中登入的使用者就是那位已登入的使用者。 所以,如果你用一個使用者帳號登入,但該帳號沒有文件庫中你想索引的文件存取權,索引器就無法存取該文件。
如果可能,建立一個新的組織使用者帳號,並授予它你希望索引器擁有的精確權限。
核准正在申請的權限。
如果先前提供的所有權限皆正確,則 Create Indexer 的初始要求會在 10 分鐘內完成。
設定權限時,請考慮以下資訊:
如果 Microsoft Entra 應用程式需要管理員批准,且在登入前未獲批准,你可能會看到以下畫面。 需經管理員核准才能繼續。
![]()
步驟七:檢查索引器狀態
建立索引器後,呼叫 「取得索引器狀態」:
GET https://[service name].search.windows.net/indexers/sharepoint-indexer/status?api-version=2026-10-01
Content-Type: application/json
api-key: [admin key]
檢查 lastResult 中最新一次執行的 status、endTime、itemsProcessed 和 itemsFailed。 即使執行作業報告成功,也要檢視錯誤與警告。 頂層索引器的狀態 running 表示索引器可執行,不表示目前有執行作業正在進行。 請參閱「監控索引器執行」。
執行完成後,請使用下列查詢檢查未套用文件層級權限篩選的索引:
GET https://[service-name].search.windows.net/indexes/[index-name]/docs?search=*&$count=true&api-version=2026-10-01
api-key: [admin-api-key]
對於啟用權限的索引,請改依 權限擷取檢查。 使用 授權的提升讀取查詢 來檢查受保護的內容。 單靠管理員金鑰無法傳回受 ACL 保護的內容。
檢查已知來源項目的 content 和元資料,而非僅檢查文件數量。 對於清單項目和現代頁面,請將結果與 預期的內容表示方式進行比較。 如果您已設定 SharePoint 群組 解析,請同時驗證文件上的 originating-site 欄位以及投影區塊上的 originating-site 欄位。
分別以 權限過濾查詢測試允許與拒絕的使用者,且不使用提升讀取標頭。 將高階讀取保留給授權的行政調查,而非作為終端使用者查詢的備用方案。
更新資料來源
索引器範例並未設定排程。 若要處理後續的來源變更,請 設定索引器排程 或 手動執行索引器。 委派驗證在其令牌到期後仍需執行以下章節的登入步驟。
如果你在裝置程式碼過期時更改資料來源,請重新登入以執行索引器。 例如,如果你更改了資料來源查詢,請再次使用 登入 https://microsoft.com/devicelogin 並取得新的裝置程式碼。
要更新資料來源,假設裝置代碼過期,請依照以下步驟操作:
呼叫 Run Indexer 以手動啟動 索引器執行。
POST https://[service name].search.windows.net/indexers/sharepoint-indexer/run?api-version=2026-10-01 Content-Type: application/json api-key: [admin key]檢查 索引器狀態。
GET https://[service name].search.windows.net/indexers/sharepoint-indexer/status?api-version=2026-10-01 Content-Type: application/json api-key: [admin key]如果出現錯誤要求你造訪
https://microsoft.com/devicelogin,打開頁面並複製新的代碼。把程式碼貼到對話框裡。
手動再執行索引器並檢查索引器狀態。 這次索引器的執行應該會成功啟動。
了解已索引的內容
content 欄位包含檔案、清單項目及現代頁面的不同呈現方式。
| SharePoint 資產 |
content 中的表示方式 |
|---|---|
| 文件庫檔案 | 使用已設定的文件擷取路徑從檔案中擷取的文字。 |
| 清單項目 | JSON 格式的欄位值。 您也可以存取個別欄位以進行 欄位對應。 |
| 現代 ASPX 網站頁面 | 序列化頁面欄位,可包含 HTML 標記與 JSON 跳脫序列。 此表示法不保證是與算繪後的頁面一致的純文字。 |
對於清單和頁面,序列化內容可以包含欄位名稱及可見文字以外的其他值。 在設定分塊或嵌入之前,請檢查傳入您的 content 的 輸入內容。
已索引的 SharePoint 知識來源會產生一個索引器,該工具會對清單與僅頁面選擇進行text解析。 它對文件庫或混合選取(如 default)使用 allSiteContent 解析。
索引器解析模式與下游技能集處理是分開的。
針對受控多語言擷取,已建立索引的 SharePoint 知識來源支援自動為每種語言套用分析器(預覽)。 對於您直接設定的索引,請將 語言分析器指派給其可搜尋字串欄位。 這些配置路徑是獨立的。
索引文件元資料
如果您為文件中繼資料建立索引("dataToExtract": "contentAndMetadata"),則可以使用下列中繼資料來建立索引。
| 識別碼 | 類型 | 描述 |
|---|---|---|
| metadata_spo_網站_圖書館_項目_ID | 埃德姆·斯特林 | 網站 ID、圖書館 ID 與項目 ID 的組合鍵,能唯一識別該網站文件庫中的項目。 使用此欄位作為 defaultSiteLibrary、allSiteLibraries 和 useQuery(函式庫或資料夾篩選器)容器值的索引鍵。 |
| metadata_spo_site_asset_item_id | 埃德姆·斯特林 | 組合鍵唯一識別清單項目、ASPX 網站頁面或混合內容模式下的任何資產。 使用此欄位作為索引鍵,顯示 allSiteLists、 allSitePages、 allSiteContent 和 container 值。 |
| metadata_spo_site_id | 埃德姆·斯特林 | SharePoint 網站的 ID。 |
| metadata_spo_library_id | 埃德姆·斯特林 | 文件庫的識別碼。 |
| metadata_spo_item_id | 埃德姆·斯特林 | 圖書館中(文件)項目的 ID。 |
| metadata_spo_item_last_modified | Edm.DateTimeOffset | 該項目的最後修改日期/時間(UTC)。 |
| metadata_spo_item_name | 埃德姆·斯特林 | 物品名稱。 |
| metadata_spo_item_size | Edm.Int64 | 項目的大小(以位元組為單位)。 |
| metadata_spo_item_content_type | 埃德姆·斯特林 | 物品的內容類型。 |
| metadata_spo_item_extension | 埃德姆·斯特林 | 項目的副檔名。 |
| metadata_spo_item_weburi | 埃德姆·斯特林 | 物品的 URI。 |
| metadata_spo_item_path | 埃德姆·斯特林 | 父路徑與項目名稱的組合。 |
| metadata_spo_site_url | 埃德姆·斯特林 | SharePoint 網站的 URL。 啟用 SharePoint 網站群組解析時必須。 請參見 配置 SharePoint 群組支援。 |
Microsoft 365 索引器的 SharePoint 也支援針對每種文件類型的特定元資料。 如需更多資訊,請參閱 Foundry IQ 中使用的內容中繼資料屬性。
若要在直接設定的索引器中公開自訂文件庫中繼資料,請在additionalColumns中指定。 接著,使用 欄位映射 將暴露的來源欄位對應到相容的索引欄位。 選取欄位與對應它們是兩個不同的步驟:對應不會擷取資料來源尚未公開的欄位。
新增自訂欄位時,請保留鍵對應,以及任何必要的 權限和來源站點對應。 對於 SharePoint list 資料行,請依照 將清單資料行對應至索引欄位。
為 SharePoint 清單建立索引
將資料來源container.name設定為allSiteLists從網站索引所有 SharePoint list 項目。 使用 allSiteContent,將清單項目與文件庫及網站頁面合併到單一索引器中。 若要包含子網站清單,請將 includeSubsites=true 加入 container.query。
對於以清單為基礎或混合內容的索引器,索引鍵欄位必須對應至 metadata_spo_site_asset_item_id。 清單項目內容以 JSON 格式的欄位值出現在欄位 content 中,標準 metadata_spo_item_* 欄位(如 metadata_spo_item_name、 metadata_spo_item_weburi、 metadata_spo_item_last_modified和 )則為每個清單項目填充。
將清單資料行對應至索引欄位
你在 SharePoint list 上定義的每一欄都會以與 SharePoint 欄位名稱相同的來源欄位出現。 使用 欄位映射 將每欄映射到索引欄位。
舉例來說,考慮一個包含以下欄位的 SharePoint list。
| SharePoint 欄位 | SharePoint 欄位類型 |
|---|---|
Title |
單行文字 |
Price |
數量 |
InStock |
是/否 |
Category |
選擇 |
在索引定義中加入匹配欄位,然後將每欄映射到索引器的目標欄位:
{
"name": "my-sharepoint-list-indexer",
"dataSourceName": "my-sharepoint-list-ds",
"targetIndexName": "products-index",
"fieldMappings": [
{
"sourceFieldName": "metadata_spo_site_asset_item_id",
"targetFieldName": "id",
"mappingFunction": { "name": "base64Encode" }
},
{ "sourceFieldName": "Title", "targetFieldName": "productName" },
{ "sourceFieldName": "Price", "targetFieldName": "price" },
{ "sourceFieldName": "InStock", "targetFieldName": "available" },
{ "sourceFieldName": "Category", "targetFieldName": "category" },
{ "sourceFieldName": "metadata_spo_item_last_modified", "targetFieldName": "lastUpdated" },
{ "sourceFieldName": "metadata_spo_item_weburi", "targetFieldName": "itemUrl" }
]
}
請確保每個目標欄位都存在於您的索引中,且具有相容的類型(例如,Edm.String 對應 Title、Edm.Double 或 Edm.Int64 對應 Price、Edm.Boolean 對應 InStock)。
為 ASPX 網站頁面編製索引
將資料來源 container.name 設定為 allSitePages 索引該網站所有現代 ASPX 網站頁面。 使用 allSiteContent 將頁面與文件庫及清單合併於單一索引器中。 若要包含子網站頁面,請將 includeSubsites=true 新增至 container.query。
對於頁面型或混合內容索引子,索引索引鍵欄位必須從 metadata_spo_site_asset_item_id 對應。 欄位 content 接收序列化的頁面欄位,可包含 HTML 標記與 JSON 跳脫序列,而非保證由瀏覽器呈現的純文字。 標準 metadata_spo_item_* 欄位(例如 metadata_spo_item_name、metadata_spo_item_weburi 和 metadata_spo_item_last_modified)都會為每一頁填入這些欄位內容。
依檔案類型包含或排除
在索引器定義的「參數」區段設定包含與排除標準,以控制哪些檔案被索引。
若要包含特定的副檔名,請設 "indexedFileNameExtensions" 為以逗號分隔、前置點的檔案副檔名列表。 要排除特定的副檔名,請設 "excludedFileNameExtensions" 為你想跳過的副檔名。 如果同一個擴充名出現在兩個清單中,索引器會將其排除在索引之外。
PUT /indexers/[indexer name]?api-version=2026-10-01
{
"parameters" : {
"configuration" : {
"indexedFileNameExtensions" : ".pdf, .docx",
"excludedFileNameExtensions" : ".png, .jpeg"
}
}
}
控制哪些文件被索引
Microsoft 365 索引器中的單一 SharePoint 可以索引一個或多個文件函式庫的內容。 要指定要索引哪些網站和文件函式庫,請使用資料來源定義中的「container」參數。
資料來源「容器」區塊有兩個屬性用於此任務:「名稱」與「查詢」。
名稱
name該屬性是必需的,且必須符合以下其中一個值:
| 價值 | 描述 |
|---|---|
| defaultSiteLibrary | 索引網站預設文件庫中的所有內容。 |
| allSiteLibraries | 索引網站上所有文件庫的內容。 來自子網站的文件函式庫不在範圍內,除非您在查詢中設定 includeSubsites=true 。 你也可以選擇 useQuery 並指定 includeLibrariesInSite 範圍到特定地點或子網站。 |
| allSiteLists | 將該網站所有SharePoint list項目索引。 |
| allSitePages | 索引該網站所有 現代 ASPX 網站頁面 。 |
| allSiteContent | 在單一索引器中索引資料庫、清單和頁面。 |
| useQuery | 僅索引在 query 中定義的內容。 |
對於使用 allSiteLists、 allSitePages或 allSiteContent的資料來源,索引器金鑰欄位映射必須使用 metadata_spo_site_asset_item_id ,而非 metadata_spo_site_library_item_id。 詳情請參見 步驟 6:建立索引器。
查詢
資料來源的「查詢」參數由關鍵字/值對組成。 請使用以下關鍵字。 這些值要麼是網站 URL,要麼是文件庫 URL。
設定權限時,請考慮以下資訊:
要取得特定關鍵字的值,請前往你想包含或排除的文件庫,並從瀏覽器複製 URI。 這個方法是取得要在查詢中與關鍵字搭配使用之值的最簡單方式。
| 關鍵詞 | 價值描述與範例 |
|---|---|
| null | 若為空或空,則根據容器名稱索引預設文件庫或所有文件庫。 範例: "container" : { "name" : "defaultSiteLibrary", "query" : null } |
| 包含子網站 | 當設定為 true時,索引器會在適用的遍歷範圍內遍歷根網站與子網站。 與 allSiteLibraries、allSiteLists、allSitePages 或 allSiteContent 結合。 範例: "container" : { "name" : "allSiteLibraries", "query" : "includeSubsites=true" } |
| includeLibrariesInSite | 在此關鍵字值所指定的網站或子網站下,從所有文件庫中索引內容。 此網站可能與 連接字串 中的 SharePointOnlineEndpoint 不同。 重複索引鍵以選取多個網站。 請參閱 「從其他網站選擇內容」。 範例一: "container" : { "name" : "useQuery", "query" : "includeLibrariesInSite=https://mycompany.sharepoint.com/mysite" } 範例二(僅包含少數子網站): "container" : { "name" : "useQuery", "query" : "includeLibrariesInSite=https://mycompany.sharepoint.com/sites/TopSite/SubSite1;includeLibrariesInSite=https://mycompany.sharepoint.com/sites/TopSite/SubSite2" } |
| includeLibrary | 索引本圖書館的所有內容。 這個值是完全限定的函式庫路徑,你可以從瀏覽器複製: 範例 1 (完全合格路徑): "container" : { "name" : "useQuery", "query" : "includeLibrary=https://mycompany.sharepoint.com/mysite/MyDocumentLibrary" } 範例二(從你的瀏覽器複製的 URI): "container" : { "name" : "useQuery", "query" : "includeLibrary=https://mycompany.sharepoint.com/teams/mysite/MyDocumentLibrary/Forms/AllItems.aspx" } |
| excludeLibrary | 不要索引這個資料庫的內容。 這個值是完全限定的函式庫路徑,你可以從瀏覽器複製: 範例 1 (完全合格路徑): "container" : { "name" : "useQuery", "query" : "includeLibrariesInSite=https://mysite.sharepoint.com/subsite1; excludeLibrary=https://mysite.sharepoint.com/subsite1/MyDocumentLibrary" } 範例二(從你的瀏覽器複製的 URI): "container" : { "name" : "useQuery", "query" : "includeLibrariesInSite=https://mycompany.sharepoint.com/teams/mysite; excludeLibrary=https://mycompany.sharepoint.com/teams/mysite/MyDocumentLibrary/Forms/AllItems.aspx" } |
| includeFolder | 索引特定資料夾及其子資料夾的內容。 Value 必須是完整的 SharePoint 資料夾 URL。 行為:遞迴套用於所有子資料夾。 可透過重複參數並加分號來指定多個資料夾。 資料夾過濾器的範圍是單一文件庫。 不支援僅限根目錄的路徑。 如果被引用的資料夾被重新命名,查詢必須更新。 範例一(單一資料夾): "container": { "name": "useQuery", "query": "includeFolder=[your-tenant-name].sharepoint.com/sites/hr/Shared Documents/Policies" }範例二(多個資料夾): "container": { "name": "useQuery", "query": "includeFolder=[your-tenant-name].sharepoint.com/sites/hr/Shared Documents/Specs;includeFolder=[your-tenant-name].sharepoint.com/sites/hr/Shared Documents/Designs" } |
| 排除資料夾 | 不要索引特定資料夾及其子資料夾的內容。 Value 必須是完整的 SharePoint 資料夾 URL。 行為:遞迴套用於所有子資料夾。 若檔案同時符合包含與排除規則,排除優先權,檔案會被跳過。 資料夾過濾器的範圍是單一文件庫。 範例 1(排除資料夾): "container": { "name": "useQuery", "query": "excludeFolder=[your-tenant-name].sharepoint.com/sites/hr/Shared Documents/Policies/Archive" }範例二(結合 包含 + 排除): "container": { "name": "useQuery", "query": "includeFolder=[your-tenant-name].sharepoint.com/sites/hr/Shared Documents/Policies;excludeFolder=[your-tenant-name].sharepoint.com/sites/hr/Shared Documents/Policies/Drafts" } |
| 額外欄位 | 文件庫中的索引欄位。 這個值是你想索引的逗號分隔欄位名稱清單。 使用雙反斜線來避免欄位名稱中的分號和逗號: 範例 1(additionalColumns=MyCustomColumn,MyCustomColumn2): "container" : { "name" : "useQuery", "query" : "includeLibrary=https://mycompany.sharepoint.com/mysite/MyDocumentLibrary;additionalColumns=MyCustomColumn,MyCustomColumn2" } 範例 2 (使用雙反斜線逸出字元): "container" : { "name" : "useQuery", "query" : "includeLibrary=https://mycompany.sharepoint.com/teams/mysite/MyDocumentLibrary/Forms/AllItems.aspx;additionalColumns=MyCustomColumnWith\\,,MyCustomColumnWith\\;" } |
從其他網站選取內容
連接字串 的 SharePointOnlineEndpoint 可識別預設網站。 將 container.name 設為 useQuery,查詢會選擇要索引的網站或程式庫。 所選站台可能與該預設站點不同。
以下設定範例使用同一租戶中的三個站台:Site A、Site B 和 Site C。請以其 SharePointOnlineEndpoint 為 https://contoso.sharepoint.com/sites/site-a 的 {{sharepoint-site-a-connection-string}} 取代 。 為每個所選網站設定匯入應用程式的權限。
此資料來源會選取網站 B,儘管其 連接字串 指出的是網站 A:
{
"name": "sharepoint-site-b",
"type": "sharepoint",
"credentials": {
"connectionString": "{{sharepoint-site-a-connection-string}}"
},
"container": {
"name": "useQuery",
"query": "includeLibrariesInSite=https://contoso.sharepoint.com/sites/site-b"
}
}
參考:資料來源 - 建立
若要選擇網站 B 和 C,請在查詢中重複 includeLibrariesInSite :
{
"name": "sharepoint-sites-b-c",
"type": "sharepoint",
"credentials": {
"connectionString": "{{sharepoint-site-a-connection-string}}"
},
"container": {
"name": "useQuery",
"query": "includeLibrariesInSite=https://contoso.sharepoint.com/sites/site-b;includeLibrariesInSite=https://contoso.sharepoint.com/sites/site-c"
}
}
參考:資料來源 - 建立
查詢選取不會授予存取權限。 當您使用 Sites.Selected時,請授權應用程式存取每個所選網站。
使用 Sites.Selected 時,請參閱「授予網站存取權限」
資料來源建立與執行時存取是分開的檢查。 如果安裝驗證會探測連線字串端點,成功存取 Site A 並不會驗證對 Site B 或 C 的存取。請檢查 索引器的狀態與執行紀錄 ,以確認所選網站的處理。
若要進行權限感知的索引,請依照 SharePoint 權限設定,將原始網站內容映射metadata_spo_site_url並保留在索引及任何投影文件中。
sharepointSiteUrl: true欄位屬性用來識別用於 SharePoint 群組 解析的網站-上下文欄位;它不是網站選擇規則或允許清單。
每個索引的網站數量限制仍然適用。
處理錯誤
識別失敗的連線
成功向 Foundry IQ 請求並不代表索引器能讀取 SharePoint。 成功擷取也不代表最終使用者能擷取受保護的項目。 在變更權限或網路設定之前,先找出失敗階段。
| Connection | 要檢查的身份或憑證 | 診斷動作 |
|---|---|---|
| 用於 Foundry IQ 的用戶端或應用程式 | 呼叫者的 Microsoft Entra 身份或已設定的 API 金鑰。 | 檢查搜尋端點、適用 的資料平面角色,以及 搜尋服務網路存取。 呼叫者身分驗證與使用者的文件權限是分開的。 |
| 索引器至 Microsoft Graph 與 SharePoint | 已設定的 SharePoint 擷取應用程式,以及(如有使用)委派登入。 | 檢視 索引器狀態與執行歷史。 檢查每個所選站台的租戶、憑證、管理員同意及 網站授權 。 僅靠 connection-string 端點並不能建立對每個查詢選取網站的存取權。 |
| 查詢時對 Microsoft Graph 與 SharePoint 的權限解析 | 最終使用者的權限情境以及已設定的 SharePoint 群組解析應用程式。 | 請依照 SharePoint 權限篩選診斷步驟進行。 檢查查詢權杖、索引權限/網站元資料,以及群組解析設定,而不是擴大匯入應用程式的存取權限。 |
| 豐富化至模型或 Foundry 端點 | 用於無金鑰呼叫的搜尋服務受控識別,或已設定的資源金鑰。 | 檢查失敗技能及其資源端點、授權、輸入限制與網路配置。 |
請分別檢查入站與出站連線。 搜尋的入站私有端點可以與 SharePoint Online 的公開出站連線共存。 共用私人連結僅適用於支援的目的地,不適用於 SharePoint Online。 條件存取限制仍然適用。
為支援,請擷取失敗階段、UTC 時間戳、HTTP 狀態,以及請求或關聯 ID。 從共用診斷中移除代幣、API 金鑰、機密資訊及租戶專屬的識別細節。
處理索引失敗
如果出現 Invalid AAD tenant 訊息、缺少 Microsoft Entra 租用戶識別碼,或索引子執行歷程記錄中出現租用戶不符,請參閱針對常見的索引子錯誤和警告進行疑難排解。
以下章節中的文件跳過設定無法修正驗證或權限失敗的問題。
預設情況下,Microsoft 365 索引器的 SharePoint 會在遇到不支援內容類型的文件(如圖片)時立即停止使用。 使用參數 excludedFileNameExtensions 跳過某些內容類型。 不過,你可能需要在不事先了解所有可能內容類型的情況下編索引文件。 當索引器遇到不支援的內容類型時,若要繼續索引,請將設定參數設 failOnUnsupportedContentType 為 false:
PUT https://[service name].search.windows.net/indexers/[indexer name]?api-version=2026-10-01
Content-Type: application/json
api-key: [admin key]
{
... other parts of indexer definition
"parameters" : { "configuration" : { "failOnUnsupportedContentType" : false } }
}
對某些文件,Foundry IQ 無法判斷內容類型,或無法處理原本支援的內容類型文件。 要忽略此故障模式,請將配置參數設 failOnUnprocessableDocument 為 false:
"parameters" : { "configuration" : { "failOnUnprocessableDocument" : false } }
SharePoint 來源檔案使用 blob 類型索引器共用的來源檔案大小和擷取字元限制。 預設情況下,超大文件會被視為錯誤。 不過,如果你將設定參數設 indexStorageMetadataOnlyForOversizedDocuments 為 true,仍然可以索引超大文件的儲存元資料:
"parameters" : { "configuration" : { "indexStorageMetadataOnlyForOversizedDocuments" : true } }
如果你新增技能組,請分別檢查每個技能的輸入和後續服務限制。 技能可接受的資料量低於 SharePoint 索引器擷取的資料。
如果在處理過程中發生錯誤,無論是在解析文件或將文件加入索引時,你也可以繼續索引。 要忽略特定數量的錯誤,請將maxFailedItems 和 maxFailedItemsPerBatch 參數,設為所需的值。 例如:
{
... other parts of indexer definition
"parameters" : { "maxFailedItems" : 10, "maxFailedItemsPerBatch" : 10 }
}
了解同步重試
追蹤 SharePoint 變更的程序可以請求同步重試。 Foundry IQ 可以重新處理先前已編索引的項目,以避免遺漏變更並維持資料完整性,即使您未編輯這些項目。
無論是否進行 ACL 擷取,此行為皆適用。 根據您的管線,重處理可能會重執行濃縮與嵌入產生,增加處理時間與成本。
同步重試與 權限重新同步彼此獨立;後者會重新整理已建立索引的權限,而不會重新執行豐富化或嵌入。 在之後的正常執行中重新處理內容,並不代表僅處理權限的執行已經完成了該工作。
如果重試一再發生或處理結果出乎意料,請檢視 索引器的執行紀錄。 聯絡支援時,請提供受影響執行的 UTC 時間、狀態、錯誤及可用請求 ID。 請勿包含憑證、使用者權杖或文件內容。