使用 LightIngest 将数据引入 Azure 数据资源管理器

项目
11/29/2024

LightIngest 是用于将即席数据引入 Azure 数据资源管理器的命令行实用工具。该实用工具可以从本地文件夹、Azure Blob 存储容器或 Amazon S3 存储桶提取源数据。

当你想要引入大量数据时，LightIngest 最有用，因为引入持续时间没有时间限制。当你想要以后根据记录的创建时间而不是引入时间来查询记录时，它也很有用。

有关如何自动生成 LightIngest 命令的示例，请参阅引入历史数据。

注意

引入支持的最大文件大小为 6 GB。建议引入 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 数据资源管理器群集的连接字符串。将连接字符串括在双引号中，并遵循 Kusto 连接字符串规范。

例如：

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

性能建议

为了以最佳方式管理引入负载并从暂时性错误中恢复，请使用 https://ingest-{yourClusterNameAndRegion}.kusto.chinacloudapi.cn 处的引入终结点。
若要提供最佳引入性能，需要原始数据大小，以便 LightIngest 可以估计本地文件的未压缩大小。但如果没有事先下载已压缩的 Blob，LightIngest 可能无法正确估算这些 Blob 的原始大小。因此，在引入压缩的 Blob 时，请将 Blob 元数据的 rawSizeBytes 属性设置为以字节为单位的非压缩数据大小。

命令行参数

参数	类型	描述	必须
	`string`	Kusto 连接字符串，指定用于处理引入操作的 Kusto 终结点。此值应用双引号引起来。	✔️
-database、-db	`string`	目标 Azure 数据资源管理器数据库名称。
-table	`string`	目标 Azure 数据资源管理器表名称。	✔️
-sourcePath、-source	`string`	源数据的位置，可以是本地文件路径、Azure Blob 容器的根 URI 或 Amazon S3 存储桶的 URI。如果数据存储在 Azure Blob 中，URI 必须包含存储帐户密钥或共享访问签名 (SAS)。如果数据位于 S3 存储桶中，URI 必须包含凭据密钥。建议将此值括在双引号中。有关详细信息，请参阅存储连接字符串。传递 -sourcePath：；模拟列出具有用户权限的 Azure 存储项（用户提示授权）。	✔️
-managedIdentity, -mi	`string`	用于连接的托管标识（用户分配或系统分配）的客户端 ID。将“系统”用于系统分配的标识的标识。
-azCli	`bool`	如果已设置，请使用 Azure CLI 向 Kusto 服务进行身份验证。必须安装并登录到 Azure CLI。
-ingestWithManagedIdentity、-ingestmi	`string`	安装在 Kusto 服务上以从存储下载的托管标识（用户分配或系统分配）的客户端 ID。将“系统”用于系统分配的标识的标识。
-connectToStorageWithManagedIdentity、-storageMi	`string`	安装在客户端上以从存储列出的托管标识（用户分配或系统分配）的客户端 ID。
-connectToStorageWithUserAuth, -storageUserAuth	`string`	使用用户凭据向数据源存储服务进行身份验证。此值的选项为 `PROMPT` 或 `DEVICE_CODE`。
-connectToStorageLoginUri, -storageLoginUri	`string`	如果设置了 `-connectToStorageWithUserAuth`，可以选择提供 Microsoft Entra ID 登录 URI。
-prefix	`string`	当要引入的源数据驻留在 Blob 存储中时，此 URL 前缀（不包括容器名称）将由所有 Blob 共享。例如，如果数据位于 `MyContainer/Dir1/Dir2` 中，则前缀应是 `Dir1/Dir2`。建议将此值括在双引号中。
-pattern	`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 的第一条记录。例如，如果源数据具有标头。
-tag	`string`	要与引入的数据相关联的标记。允许多个标记
-dontWait	`bool`	如果设置为 `true`，则不等待引入完成。引入大量文件/Blob 时非常有用。
-compression、-cr	Double	压缩比提示。引入压缩的文件/Blob 来帮助 Azure 数据资源管理器评估原始数据大小时，此参数非常有用。计算方式为原始大小除以压缩大小。
-limit、-l	integer	如果设置此参数，则会将引入限制为前 N 个文件。
-listOnly、-list	`bool`	如果设置此参数，仅显示已选择引入的项。
-ingestTimeout	integer	完成所有引入操作的超时（分钟）。默认为 `60`。
-forceSync	`bool`	如果设置此参数，将强制同步引入。默认为 `false`。
-interactive	`bool`	如果设置为 `false`，则不会提示确认参数。适用于无人参与的流和非交互式环境。默认值为 `true`。
-dataBatchSize	integer	设置每个引入操作的总大小限制（MB，非压缩）。
-filesInBatch	integer	设置每个引入操作的文件/Blob 计数限制。
-devTracing、-trace	`string`	如果设置此参数，诊断日志将写入本地目录（默认为当前目录中的 `RollingLogs`，可以通过设置开关值修改此位置）。

特定于 Azure Blob 的功能

与 Azure Blob 配合使用时，LightIngest 将使用特定的 Blob 元数据属性来增强引入过程。

元数据属性	使用情况
`rawSizeBytes`，`kustoUncompressedSizeBytes`	如果设置此参数，它将解释为非压缩数据大小
`kustoCreationTime`，`kustoCreationTimeUtc`	解释为 UTC 时间戳。如果设置此参数，它将用于重写 Kusto 中的创建时间。在回填方案中非常有用

用法示例

以下示例假设操作系统已安装了 LightIngest 二进制文件。如果已将 LightIngest 安装为 .NET 工具，请在示例中用 LightIngest 代替 LightIngest。

使用 CreationTime 属性获取历史数据

将历史数据从现有系统加载到 Azure 数据资源管理器时，所有记录接收相同的引入日期。若要启用按创建时间而不是引入时间对数据进行分区，可以使用 -creationTimePattern 参数。 -creationTimePattern 参数从文件或 Blob 路径中提取 CreationTime 属性。此模式不需要反映整个项路径，只需反映包含要使用的时间戳的部分。

参数值必须包括：

紧邻在时间戳格式前面的常量文本，用单引号括起来（前缀）
时间戳格式，采用标准的 .NET 日期时间表示法
紧跟在时间戳之后的常量文本（后缀）。

重要

在指定应重写创建时间时，请确保目标表的有效区合并策略中的 Lookback 属性与文件或 Blob 路径中的值一致。

示例

包含如下日期时间的 Blob 名称：historicalvalues19840101.parquet（时间戳中年份以四位数表示，月份以两位数表示，日期以两位数表示）

-creationTimePattern 参数的值是文件名的一部分：“'historicalvalues'yyyyMMdd'.parquet'”

LightIngest "https://ingest-{Cluster name and region}.kusto.chinacloudapi.cn;Fed=True" -db:{Database} -table:Trips -source:"https://{Account}.blob.core.chinacloudapi.cn/{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.chinacloudapi.cn;Fed=True" -db:{Database} -table:Trips -source:"https://{Account}.blob.core.chinacloudapi.cn/{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 下文件夹 DIR 中容器 CONT 下的与模式 *.csv.gz 匹配的 10 个 Blob
目标是数据库 DB 表 TABLE，引入映射 MAPPING 已在目标中预先创建
工具将等到引入操作完成
请注意，有不同的选项用于指定目标数据库和存储帐户密钥与SAS 令牌

LightIngest "https://ingest-{ClusterAndRegion}.kusto.chinacloudapi.cn;Fed=True"
  -database:DB
  -table:TABLE
  -source:"https://ACCOUNT.blob.core.chinacloudapi.cn/{ROOT_CONTAINER};{StorageAccountKey}"
  -prefix:"DIR"
  -pattern:*.csv.gz
  -format:csv
  -mappingRef:MAPPING
  -limit:10

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

引入容器中的所有 Blob，不包括标头行

引入指定存储帐户 ACCOUNT 下文件夹 DIR1/DIR2 中容器 CONT 下的与模式 *.csv.gz 匹配的所有 Blob
目标是数据库 DB 表 TABLE，引入映射 MAPPING 已在目标中预先创建
源 Blob 包含标头行，因此工具被指示删除每个 Blob 的第一条记录
工具将发布要引入的数据，且不会等待引入操作完成

LightIngest "https://ingest-{ClusterAndRegion}.kusto.chinacloudapi.cn;Fed=True"
  -database:DB
  -table:TABLE
  -source:"https://ACCOUNT.blob.core.chinacloudapi.cn/{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.chinacloudapi.cn;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.chinacloudapi.cn;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 服务。因此，建议设置所有三个参数。

通过