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

發行項
11/19/2024

在本文中，了解如何設定索引子，以從 Azure Blob 儲存體匯入內容，並將內容變成可在 Azure AI 搜尋服務中搜尋。索引子的輸入是單一容器中的 Blob。輸出是搜尋索引，且各欄位中儲存可搜尋的內容和中繼資料。

若要設定和執行索引器，您可以使用：

Search Service REST API，任何版本。
Azure SDK 套件，任何版本。
在 Azure 入口網站匯入數據精靈。
在 Azure 入口網站中匯入和向量化數據精靈。

本文使用 REST API 來說明每個步驟。

必要條件

Azure Blob 儲存體，標準效能 (一般用途 v2)。
存取層包括經常性存取層、非經常性存取層、極非經常性存取層和封存層。索引子可以在經常性存取層、非經常性存取層和極非經常性存取層上擷取 Blob。
Blob 提供文字內容和中繼資料。若 Blob 包含二進位內容或非結構化文字，請考慮為映像和自然語言處理新增 AI 擴充。 Blob 內容不能超過搜尋服務層級的索引子限制。
支援的網路設定和資料存取。您至少需要 Azure 儲存體的讀取權限。包含存取金鑰的儲存體連接字串可提供儲存體內容的讀取存取。如果您改用 Microsoft Entra 登入和角色，請確保搜尋服務的受控識別具有儲存體 Blob 資料讀取者權限。

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

支援的工作

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

數據索引編製和累加式索引編製： 索引器可以從 Blob 容器和資料夾為檔案和相關聯的元數據編製索引。它會透過內建變更偵測來偵測新的和更新的檔案與中繼資料。您可以依排程或視需要設定資料重新整理。
刪除偵測： 索引器可以透過原生虛刪除或自定義元數據偵測刪除。
透過技能集套用 AI：索引器完全支援技能集。這包括重要功能，例如，可新增資料區塊化和內嵌步驟的整合向量化。
剖析模式: 如果您想要將 JSON 陣列或行剖析成個別搜尋文件，索引子支援 JSON 剖析模式。它也支援 Markdown 剖析模式。
與其他功能的相容性： 索引器的設計目的是與其他索引器功能順暢地運作，例如偵錯會話、累加擴充的索引器快取，以及知識存放區。

支援的文件格式

Blob 索引器可以從下列文件格式中擷取文字：

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

決定要編製索引的 Blob

設定索引前，請檢閱來源資料並判斷事先是否要進行任何變更。索引子一次可編製一個容器的內容索引。預設處理容器中所有的 Blob。提供您數個更具選擇性的處理選項：

在虛擬資料夾中放置 Blob。索引子資料來源定義包含可採用虛擬資料夾的「查詢」參數。若您指定虛擬資料夾，只有資料夾中的 Blob 會編製索引。
依檔案類型包含或排除 Blob。支援的文件格式清單可協助您判斷要排除的 Blob。例如，您可能要排除不提供可搜尋文字的影像或音訊檔案。此功能是透過索引子中的設定控制。

包含或排除任意 Blob。如果您基於任何原因要跳過特定 Blob，請新增下列中繼資料屬性和值至 Blob 儲存體中的 Blob。遇到此屬性時，索引子會跳過索引執行中的 Blob 或 Blob 內容。

屬性名稱	屬性值	說明
"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 有 Sensitivity 的中繼索引鍵且值為 High，請在搜尋索引中定義名為 Sensitivity 的欄位，系統會自動填入值 High。

標準 Blob 中繼資料屬性可擷取至相似的具名和具類型的欄位，如下所示。 Blob 索引子會自動針對這些 Blob 中繼資料屬性，建立內部欄位對應，並轉換原始連字號名稱 (「metadata-storage-name」) 為底線對等名稱 (「metadata_storage_name」)。

您仍必須新增底線欄位至索引定義，但可省略欄位對應，因為索引子會自動建立關聯。

metadata_storage_name (Edm.String) - Blob 的檔案名稱。例如，如果您有 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_md5 (Edm.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 認證，您必須使用更新的簽章定期更新資料來源認證以防止其到期。如果 SAS 認證過期，索引子會失敗並出現錯誤訊息，如「連接字串提供的認證無效或過期」。

新增搜尋欄位至索引

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

建立或更新索引，並定義搜尋欄位儲存 Blob 內容和中繼資料：

POST https://[service name].search.windows.net/indexes?api-version=2024-07-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 (預設) 物件或檔案的完整路徑。索引鍵欄位 (此範例為「識別碼」) 會填入 metadata_storage_path 的值，因為是預設值。
- metadata_storage_name，只有名稱是唯一名稱時，才能使用。如果您要此欄位作為索引鍵，請將 "key": true 移至此欄位的定義。
- 新增至 Blob 的自訂中繼資料屬性。此選項需要 Blob 上傳程序新增該中繼資料屬性至所有 Blob。鑑於索引鍵是必要屬性，遺漏值的任何 Blob 即無法編製索引。如果您使用自訂中繼資料屬性作為索引鍵，請避免變更該屬性。如果索引鍵屬性變更，索引子會針對相同的 Blob 新增重複文件。
中繼資料屬性通常包含對文件索引鍵無效的字元，例如 / 和 -。然而，索引子會自動編碼索引鍵中繼資料屬性，不需要任何設定或欄位對應。
透過 Blob 的「內容」屬性，新增「內容」欄位儲存從每個檔案擷取的文字。您不必使用此名稱，但這麼做即可利用隱含欄位對應。
新增標準中繼資料屬性的欄位。索引子可讀取自訂中繼資料屬性、標準中繼資料屬性和內容特定的中繼資料屬性。

設定和執行 Blob 索引子

建立索引與資料來源之後，您就可以開始建立索引子。索引子會設定指定輸入、參數和屬性，控制執行階段行為。您也可指定要編製索引的 Blob 部分。

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

POST https://[service name].search.windows.net/indexers?api-version=2024-07-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 個文件。
在「設定」下，根據檔案類型控制要編製索引的 Blob，或不指定檔案類型，然後擷取所有 Blob。

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

在 Blob 索引中，您通常可以省略欄位對應，因為索引子使用內建支援對應「內容」和中繼資料屬性，與索引中類似的具名和具類型欄位。針對中繼資料屬性，索引子會在搜尋索引中自動以底線取代連字號 -。
如需其他屬性的詳細資訊，請參閱建立索引子。如需參數描述的完整清單，請參閱 REST API。

索引子建立後會自動執行。您可以將「停用」設為 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=2024-07-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=2024-07-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=2024-07-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=2024-07-01
{
  "parameters" : { 
    "maxFailedItems" : 10, 
    "maxFailedItemsPerBatch" : 10,
    "configuration" : { 
        "failOnUnsupportedContentType" : false, 
        "failOnUnprocessableDocument" : false,
        "indexStorageMetadataOnlyForOversizedDocuments": false
      }
    }
}

參數	有效值	描述
「maxFailedItems」	-1、null 或 0、正整數	如果處理期間 (剖析 Blob 或新增文件至索引時) 發生任何錯誤，仍要繼續編製索引，請將這些屬性設為可接受失敗的次數。無論錯誤發生的次數，`-1` 的值允許繼續編製索引。否則，此值為正整數。
「maxFailedItemsPerBatch」	-1、null 或 0、正整數	同上，但用於批次編製索引。
「failOnUnsupportedContentType」	[True] 或 [False]	如果索引子無法判斷內容類型，請指定是否繼續或放棄作業。
「failOnUnprocessableDocument」	[True] 或 [False]	如果索引子無法處理其他支援內容類型的文件，請指定是否繼續或放棄作業。
「indexStorageMetadataOnlyForOversizedDocuments」	[True] 或 [False]	預設會將過大的 Blob 視為錯誤。如果您將此參數設定為 true，則即使無法編製內容索引，索引子仍會嘗試編製其中繼資料索引。有關 Blob 的大小限制，請參閱服務限制。

共用方式為