你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
使用 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.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 可以估计本地文件的未压缩大小。 但如果没有事先下载已压缩的 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.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下文件夹DIR中容器CONT下的与模式*.csv.gz匹配的 10 个 Blob - 目标是数据库
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下文件夹DIR1/DIR2中容器CONT下的与模式*.csv.gz匹配的所有 Blob - 目标是数据库
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 服务。 因此，建议设置所有三个参数。