為 Azure 檔案儲存體中的資料編製索引 (預覽)

Note

Azure AI 搜尋服務可透過 Azure 入口網站、REST API 及 Azure SDK 取得。它同時也是 Foundry IQ 的基礎，這是一個管理式知識層，能將企業內容轉化為可重複使用、權限感知的知識庫，供 Microsoft Foundry 入口網站中的代理使用。

重要

標記（預覽）的功能、能力或屬性不受服務等級協議涵蓋，也不建議用於生產工作負載，且在正式上架前可能會有所變動或受限。 Azure AI 搜尋服務預覽條款適用於所有預覽功能，無論是獨立功能還是正式推出功能的一部分。

重要

這些功能支援與其他 Microsoft 服務及第三方服務的連結。使用這些服務須遵守其各自的條款，可能導致資料處理或儲存超出 Azure 合規邊界，以及資料流入 Azure 合規邊界。

你有責任管理資料是否會超出組織的合規與地理邊界及相關影響，並確保適當的權限、邊界與核准被提供。

你有責任仔細審查並測試你在特定使用情境中所建置的應用程式，並做出所有適當的決策與客製化。這包括實施你自己負責任的 AI 緩解措施，例如元提示、內容過濾器或其他安全系統，並確保你的應用程式符合適當的品質、可靠性、安全性與可信度標準。欲了解更多資訊，請參閱Azure AI 搜尋服務透明度說明。

Azure 檔案儲存體索引器（預覽版）會將檔案分享的內容匯入 Azure AI 搜尋服務索引。索引子的輸入是單一共用中的檔案。輸出是一個搜尋索引，包含可搜尋的內容和元資料，分別儲存在各個欄位中。

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

搜尋服務預覽 REST API，任何預覽版本。
一個 Azure SDK 套件，任何版本。
匯入資料精靈在Azure入口網站中。

先決條件

Azure 檔案儲存體，交易優化層級。
一個提供來源內容的 SMB 檔案分享。 NFS 分享不被支援。
包含文字的檔案。如果你有二進位資料，可以應用AI 增強來進行影像分析。
由 Azure 檔案儲存體索引器處理的原始碼檔案會使用類似 blob 索引器的共用原始碼大小與擷取字元限制。
Azure 儲存體上的讀取權限。「完整存取」連接字串包含授與內容存取權的金鑰。
使用 REST 用戶端來制定類似本文所示的 REST 呼叫。

支援任務

你可以用這個索引器執行以下任務：

資料索引與增量索引： 索引器可以從資料表中索引檔案及相關的元資料。它透過內建的變更偵測功能，偵測新的和更新的檔案及元資料。你可以設定排程或按需設定資料刷新。
刪除偵測：索引器能透過自訂元資料偵測刪除。
透過技能組合應用 AI：技能組合由索引者全面支援。這包括整合向量化，新增資料分塊與嵌入步驟等關鍵功能。
解析模式： 如果你想將 JSON 陣列或行解析成個別搜尋文件，索引器支援 JSON 解析模式。它也支援 Markdown 解析模式。
與其他功能相容性： 該索引器設計為能與其他索引器功能無縫結合，例如除錯工作階段、用於增量豐富的索引快取，以及知識儲存。

支援的文件格式

Azure 檔案儲存體索引器可從以下文件格式擷取文字：

CSV（參見 CSV 塊狀索引）
EML
EPUB
GZ
HTML
JSON（參見索引 JSON blobs）
KML（用於地理表現的 XML）
Markdown
Microsoft Office 格式：DOCX/DOC/DOCM、XLSX/XLSM、PPTX/PPT/PPTM、MSG（Outlook 電子郵件）、XML（2003 及 2006 WORD XML）
開放文件格式：ODT、ODS、ODP
PDF
純文字檔案（另見索引純文字）
RTF
XML
ZIP

Azure 檔案儲存體的索引方式

預設情況下，大多數檔案會作為單一搜尋文件被索引，包括結構化內容的檔案，如 JSON 或 CSV，這些檔案會作為單一文字區塊進行索引。

複合文件或嵌入文件（例如 ZIP 壓縮檔、帶有 Outlook 電子郵件且包含附件的 Word 文件，或是 .帶有附件的 MSG 檔案）也被索引為單一文件。例如，從 .MSG 檔案的附件中擷取的所有影像將會返回在 normalized_images 欄位中。如果你有圖片，可以考慮加入 AI 豐富功能，讓這些內容更有搜尋價值。

文件的文字內容會被擷取到一個名為「content」的字串欄位中。你也可以擷取標準和使用者自訂的元資料。

定義資料來源

資料來源定義指定了索引資料、憑證及識別資料變更的政策。資料來源被定義為獨立的資源，以便多個索引器都能使用。

您可以使用 2020-06-30-preview 或更新版本來設定 "type": "azurefile"。我們推薦使用最新的預覽 API。

使用預覽 API 建立資料來源以設定其定義，並將 "type": "azurefile"。

POST /datasources?api-version=2026-08-01-preview
{
    "name" : "my-file-datasource",
    "type" : "azurefile",
    "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
    "container" : { "name" : "my-file-share", "query" : "<optional-directory-name>" }
}

將「type」設為 "azurefile" （必需）。
將憑證設為 Azure 儲存連接字串。下一節將介紹所支援的格式。
將「container」設為根檔案共享，並用「query」指定任何子資料夾。

資料來源定義也可以包含軟刪除政策，例如當你希望索引器刪除搜尋文件時，當該文件被標記為刪除時。

支援的憑證與連線字串

索引器可透過以下連線連接檔案分享。

完整存取儲存體帳戶連接字串
`{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" }`
你可以在 Azure 入口網站的儲存帳戶頁面中，選擇左側窗格的存取金鑰來取得連接字串。務必選擇完整的連線字串，而非僅選擇一個金鑰。

在索引中新增搜尋欄位

在 search index 中，新增欄位以接受你的 Azure 檔案的內容和元資料。

建立或更新索引以定義可儲存檔案內容與元資料的搜尋欄位。

POST /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_path", "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": true, "filterable": true, "sortable": true }        
  ]
}

建立文件鍵欄位（「鍵」：真）。對於 blob 內容，最好的候選是元資料屬性。元資料屬性通常包含對文件鍵無效的字元，如 / 和 -。索引器會自動編碼關鍵元資料屬性，無需設定或欄位映射。
- metadata_storage_path （預設）物件或檔案的完整路徑
- metadata_storage_name 只有在名稱唯一時才可用
- 一個自訂的元資料屬性，可以加到 blobs 裡。這個選項要求你的 blob 上傳程序將 metadata 屬性加入到所有 blob 上。由於鍵是必修屬性，任何缺少值的斑點都無法被索引。如果你用自訂的元資料屬性作為鍵，請避免對該屬性做更改。索引器會在相同 blob 的 key 屬性改變時新增重複文件。
新增一個「content」欄位，透過 blob 的「content」屬性來儲存從每個檔案擷取的文字。你不一定要使用這個名稱，但使用後可以利用隱含的欄位映射。
新增標準元資料屬性欄位。在檔案索引中，標準的元資料屬性與 blob 的元資料屬性相同。 Azure 檔案儲存體索引器會自動為這些屬性建立內部欄位映射，將連字號的屬性名稱轉換為底線屬性名稱。你仍然需要用索引定義新增你想加入的欄位，但你可以省略在資料來源中建立欄位映射。
- metadata_storage_name （Edm.String） - 檔名。例如，如果你有一個檔案 /my-share/my-folder/subfolder/resume.pdf，這個欄位的值是 resume.pdf。
- metadata_storage_path （Edm.String） - 檔案的完整 URI，包括儲存帳號。例如， https://myaccount.file.core.windows.net/my-share/my-folder/subfolder/resume.pdf
- metadata_storage_content_type （Edm.String） - 依據上傳檔案所使用的程式碼所指定的內容類型。例如， application/octet-stream。
- metadata_storage_last_modified （Edm.DateTimeOffset） - 檔案最後修改的時間戳。 Azure AI 搜尋服務會使用此時間戳記來識別變更的檔案，避免在初始索引後重新索引所有檔案。
- metadata_storage_size （Edm.Int64） - 檔案大小（位元組）。
- metadata_storage_content_md5 （Edm.String） - 檔案內容的 MD5 雜湊值（如有）。
- metadata_storage_sas_token （Edm.String） - 一個臨時的 SAS 標記，可由自訂技能使用以取得檔案存取權。這個代幣不應該儲存以備後續使用，因為可能會過期。

配置並執行 Azure 檔案儲存體索引器

一旦索引和資料來源建立完成，你就可以開始建立索引器了。索引器配置指定控制執行時行為的輸入、參數與屬性。

透過命名索引器並引用資料來源與目標索引，建立或更新它：

POST /indexers?api-version=2026-04-01
{
  "name" : "my-file-indexer",
  "dataSourceName" : "my-file-datasource",
  "targetIndexName" : "my-search-index",
  "parameters": {
     "batchSize": null,
     "maxFailedItems": null,
     "maxFailedItemsPerBatch": null,
     "configuration": {
        "indexedFileNameExtensions" : ".pdf,.docx",
        "excludedFileNameExtensions" : ".png,.jpeg" 
    }
  },
  "schedule" : { },
  "fieldMappings" : [ ]
}

在可選的「配置」區塊中，提供任何包含或排除條件。若未指定，檔案共享中的所有檔案都會被檢索。

如果同時有 indexedFileNameExtensions 和 excludedFileNameExtensions 參數，Azure AI 搜尋服務先看 indexedFileNameExtensions，再看 excludedFileNameExtensions。如果兩個清單中都存在相同的副檔名，該檔案將被排除在索引之外。
如果欄位名稱或類型有差異，或搜尋索引中需要多個來源欄位版本，請指定欄位對應。

在檔案索引中，你常常可以省略欄位映射，因為索引器內建支援將「內容」和元資料屬性映射到索引中名稱和類型相似的欄位。對於中繼資料屬性，索引子會在搜尋索引中自動將連字號 - 替換為底線。
請參閱建立索引器以了解更多其他屬性的資訊。

索引器在建立時會自動執行。你可以把「停用」設為 true，來避免這種情況。要控制索引器的執行，請按需求執行索引器或將其列入排程。

檢查索引器狀態

要監控索引器狀態與執行歷史，請發送「取得索引器狀態」請求：

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 次最近完成的執行，並依逆時間順序排序，使最新的執行先行。

下一步

你現在可以執行索引器、監控狀態，或排程索引器執行。以下文章適用於從 Azure 儲存體拉取內容的索引器：

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-09-17