使用 LightIngest 将数据引入 Azure 数据资源管理器
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。 将“系统”用于系统分配的标识的标识。 | |
-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 服务。 因此,建议设置所有三个参数。