Share via

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

externaldata 运算符

  • 项目

externaldata 运算符返回一个表，该表的架构是在查询自身中定义的，并且该表的数据是从外部存储项目（如 Azure Blob 存储中的 Blob 或 Azure Data Lake Storage 中的文件）中读取的。

注意

externaldata 运算符支持一组特定的存储服务，如存储连接字符串下所列。

注意

操作员externaldata支持共享访问签名 (SAS) 密钥、访问密钥和Microsoft Entra令牌身份验证方法。 有关详细信息，请参阅存储身份验证方法。

注意

请使用 externaldata 运算符从外部存储项目检索最多 100 MB 的小型引用表。 该运算符并非为大数据量而设计。 若要检索大量外部数据，建议将外部数据作为自定义日志引入 Log Analytics。 当存储项目的公共终结点位于防火墙后面时，不支持此运算符。

语法

externaldata(columnName:columnType [, ...] )[storageConnectionString [, ...] ] [with(propertyName=propertyValue [, ...])]

详细了解语法约定。

参数

名称 类型 必需 说明
columnName, columnType string ✔️ 列名及其类型的列表。 此列表定义表的架构。
storageConnectionString string ✔️ 要查询的存储项目的存储连接字符串。
propertyName, propertyValue string 可选 支持的属性 列表，用于确定如何解释从存储中检索到的数据。

支持的属性

属性 类型 说明
format string 数据格式。 如果未指定，则会尝试从文件扩展名检测数据格式。 默认为 CSV。 支持所有引入数据格式。
ignoreFirstRecord bool 如果设置为 true，则会忽略每个文件中的第一条记录。 在查询带有标题的 CSV 文件时，此属性很有用。
ingestionMapping string 指示如何将数据从源文件映射到运算符结果集中的实际列。 请参阅数据映射。

注意

此运算符不接受任何管道输入。

标准查询限制还适用于外部数据查询。

返回

externaldata 运算符返回给定架构的数据表，表中的数据是从指定的存储项目中分析的，由存储连接字符串指示。

示例

提取存储在 Azure Blob 存储中的用户 ID 的列表

下面的示例显示了如何查找表中的所有记录，该表的 UserID 列属于一个已知 ID 集，这些 ID 保存在外部存储文件中（每行一个 ID）。 由于未指定数据格式，因此检测到的数据格式是 TXT。

Users
| where UserID in ((externaldata (UserID:string) [
    @"https://storageaccount.blob.core.windows.net/storagecontainer/users.txt" 
      h@"?...SAS..." // Secret token needed to access the blob
    ]))
| ...

查询多个数据文件

下面的示例查询外部存储中存储的多个数据文件。

externaldata(Timestamp:datetime, ProductId:string, ProductDescription:string)
[
  h@"https://mycompanystorage.blob.core.windows.net/archivedproducts/2019/01/01/part-00000-7e967c99-cf2b-4dbb-8c53-ce388389470d.csv.gz?...SAS...",
  h@"https://mycompanystorage.blob.core.windows.net/archivedproducts/2019/01/02/part-00000-ba356fa4-f85f-430a-8b5a-afd64f128ca4.csv.gz?...SAS...",
  h@"https://mycompanystorage.blob.core.windows.net/archivedproducts/2019/01/03/part-00000-acb644dc-2fc6-467c-ab80-d1590b23fc31.csv.gz?...SAS..."
]
with(format="csv")
| summarize count() by ProductId

可将上述示例视为快速查询多个数据文件（无需定义外部表）的方法。

注意

externaldata 运算符无法识别数据分区。

查询分层数据格式

若要查询分层数据格式（如 JSON、 Parquet、 Avro或 ORC），必须在运算符属性中指定 ingestionMapping。 在此示例中，有一个 JSON 文件存储在 Azure Blob 存储中，该文件包含以下内容：

{
  "timestamp": "2019-01-01 10:00:00.238521",   
  "data": {    
    "tenant": "e1ef54a6-c6f2-4389-836e-d289b37bcfe0",   
    "method": "RefreshTableMetadata"   
  }   
}   
{
  "timestamp": "2019-01-01 10:00:01.845423",   
  "data": {   
    "tenant": "9b49d0d7-b3e6-4467-bb35-fa420a25d324",   
    "method": "GetFileList"   
  }   
}
...

若要使用 externaldata 运算符查询此文件，必须指定数据映射。 该映射指示如何将 JSON 字段映射到运算符结果集列：

externaldata(Timestamp: datetime, TenantId: guid, MethodName: string)
[ 
   h@'https://mycompanystorage.blob.core.windows.net/events/2020/09/01/part-0000046c049c1-86e2-4e74-8583-506bda10cca8.json?...SAS...'
]
with(format='multijson', ingestionMapping='[{"Column":"Timestamp","Properties":{"Path":"$.timestamp"}},{"Column":"TenantId","Properties":{"Path":"$.data.tenant"}},{"Column":"MethodName","Properties":{"Path":"$.data.method"}}]')

此处使用 MultiJSON 格式，因为单个 JSON 记录跨越多行。

有关映射语法的详细信息，请参阅数据映射。