從 Azure Data Lake Storage Gen2 編製資料索引

備註

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

Azure Data Lake Storage Gen2 索引器會將內容從 Azure Data Lake Storage Gen2(ADLS Gen2)匯入到 Foundry IQ(Azure AI 搜尋服務)索引中。 索引子的輸入是單一容器中的 Blob。 輸出是搜尋索引,且各欄位中儲存可搜尋的內容和中繼資料。

本文提供從 ADLS Gen2 編制索引的特定資訊,以補充建立索引子。 其中使用 REST API 來示範所有索引子通用的三部分工作流程:建立資料來源、建立索引、建立索引子。 提交建立索引子要求時會擷取資料。

如需 C# 中的程式碼範例,請參閱 在 GitHub 上 使用 Microsoft Entra ID 編製 資料湖 Gen2 索引 。

備註

支援 ADLS Gen2 的 ACL 與容器 RBAC 範圍匯入和查詢篩選功能已在 REST API 2026-10-01 中正式推出。 權限擷取需要來源路徑的中繼資料,即使是僅使用 RBAC 的設定也需要。 關於設定、區塊投影以及預設啟用的 ACL 重新整理,請參閱「導入 ADLS Gen2 權限元資料」。

先決條件

  • ADLS Gen2 已啟用 階層命名空間。 ADLS Gen2 可透過 Azure 儲存體取得。 設定儲存體帳戶時,您可以選擇啟用 階層式命名空間、將檔案組織成目錄和巢狀子目錄的階層。 藉由啟用階層式命名空間,您可以啟用 ADLS Gen2。

  • ADLS Gen2 的存取層級包括熱、冷及歸檔。 搜尋引擎索引器只能存取熱資料和冷資料。

  • 包含文字的 Blob。 如果您有二進位資料,您可以加上 AI 擴充以分析影像。 Blob 內容不得超過您 Foundry IQ 服務層級的 索引器限制 。

    將來源索引與 AI 豐富化視為獨立的處理階段。 技能或外部服務的輸入限制可能低於索引器能擷取的內容量。 查看 你技能組中每個技能的參考文章 。

  • Azure 儲存體的讀取權限。 「完全存取」連接字串 包含一個授予內容存取權的金鑰,但如果您改用 Azure 角色,請確保 Foundry IQ 服務的管理身份具有 Storage Blob Data Reader 權限。

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

局限性

  • 不同於 Blob 索引子,ADLS Gen2 索引子無法使用容器層級 SAS 權杖來列舉儲存體帳戶中的內容並編製索引。 此限制存在於索引器透過呼叫 檔案系統 - 取得屬性 API 來檢查儲存帳號是否啟用階層命名空間。 對於沒有啟用階層命名空間的儲存帳號,建議改用 blob 索引器 ,以確保 blob 的列舉效能。

  • 如果屬性 metadata_storage_path 對應為索引鍵欄位,則不保證 Blob 會在目錄重新命名時重新編製索引。 如果您想要重新編製屬於已重新命名目錄的 Blob 索引,請更新其全部的 LastModified 時間戳記。

支援的文件格式

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

  • 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。 索引子資料來源定義包含可採用虛擬資料夾的「查詢」參數。 若您指定虛擬資料夾,只有資料夾中的 Blob 會編製索引。

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

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

    屬性名稱 屬性值 Explanation
    "AzureSearch_Skip" "true" 指示 blob 索引子以完全略過 blob。 不會嘗試擷取中繼資料或內容。 當特定 blob 一直失敗,並且中斷編製索引程序時,這非常有用。
    "AzureSearch_SkipContent" "true" 跳過內容並僅擷取中繼資料。 此設定相當於 "dataToExtract" : "allMetadata"中所述的 設定,但其適用於特定 Blob。

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

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

編製 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 的最後修改時間戳。 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 文件格式特定的任何中繼資料屬性,也可以索引結構描述呈現。 如需內容特定中繼資料的詳細資訊,請參閱內容中繼資料屬性。

請務必指出您的搜尋索引不必定義上述所有屬性的欄位,只要擷取應用程式所需的屬性。

定義資料來源

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

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

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

  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) 應該擁有列出和讀取權限。

備註

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

將搜尋欄位新增至索引

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

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

    {
        "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. 透過 Blob 的「內容」屬性,新增「內容」欄位儲存從每個檔案擷取的文字。 您不必使用此名稱,但這麼做即可利用隱含欄位對應。

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

設定並執行 ADLS Gen2 索引子

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

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

    {
      "name" : "my-adlsgen2-indexer",
      "dataSourceName" : "my-adlsgen2-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. 在「設定」下,根據檔案類型控制要編製索引的 Blob,或不指定檔案類型,然後擷取所有 Blob。

    針對 "indexedFileNameExtensions",提供副檔名的逗號分隔清單 (包含前置點)。 針對 "excludedFileNameExtensions" 執行相同動作,並指出要跳過的副檔名。 如果同一個擴充名同時出現在兩個清單中,則不會被納入索引。

  4. 在「設定」下,設定「dataToExtract」控制要編製索引的 Blob 部分:

  5. 啟用文件層級權限匯入時,在 configuration 下,將 parsingMode 保持設為 default。 專用的解析模式不支援權限。 有關支援的內容理解式擷取和分塊需求,請參閱 「權限擷取適用的支援剖析與內容擷取」。

    未使用權限擷取時,請設定 parsingMode,以指定 blob 是否應對應到 多個搜尋文件,或是否由 純文字、JSON 文件或 CSV 檔案組成。

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

    在 Blob 索引中,您通常可以省略欄位對應,因為索引子使用內建支援對應「內容」和中繼資料屬性,與索引中類似的具名和具類型欄位。 對於中繼資料屬性,索引子會自動將連字號- 替換為搜尋索引中的底線。

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

索引器建立後會自動執行。 您可以將「停用」設為 true 避免此情況。 若要控制索引子執行,請按需執行索引子或安排排程執行。

檢查索引子狀態

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

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":"2024-02-21T00:23:24.957Z",
            "endTime":"2024-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2024-02-21T00:23:24.957Z",
                "endTime":"2024-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=2026-10-01
{
  "parameters" : { 
    "maxFailedItems" : 10, 
    "maxFailedItemsPerBatch" : 10,
    "configuration" : { 
        "failOnUnsupportedContentType" : false, 
        "failOnUnprocessableDocument" : false,
        "indexStorageMetadataOnlyForOversizedDocuments": false
    }
  }
}
參數 有效值 Description
"maxFailedItems" -1、null 或 0、正整數 如果處理期間 (剖析 Blob 或新增文件至索引時) 發生任何錯誤,仍要繼續編製索引, 請將這些屬性設為可接受失敗的次數。 無論錯誤發生的次數,-1 的值允許繼續編製索引。 否則,此值為正整數。
"maxFailedItemsPerBatch" -1、null 或 0、正整數 同上,但用於批次編製索引。
"failOnUnsupportedContentType" 真或假 如果索引子無法判斷內容類型,請指定是否繼續或放棄作業。
"failOnUnprocessableDocument" 真或假 如果索引子無法處理其他支援內容類型的文件,請指定是否繼續或放棄作業。
"indexStorageMetadataOnlyForOversizedDocuments" 真或假 預設會將過大的 Blob 視為錯誤。 如果你把這個參數設為 true,索引器會嘗試索引其元資料,即使內容無法被索引。 如需 Blob 的大小限制,請參閱服務限制。

後續步驟

您目前已可執行索引子、監視狀態或排程執行索引子。 下列文章適用於從 Azure 儲存體提取內容的索引子: