從Azure Data Lake Storage Gen2編制資料的索引

在本文中,瞭解如何設定索引子,以從 Azure Data Lake Storage (ADLS) Gen2 匯入內容,並在 Azure 認知搜尋 中加以搜尋。 索引子的輸入是單一容器中的 Blob。 輸出是搜尋索引,且各欄位中儲存可搜尋的內容和中繼資料。

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

如需 C# 中的程式碼範例,請參閱在 GitHub 上使用 Azure AD 為 Data Lake Gen2 編制索引

必要條件

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

  • ADLS Gen2的存取層包括經常性存取層、非經常性存取層和封存層。 搜尋索引子只能存取經常性存取和非經常性存取。

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

  • Azure 儲存體的讀取權限。 「完整存取」連接字串包含可授與內容存取權的金鑰,但如果您改用 Azure 角色,請確定 搜尋服務受控識別 具有 儲存體 Blob 資料讀取器 許可權。

  • REST 用戶端,例如 Postman,用來傳送 REST 呼叫,以建立資料來源、索引和索引子。

注意

ADLS Gen2 會實作 存取控制模型 ,其支援 Azure 角色型存取控制 (Azure RBAC) 和類似 POSIX 的存取控制清單,) blob 層級 (ACL。 Azure 認知搜尋不支援檔層級許可權。 所有使用者都具有索引中所有可搜尋和可擷取內容的相同層級存取權。 如果檔層級許可權是應用程式需求,請考慮 將安全性修剪 視為潛在的解決方案。

支援的文件格式

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

  • CSV (請參閱 索引 CSV Blob)
  • EML
  • EPUB
  • 廣州
  • 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 或其內容。

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

如果您未設定包含或排除準則,索引子會將不符合資格的 Blob 回報為錯誤並繼續進行。 如果發生足夠的錯誤,處理可能會停止。 您可以在索引子組 態設定中指定錯誤容錯。

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

編製 Blob 中繼資料的索引

Blob 中繼資料也可以編制索引,如果您認為任何標準或自訂中繼資料屬性在篩選和查詢中很有用,這會很有説明。

使用者指定的中繼資料屬性會逐字擷取。 若要接收值,您必須在 類型的 Edm.String 搜尋索引中定義欄位,其名稱與 Blob 的中繼資料索引鍵相同。 例如,如果 Blob 具有具有值的 High 中繼資料索引鍵 Sensitivity ,則您應該在搜尋索引中定義名為 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 認知搜尋使用此時間戳記來識別已變更的 Blob,以避免在初始編制索引之後重新編制所有索引。

  • metadata_storage_size (Edm.Int64) - 以位元組為單位的 Blob 大小。

  • metadata_storage_content_md5 (Edm.String) - 如果有的話,Blob 內容的 MD5 雜湊。

  • metadata_storage_sas_token (Edm.String) - 自訂 技能 可用來存取 Blob 的暫存 SAS 權杖。 此權杖不應儲存以供稍後使用,因為它可能會過期。

最後,您編制索引之 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>/;" }
此連接字串不需要帳戶金鑰,但您先前必須已設定搜尋服務,才能 使用受控識別進行連線
儲存體帳戶共用存取簽章** (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 的內容和中繼資料。

  1. 建立或更新索引 ,以定義將儲存 Blob 內容和中繼資料的搜尋欄位:

    POST https://[service name].search.windows.net/indexes?api-version=2020-06-30
    {
        "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 (預設) 物件或檔案的完整路徑。 此範例中的索引鍵欄位 (「識別碼」,) 會填入來自metadata_storage_path的值,因為它是預設值。

    • metadata_storage_name只有在名稱是唯一的時,才能使用。 如果您想要此欄位作為索引鍵,請移至 "key": true 此欄位定義。

    • 您新增至 Blob 的自訂中繼資料屬性。 此選項需要您的 Blob 上傳程式將該中繼資料屬性新增至所有 Blob。 因為索引鍵是必要屬性,所以遺漏值的任何 Blob 將無法編制索引。 如果您使用自訂中繼資料屬性作為索引鍵,請避免對該屬性進行變更。 索引子會在索引鍵屬性變更時,為相同的 Blob 新增重複的檔。

    中繼資料屬性通常包含對於檔索引鍵不正確字元,例如 /- 。 由於索引子) 預設為 「base64EncodeKeys」 屬性 (true,因此會自動編碼中繼資料屬性,而不需要任何組態或欄位對應。

  3. 新增 「內容」欄位,以透過 Blob 的 「內容」屬性,儲存每個檔案中擷取的文字。 您不需要使用此名稱,但這麼做可讓您利用隱含欄位對應。

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

設定和執行 ADLS Gen2 索引子

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

  1. 建立或更新索引子,指定其名稱並參考資料來源和目標索引:

    POST https://[service name].search.windows.net/indexers?api-version=2020-06-30
    {
      "name" : "my-adlsgen2-indexer,
      "dataSourceName" : "my-adlsgen2-datasource",
      "targetIndexName" : "my-search-index",
      "parameters": {
          "batchSize": null,
          "maxFailedItems": null,
          "maxFailedItemsPerBatch": null,
          "base64EncodeKeys": 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. 在 [組態] 底下,如果 Blob 應該對應至 多個搜尋檔,或是由 純文字JSON 檔CSV 檔案所組成,請設定 「parsingMode」。

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

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

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

索引子建立後會自動執行。 將 "disabled" 設定為 true 就不會這樣。 若要控制索引子執行,請視需要執行索引子放入排程中

檢查索引子狀態

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

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2020-06-30
  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=2020-06-30
{
  "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 大小的限制,請參閱 服務限制

下一步

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