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

在本文中，您將學習如何設定一個索引器，從 Azure Blob Storage 匯入內容，並使其能在 Azure AI Search 中搜尋。索引器接收單一容器中的 blob 作為輸入。輸出是一個搜尋索引，將可搜尋的內容和中繼資料儲存在各個欄位中。

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

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

備註

Azure AI Search 可以在索引過程中導入基於角色的存取控制（RBAC）範圍，並將這些權限轉移到搜尋索引中被索引的內容。欲了解更多資訊，請參閱使用 blob 索引器或知識來源來擷取 RBAC 範圍的元資料。

先決條件

Azure Blob 儲存體，標準效能 (一般用途 v2)。
存取層包括經常性存取層、非經常性存取層、極非經常性存取層和封存層。索引子可以在經常性存取層、非經常性存取層和極非經常性存取層上擷取 Blob。
Blob 提供文字內容和中繼資料。若 Blob 包含二進位內容或非結構化文字，請考慮為映像和自然語言處理新增 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 Storage 中為該 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 元資料。如果你認為標準或自訂的元資料屬性在篩選和查詢中有用，這個功能很有幫助。

索引器會逐字擷取使用者指定的元資料屬性。要接收這些值，你必須在搜尋索引中定義一個欄位，該欄位的類型 Edm.String 與 blob 的元資料鍵同名。例如，若一個 blob 的元資料鍵值為 SensitivityHigh，請在搜尋索引中定義一個欄位 Sensitivity 。索引欄位填充值 High。

你可以將標準的 blob 元資料屬性抽取到名稱和類型相似的欄位，如下所示。 Blob 索引器會自動為這些 Blob 中繼資料屬性建立內部欄位對應，將原本以連字號 (metadata-storage-name) 命名的名稱轉換為以底線 (metadata_storage_name) 表示的對等名稱。

您仍然需要將加底線的欄位新增至索引定義，但您可以省略欄位映射，因為索引器會自動建立關聯。

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 。
metadata_storage_content_type （Edm.String）是你用來上傳 blob 的程式碼所指定的內容類型。例如： application/octet-stream 。
metadata_storage_last_modified （Edm.DateTimeOffset）是該 blob 最後修改的時間戳。 Azure AI 搜尋服務會使用此時間戳記來識別已變更的 blob，以避免在初始編製索引之後重新對所有項目編制索引。
metadata_storage_size （Edm.Int64）是 blob 的大小（以位元組為單位）。
metadata_storage_content_md5Edm.String（）是blob內容的MD5雜湊值（若有的話）。
metadata_storage_sas_token （Edm.String）是臨時的 SAS 代幣，自訂技能可以用來取得 blob 的存取權。不要將此代幣存起來以備後續使用，因為可能會過期。

最後，你可以在索引結構中表示與你所索引的 blob 文件格式相關的元資料屬性。如需內容特定中繼資料的詳細資訊，請參閱內容中繼資料屬性。

需要指出的是，你不需要在搜尋索引中為上述所有屬性定義欄位。只要擷取你申請所需的屬性即可。

目前，此索引子不支援編製 Blob 索引標籤的索引。

定義資料來源

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

建立或更新資料來源以設定其定義：

{
    "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>" }
}

將 type 設為 azureblob (必要)。
設定 credentials 為 Azure 儲存體連接字串。下一節說明支援的格式。
設置 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>/;" }`
此連接字串不需要帳戶金鑰，但您之前必須將搜尋服務設為使用受控識別連線。

儲存體帳戶共享存取簽章（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 的內容和中繼資料。

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

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

建立文件鍵欄位（"key": true）。如果是 Blob 內容，最佳候選是中繼資料屬性。
- metadata_storage_path （預設）是物件或檔案的完整路徑。這個例子中的鍵欄位ID 會被填入 metadata_storage_path 的值，因為它是預設值。
- metadata_storage_name 只有在名稱唯一時才可用。如果您要此欄位作為索引鍵，請將 "key": true 移至此欄位的定義。
- 新增至 Blob 的自訂中繼資料屬性。此選項需要 Blob 上傳程序新增該中繼資料屬性至所有 Blob。由於鍵是必修屬性，任何缺少值的斑點都無法被索引。如果您使用自訂中繼資料屬性作為索引鍵，請避免變更該屬性。索引器會在相同 blob 的 key 屬性改變時新增重複文件。
中繼資料屬性通常包含對文件索引鍵無效的字元，例如 / 和 -。然而，索引子會自動編碼索引鍵中繼資料屬性，不需要任何設定或欄位對應。
新增一個content欄位，使用 blob 的content屬性來儲存從每個檔案擷取的文字。你不必使用這個名稱，但透過使用它，你可以利用隱含的欄位映射。
新增標準中繼資料屬性的欄位。索引子可讀取自訂中繼資料屬性、標準中繼資料屬性和特定內容的中繼資料屬性。

設定和執行 Blob 索引子

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

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

POST https://[service name].search.windows.net/indexers?api-version=2025-09-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" : [ ]
}

如果預設（10 份文件）無法充分利用或超過可用資源，則會設定 batchSize 。預設批次大小是資料來源特定的。基於平均文件大小較大的考量，Blob 索引會將批次大小設為 10 個文件。
在 configuration 下，控制哪些 blob 根據檔案類型被索引，或不指定以檢索所有 blob。

針對 indexedFileNameExtensions，提供副檔名的逗號分隔清單 (包含前置點)。請對 excludedFileNameExtensions 執行相同的操作，以指示索引器應該跳過哪些擴展。如果同一個擴展名出現在兩個清單中，索引器會將其排除在索引之外。
在 configuration 下，設定 dataToExtract 以控制大型二進制物件中哪些部分被索引：
- contentAndMetadata 指定索引器會索引從 blob 中擷取的所有元資料和文字內容。這是預設值。
- storageMetadata 指定索引器僅索引標準的 blob 屬性與使用者指定的元資料。
- allMetadata 指定索引器從 blob 內容中擷取，並索引標準 blob 屬性及任何找到內容類型的元資料。
在 configuration下，設定 parsingMode。預設剖析模式是每個 Blob 有一個搜尋文件。如果 Blob 是純文字，您可以切換至純文字剖析以提升效能。如果您需要更細緻的剖析以將 Blob 對應至多個搜尋文件，請指定不同的模式。一對多剖析支援包含下列項目的 Blob：
- JSON 檔
- CSV 檔案
如果欄位名稱或類型有差異，或如果您在搜尋索引中需要來源欄位的多個版本，請指定欄位對應。

在 blob 索引中，你通常可以省略欄位映射，因為索引器內建支援將 content 和元資料屬性映射到索引中名稱和類型相似的欄位。針對中繼資料屬性，索引子會在搜尋索引中自動以底線取代連字號 -。
如需其他屬性的詳細資訊，請參閱建立索引子。如需參數描述的完整清單，請參閱 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=2025-09-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=2025-09-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=2025-09-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 次最近完成的執行。條目依時間倒序排列，因此最新執行的先行。

處理錯誤

編製索引期間常發生的錯誤包括內容類型不支援、內容遺漏或 Blob 過大。

根據預設，遇到 blob 包含不支援的內容類型 (例如音訊檔案) 時，Blob 索引子會立即停止。您可以使用 excludedFileNameExtensions 參數來略過特定內容類型。不過，您可能需要繼續編製索引 (即使發生錯誤)，並在稍後偵錯個別文件。如需索引子錯誤的詳細資訊，請參閱索引子疑難排解指導和索引子錯誤和警告。

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

PUT /indexers/[indexer name]?api-version=2025-09-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 的大小限制，請參閱服務限制。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-01-22