從 Azure Blob 儲存體編製資料索引

備註

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

Important

本文中標示為(預覽)的功能或特性目前處於公開預覽狀態,並受 Microsoft Azure 預覽版補充使用條款的約束。

有關 Foundry IQ(Azure AI 搜尋服務)專屬的預覽詞,請參閱預覽功能。

blob 索引器會從 Azure Blob 儲存體 匯入內容,並使其可在 Foundry IQ 中搜尋。 索引器接收單一容器中的 blob 作為輸入。 輸出是一個搜尋索引,將可搜尋的內容和中繼資料儲存在各個欄位中。

本文使用 Search Service REST API 來示範如何配置與執行索引器。 不過,你也可以使用:

備註

標準的 Blob 容器、RBAC 作用域匯入與查詢權限過濾功能通常可在 REST API 2026-10-01中提供。 此可用性不包含 ADLS 檔案或目錄 ACL。 關於設定以及儲存範圍與查詢時授權的區別,請參閱「擷取 Blob RBAC 範圍」。

先決條件

  • Azure Blob 儲存體, Standard performance (general-purpose v2).

  • 存取層級 包括熱、涼、冷及歸檔。 索引子可以在經常性存取層、非經常性存取層和極非經常性存取層上擷取 Blob。

  • Blob 提供文字內容和中繼資料。 若 Blob 包含二進位內容或非結構化文字,請考慮為映像和自然語言處理新增 AI 擴充。 Blob 內容不能超過你定價層級的 索引器限制 。

    blob 索引器的限制涵蓋了 blob 的最大大小以及 Foundry IQ 從 blob 中擷取的字元數。 如果你使用技能組,每個技能的輸入或服務限制在破解文件後會分別適用。

  • 支援的網路設定和資料存取。 您至少需要 Azure 儲存體的讀取權限。 包含存取金鑰的儲存體連接字串可提供儲存體內容的讀取存取。 如果您改用 Microsoft Entra 登入帳號與角色,請確保 Foundry IQ 服務的管理身份具有 Storage Blob 資料讀取器的權限。

    根據預設,搜尋和儲存體都會接受來自公用 IP 位址的要求。 若網路安全性不是立即考量事項,您可僅使用連接字串和讀取權限來編製 Blob 資料索引。 當您準備好新增網路保護時,請參閱索引子存取受 Azure 網路安全性功能保護的內容以取得有關資料儲存的指引。

  • 使用 REST 用戶端編寫接近於本文示範的 REST 呼叫。

支援的任務

您可以針對下列工作使用此索引子:

支援的文件格式

blob 索引子可以從下列文件格式擷取文字:

  • CSV (請參閱編製 CSV Blob 的索引)
  • EML
  • EPUB
  • GZ
  • HTML
  • JSON (請參閱編製 JSON Blob 的索引)
  • KML (用於地理標記法的 XML)
  • Markdown
  • 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

決定要編製索引的 Blob

在設定索引之前,先檢視你的來源資料,判斷是否需要做任何修改。 索引子一次可編製一個容器的內容索引。 預設情況下,索引器會處理容器中的所有 blob。 提供您數個更具選擇性的處理選項:

  • 在虛擬資料夾中放置 Blob。 索引器 資料來源定義 包含 query 一個參數,可以取虛擬資料夾。 如果你指定虛擬資料夾,索引器只會索引資料夾裡的那些 blob。

  • 依檔案類型包含或排除 Blob。 支援的文件格式清單可協助您判斷要排除的 Blob。 例如,您可能要排除不提供可搜尋文字的影像或音訊檔案。 你可以透過索引器中的 設定 來控制這項功能。

  • 包含或排除任意 Blob。 要跳過特定的 blob,請在 Azure Blob 儲存體 中為該 blob 新增以下的中繼資料屬性和值。 遇到此屬性時,索引子會跳過索引執行中的 Blob 或 Blob 內容。

    屬性名稱 屬性值 Explanation
    AzureSearch_Skip true 指示 blob 索引子以完全略過 blob。 索引器不會嘗試擷取元資料或內容。 當特定 blob 反覆失敗並中斷索引程序時,此特性非常有用。
    AzureSearch_SkipContent true 索引器會跳過內容,只擷取元資料。 此屬性等同於"dataToExtract": "allMetadata"中所描述的 設定,但其作用範圍僅限於特定 Blob。

如果你沒有設定包含或排除標準,索引器會把不合格的 blob 當成錯誤回報,然後繼續往下走。 若發生足夠的錯誤,處理可能停止。 您可在索引子設定中指定錯誤容錯。

索引子通常會為每個 Blob 建立一個搜尋文件,文件中的文字內容和中繼資料會擷取為索引中的可搜尋欄位。 如果 Blob 是整個檔案,您可以剖析這些 Blob 為多個搜尋文件。 例如,您可剖析 CSV 檔案中的資料列,並為每個資料列建立一個搜尋文件。

複合或內嵌文件,例如 ZIP 封存、具有內嵌 Outlook 電子郵件的 Word 文件 (內含附件),或者內含附件的 .MSG 檔案,也會編制索引為單一文件。 例如,從 .MSG 檔案的附件中擷取的所有影像都會被返回到 normalized_images 欄位。 如果您有影像,請考慮新增 AI 擴充,以從該內容取得更多搜尋公用程式。

索引器會將文件的文字內容擷取到一個名為 content的字串欄位中。 您也可以擷取標準和使用者定義的中繼資料。

編製 Blob 中繼資料的索引

你可以將 Blob 中繼資料與內容一併建立索引。 索引器會擷取元資料屬性並將其儲存在索引欄位中,這對於建立篩選器和查詢非常有幫助。

在搜尋索引中定義你想要捕捉的元資料屬性欄位。 你不需要定義所有可用的標準或自訂元資料屬性。 只要擷取你申請所需的屬性即可。

目前,這個索引器不支援索引 blob 索引標籤。

Important

索引器只會填充已經在搜尋索引中定義的元資料欄位。 此要求適用於標準 blob 元資料及自訂元資料。 如果欄位沒有定義,索引時會擷取中繼資料值,但會被靜默丟棄,因此不會出現在搜尋結果中。 這是搜尋結果中最常見的空元資料欄位來源。 欲了解更多資訊,請參閱 搜尋結果中的元資料欄位為空。

標準 Blob 中繼資料屬性

對於標準 Blob 中繼資料,請在索引中使用相同的底線名稱來定義欄位。 關於逐步欄位定義範例,請參見 「將搜尋欄位加入索引」。

關於索引器的設定,包括控制要提取哪些元資料的 dataToExtract 設定,請參見 「配置並執行 blob 索引器」。

索引器能辨識並映射這些標準的元資料屬性,只要你在索引中定義對應欄位:

  • metadata_storage_name (Edm.String) 是 blob 的檔名。 例如,若你有一個斑點 /my-container/my-folder/subfolder/resume.pdf,該欄位的值為 resume.pdf。

  • metadata_storage_path (Edm.String) 是 blob 的完整 URI,包含儲存帳戶。 例如: https://myaccount.blob.core.windows.net/my-container/my-folder/subfolder/resume.pdf 。 使用此特性在搜尋結果中包含 blob URL,以便導覽或來源標註。

  • metadata_storage_content_type(Edm.String)是由您用來上傳 Blob 的程式碼所指定的內容類型。 例如: application/octet-stream 。

  • metadata_storage_last_modified (Edm.DateTimeOffset)是該 blob 的最後修改時間戳記。 Foundry IQ 利用此時間戳記來識別已變更的 Blob,避免在初始索引後重新索引所有內容。

  • metadata_storage_size (Edm.Int64) 是 blob 的大小(以位元組為單位)。

  • metadata_storage_content_md5 (Edm.String) 是 blob 內容的 MD5 雜湊值(如有的話)。

  • metadata_storage_sas_token (Edm.String)是一個臨時的SAS代幣,自訂 技能 可以用來取得blob的存取權。 不要將此代幣存起來以備後續使用,因為可能會過期。

自訂及內容特定的中繼資料

對於自訂或使用者定義的 blob 元資料,請定義一個與 blob 元資料鍵號名稱完全相同的欄位。 例如,如果您的 Blob 物件有一個中繼資料索引鍵 Sensitivity,其值為 High,請在索引中定義一個名為 Sensitivity、類型為 Edm.String 的欄位。

在使用自訂中繼資料作為文件金鑰或權限之前,請先檢查哪些人可以寫入自訂中繼資料。 相符的欄位名稱會建立對應關係,而非值的依據。 請參閱 「保護文件身份與權限來源」。

您也可以表示您建立索引的 Blob 文件格式特定的中繼資料屬性。 欲了解更多資訊,請參閱 內容元資料屬性。

定義資料來源

資料來源定義指定要編製索引的資料、認證,以及用於識別資料變更的原則。 資料來源定義為獨立的資源,因此可供多個索引子使用。

  1. 建立或更新資料來源 以設定其定義:

    {
        "name" : "my-blob-datasource",
        "type" : "azureblob",
        "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
        "container" : { "name" : "my-container", "query" : "<optional-virtual-directory-name>" }
    }
    
  2. 將 type 設為 azureblob (必要)。

  3. 設定 credentials 為 Azure 儲存體連接字串。 下一節說明支援的格式。

  4. 設置 container 為 blob 容器,然後使用 query 指定任何子資料夾。

如果你希望索引器在搜尋文件被標記刪除時刪除,也可以在資料來源定義中包含 軟刪除政策 。

支援的認證和連接字串

索引器可以透過以下連線連接到 blob 容器。

完整存取儲存體帳戶連接字串
{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" }
您可以從 Azure 入口網站中的 [記憶體帳戶] 頁面取得連接字串,方法是在左窗格中選取 [存取金鑰 ]。 請務必選取完整的連接字串,而不只是金鑰。
受控識別連接字串
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;" }
此 連接字串 不需要帳戶金鑰,但您必須先前已設定 Foundry IQ 服務以使用管理身份進行連線。
儲存體帳戶共享存取簽章(SAS)連線字串
{ "connectionString" : "BlobEndpoint=https://<your account>.blob.core.windows.net/;SharedAccessSignature=?sv=2016-05-31&sig=<the signature>&spr=https&se=<the validity end time>&srt=co&ss=b&sp=rl;" }
SAS 對於容器和物件 (在此案例中為 blob) 應該擁有列出和讀取權限。
容器共用存取簽章
{ "connectionString" : "ContainerSharedAccessUri=https://<your storage account>.blob.core.windows.net/<container name>?sv=2016-05-31&sr=c&sig=<the signature>&se=<the validity end time>&sp=rl;" }
SAS 對於容器應該擁有列出和讀取權限。 如需詳細資訊,請參閱使用共用存取簽章 (SAS) 對 Azure 儲存體資源授與有限存取權。

備註

如果你使用 SAS 憑證,你需要定期更新資料來源憑證並更新簽章,以防止其過期。 若 SAS 憑證過期,索引器會以類似「連線字串中提供的憑證無效或已過期」的錯誤訊息失敗。

將搜尋欄位新增至索引

在搜尋索引中,新增欄位接受 Azure Blob 的內容和中繼資料。

  1. 建立或更新索引 以定義儲存 blob 內容與元資料的搜尋欄位:

    POST https://[service name].search.windows.net/indexes?api-version=2026-10-01
    {
        "name" : "my-search-index",
        "fields": [
            { "name": "ID", "type": "Edm.String", "key": true, "searchable": false },
            { "name": "content", "type": "Edm.String", "searchable": true, "filterable": false },
            { "name": "metadata_storage_name", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true  },
            { "name": "metadata_storage_size", "type": "Edm.Int64", "searchable": false, "filterable": true, "sortable": true  },
            { "name": "metadata_storage_content_type", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true },        
        ]
    }
    
  2. 建立文件鍵欄位("key": true)。 選擇代表預期文件身份的金鑰來源,並檢視誰可以控制其值。

    • metadata_storage_path 是預設的 Blob 金鑰來源,並包含物件或檔案的完整路徑。 檢視您的解析器與映射以確定有效鍵值;這個預設並不是所有權的保證。

    • metadata_storage_name 只有在名稱唯一的情況下才可用。 如果您要此欄位作為索引鍵,請將 "key": true 移至此欄位的定義。

    • 新增至 Blob 的自訂中繼資料屬性。 此選項需要 Blob 上傳程序新增該中繼資料屬性至所有 Blob。 由於鍵是必修屬性,任何缺少值的斑點都無法被索引。 如果您使用自訂中繼資料屬性作為索引鍵,請避免變更該屬性。 索引器會在相同 blob 的 key 屬性改變時新增重複文件。

    中繼資料屬性通常包含對文件索引鍵無效的字元,例如 / 和 -。 然而,索引子會自動編碼索引鍵中繼資料屬性,不需要任何設定或欄位對應。

  3. 新增一個content欄位,使用 blob 的content屬性來儲存從每個檔案擷取的文字。 你不必使用這個名稱,但透過使用它,你可以利用隱含的欄位映射。

  4. 新增標準中繼資料屬性的欄位。 索引子可讀取自訂中繼資料屬性、標準中繼資料屬性和特定內容的中繼資料屬性。

保護文件身分與權限來源追溯

文件鍵用來識別更新或合併所針對的索引記錄。 這不是授權界線。 寫入來源內容的權限,並不表示您就有權選取其他文件的索引身分識別,或存取該文件。

Blob 屬性、自訂元資料、解析內容、 欄位映射及 豐富化輸出映射會 為索引貢獻值。 對於區塊內容, 索引投影 也會控制寫入每個子節點的欄位。 名為 metadata_storage_path 的欄位,並不能證明其值在所有設定中都具有權威性。 不要以為這個名稱能防止與其他輸入的碰撞,或認為這個欄位永遠是最終鍵。

Base64 編碼會改變金鑰的表示方式;它不會驗證其來源的真實性,也不會阻止其他寫入者使用相同的識別。 僅僅保留欄位名稱或新增鍵前綴,並不能強制執行文件歸屬。

對於必須保持獨立的紀錄,請使用穩定且具適當唯一性的識別碼。 當應用程式業務識別碼無法唯一識別預期的來源記錄時,請將應用程式業務識別碼與索引鍵分開。 如果多個來源有意更新同一條邏輯記錄,請就其受信任的寫入者與權限政策達成共識。 請參閱 「索引多個資料來源」。

以下範例指出需檢視的配置選項,而非所有權強制執行設定:

來源設定 身分與權限審查
兩個容器中各包含一個名為 policy.pdf的 blob。 僅檔名的金鑰無法區分兩個來源項目。 檢查兩個來源間的最終對應鍵,而非僅檢查各容器內的檔名。
獨立 blob 中的 JSON 記錄包含相同的業務 ID。 判斷這些是獨立記錄還是有意共享的記錄。 在允許該 ID 選取已建立索引的記錄之前,請先檢視已解析的鍵與對應。
兩個可信來源會刻意貢獻一份紀錄。 檢視由哪位撰寫者控制每個欄位及最終權限政策。 不要以為合併權限集合會合併授權或保留其與預期內容的關聯。

檢閱您的資料擷取設定

在部署索引器或變更其對應之前:

  1. 限制對來源內容及自訂元資料的寫入存取。 另行限制誰可以變更資料來源、解析器、映射、技能集、預測以及索引文件。
  2. 選擇並控制每個解析器與匯入路徑的金鑰來源。 同時考慮隱含映射以及顯式映射與豐富輸出。 不要讓信任度較低的內容為其未被授權維護的紀錄選擇金鑰。
  3. 在所有貢獻來源間,為獨立紀錄保持鍵彼此區分。 請考慮商業識別碼、轉換與產生的子金鑰。 僅允許有權維持相同邏輯記錄的寫入者之間進行有意合併。
  4. 僅接受來自授權政策來源的權限授與。 在匯入前,並在合併與投影過程中持續,請將授權資料綁定於預期文件的身份。 不要將類似權限的值從一般內容複製到受信任的權限欄位中。
  5. 對擷取管理員與文件發佈者套用最小權限。 任何被授權提交索引更新的寫入者,都可以依照鍵選擇目標紀錄;金鑰並不限制該寫入者只能使用他們擁有的文件。
  6. 透過適當的存取控制,將獨立受信任的資料集與寫入者區分開來。 如果共用的服務層級認證或系統管理員可以跨索引寫入,單靠將索引分開並不能構成完整的隔離邊界。
  7. 設定每個受保護投影,以承載同一來源文件的內容、父身份、來源上下文及權限。 將 權限更新 保留在同一受信任的擷取流程內。

對於 連接器衍生的 Blob RBAC 範圍,請使用支援的匯入設定,並檢視每個文件與其來源容器之間的關聯。 對於 客戶管理的推播權限,授權發佈者需同時負責文件識別與權限值。 無論是權限欄位註解還是成功的索引,都無法證明一般內容撰寫者有權授予存取權。

這些控制必須是擷取設計的一部分。 索引鍵與欄位名稱無法提供歷史所有權或誰提供值的確鑿證據。 設定慣例並不妨礙授權寫入者鎖定其他紀錄。

變更金鑰來源或對應可以建立新紀錄,同時保留舊紀錄在索引中。 僅僅重設、權限重新同步或 API 版本變更,並不能建立受信任的文件擁有權。

設定和執行 Blob 索引子

建立索引和資料來源後,再建立索引器。 索引器配置指定控制執行時行為的輸入、參數與屬性。 您也可指定要編製索引的 Blob 部分。

  1. 透過為索引器命名,並參考資料來源與目標索引,建立或更新索引器:

    POST https://[service name].search.windows.net/indexers?api-version=2026-10-01
    {
      "name" : "my-blob-indexer",
      "dataSourceName" : "my-blob-datasource",
      "targetIndexName" : "my-search-index",
      "parameters": {
          "batchSize": null,
          "maxFailedItems": null,
          "maxFailedItemsPerBatch": null,
          "configuration": {
              "indexedFileNameExtensions" : ".pdf,.docx",
              "excludedFileNameExtensions" : ".png,.jpeg",
              "dataToExtract": "contentAndMetadata",
              "parsingMode": "default"
          }
      },
      "schedule" : { },
      "fieldMappings" : [ ]
    }
    
  2. 如果預設(10 份文件)無法充分利用或超過可用資源,則會設定 batchSize 。 預設批次大小是資料來源特定的。 基於平均文件大小較大的考量,Blob 索引會將批次大小設為 10 個文件。

  3. 在 configuration 下,控制哪些 blob 根據檔案類型被索引,或不指定以檢索所有 blob。

    針對 indexedFileNameExtensions,提供副檔名的逗號分隔清單 (包含前置點)。 請對 excludedFileNameExtensions 執行相同的操作,以指示索引器應該跳過哪些擴展。 如果同一個擴展名出現在兩個清單中,索引器會將其排除在索引之外。

  4. 在 configuration 下,設定 dataToExtract 以控制大型二進制物件中哪些部分被索引:

  5. 在 configuration下,設定 parsingMode。 預設剖析模式是每個 Blob 有一個搜尋文件。 在文件層級權限匯入時, default保留;不支援專用的解析模式。 請參閱 權限匯入支援的解析與內容擷取。

    在沒有權限匯入的情況下,純文字 blob 可以使用 純文字 解析以提升效能。 若要進行更細緻的解析,將 blob 對應 到多個搜尋文件,請指定不同的模式。 一對多剖析支援包含下列項目的 Blob:

  6. 請指定欄位對應,如果欄位名稱或類型有差異,或如果您需要在搜尋索引中使用同一個來源欄位的多個版本。

    在 blob 索引中,你通常可以省略欄位映射,因為索引器內建支援將 content 和 元資料屬性映射到索引中名稱和類型相似的欄位。 針對中繼資料屬性,索引子會在搜尋索引中自動以底線取代連字號 -。

  7. 如需其他屬性的詳細資訊,請參閱建立索引子。 如需參數描述的完整清單,請參閱 REST API。

索引器建立後會自動執行。 你可以透過將此動作設 disabled 為 true來避免。 若要控制索引子執行,請按需執行索引子或安排排程執行。

將多個 Azure Blob 容器的資料索引到單一索引

請記得索引器只能索引單一容器的資料。 如果您需要將多個容器的資料建立索引並整合到單一 Foundry IQ 索引中,請設定多個索引器,讓它們都指向同一個索引。 請注意 每個 SKU 可用的索引器數量上限。

例如,你可以使用兩個索引器,從兩個名為 my-blob-datasource1 和 my-blob-datasource2的不同資料來源拉取資料。 每個資料來源都指向個別的 Azure Blob 容器,但兩者都直接指向名為 my-search-index 的相同索引。

第一個索引子定義範例:

POST https://[service name].search.windows.net/indexers?api-version=2026-10-01
{
  "name" : "my-blob-indexer1",
  "dataSourceName" : "my-blob-datasource1",
  "targetIndexName" : "my-search-index",
  "parameters": {
      "batchSize": null,
      "maxFailedItems": null,
      "maxFailedItemsPerBatch": null,
      "configuration": {
          "indexedFileNameExtensions" : ".pdf,.docx",
          "excludedFileNameExtensions" : ".png,.jpeg",
          "dataToExtract": "contentAndMetadata",
          "parsingMode": "default"
      }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

在平行範例中執行的第二個索引子定義:

POST https://[service name].search.windows.net/indexers?api-version=2026-10-01
{
  "name" : "my-blob-indexer2",
  "dataSourceName" : "my-blob-datasource2",
  "targetIndexName" : "my-search-index",
  "parameters": {
      "batchSize": null,
      "maxFailedItems": null,
      "maxFailedItemsPerBatch": null,
      "configuration": {
          "indexedFileNameExtensions" : ".pdf,.docx",
          "excludedFileNameExtensions" : ".png,.jpeg",
          "dataToExtract": "contentAndMetadata",
          "parsingMode": "default"
      }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

檢查索引子狀態

若要監視索引子狀態和執行歷程記錄,請傳送取得索引子狀態要求:

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2026-10-01
  Content-Type: application/json  
  api-key: [admin key]

回應包含狀態和已處理的項目數目。 回應會類似於下列範例:

    {
        "status":"running",
        "lastResult": {
            "status":"success",
            "errorMessage":null,
            "startTime":"2022-02-21T00:23:24.957Z",
            "endTime":"2022-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2022-02-21T00:23:24.957Z",
                "endTime":"2022-02-21T00:36:47.752Z",
                "errors":[],
                "itemsProcessed":1599501,
                "itemsFailed":0,
                "initialTrackingState":null,
                "finalTrackingState":null
            },
            ... earlier history items
        ]
    }

執行歷史最多包含 50 次最近完成的執行。 條目依時間倒序排列,因此最新執行的先行。

Troubleshooting

使用此區塊來診斷缺少的元資料值及常見的 blob 索引失敗。

搜尋結果中元資料欄位為空

如果您在搜尋結果中看到中繼資料欄位顯示為 null 或空白值,請參考以下檢查清單:

  1. 確認該欄位在您的索引結構中是否存在: 檢查您是否為每個想要擷取的元資料屬性定義欄位。 在你的索引上執行 GET 請求,確認該欄位是否存在。

  2. 請使用正確的欄位名稱:對於標準 blob 屬性,請使用帶底線的名稱,例如 metadata_storage_path 而不是 metadata-storage-path。 對於自訂元資料,欄位名稱必須與 blob 的元資料鍵完全一致。

  3. 確認索引器已 dataToExtract 正確設定:

    • contentAndMetadata (預設)同時擷取內容及標準/自訂元資料。
    • storageMetadata 僅擷取標準 BLOB 屬性與自訂元資料。
    • allMetadata 擷取標準屬性加上內容類型專屬的中繼資料。

    檢查你的索引器設定,確保設定符合你的意圖。

  4. 結構更新後重新執行索引器:如果您新增了索引欄位,請再次執行索引器,以便文件能根據更新後的架構進行處理。 現有文件可能需要在新欄位填充前重新處理。

  5. 檢查索引器的執行紀錄:前往 Azure 入口網站中的索引器,或使用取得索引器狀態(REST API)檢視執行細節及任何錯誤訊息。

索引器故障與不支援的內容類型

預設情況下,blob 索引器會在遇到不支援內容類型的 blob(例如音訊檔案)時立即停止。 您可以使用 excludedFileNameExtensions 參數來略過特定內容類型。

如果你希望索引在某些文件失敗時繼續進行,請調整以下參數,然後再調查個別文件。 欲了解更多資訊,請參閱 索引器故障排除指引 及 索引器錯誤與警告。

當出現錯誤時,五個索引器參數控制索引器的回應:

PUT /indexers/[indexer name]?api-version=2026-10-01
{
  "parameters" : { 
    "maxFailedItems" : 10, 
    "maxFailedItemsPerBatch" : 10,
    "configuration" : { 
        "failOnUnsupportedContentType" : false, 
        "failOnUnprocessableDocument" : false,
        "indexStorageMetadataOnlyForOversizedDocuments": false
      }
    }
}
參數 有效值 Description
maxFailedItems -1,零,或0,正整數 如果處理期間 (剖析 Blob 或新增文件至索引時) 發生任何錯誤,仍要繼續編製索引, 將此屬性設為可接受的失敗次數。 無論錯誤發生的次數,-1 的值允許繼續編製索引。 否則,此值為正整數。
maxFailedItemsPerBatch -1,零,或0,正整數 同上,但用於批次編製索引。
failOnUnsupportedContentType 真或假 如果索引器無法判斷內容類型,請指定是繼續工作還是失敗。
failOnUnprocessableDocument 真或假 如果索引器無法處理其他支援內容類型的文件,請指定是繼續或失敗該工作。
indexStorageMetadataOnlyForOversizedDocuments 真或假 預設會將過大的 Blob 視為錯誤。 如果您將此參數設定為 true,則即使無法編製內容索引,索引子仍會嘗試編製其中繼資料索引。 在一對多解析中,超大 blob 會產生一份僅包含元資料的文件,其原始金鑰來源為 metadata_storage_path,在任何金鑰編碼之前。 此組合不支援 ACL 匯入。 大小變更可能會讓文件處於舊鍵之下,包括先前的 ACL 值。 請參閱 「超大 blob 與一對多金鑰」 以及 「服務限制」。