共用方式為

使用 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：

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

    提示

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

  2. 輸入 ingest- ，後面接著將管理擷取的 Azure 數據總管叢集 連接字串。 以雙引弧括住 連接字串，並遵循 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 特定功能

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

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

使用範例

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

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

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

自變數值必須包含：

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

重要

指定應該覆寫建立時間時，請確定 Lookback 目標數據表之有效 Extents 合併 原則中的 屬性符合檔案或 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 服務。 因此，建議設定這三個自變數。