從 SharePoint 文件庫為資料編製索引

本文說明如何設定搜尋索引子，來為儲存在 SharePoint 文件庫中的文件編製索引，以在 Azure AI 搜尋服務中全文檢索搜尋。 首先進行設定步驟，接著是行為和情境

功能

Azure AI 搜尋服務中的索引子是一種編目程式，會從資料來源擷取可搜尋的資料和中繼資料。 SharePoint Online 索引子會連線到您的 SharePoint 站台，並為來自一或多個文件庫的文件編製索引。 此索引子提供下列功能：

• 為來自一或多個文件庫的檔案和中繼資料編製索引。
• 以累加方式編製索引，只挑選新增和變更的檔案和中繼資料。
• 刪除偵測是內建的。 在下一次索引子執行時，將會挑選文件庫中的刪除，並將文件從索引中移除。
• 預設會從編製索引的文件擷取文字和正規化影像。 您可以視需要為更深入的 AI 擴充新增技能集，例如 OCR 或文字翻譯。

必要條件

• Microsoft 365 雲端服務中的 SharePoint

• 文件庫中的檔案

支援的文件格式

SharePoint Online 索引子可以從下列文件格式擷取文字：

• CSV (請參閱編製 CSV Blob 的索引)
• EML
• EPUB
• GZ
• HTML
• JSON (請參閱編製 JSON Blob 的索引)
• KML (用於地理標記法的 XML)
• Microsoft Office 格式：DOCX/DOC/DOCM、XLSX/XLS/XLSM、PPTX/PPT/PPTM、MSG (Outlook 電子郵件)、XML (2003 和 2006 WORD XML)
• 開放式文件格式：ODT、ODS、ODP
• PDF
• 純文字檔案 (另請參閱編制純文字的索引)
• RTF
• XML
• ZIP

限制與考量

此功能的限制如下：

• 不支援編製 SharePoint 清單的索引。

• 不支援編製 SharePoint .ASPX 網站內容的索引。

• 不支援 OneNote 筆記本檔案。

• 不支援私人端點。

• 重新命名 SharePoint 資料夾不會觸發累加式索引編製。 重新命名的資料夾會視為新內容。

• SharePoint 支援細微的授權模型，可決定文件層級的每個使用者存取權。 索引子不會將這些權限提取到索引中，且 Azure AI 搜尋服務不支援文件層級授權。 當您從 SharePoint 將文件編製索引到搜尋服務時，任何可讀取索引存取權的人員都可以使用內容。 如果您需要文件層級權限，您應該考慮使用安全性篩選條件來修剪結果，並將檔案層級的權限自動複製到索引中的欄位。

• 編製索引不支援使用者加密的檔案、受資訊版權管理 (IRM) 保護的檔案、密碼或類似加密內容的 ZIP 檔案。 若要處理加密的內容，具有該特定檔案適當權限的使用者必須移除加密，以便在索引子在執行下一次排程的反覆作業時，為該項目編製索引。

• 不支援以遞迴方式從提供的特定網站編製子網站索引。

• 啟用 Microsoft ENTRA ID 條件式存取時，不支援 SharePoint Online 索引子。

以下是使用此功能時的考量事項：

• 如果您需要建立自訂 Copilot/RAG (擷取擴增生成) 應用程式來與 SharePoint 資料聊天，建議的方法是使用 Microsoft Copilot Studio，而不是此預覽功能。

• 如果您要在實際執行環境中使用 SharePoint 內容編製索引解決方案，請考慮使用 SharePoint Webhook (英文) 建立自訂連接器、呼叫 Microsoft Graph API (英文) 將資料匯出至 Azure Blob 容器，然後使用 Azure Blob 索引子進行累加式索引編製。

• 如果您的 SharePoint 設定允許 Microsoft 365 處理程序更新 SharePoint 文件系統中繼資料，請注意這些更新可以觸發 SharePoint Online 索引子，並導致索引子多次內嵌文件。 由於 SharePoint Online 索引子是 Azure 的第三方連接器，因此索引子無法讀取設定或變更其行為。 不論更新方式為何，索引子都會回應新增和變更內容中的變更。 因此，請務必先測試您的設定，並在使用索引子和任何 AI 擴充之前先了解文件處理計數。

設定 SharePoint Online 索引子

若要設定 SharePoint Online 索引子，請使用 Azure 入口網站和預覽版 REST API。 您可以使用 2020-06-30-preview 或更新版本。 我們建議使用最新的預覽版 API。

本節將會提供步驟。 您也可以觀看下列影片。

步驟 1 (選擇性)：啟用系統指派的受控識別

啟用系統指派的受控識別，以自動偵測佈建搜尋服務的租用戶。

如果 SharePoint 網站與搜尋服務位於相同的租用戶中，請執行此步驟。 如果 SharePoint 網站位於不同的租用戶中，請略過此步驟。 身分識別僅用於租用戶偵測，不會用於編製索引。 如果您想要將租用戶識別碼放在連接字串中，也可以略過此步驟。

選取 [儲存] 之後，您會取得已指派給搜尋服務的物件識別碼。

步驟 2：決定索引子所需的權限

SharePoint Online 索引子同時支援委派和應用程式權限。 根據情況選擇您想要使用的權限。

我們建議使用以應用程式為基礎的權限。 請參閱委派權限相關已知問題的限制。

• 應用程式權限 (建議)，索引子會在 SharePoint 租用戶的身分識別下執行，且可存取所有站台和檔案。 索引子需要用戶端密碼。 索引子也需要租用戶管理員核准，才能編製任何內容的索引。

• 委派權限，索引子會在傳送要求的使用者或應用程式身分識別下執行。 資料存取僅限於呼叫者可存取的站台和檔案。 若要支援委派權限，索引子需要裝置程式碼提示，才能代表使用者登入。 根據用來實作此驗證類型的最新安全性程式庫，使用者委派權限每隔 75 分鐘會強制權杖到期一次。 此行為無法進行調整。 到期的權杖需要使用執行索引子 (預覽) 手動編製索引。 為此，您可能會想改用以應用程式為基礎的權限。

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

SharePoint Online 索引子會使用此 Microsoft Entra 應用程式進行驗證。

1. 登入 Azure 入口網站。

2. 搜尋或瀏覽至 Microsoft Entra ID，然後選取 [應用程式註冊]。

3. 選取 [+ 新增註冊]：

   1. 為應用程式提供名稱。
   2. 選取 [單一租用戶]。
   3. 略過 URI 指定步驟。 不需要將 URI 重新導向。
   4. 選取註冊。

4. 在左側，選取 [API 權限]、選取 [新增權限]，然後選取 [Microsoft Graph]。

   • 如果索引子使用應用程式 API 權限，請選取 [應用程式權限]，然後新增下列項目：

     • 應用程式 - Files.Read.All
     • 應用程式 - Sites.Read.All

     

     使用應用程式權限表示索引子會存取服務內容中的 SharePoint 站台。 因此，當您執行索引子時，其會存取 SharePoint 租用戶中的所有內容，這需要租用戶管理員核准。 驗證也需要用戶端密碼。 本文稍後會說明如何設定用戶端密碼。

   • 如果索引子使用委派的 API 權限，請選取 [委派權限]，然後新增下列項目：

     • 委派 - Files.Read.All
     • 委派 - Sites.Read.All
     • 委派 - User.Read

     

     委派權限可讓搜尋用戶端以目前使用者的安全性身分識別連線到 SharePoint。

5. 給予管理員同意。

   使用應用程式 API 權限時，需要租用戶管理員同意。 有些租用戶也會受到鎖定，如此一來，委派的 API 權限也需要租用戶管理員同意。 如果適用上述任一條件，您必須先取得租用戶管理員授與此 Microsoft Entra 應用程式的同意，才能建立索引子。

   

6. 選取 [驗證] 索引標籤。

7. 將 [允許公用用戶端流程] 設定為 [是]，然後選取 [儲存]。

8. 選取 [+ 新增平台]、選取 [行動裝置和桌面應用程式]、核取 [https://login.microsoftonline.com/common/oauth2/nativeclient]，然後選取 [設定]。

   

9. (僅限應用程式 API 權限) 若要使用應用程式權限向 Microsoft Entra 應用程式進行驗證，則索引子需要用戶端密碼。

   • 從左側功能表中選取 [憑證和密碼]、選取 [用戶端密碼]，然後選取 [新增用戶端密碼]。

     

   • 在快顯的功能表中，輸入新用戶端密碼的描述。 視需要調整到期日。 如果秘密到期，則必須重新建立，且索引子必須以新的秘密進行更新。

     

   • 新的用戶端密碼會顯示在秘密清單中。 當您離開頁面後，將無法再看到秘密，因此請使用 [複製] 按鈕複製祕密，並將其儲存在安全的位置。

     

步驟 4：建立資料來源

從本節開始，剩餘步驟請使用預覽 REST API。 我們建議使用最新的預覽版 API。

資料來源能指定要編製索引的資料、認證，以及能有效識別資料變更 (新增、修改或刪除的資料列) 的原則。 資料來源可供同一個搜尋服務中的多個索引子使用。

若要為 SharePoint 編製索引，資料來源必須具有下列必要屬性︰

• 名稱是搜尋服務中資料來源的唯一名稱。
• type 必須是「sharepoint」。 此值區分大小寫。
• credentials 會提供 SharePoint 端點和 Microsoft Entra 應用程式 (用戶端) 識別碼。 SharePoint 端點範例為 https://microsoft.sharepoint.com/teams/MySharePointSite。 您可以瀏覽至 SharePoint 站台的首頁，並從瀏覽器複製 URL 來取得端點。
• container 會指定要編製索引的文件庫。 屬性會控制要編製哪些文件的索引。

若要建立資料來源，請呼叫建立資料來源 (預覽)。

POST https://[service name].search.windows.net/datasources?api-version=2024-05-01-preview
Content-Type: application/json
api-key: [admin key]

{
    "name" : "sharepoint-datasource",
    "type" : "sharepoint",
    "credentials" : { "connectionString" : "[connection-string]" },
    "container" : { "name" : "defaultSiteLibrary", "query" : null }
}

連接字串格式

連接字串的格式會根據索引子是使用委派的 API 權限還是應用程式 API 權限而變更

• 委派的 API 權限連接字串格式

  SharePointOnlineEndpoint=[SharePoint site url];ApplicationId=[Azure AD App ID];TenantId=[SharePoint site tenant id]

• 應用程式 API 權限連接字串格式

  SharePointOnlineEndpoint=[SharePoint site url];ApplicationId=[Azure AD App ID];ApplicationSecret=[Azure AD App client secret];TenantId=[SharePoint site tenant id]

步驟 5：建立索引

索引會指定文件、屬性和其他建構中可形塑搜尋體驗的欄位。

如需建立索引，請呼叫建立索引 (預覽)：

POST https://[service name].search.windows.net/indexes?api-version=2024-05-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 }
    ]
}

步驟 6：建立索引子

索引子會以目標搜尋索引連接資料來源，並提供排程來將資料重新整理自動化。 建立索引和資料來源之後，您便可以建立索引子。

如果您使用委派的權限，在此步驟期間，系統會要求您使用可存取 SharePoint 站台的組織認證進行登入。 如果可能，建議您建立新的組織使用者帳戶，並為該新使用者授與您想要索引子擁有的確切權限。

建立索引子有下列幾個步驟：

1. 傳送建立索引子 (預覽) 要求：

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

   如果您使用應用程式權限，則必須等到初始執行完成，再開始查詢索引。 此步驟中提供的下列指示僅適用於委派的權限，不適用於應用程式權限。

2. 當您第一次建立索引子時，建立索引子 (預覽) 要求會等到您完成下一個步驟為止。 您必須呼叫取得索引子狀態以取得連結，然後輸入新的裝置代碼。

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

   如果您在 10 分鐘內未執行取得索引子狀態，代碼就會過期，您必須重新建立資料來源。

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. SharePoint Online 索引子會以登入的使用者身分來存取 SharePoint 內容。 在此步驟中登入的使用者將為該登入的使用者。 因此，如果您用來登入的使用者帳戶無法存取您所要編製索引文件庫中的文件，索引子將無法存取該文件。

   如果可能，建議您建立新的使用者帳戶，並為該新使用者授與您想要索引子擁有的確切權限。

6. 核准正在要求的權限。

   

7. 如果上述所有權限都正確且在 10 分鐘內，建立索引子 (預覽) 初始要求就會完成。

步驟 7：檢查索引子狀態

建立索引子之後，您可以呼叫取得索引子狀態：

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

更新資料來源

如果沒有資料來源物件的更新，索引子會依排程執行，而不需要任何使用者互動。

不過，如果您在裝置代碼過期時修改資料來源物件，您必須再次登入才能執行索引子。 例如，如果您變更資料來源查詢，請使用 https://microsoft.com/devicelogin 再次登入並取得新的裝置代碼。

以下是更新資料來源的步驟，假設裝置代碼已到期：

1. 呼叫執行索引子 (預覽) 以手動啟動索引子執行。

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

2. 檢查索引子狀態。

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

3. 如果您收到錯誤，要求您造訪 https://microsoft.com/devicelogin，請開啟該頁面並複製新的代碼。

4. 將代碼貼到對話方塊中。

5. 再次手動執行索引子，然後檢查索引子狀態。 這一次，應該會順利啟動索引子執行。

編製文件中繼資料的索引

如果您在編製文件中繼資料 ("dataToExtract": "contentAndMetadata") 的索引，下列中繼資料將可供編製索引。

SharePoint Online 索引子也支援每個文件類型特定的中繼資料。 如需詳細資訊，請參閱 Azure AI 搜尋服務中使用的內容中繼資料屬性。

依檔案類型包含或排除

您可在索引子定義的「parameters」區段中設定包含和排除準則，以控制要編製索引的檔案。

您可將 "indexedFileNameExtensions" 設定為以逗號分隔的副檔名清單 (前面加上點) 來包含特定副檔名。 將 "excludedFileNameExtensions" 設定為應略過的副檔名，可排除特定副檔名。 若兩份清單中有相同的副檔名，則會排除在索引編製外。

PUT /indexers/[indexer name]?api-version=2024-05-01-preview
{
    "parameters" : { 
        "configuration" : { 
            "indexedFileNameExtensions" : ".pdf, .docx",
            "excludedFileNameExtensions" : ".png, .jpeg" 
        } 
    }
}

控制要編製哪些文件的索引

單一 SharePoint Online 索引子可以從一或多個文件庫編製內容的索引。 在資料來源定義上使用「container」參數，可指出要從哪些站台和文件庫編製索引。

資料來源「container」區段包含此工作的兩個屬性：「name」和「query」。

名稱

「name」為必要屬性，且必須是三個值的其中一個：

查詢

資料來源的「query」參數是由關鍵字/值組所組成。 以下為可以使用的關鍵字。 這些值為站台 URL 或文件庫 URL。

處理錯誤

根據預設，一旦遇到不受支援內容類型 (例如影像) 的文件時，SharePoint Online 索引子就會停止。 您可以使用 excludedFileNameExtensions 參數來略過特定內容類型。 不過，有時在編製文件的索引，您可能不知道所有的內容類型。 若要在遇到不受支援的內容類型時繼續編製索引，請將 failOnUnsupportedContentType 組態參數設定為 false：

PUT https://[service name].search.windows.net/indexers/[indexer name]?api-version=2024-05-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 } }

Azure AI 搜尋服務會限制編列索引的文件大小。 這些限制記載於 Azure AI 搜尋服務中的限制。 預設會將過大的文件視為錯誤。 不過，如果您將 indexStorageMetadataOnlyForOversizedDocuments 組態參數設為 true，仍可以針對過大文件的儲存體中繼資料編列索引：

"parameters" : { "configuration" : { "indexStorageMetadataOnlyForOversizedDocuments" : true } }

如果在處理期間發生任何錯誤，當剖析文件或是將文件新增至索引時，您還是可以繼續編製索引。 若要忽略特定錯誤數目，請將 maxFailedItems 和 maxFailedItemsPerBatch 組態參數設定為所需的值。 例如：

{
    ... other parts of indexer definition
    "parameters" : { "maxFailedItems" : 10, "maxFailedItemsPerBatch" : 10 }
}

如果 SharePoint 網站上的檔案已啟用加密，可能會遇到類似下列的錯誤訊息：

Code: resourceModified Message: The resource has changed since the caller last read it; usually an eTag mismatch Inner error: Code: irmEncryptFailedToFindProtector

錯誤訊息也會包含 SharePoint 站點識別碼、磁碟機識別碼和磁碟機項目識別碼，模式如下：<sharepoint site id> :: <drive id> :: <drive item id>。 這項資訊可用來識別 SharePoint 端失敗的項目。 接著，使用者可以移除該項目的加密以解決問題。

另請參閱

• Azure AI 搜尋服務中的索引子
• Azure AI 搜尋服務中使用的內容中繼資料屬性