在 Microsoft 365 中索引來自 SharePoint 的內容（預覽版）

Microsoft 365 索引器中的 SharePoint（預覽版）可從 SharePoint 文件庫匯入文件，並使其可在 Azure AI 搜尋服務 中搜尋。 首先是設定步驟，接著是行為和情境。

在 Azure AI 搜尋服務 中，索引器會從資料來源中擷取可搜尋的資料和元資料。 Microsoft 365 索引器中的 SharePoint 提供以下功能：

• 索引一個或多個文件函式庫的檔案與元資料。
• 為SharePoint 清單及其項目欄位值建立索引，其中每個清單欄都可作為欄位對應的來源欄位。 此功能目前處於預覽階段，始於 2026-05-01-preview REST API。
• 索引 ASPX網站頁面 （現代網站頁面）。 此功能目前處於預覽階段，始於 2026-05-01-preview REST API。
• 使用 allSiteContent 容器值，在單一索引器中為混合的 SharePoint 內容（文件庫、清單和網站頁面）建立索引。 此功能目前處於預覽階段，始於 2026-05-01-preview REST API。
• 當 includeSubsites=true 資料來源查詢中設定為 時，會索引跨子網站的內容。 此功能目前處於預覽階段，始於 2026-05-01-preview REST API。
• 以累加方式建立索引，僅擷取新增和已變更的檔案、清單項目、頁面及中繼資料。
• 自動偵測已刪除內容。 檔案、清單項目或頁面的刪除會在下一次索引器執行時被移除，對應的搜尋文件也會從索引中移除。
• 自動從索引文件中擷取文字及正規化影像。 你也可以選擇加入更深入的 AI 強化技能，例如光學字元辨識（OCR）或實體辨識。
• 支援文件基本存取控制清單 (ACL) 擷取 (預覽版)。 自 2026-05-01-preview 版開始，系統會針對具有唯一權限的項目，在每次索引器成功執行時偵測 ACL 變更並以累加方式更新。 此版本同時將 ACL 攝取擴展至清單項目、ASPX 網站頁面及 SharePoint 群組。 關於注意事項與設定步驟，請參見 使用 SharePoint 索引器來擷取權限元資料。
• 支援查詢時擷取及接受 Microsoft Purview 敏感度標籤。 此功能目前還在預覽階段。

先決條件

• 請填寫 索引預覽註冊表單。 報名會自動通過。

• Azure AI 搜尋服務，基本價格層級或更高。

• SharePoint 在 Microsoft 365 雲端服務中（OneDrive 不是支援的資料來源）。

• 文件 庫中的檔案。

• Visual Studio Code搭配 REST Client 擴充功能來設定和執行索引器管線。

選擇你的權限設定

在第三 步建立應用程式註冊前，請先在下表中確認你的情境。 請注意所需的 Microsoft Graph 權限、SharePoint API 權限以及憑證類型。 接著，請依照本文後面連結的步驟來應用這些步驟。

設定權限時，請考慮以下資訊：

• 委派權限只適用於小型測試，且不支援 ACL 擷取。
• 聯邦憑證是推薦的無秘密認證方式。 涵蓋索引器驗證和查詢時的 SharePoint 群組解析。
• 使用 Sites.Selected 時，先明確授權應用程式對每個目標SharePoint網站的存取權限，再進行索引。 Microsoft Entra ID 的管理員同意Sites.Selected本身並不授權該應用程式存取網站內容。 你也必須在每個目標網站分配權限。 如果你在沒有明確授權網站權限的情況下將網站加入資料來源，索引器就會失敗。 使用 Sites.Selected 時，請參閱「授予網站存取權限」

支援的文件格式

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
• PDF
• 純文字檔案（另見 索引純文字）
• RTF
• XML
• ZIP

限制與考量

以下是此功能的限制：

• OneNote筆記本檔案不支援。

• 增量索引限制：

  • 重新命名 SharePoint 資料夾會破壞增量索引。 重新命名的資料夾會被視為新內容。

  • Microsoft 365 更新 SharePoint 檔案系統元資料的程序，即使內容沒有其他變更，也可能觸發增量索引。 在依賴索引器或 AI 豐富功能之前，先先測試你的設備。 確認 Microsoft 365 如何處理你的文件。

• 安全限制：

  • 不支援 私有端點。 必須 透過防火牆啟用安全網路配置。

  • 不支援啟用 Microsoft Entra ID條件存取的租戶。

  • 不支援使用者加密檔案及受密碼保護的 ZIP 檔案。 不過，如果加密內容受到Microsoft Purview 敏感標籤保護，且啟用了設定以保留並尊重這些標籤（預覽），即可允許。

  • 對文件層級存取權限的支援有限。 ACL 同步的基本功能目前還在預覽階段。 詳情與設定請參見 SharePoint ACL 設定文件。 關於每種情境所需的權限，請參見 「選擇你的權限設定」。

以下是使用此功能時的一些考量：

• 若要建立一個自訂的Copilot或檢索增強生成（RAG）應用程式，並利用Azure AI 搜尋服務與SharePoint資料互動，Microsoft建議使用 遠端SharePoint知識來源。 此知識來源使用 Copilot檢索 API直接從 Microsoft 365 SharePoint 查詢文字內容，並將結果回傳至代理檢索引擎，用於合併、排名及回應的制定。 這個知識來源沒有使用搜尋索引，只查詢文字內容。 Azure AI 搜尋服務 不會複製資料。 它透過只回傳每個使用者被授權查看的結果，強制執行 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 連接器 和 Azure AI 搜尋服務 連接器。 Azure AI 搜尋服務 連接器一旦正式上市即可使用。 以 Azure 入口網站精靈 產生的工作流程作為起點，然後在 Azure Logic Apps designer 中自訂，加入你需要的轉換步驟。 Azure AI 搜尋服務精靈建立的工作流程是取用工作流程。 對於生產工作負載，請切換到 標準邏輯應用程式的工作流程 ，以利用其額外的企業功能。

無論你選擇哪種方式，無論是用 SharePoint webhook 建立自訂連接器，還是建立 Azure Logic Apps 工作流程，務必實施強而有力的安全措施。 這些措施包括設定共享私有連結、設置防火牆，以及保留使用者權限，並在查詢時尊重這些權限。 你也應該定期審核並監控你的管道。

如果您為 SharePoint ACL 建立索引，請檢視支援的群組關係。 Microsoft Entra 群組在 SharePoint 群組中巢狀的群組不會被擴充。

在 Microsoft 365 索引器中設定 SharePoint

要在 Microsoft 365 索引器中設定 SharePoint，請使用預覽版的 REST API。 本節提供步驟說明。

（可選）步驟 1：啟用系統指派的管理身份

啟用系統指派的管理身份，自動偵測搜尋服務所配置的 Microsoft Entra 租戶。

如果 SharePoint 網站與搜尋服務在同一個 Microsoft Entra 租戶中，請執行此步驟。 如果他們在不同的 Microsoft Entra 租戶中，可以跳過這個步驟。 該身分識別用於租戶識別。 如果你想在 連接字串 裡放 Microsoft Entra 租戶 ID，也可以跳過這個步驟。 若要使用系統指派或使用者指派的管理身份來進行無秘密索引，請以 無秘密認證來設定應用程式權限。

選擇 儲存後，你會收到一個分配給搜尋服務的物件 ID。

步驟 2：決定索引器需要哪些權限

關於涵蓋 ACL 與非 ACL 情境的決策矩陣，請參見 「選擇你的權限設定」。 如果你選擇委派權限，使用者委派的代幣每 75 分鐘到期一次，到期後需要使用 Run Indexer（預覽） 手動索引。 僅建議在小型測試作業中使用授權權限。

步驟 3：建立 Microsoft Entra 應用程式註冊

Microsoft 365 索引器的 SharePoint 使用 Microsoft Entra 應用程式進行認證。 在設定應用程式的權限和憑證之前，先建立應用程式註冊。

1. 登入 Azure 入口網站。

2. 搜尋或導航至 Microsoft Entra ID。

3. 在 概覽 頁面，選擇 + 新增>應用程式註冊。

   1. 輸入你的應用程式名稱。
   2. 選擇 僅限單一租戶- 租戶名稱。
   3. 跳過URI指定步驟。 不需要重定向 URI。
   4. 選擇 登記。

4. 從左側窗格選擇 「管理>API 權限」。

5. 選擇 + 新增權限，然後選擇 Microsoft Graph。

   • 如果你的索引器使用 Application API 權限，請選擇 應用程式權限。

     • 標準索引時，選擇：

       • Files.Read.All
       • Sites.Read.All

       

     • 如果你啟用了 ACL 收錄（預覽），所需的權限會依據你索引的項目類型（文件庫檔案、清單項目、ASPX 頁面）和群組類型（Microsoft Entra 與 SharePoint 網站群組）而定。 在完成此步驟前，請參考 「依 ACL 授權」情境。 關於跨情境的摘要，請參見 「選擇你的權限設定」。

       使用應用程式權限表示索引器在服務環境中存取 SharePoint 網站。 因此，當你執行索引器時，它能存取 SharePoint 租戶中的所有內容，這需要租戶管理員的審核。 驗證也需要用戶端秘密或無秘密設定。 關於建立認證機制，本文後面的「 僅適用於應用程式 API 權限的可用認證方法」將詳細說明。

   • 如果你的索引器使用委派 API 權限，請選擇 委派權限，然後選擇：

     • Files.Read.All
     • Sites.Read.All
     • User.Read

     

     委派權限允許搜尋用戶端以目前使用者的安全身份連接 SharePoint。

6. 選取 為租用戶名稱授予管理員同意。

   使用應用程式 API 權限時，必須取得租戶管理員同意。 有些租戶被鎖定，授權 API 權限也必須租戶管理員同意。 若符合任一條件，租戶管理員必須在建立索引器前，先同意此 Microsoft Entra 應用程式。

   

7. 從左側窗格選擇 「管理>認證（預覽）」。

8. 在「Redirect URI」設定標籤中，選擇 + 新增 Redirect URI。

   1. 選取 行動和桌面應用程式。
   2. 選取 https://login.microsoftonline.com/common/oauth2/nativeclient 重新導向 URI。
   3. 選擇 設定。

9. 在 設定 標籤中，啟用 允許公開客戶端流程 切換，然後選擇 儲存。

10. 根據你的解決方案需求設定索引器 認證方法 。

使用 Sites.Selected 時授予網站存取權限

如果你使用 Sites.Selected 設定應用程式註冊，請先完成以下步驟，再執行索引子。 在 Microsoft Entra ID 中，管理員同意Sites.Selected只允許應用程式使用有範圍的 SharePoint 權限。 除非你另外分配網站權限，否則不會授予任何網站存取權限。

1. 在 Microsoft Entra ID 中：將 Sites.Selected 新增至應用程式註冊，並授與系統管理員同意。 在你的案例所需的 API 介面下新增權限，例如 Microsoft Graph；而在 ACL 擷取案例中，則為 SharePoint。

2. 在 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 擷取資料，而不需儲存祕密。 下一節將逐步說明如何設定管理身份。

配置註冊的應用程式以使用受管理的身分識別

1. 建立（或選擇）使用者指派的管理身份，並將其指派給搜索服務 ，或選擇 系統指派的管理身份 ，具體根據您的情境需求。

2. 擷取 物件（主體）ID。 在建立資料來源時，將此值作為憑證設定的一部分。

3. 從左側選單選擇「 憑證與秘密 」。

4. 在 聯邦憑證中選擇+ 新增憑證。

5. 在 聯邦憑證情境 下，選擇 「管理身份」。

6. 選擇受管理身份：選擇步驟 1 中建立的受管理身份。

7. 新增你的憑證名稱並選擇 儲存。

步驟 4：建立資料來源

從本節開始，請使用最新的預覽版 REST API 以及你偏好的最新支援 REST 客戶端或最新支援的測試版 SDK，完成剩餘步驟。

資料來源指定要索引哪些資料、憑證及政策，以有效識別資料變更（新增、修改或刪除的列）。 同一搜尋服務中的多個索引器可以使用相同的資料來源。

對於 SharePoint 索引，資料來源必須具備以下必要的屬性：

• 名稱 是你搜尋服務中資料來源的唯一名稱。
• 類型 必須是「SharePoint」。 此值區分大小寫。
• credentials 提供 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-08-01-preview
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設定為使用者指派之受控身分識別自身的應用程式 (用戶端) 識別碼。

POST https://[service name].search.windows.net/datasources?api-version=2026-08-01-preview
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]

下表描述每個連接字串欄位。

設定權限時，請考慮以下資訊：

為了向下相容，SharePoint 索引器仍接受連接字串中的 FederatedCredentialObjectId（擷取應用程式上同盟識別憑證的物件 ID/主體 ID），因此現有的資料來源無須變更即可繼續運作。 針對新的與已更新的資料來源，請使用 FederatedCredentialApplicationId。

要取得 TenantId，請開啟擁有該 SharePoint 網站的租戶的 Microsoft Entra 系統管理中心，並從概覽中複製租戶 ID。

你可以從object (principal) ID」的部分取得受管理身份。

設定權限時，請考慮以下資訊：

如果 SharePoint 網站和搜尋服務在同一個 Microsoft Entra 租戶中，且系統已啟用系統指派的管理身份，你就不必在 連接字串 中包含TenantId。 如果它們位於不同的 Microsoft Entra 租戶中，您必須包含 TenantId。

以下範例展示了以以下 FederatedCredentialApplicationId方式建立的資料來源：

系統指派的管理身份與聯邦憑證：

POST https://[service name].search.windows.net/datasources?api-version=2026-08-01-preview
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]"
  }
}

具備聯合憑證的跨租用戶使用者指派受控身分識別 (進階)：

使用此設定前，請確保使用者指派的管理身份已設定為聯邦身份憑證，且該憑證信任多租戶的 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-08-01-preview
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 }
    ]
}

步驟六：建立索引器

索引器將資料來源與目標搜尋索引連結，並提供自動資料更新的排程。 建立資料來源和索引後，再建立索引器。

要建立索引器：

1. 發送 建立索引器（預覽） 請求：

   POST https://[service name].search.windows.net/indexers?api-version=2026-08-01-preview
   Content-Type: application/json
   api-key: [admin key]
   
   {
       "name" : "sharepoint-indexer",
       "dataSourceName" : "sharepoint-datasource",
       "targetIndexName" : "sharepoint-index",
       "parameters": {
       "batchSize": null,
       "maxFailedItems": null,
       "base64EncodeKeys": null,
       "maxFailedItemsPerBatch": null,
       "configuration": {
           "indexedFileNameExtensions" : ".pdf, .docx",
           "excludedFileNameExtensions" : ".png, .jpg",
           "dataToExtract": "contentAndMetadata"
         }
       },
       "schedule" : { },
       "fieldMappings" : [
           { 
             "sourceFieldName" : "metadata_spo_site_library_item_id", 
             "targetFieldName" : "id", 
             "mappingFunction" : { 
               "name" : "base64Encode" 
             } 
            }
       ]
   }
   

   對於使用 allSiteLists、 allSitePages或 allSiteContent 容器值的資料來源，請用 map metadata_spo_site_asset_item_id 代替 metadata_spo_site_library_item_id。

   使用應用程式權限時，你可以在索引器初始執行時查詢索引，但只有已被索引的項目會返回結果。 等候執行完成以取得完整涵蓋範圍。 此步驟剩餘的指示僅適用於委派權限。

2. 當你第一次建立索引器時， 建立索引器（預覽） 請求會等到你完成下一步後才會發生。 您必須致電 「取得索引器狀態 」取得連結並輸入您的新裝置代碼。

   GET https://[service name].search.windows.net/indexers/sharepoint-indexer/status?api-version=2026-08-01-preview
   Content-Type: application/json
   api-key: [admin key]
   

   如果你在 10 分鐘內沒有呼叫 「Get Indexer Status 」，程式碼就會過期，你必須重新建立 資料來源。

3. 複製「 取得索引器狀態 」回應中的裝置登入代碼。 裝置登入代碼可在「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."
       }
   }
   

4. 輸入錯誤訊息中包含的代碼。

   

5. Microsoft 365 中的 SharePoint 索引器會以已登入使用者的身分存取 SharePoint 內容。 在這個步驟中登入的使用者就是那位已登入的使用者。 所以，如果你用一個使用者帳號登入，但該帳號沒有文件庫中你想索引的文件存取權，索引器就無法存取該文件。

   如果可能，建立一個新的組織使用者帳號，並授予它你希望索引器擁有的精確權限。

6. 核准正在申請的權限。

   

7. 建立索引器（預覽）的初始要求會在先前提供的所有權限皆正確，且處於 10 分鐘時限內時完成。

設定權限時，請考慮以下資訊：

如果 Microsoft Entra 應用程式需要管理員批准，且在登入前未獲批准，你可能會看到以下畫面。 繼續進行需經行政批准。

步驟七：檢查索引器狀態

建立索引器後，呼叫 「取得索引器狀態」：

GET https://[service name].search.windows.net/indexers/sharepoint-indexer/status?api-version=2026-08-01-preview
Content-Type: application/json
api-key: [admin key]

GET https://[service-name].search.windows.net/indexes/[index-name]/docs?search=*&$count=true&api-version=2026-08-01-preview
api-key: [admin-api-key]

更新資料來源

如果你不更新資料來源物件，索引器會依照排程運行，不會有使用者互動。

如果你在裝置程式碼過期時更改資料來源，請重新登入以執行索引器。 例如，如果你更改了資料來源查詢，請再次使用 登入 https://microsoft.com/devicelogin 並取得新的裝置程式碼。

要更新資料來源，假設裝置代碼過期，請依照以下步驟操作：

1. 呼叫 Run Indexer（預覽） 來手動啟動 索引器執行。

   POST https://[service name].search.windows.net/indexers/sharepoint-indexer/run?api-version=2026-08-01-preview
   Content-Type: application/json
   api-key: [admin key]
   

2. 檢查 索引器狀態。

   GET https://[service name].search.windows.net/indexers/sharepoint-indexer/status?api-version=2026-08-01-preview
   Content-Type: application/json
   api-key: [admin key]
   

3. 如果出現錯誤要求你造訪 https://microsoft.com/devicelogin，打開頁面並複製新的代碼。

4. 把程式碼貼到對話框裡。

5. 手動再執行索引器並檢查索引器狀態。 這次索引器的執行應該會成功啟動。

索引文件元資料

如果您為文件中繼資料建立索引（"dataToExtract": "contentAndMetadata"），則可以使用下列中繼資料來建立索引。

Microsoft 365 索引器的 SharePoint 也支援針對每種文件類型的特定元資料。 欲了解更多資訊，請參閱 Azure AI 搜尋服務 中使用的 Content metadata 屬性。

設定權限時，請考慮以下資訊：

若要索引自訂元資料，請在 資料來源的查詢參數中指定「additionalColumns」。

為 SharePoint 清單建立索引

SharePoint 列表 在預覽版中可索引，從 2026-05-01-preview REST API 開始。 將資料來源 container.name 設定為 allSiteLists 索引該網站中的所有清單項目，或 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。

在索引定義中加入匹配欄位，然後將每欄映射到索引器的目標欄位：

{
  "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 網站頁面編製索引

你可以在預覽版中索引現代 ASPX 網站頁面，從 2026-05-01-preview REST API 開始。 將資料來源 container.name 設定為 allSitePages 索引該網站的所有頁面，或 allSiteContent 將頁面與文件庫及清單合併於單一索引器中。 若要包含子網站頁面，請將 includeSubsites=true 新增至 container.query。

對於頁面型或混合內容索引子，索引索引鍵欄位必須從 metadata_spo_site_asset_item_id 對應。 頁面文字會擷取至 content 欄位中，而每個頁面都會填入標準的 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-08-01-preview
{
    "parameters" : { 
        "configuration" : { 
            "indexedFileNameExtensions" : ".pdf, .docx",
            "excludedFileNameExtensions" : ".png, .jpeg" 
        } 
    }
}

控制哪些文件被索引

Microsoft 365 索引器中的單一 SharePoint 可以索引一個或多個文件函式庫的內容。 要指定要索引哪些網站和文件函式庫，請使用資料來源定義中的「container」參數。

資料來源「容器」區塊有兩個屬性用於此任務：「名稱」與「查詢」。

名稱

name該屬性是必需的，且必須符合以下其中一個值：

對於使用 allSiteLists、 allSitePages或 allSiteContent的資料來源，索引器金鑰欄位映射必須使用 metadata_spo_site_asset_item_id ，而非 metadata_spo_site_library_item_id。 詳情請參見 步驟 6：建立索引器。

查詢

資料來源的「查詢」參數由關鍵字/值對組成。 請使用以下關鍵字。 這些值要麼是網站 URL，要麼是文件庫 URL。

設定權限時，請考慮以下資訊：

要取得特定關鍵字的值，請前往你想包含或排除的文件庫，並從瀏覽器複製 URI。 這個方法是取得要在查詢中與關鍵字搭配使用之值的最簡單方式。

處理錯誤

如果出現 Invalid AAD tenant 訊息、缺少 Microsoft Entra 租用戶識別碼，或索引子執行歷程記錄中出現租用戶不符，請參閱針對常見的索引子錯誤和警告進行疑難排解。

預設情況下，Microsoft 365 索引器的 SharePoint 會在遇到不支援內容類型的文件（如圖片）時立即停止使用。 使用參數 excludedFileNameExtensions 跳過某些內容類型。 不過，你可能需要在不事先了解所有可能內容類型的情況下編索引文件。 當索引器遇到不支援的內容類型時，若要繼續索引，請將設定參數設 failOnUnsupportedContentType 為 false：

PUT https://[service name].search.windows.net/indexers/[indexer name]?api-version=2026-08-01-preview
Content-Type: application/json
api-key: [admin key]

{
    ... other parts of indexer definition
    "parameters" : { "configuration" : { "failOnUnsupportedContentType" : false } }
}

對於某些文件，Azure AI 搜尋服務 無法判斷內容類型，或無法處理原本支援的內容類型文件。 要忽略此故障模式，請將配置參數設 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 }
}

相關內容

• YouTube 影片：Microsoft 365 中的 SharePoint 索引子
• Azure AI 搜尋服務 中的索引器
• Azure AI 搜尋服務 中使用的內容中繼資料屬性
• 使用 Azure Logic App 連接器在 Azure AI 搜尋服務 中索引 SharePoint 內容及其他來源
• 擷取 SharePoint ACL 配置（預覽）
• 同步 SharePoint 與索引之間的 ACL
• 配置 SharePoint 群組支援
• 保留並尊重Microsoft Purview敏感標籤（預覽）