將 Azure 檔案儲存體中的資料編製索引

文章
10/16/2024

重要

Azure 檔案儲存體索引子目前處於公開預覽狀態，遵守增補使用條款。使用預覽 REST API 來建立索引子資料來源。

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

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

必要條件

Azure 檔案儲存體交易最佳化階層。
提供來源內容的 SMB 檔案共用。不支援 NFS 共用。
包含文字的檔案。如果您有二進位資料，您可以加上 AI 擴充以分析影像。
Azure 儲存體的讀取權限。「完整存取」連接字串包含金鑰，其可授與內容的存取權。
使用 REST 用戶端編寫接近於本文示範的 REST 呼叫。

支援的文件格式

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

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

如何編製 Azure 檔案儲存體的索引

根據預設，大部分的檔案會編製索引，作為索引中的單一搜尋文件，包括具有結構化內容的檔案，例如 JSON 或 CSV，這類檔案會編製索引為單一文字區塊。

複合或內嵌文件，例如 ZIP 封存、具有內嵌 Outlook 電子郵件的 Word 文件 (內含附件)，或者內含附件的 .MSG 檔案，也會編制索引為單一文件。例如，從 .MSG 檔案附件擷取的所有影像，都會傳回 normalized_images 欄位。如果您有影像，請考慮新增 AI 擴充，以從該內容取得更多搜尋公用程式。

文件的文字內容會擷取至名為 "content" 的字串欄位。您也可以擷取標準和使用者定義的中繼資料。

定義資料來源

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

您可以使用 2020-06-30-預覽版或更新版本的「類型」: "azurefile"。我們建議使用最新的預覽版 API。

使用預覽 API 的「type」建立資料來源以設定其定義："azurefile"。

POST /datasources?api-version=2024-05-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" (必要)。
將 "credentials" 設定為 Azure 儲存體連接字串。下一節說明支援的格式。
將 "container" 設定為根檔案共用，並使用 "query" 來指定子資料夾。

如果您希望索引子在原始文件標幟為待刪除時刪除搜尋文件，資料來源定義也可以包含虛刪除原則。

支援的認證和連接字串

索引子可以使用下列連線來連線到檔案共用。

完整存取儲存體帳戶連接字串
`{ "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>;" }`
您可以在 Azure 入口網站中，從 [儲存體帳戶] 頁面的左側瀏覽窗格，選取 [存取金鑰] 取得連接字串。請務必選取完整的連接字串，而不只是金鑰。

新增搜尋欄位至索引

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

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

POST /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_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 }        
  ]
}

建立文件索引鍵欄位 ("key": true)。針對 Blob 內容，最佳候選項目是中繼資料屬性。中繼資料屬性通常包含對文件索引鍵無效的字元，例如 / 和 -。索引子會自動編碼索引鍵中繼資料屬性，不需要任何設定或欄位對應。
- metadata_storage_path (預設) 物件或檔案的完整路徑
- metadata_storage_name，僅當名稱為唯一時才能使用
- 新增至 Blob 的自訂中繼資料屬性。此選項需要 Blob 上傳程序新增該中繼資料屬性至所有 Blob。鑑於索引鍵是必要屬性，遺漏值的任何 Blob 即無法編製索引。如果您使用自訂中繼資料屬性作為索引鍵，請避免變更該屬性。索引子會在索引鍵屬性變更時，新增相同 Blob 的重複文件。
新增 "content" 欄位，以透過 Blob 的 "content" 屬性來儲存每個檔案中擷取的文字。您不必使用此名稱，但這麼做即可利用隱含欄位對應。
新增標準中繼資料屬性的欄位。在編製檔案索引時，標準中繼資料屬性與 Blob 中繼資料屬性相同。 Azure 檔案儲存體索引子會自動針對這些屬性建立內部欄位對應，以將連字號屬性名稱轉換成底線屬性名稱。您仍然需要新增想要使用索引定義的欄位，但可以省略在資料來源中建立欄位對應。
- metadata_storage_name (Edm.String) - 檔案名稱。例如，如果您有檔案 /my-container/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=2024-07-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。如果兩份清單中有相同的副檔名，就會排除在索引編製外。
如果欄位名稱或類型有差異，或如果您在搜尋索引中需要來源欄位的多個版本，請指定欄位對應。

在編製檔案索引時，您通常可以省略欄位對應，因為索引子具備內建支援，可將 "content" 和中繼資料屬性對應至索引中具有類似名稱和類型的欄位。針對中繼資料屬性，索引子會在搜尋索引中自動將連字號 - 取代為底線。
如需其他屬性的詳細資訊，請參閱建立索引子。

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

檢查索引子狀態

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

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 個最近完成的執行，以顛倒的時序排序，因此最後的執行最先出現。

下一步

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

分享方式：