使用 LightIngest 將資料內嵌至 Azure Data Explorer

  • 發行項

LightIngest 是一個命令行公用程式，可用於將臨機操作數據擷取至 Azure Data Explorer。 公用程式可以從本機資料夾、Azure Blob 記憶體容器或 Amazon S3 貯體提取源數據。

當您想要擷取大量數據時，LightIngest 最有用，因為擷取持續時間沒有時間限制。 當您想要根據建立記錄的時間來查詢記錄，而不是擷取記錄的時間時，也很有用。

如需如何自動產生 LightIngest 命令的範例，請參閱 內嵌歷程記錄數據。

注意

擷取最多可支援 6GB 的檔案大小。 建議內嵌 100 MB 和 1 GB 之間的檔案。

必要條件

執行 LightIngest

若要執行 LightIngest：

  1. 在命令提示字元中，輸入 LightIngest ，後面接著相關的命令行自變數。

    提示

    如您支援的指令列自變數清單， 請輸入 LightIngest /help。

  2. 輸入 ingest- ，後面接著將管理擷取的 Azure Data Explorer 叢集 連接字串。 以雙引弧括住 連接字串，並遵循 Kusto 連接字串規格。

    例如：

    LightIngest "https://ingest-{Cluster name and region}.kusto.windows.net;Fed=True" -db:{Database} -table:Trips -source:"https://{Account}.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}" -pattern:"*.csv.gz" -format:csv -limit:2 -ignoreFirst:true -cr:10.0 -dontWait:true

效能建議

  • 若要最好管理擷取負載並從暫時性錯誤中復原，請使用 位於 https://ingest-{yourClusterNameAndRegion}.kusto.windows.net的擷取端點。

  • 為了獲得最佳擷取效能，需要原始數據大小，因此 LightIngest 可以估計本機檔案未壓縮的大小。 不過，LightIngest 可能無法正確估計壓縮 Blob 的原始大小，而不需要先下載它們。 因此，在擷取壓縮的 Blob 時，將 rawSizeBytes Blob 元數據上的 屬性設定為位元組的未壓縮數據大小。

命令列引數

引數 類型 Description 必要
string Kusto 連接字串 指定處理擷取的 Kusto 端點。 此值應該以雙引弧括住。 ✔️
-database， -db string 目標 Azure Data Explorer 資料庫名稱。
-表 string 目標 Azure Data Explorer 資料表名稱。 ✔️
-sourcePath、-source string 源數據的位置，可以是本機檔案路徑、Azure Blob 容器的根 URI 或 Amazon S3 貯體 URI。 如果數據儲存在 Azure Blob 中，URI 必須包含記憶體帳戶密鑰或共用存取簽章 (SAS) 。 如果數據位於 S3 貯體中，URI 必須包含認證密鑰。 建議以雙引弧括住此值。 如需詳細資訊，請參閱 記憶體連接字串。 傳遞 -sourcePath：;模擬 以列出具有用戶權力的 Azure 記憶體專案， (使用者提示授權) 。 ✔️
-managedIdentity， -mi string 用於連線之受控識別的用戶端標識碼 (使用者指派或系統指派) 。 針對系統指派的身分識別使用 「system」。
-ingestWithManagedIdentity， -imgestmi string 用於連線之受控識別的用戶端標識碼 (使用者指派或系統指派) 。 針對系統指派的身分識別使用 「system」。
-connectToStorageWithUserAuth、-storageUserAuth string 使用使用者認證向數據源記憶體服務進行驗證。 這個值的選項為 PROMPT 或 DEVICE_CODE。
-connectToStorageLoginUri、 -storageLoginUri string 如果-connectToStorageWithUserAuth已設定，您可以選擇性地提供 Microsoft Entra ID 登入 URI。
-前置綴 string 當要擷取的源數據位於 Blob 記憶體上時，此 URL 前置詞會由所有 Blob 共用，但不包括容器名稱。
例如，如果數據位於 MyContainer/Dir1/Dir2中，則前置詞應該是 Dir1/Dir2。 建議以雙引弧括住此值。
-模式 string 選取來源檔案/Blob 的模式。 支援通配符。 例如： "*.csv" 。 建議以雙引弧括住此值。
-zipPattern string 選取要內嵌之 ZIP 封存中的檔案時要使用的正則表達式。 封存中的所有其他檔案都會被忽略。 例如： "*.csv" 。 建議以雙引弧括住此值。
-format， -f string 源數據格式。 必須是其中一種 支援的格式
-ingestionMappingPath， -mappingPath string 用於擷取數據行對應的本機檔案路徑。 請參閱資料對應。
-ingestionMappingRef， -mappingRef string 先前在數據表上建立的擷取數據行對應名稱。 請參閱資料對應。
-creationTimePattern string 設定時，會用來從檔案或 Blob 路徑擷取 CreationTime 屬性。 請參閱 如何使用 擷取數據 CreationTime。
-ignoreFirstRow、 -ignoreFirst bool 如果設定，則會忽略每個檔案/Blob 的第一筆記錄。 例如，如果源數據有標頭。
-標記 string 要與擷取數據產生關聯的標記。 允許多次出現
-dontWait bool 如果設定為 true，則不會等候擷取完成。 擷取大量檔案/Blob 時很有用。
-compression， -cr double 壓縮比例提示。 擷取壓縮檔/Blob 以協助 Azure Data Explorer 評估原始數據大小時很有用。 計算為原始大小除以壓縮大小。
-limit， -l 整數 如果設定，則會將擷取限製為前 N 個 檔案。
-listOnly、-list bool 如果設定，則只會顯示已選取要擷取的專案。
-ingestTimeout 整數 所有內嵌作業完成的分鐘數逾時。 預設值為 60。
-forceSync bool 如果設定，則會強制同步擷取。 預設值為 false。
-互動 bool 如果設定為 false，則不會提示確認自變數。 針對自動流程和非互動式環境。 預設為 true。
-dataBatchSize 整數 設定每個擷取作業 (MB、未壓縮) 的總大小限制。
-filesInBatch 整數 設定每個擷取作業的檔案/Blob 計數限制。
-devTracing， -trace string 如果設定，診斷記錄預設 RollingLogs 會寫入本機目錄， (在目前目錄中，也可以藉由設定參數值) 來修改。

Azure Blob 特定功能

搭配 Azure Blob 使用時，LightIngest 會使用特定 Blob 元數據屬性來增強擷取程式。

元數據屬性 使用方式
rawSizeBytes, kustoUncompressedSizeBytes 如果設定，則會解譯為未壓縮的數據大小
kustoCreationTime, kustoCreationTimeUtc 解譯為UTC時間戳。 如果設定，則會用來覆寫 Kusto 中的建立時間。 適用於回填案例

使用範例

下列範例假設您已為操作系統安裝 LightIngest 二進位檔。 如果您已將 LightIngest 安裝為 .NET 工具，請在範例中以 取代 LightIngestLightIngest 。

使用 CreationTime 屬性擷取歷程記錄數據

當您將歷程記錄數據從現有系統載入 Azure Data Explorer 時，所有記錄都會收到相同的擷取日期。 若要藉由建立時間而非擷取時間來啟用數據分割，您可以使用 -creationTimePattern 自變數。 自 -creationTimePattern 變數會 CreationTime 從檔案或 Blob 路徑擷取 屬性。 模式不需要反映整個項目路徑，只要包含您要使用的時間戳的區段即可。

自變數值必須包含：

  • 時間戳格式前面的常數文字，以單引弧括住， (前置詞)
  • 標準 .NET DateTime 表示法的時間戳格式
  • 緊接在時間戳後置詞 (後置詞) 的常數文字。

重要

指定應該覆寫建立時間時，請確定 Lookback 目標數據表的有效 Extents 合併原則 中的 屬性會與檔案或 Blob 路徑中的值一致。

範例

  • 包含日期時間的 Blob 名稱，如下所示： historicalvalues19840101.parquet (時間戳是年份的四位數、月份的兩位數，以及月份日期的兩位數) ，

    自變數的值 -creationTimePattern 是檔名的一部分： “'historicalvalues'yyyyMMmdd'.parquet'”

    LightIngest "https://ingest-{Cluster name and region}.kusto.windows.net;Fed=True" -db:{Database} -table:Trips -source:"https://{Account}.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}" -creationTimePattern:"'historicalvalues'yyyyMMdd'.parquet'"
 -pattern:"*.parquet" -format:parquet -limit:2 -cr:10.0 -dontWait:true

  • 針對參考階層式資料夾結構的 Blob URI， 例如 https://storageaccount/mycontainer/myfolder/2002/12/01/blobname.extension。

    自變數的值 -creationTimePattern 是資料夾結構的一部分： “'folder/'yyyy/MM/dd'/blob'”

      LightIngest "https://ingest-{Cluster name and region}.kusto.windows.net;Fed=True" -db:{Database} -table:Trips -source:"https://{Account}.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}" -creationTimePattern:"'mycontainer/myfolder/'yyyy/MM/dd'/'"
   -pattern:"*.csv.gz" -format:csv -limit:2 -ignoreFirst:true -cr:10.0 -dontWait:true

使用記憶體帳戶金鑰或 SAS 令牌擷取 Blob

  • 在指定的記憶體帳戶 ACCOUNT底下內嵌 10 個 Blob，在資料夾 DIR、容器 CONT底下，以及比對模式 *.csv.gz
  • 目的地是資料庫 DB、數據表 TABLE和擷取對應 MAPPING ，會在目的地上預先建立
  • 此工具會等到擷取作業完成為止
  • 請注意指定目標資料庫和記憶體帳戶金鑰與 SAS 令牌的不同選項
LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"https://ACCOUNT.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}"
  -prefix:"DIR"
  -pattern:*.csv.gz
  -format:csv
  -mappingRef:MAPPING
  -limit:10

LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True;Initial Catalog=DB"
  -table:TABLE
  -source:"https://ACCOUNT.blob.core.windows.net/{ROOT_CONTAINER}?{SAS token}"
  -prefix:"DIR"
  -pattern:*.csv.gz
  -format:csv
  -mappingRef:MAPPING
  -limit:10

擷取容器中的所有 Blob，不包含標頭數據列

  • 擷取指定記憶體帳戶 ACCOUNT底下的所有 Blob、資料夾 DIR1/DIR2、容器 CONT底下，以及比對模式 *.csv.gz
  • 目的地是資料庫 DB、數據表 TABLE和擷取對應 MAPPING ，會在目的地上預先建立
  • 來源 Blob 包含標頭行，因此會指示工具卸除每個 Blob 的第一筆記錄
  • 此工具會張貼數據以進行擷取，且不會等待擷取作業完成
LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"https://ACCOUNT.blob.core.windows.net/{ROOT_CONTAINER}?{SAS token}"
  -prefix:"DIR1/DIR2"
  -pattern:*.csv.gz
  -format:csv
  -mappingRef:MAPPING
  -ignoreFirstRow:true

從路徑擷取所有 JSON 檔案

  • 擷取路徑 PATH下的所有檔案，符合模式 *.json
  • 目的地是資料庫 DB、數據表 TABLE和擷取對應定義在本機檔案中 MAPPING_FILE_PATH
  • 此工具會張貼數據以進行擷取，且不會等待擷取作業完成
LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"PATH"
  -pattern:*.json
  -format:json
  -mappingPath:"MAPPING_FILE_PATH"

擷取檔案和寫入診斷追蹤檔案

  • 擷取路徑 PATH下的所有檔案，符合模式 *.json
  • 目的地是資料庫 DB、數據表 TABLE和擷取對應定義在本機檔案中 MAPPING_FILE_PATH
  • 此工具會張貼數據以進行擷取，且不會等待擷取作業完成
  • 診斷追蹤檔案會寫入本機資料夾下 LOGS_PATH
LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"PATH"
  -pattern:*.json
  -format:json
  -mappingPath:"MAPPING_FILE_PATH"
  -trace:"LOGS_PATH"