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

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

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

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

注意

擷取最多可支援 6GB 的檔案大小。建議擷取介於 100 MB 到 1 GB 之間的檔案。

必要條件

LightIngest。透過以下兩種方式之一取得 LightIngest：
- 下載您操作系統的 LightIngest 二進位檔。下載之後，請務必將二進位檔解壓縮。
- 將 LightIngest 安裝為 .NET 工具。此方法會要求您在計算機上安裝 .NET SDK 6.0 版或更高版本。然後，執行下列命令：
```
dotnet tool install -g Microsoft.Azure.Kusto.LightIngest
```

注意

考慮使用排隊式擷取命令，因為它們不需安裝軟體。

執行 LightIngest

若要執行 LightIngest：

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

提示

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

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

例如：

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 時，將 Blob 元數據上的屬性設定 rawSizeBytes 為位元組未壓縮的數據大小。

命令列引數

Argument	類型	描述	必要
	`string`	Kusto 連接字串指定處理擷取的 Kusto 端點。將此值括在雙引號中。	✔️
-database、 -db	`string`	目標 Azure 資料總管資料庫名稱。
-桌子	`string`	目標 Azure 資料總管數據表名稱。	✔️
-sourcePath、-source	`string`	源數據的位置，可以是本機檔案路徑、Azure Blob 容器的根 URI 或 Amazon S3 貯體 URI。如果數據儲存在 Azure Blob 中，URI 必須包含記憶體帳戶密鑰或共用存取簽章（SAS）。如果數據位於 S3 貯體中，URI 必須包含認證密鑰。將此值括在雙引號中。如需詳細資訊，請參閱記憶體連接字串。傳遞 -sourcePath：; 模擬列出具有用戶許可權的 Azure 記憶體專案（使用者提示授權）。	✔️
-managedIdentity， -mi	`string`	用於連線之受控識別的用戶端標識碼（使用者指派或系統指派）。針對系統指派的身分識別使用「system」。
-azCli	`bool`	如果已設定，請使用 Azure CLI 向 Kusto 服務進行驗證。必須安裝並登入 Azure CLI。
-ingestWithManagedIdentity， -ingestmi	`string`	安裝在 Kusto 服務上的受控識別（使用者指派或系統指派）的用戶端識別碼，以從記憶體下載。針對系統指派的身分識別使用「system」。
-connectToStorageWithManagedIdentity， -storageMi	`string`	用戶端上安裝受控識別的用戶端標識碼（使用者指派或系統指派），以從記憶體列出。
-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 資料總管評估原始資料大小。計算為原始大小除以壓縮大小。
-limit、 -l	整數	如果已設定，則會將擷取限製為前 N 個檔案。
-listOnly、-list	`bool`	如果已設定此選項，則只會顯示可能被選中的擷取項目。
-ingestTimeout	整數	所有擷取作業完成的分鐘數逾時。預設為 `60`。
-forceSync	`bool`	如果設定，會強制同步擷取。預設為 `false`。
-互動	`bool`	如果設定為 `false`，則不會提示輸入自變數確認。針對自動流程和非互動式環境。預設值為 `true`。
-dataBatchSize	整數	設定每個擷取作業的大小總計限制（MB、未壓縮）。
-filesInBatch	整數	設定每個匯入作業的檔案及 Blob 的數目限制。
-devTracing、-trace	`string`	如果設定，診斷記錄會寫入本機目錄（根據預設， `RollingLogs` 在目前目錄中，或設定 switch 值即可修改）。

Azure Blob 特定功能

當您使用 LightIngest 搭配 Azure Blob 時，它會使用某些 Blob 的中繼資料屬性來增強資訊擷取過程。

元數據屬性	使用方式
`rawSizeBytes`、`kustoUncompressedSizeBytes`	如果設定，LightIngest 會將這些屬性解譯為未壓縮的資料大小
`kustoCreationTime`、`kustoCreationTimeUtc`	LightIngest 會將這些屬性解譯為 UTC 時間戳記。如果已設定，它會使用這些屬性來覆蓋 Kusto 中的創建時間戳記。此功能對於回填情境很有用

使用範例

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

使用 CreationTime 屬性內嵌歷程記錄數據

當您將歷程記錄資料從現有系統載入 Azure 資料總管時，所有記錄都會取得相同的擷取日期。若要依建立時間而非擷取時間來分割資料，請使用引數。-creationTimePattern 自 -creationTimePattern 變數會 CreationTime 從檔案或 Blob 路徑擷取屬性。模式不需要反映整個項目路徑，只需反映包含您要使用的時間戳記的區段。

自變數值必須包含：

時間戳格式正前的常數文字，以單引弧括住（前置詞）
標準 .NET DateTime 表示法中的時間戳格式
緊接在時間戳之後的常數文字（後綴）。

重要

當您指定要覆寫建立時間時，請確保目標資料表的 Lookback 屬性在有效的範圍合併策略中與檔案或 Blob 路徑中的值一致。

範例

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

自變數的值 -creationTimePattern 是檔名的一部分： “'historicalvalues'yyyyMmdd'.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"

使用受控識別進行驗證

LightIngest 會執行三個動作，這些動作可以使用受控識別進行驗證。在每個步驟中使用受控識別時，並不需要在其他步驟中也這樣做。針對每個動作，會提供相關的命令行自變數。

聯機到 Kusto 叢集：若要將擷取排入佇列，此工具會使用連接字串。使用「-mi」自變數來指定安裝在用戶端 VM 上且在目標資料庫中具有內嵌許可權的受控識別。
聯機到 Azure 儲存體以下載 Blob：使用 “-ingestmi” 來指定在具有記憶體容器讀取許可權的 Kusto 服務上安裝的受控識別。
線上至 Azure 儲存體以列出容器 Blob：使用 “-storageMi” 自變數來指定安裝在用戶端 VM 上且具有記憶體容器清單許可權的受控識別。如果您使用此方法，但未使用前一種方法（連線至 Azure 儲存體以下載 Blob），則受控識別也必須具有讀取權限，而且權杖會傳遞至 Kusto 服務以供後續擷取使用。設定所有三個引數。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-12-01