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

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

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

• 一個 Azure SDK 套件（任何版本）
• Azure 入口網站中的匯入資料精靈

先決條件

• Azure Blob 儲存體，標準效能 (一般用途 v2)。

• 存取層包括經常性存取層、非經常性存取層、極非經常性存取層和封存層。 索引子可以在經常性存取層、非經常性存取層和極非經常性存取層上擷取 Blob。

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

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

• 支援的網路設定和資料存取。 您至少需要 Azure 儲存體的讀取權限。 包含存取金鑰的儲存體連接字串可提供儲存體內容的讀取存取。 如果您改用 Microsoft Entra 內容和角色，請確保搜尋服務的受控識別具有儲存體 Blob 資料讀取者權限。

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

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

支援的任務

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

• 資料編製索引和累加編製索引：索引子可以從 Blob 容器和資料夾為檔案和相關聯的中繼資料編製索引。 它會透過內建變更偵測來偵測新的和更新的檔案與中繼資料。 您可以依排程或視需要設定資料重新整理。

• 刪除偵測：索引子可以透過原生虛刪除或透過自訂中繼資料刪除偵測。

• 透過技能組合應用人工智慧： 索引器完全支援 技能組合。 此支援包含 整合向量化等關鍵功能，可加入資料分塊與嵌入功能。

• 剖析模式: 如果您想要將 JSON 陣列或行剖析成個別搜尋文件，索引子支援 JSON 剖析模式。 它也支援 Markdown 剖析模式。

• 與其他功能相容性： 索引器能與其他索引器功能無縫結合，如 除錯工作階段、 用於增量豐富（預覽）的索引快取，以及 知識儲存庫。

支援的文件格式

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 索引標籤。

標準 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 最後修改的時間戳。 Azure AI 搜尋服務 會利用此時間戳記來識別已變更的 Blob 物件，避免在初始編製索引後重新為所有 Blob 物件編製索引。

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

• metadata_storage_content_md5Edm.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 容器。

將搜尋欄位新增至索引

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

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

   POST https://[service name].search.windows.net/indexes?api-version=2026-04-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）。 如果是 Blob 內容，最佳候選是中繼資料屬性。

   • metadata_storage_path （預設）是物件或檔案的完整路徑。 這個例子中的鍵欄位ID 會被填入 metadata_storage_path 的值，因為它是預設值。

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

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

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

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

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

設定和執行 Blob 索引子

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

1. 建立或更新索引子，指定其名稱並參考資料來源和目標索引：

   POST https://[service name].search.windows.net/indexers?api-version=2026-04-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 以控制大型二進制物件中哪些部分被索引：

   • contentAndMetadata 指定索引器會索引從 blob 中擷取的所有元資料和文字內容。 這是預設值。

   • storageMetadata 指定索引器僅索引 標準的 blob 屬性與使用者指定的元資料。

   • allMetadata 指定索引器從 blob 內容中擷取，並索引標準 blob 屬性及 任何找到內容類型的元資料。

   • 欲了解完整的標準元資料屬性及其欄位類型，請參見 Indexing blob metadata。

5. 在 configuration下，設定 parsingMode。 預設剖析模式是每個 Blob 有一個搜尋文件。 如果 Blob 是純文字，您可以切換至純文字剖析以提升效能。 如果您需要更細緻的剖析以將 Blob 對應至多個搜尋文件，請指定不同的模式。 一對多剖析支援包含下列項目的 Blob：

   • JSON 檔
   • CSV 檔案

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

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

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

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

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

請記得索引器只能索引單一容器的資料。 如果你需要從多個容器索引資料並整合成單一 AI 搜尋索引，請設定多個索引器，讓它們指向同一個索引。 請注意 每個 SKU 可用的索引器數量上限。

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

第一個索引子定義範例：

POST https://[service name].search.windows.net/indexers?api-version=2026-04-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-04-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-04-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 入口網站中的索引器，或使用 Get Indexer Status（REST API）查看執行細節及任何錯誤訊息。

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

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

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

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

PUT /indexers/[indexer name]?api-version=2026-04-01
{
  "parameters" : { 
    "maxFailedItems" : 10, 
    "maxFailedItemsPerBatch" : 10,
    "configuration" : { 
        "failOnUnsupportedContentType" : false, 
        "failOnUnprocessableDocument" : false,
        "indexStorageMetadataOnlyForOversizedDocuments": false
      }
    }
}

相關內容

• 變更偵測和刪除偵測
• 索引大型資料集
• 索引子存取受 Azure 網路安全性功能保護的內容