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

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

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

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

注意

引入支持的最大文件大小为 6 GB。 建议引入 100 MB 到 1 GB 的文件。

先决条件

运行 LightIngest

要运行 LightIngest:

  1. 在命令提示符下,输入 LightIngest,后接相关的命令行参数。

    提示

    若要查看支持的命令行参数列表,请输入 LightIngest /help

  2. 输入 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 使用用户凭据向数据源存储服务进行身份验证。 此值的选项为 PROMPTDEVICE_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
  • 目标是数据库 DBTABLE,引入映射 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
  • 目标是数据库 DBTABLE,引入映射 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 匹配的所有文件
  • 目标为数据库 DBTABLE,引入映射已在本地文件 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 匹配的所有文件
  • 目标为数据库 DBTABLE,引入映射已在本地文件 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 服务。 因此,建议设置所有三个参数。