通过

.list blobs 命令 （预览版）

适用于：✅Azure 数据资源管理器

.list blobs 命令列出指定容器路径下的 blob。

此命令通常用于 .ingest-from-storage-queued 到引入数据。 还可以自行使用它来更好地了解文件夹内容并参数化引入命令。

Note

  • 排队引入命令在数据引入 URI 终结点 https://ingest-<YourClusterName><Region>.kusto.chinacloudapi.cn 上运行。

  • 当命令本身使用时，可能会截断结果以限制 Blob 数。 但是，与 .ingest-from-storage-queued 一起使用时，不会应用截断。

Permissions

必须至少具有 表引入器 权限才能运行此命令。

Syntax

.list blobs（SourceDataLocators）[SuffixValue] [MaxFiles==SuffixMaxFilesValue] [PathFormat=PathFormatValue]

详细了解 语法约定。

Parameters

Name 类型 Required Description
SourceDataLocators string ✔️ 一个或多个 存储连接字符串 用逗号字符分隔。 每个连接字符串都可以引用容器中的存储容器或文件前缀。 目前，仅支持一个存储连接字符串。
SuffixValue string 启用 Blob 筛选的后缀。
MaxFilesValue integer 要返回的最大 Blob 数。
PathFormatValue string Blob 路径中的模式，可用于检索创建时间作为输出字段。 有关详细信息，请参阅 路径格式。

Note

  • 若要保护敏感信息，请使用 SourceDataLocators的模糊字符串文本。

  • 单独使用时， .list blob 返回最多 1,000 个文件，而不考虑 MaxFiles 中指定的任何更大的值。

Ingestion properties

Important

在排队引入 数据是使用引入属性批处理的。 使用的不同引入映射属性（如不同的 ConstValue 值）越分散，引入就越分散，这可能会导致性能下降。

下表列出了和支持的属性，并提供示例：

Property Description Example
ingestionMapping 表示如何将数据从源文件映射到表中实际列的字符串值。 请使用相关的映射类型定义format值。 请参阅数据映射。 with (format="json", ingestionMapping = "[{\"column\":\"rownumber\", \"Properties\":{\"Path\":\"$.RowNumber\"}}, {\"column\":\"rowguid\", \"Properties\":{\"Path\":\"$.RowGuid\"}}]")
(已弃用: avroMapping, csvMapping, jsonMapping)
ingestionMappingReference 字符串值，指示如何使用命名的映射策略对象将源文件中的数据映射到表中的实际列。 请使用相关的映射类型定义format值。 请参阅数据映射。 with (format="csv", ingestionMappingReference = "Mapping1")
(已弃用: avroMappingReference, csvMappingReference, jsonMappingReference)
creationTime 日期/时间值（格式化为 ISO8601 字符串），在创建引入的数据盘区时使用。 如果未指定，则使用当前值（now()）。 引入旧数据时，重写默认值非常有用，以便正确应用保留策略。 指定时，请确保目标表中Lookback属性的有效范围合并策略与指定值保持一致。 with (creationTime="2017-02-13")
extend_schema 如果指定，则为布尔值，指示命令扩展表的模式（默认为 false）。 此选项仅适用于 .append 和 .set-or-append 命令。 唯一允许的架构扩展在末尾将更多列添加到表中。 如果原始表架构是(a:string, b:int)，那么有效的架构扩展可以是(a:string, b:int, c:datetime, d:string)，但(a:string, c:datetime)就无效。
folder 使用 ingest-from-query 命令时分配给表的文件夹。 如果该表已存在，则此属性将替代表的文件夹。 with (folder="Tables/Temporary")
format 数据格式（参见支持的数据格式）。 with (format="csv")
ingestIfNotExists 一个字符串值，如果已指定，则在表的数据已通过一个具有相同值的 ingest-by: 标记进行了标记时，引入操作会失败。 这确保了幂等数据引入。 欲了解更多信息，请参阅ingest-by: tags。 属性 with (ingestIfNotExists='["Part0001"]', tags='["ingest-by:Part0001"]') 表示如果标记 ingest-by:Part0001 的数据已经存在，那么不要完成当前的摄取过程。 如果该数据不存在，则在执行这个新的引入操作时，应该设置此标记（防止将来有人尝试再次引入相同的数据）。
ignoreFirstRecord 一个布尔值，在设置为 true 的情况下表示引入操作应该忽略每个文件的第一条记录。 此属性对 CSV和类似格式的文件非常有用，如果文件的第一条记录是列名。 默认情况下，假定使用 false。 with (ignoreFirstRecord=false)
policy_ingestiontime 如果指定，布尔值描述是否在此命令创建的表上启用摄取时间策略。 默认值为 true。 with (policy_ingestiontime=false)
recreate_schema 如果指定，布尔值会描述命令是否可以重建表的架构。 此属性仅适用于.set-or-replace命令。 在同时设置的情况下，此属性优先于 extend_schema 属性。 with (recreate_schema=true)
tags 与引入的数据（格式化为 JSON 字符串）相关联的标记的列表 with (tags="['Tag1', 'Tag2']")
TreatGzAsUncompressed 一个布尔值，如果设置为 true，则表示扩展名为 .gz 的文件不会被压缩。 从 Amazon AWS S3 引入时，有时需要此标志。 with (treatGzAsUncompressed=true)
validationPolicy 一个 JSON 字符串，指示在引入使用 CSV 格式表示的数据期间要运行的验证。 查看数据导入，以了解不同选项的说明。 with (validationPolicy='{"ValidationOptions":1, "ValidationImplications":1}')（这是默认策略）
zipPattern 当从存储中导入包含 ZIP 存档的数据时，请使用此属性。 这是一个字符串值，用于指示选择在 ZIP 存档中要导入的文件时使用的正则表达式。 将忽略存档中的所有其他文件。 with (zipPattern="*.csv")

身份验证和授权

每个存储连接字符串指示用于访问存储的授权方法。 根据授权方法，可能需要向主体授予对外部存储的权限才能执行引入。

下表列出了支持的身份验证方法和从外部存储引入数据所需的权限。

Authentication method Azure Blob 存储/Data Lake Storage Gen2 Data Lake Storage Gen1
共享访问（SAS）令牌 列表 + 读取 Gen1 不支持此身份验证方法。
存储帐户访问密钥 Gen1 不支持此身份验证方法。
Managed identity 存储 Blob 数据读取者 Reader

Note

若要在使用 SAS 令牌或存储帐户访问密钥时保护敏感信息，请使用 模糊字符串文本。 有关详细信息，请参阅 示例 。

.list blobs 的主要用途是排队引入，该引入以异步方式完成，没有用户上下文。 因此，不支持 模拟 。

Path format

PathFormat 参数允许指定列出 blob 的创建时间的格式。 它由文本分隔符和分区元素序列组成。 分区元素是指在分区 by 子句中声明的分区，文本分隔符是用引号括起来的任何文本。 必须使用文本分隔符分隔连续分区元素。

[ StringSeparator ] Partition [ StringSeparator ] [Partition [ StringSeparator ] ...]

若要构造原始文件路径前缀，分区元素将呈现为字符串，并用相应的文本分隔符分隔。 可以使用 datetime_pattern 宏（datetime_pattern(DateTimeFormat,PartitionName)）指定用于呈现日期/时间分区值的格式。 该宏遵循 .NET 格式规范，并允许将格式说明符括在大括号中。 例如，以下两种格式等效：

  • 'year='yyyy'/month='MM
  • year={yyyy}/month={MM}

默认情况下，日期/时间值使用以下格式呈现：

Partition function Default format
startofyear yyyy
startofmonth yyyy/MM
startofweek yyyy/MM/dd
startofday yyyy/MM/dd
bin( 列, 1d) yyyy/MM/dd
bin( 列, 1h) yyyy/MM/dd/HH
bin( 列, 1m) yyyy/MM/dd/HH/mm

Returns

该命令的结果是一个表，其中每个 Blob 列出一条记录。

Name 类型 Description
BlobUri string Blob 的 URI。
SizeInBytes long Blob 的字节数或内容长度。
CapturedVariables dynamic 捕获的变量。 目前仅支持 CreationTime。

Examples

列出最大 blob 数

以下命令使用 myfolder 身份验证列出 文件夹中最多 20 个 blob。

.list blobs (
    "https://mystorageaccount.blob.core.chinacloudapi.cn/datasets/myfolder;managed_identity=system"
)
MaxFiles=20

使用模糊处理的 SAS 令牌列出 Blob

以下命令使用myfolder列出文件夹中最多 20 个 Blob 进行身份验证。 SAS 令牌经过模糊处理，以保护敏感信息。

.list blobs (
    h"https://mystorageaccount.blob.core.chinacloudapi.cn/datasets/myfolder?sv=..."
)
MaxFiles=20

列出 Parquet Blob

以下命令使用 .parquet 身份验证列出文件夹中最多 10 个类型 blob。

.list blobs (
    "https://mystorageaccount.blob.core.chinacloudapi.cn/datasets/myfolder;managed_identity=system"
)
Suffix=".parquet"
MaxFiles=10

从 Blob 路径捕获日期

以下命令使用 .parquet 身份验证从文件夹中列出最多 10 个类型 blob，并从 URL 路径中提取日期。

.list blobs (
    "https://mystorageaccount.blob.core.chinacloudapi.cn/spark/myfolder;managed_identity=system"
)
Suffix=".parquet"
MaxFiles=10
PathFormat=("myfolder/year=" datetime_pattern("yyyy'/month='MM'/day='dd", creationTime) "/")

该 PathFormat 参数可以从各种文件夹层次结构中提取日期，例如：

  • Spark 文件夹路径，例如： https://mystorageaccount.blob.core.chinacloudapi.cn/spark/myfolder/year=2024/month=03/day=16/myblob.parquet

  • 常见文件夹路径，例如： https://mystorageaccount.blob.core.chinacloudapi.cn/datasets/export/2024/03/16/03/myblob.parquet 路径中包含小时 03 。

可以使用以下命令提取创建时间：

.list blobs (
    "https://mystorageaccount.blob.core.chinacloudapi.cn/datasets/export;managed_identity=system"
)
Suffix=".parquet"
MaxFiles=10
PathFormat=("datasets/export/" datetime_pattern("yyyy'/'MM'/'dd'/'HH", creationTime) "/")

Related content