使用 “版本 ”下拉列表切换服务。 了解有关导航的详细信息。
适用于：✅ Azure Data Explorer ✅ Azure Monitor ✅ Microsoft Sentinel
externaldata 运算符返回一个表，该表的架构在查询本身中定义，以及从外部storage项目（如Azure Blob Storage中的 blob 或Azure Data Lake Storage中的文件）读取其数据。
注意
externaldata 运算符支持：
- 一组特定的storage服务，如Storage连接字符串下列出。
- 共享Access签名（SAS）密钥、Access密钥、Microsoft Entra 令牌和托管标识身份验证方法。 有关详细信息，请参阅Storage身份验证方法。
注意
使用 externaldata 运算符从外部storage项目检索高达 100 MB 的小引用表。 该运算符并非为大数据量而设计。
当storage项目的公共终结点位于防火墙后面时，不支持此运算符。
语法
externaldata
(
columnName:columnType [, ...] )[storageConnectionString [, ...] ] [with(propertyName=propertyValue [, ...])]
详细了解语法约定。
参数
| 客户 | 类型 | 必需 | 说明 |
|---|---|---|---|
| columnName、 columnType | string |
✔️ | 列名及其类型的列表。 此列表定义表的架构。 |
| storageConnectionString | string |
✔️ | 要查询的storage项目的 storage connection string。 |
| propertyName、propertyValue | string |
可选的 supported 属性列表，用于确定如何解释从storage检索到的数据。 |
[!警告] 出于安全原因，请确保 storageConnectionString 属性未指定任何凭据。 如果查询需要指定凭据，请使用 query 参数指定整个connection string。
例如，假设查询包含名为
URI的查询参数，其值指向Blob Storage，则查询如下所示：declare query_parameters(URI:string); externaldata(x:string)[URI]如果这是不可能的（例如，你正在使用不支持设置查询参数的客户端），请确保使用 模糊字符串文本。
支持的属性
| 属性 | 类型 | 说明 |
|---|---|---|
| 格式 | string |
数据格式。 如果未指定，则会尝试从文件扩展名检测数据格式。 默认为 CSV。 支持所有引入数据格式。 |
| ignoreFirstRecord | bool |
如果设置为 true，则会忽略每个文件中的第一条记录。 在查询带有标题的 CSV 文件时，此属性很有用。 |
| ingestionMapping | string |
指示如何将数据从源文件映射到运算符结果集中的实际列。 请参阅数据映射。 |
返回
externaldata 运算符返回给定架构的数据表，该表的数据是从指定的storage项目分析的，由storage connection string指示。
示例
以下示例演示如何查找表中的所有记录，其 UserID 列属于存储在Azure Blob Storage的外部storage文件中的已知 ID 集（每行一行）。 由于未指定数据格式，因此检测到的数据格式是 TXT。
Users
| where UserID in ((externaldata (UserID:string) [
@"https://storageaccount.blob.core.chinacloudapi.cn/storagecontainer/users.txt;managed_identity=..."
]))
| ...
以下示例查询存储在外部storage中的多个数据文件。
externaldata(Timestamp:datetime, ProductId:string, ProductDescription:string)
[
h@"https://mycompanystorage.blob.core.chinacloudapi.cn/archivedproducts/2019/01/01/part-00000-7e967c99-cf2b-4dbb-8c53-ce388389470d.csv.gz?...SAS...",
h@"https://mycompanystorage.blob.core.chinacloudapi.cn/archivedproducts/2019/01/02/part-00000-ba356fa4-f85f-430a-8b5a-afd64f128ca4.csv.gz?...SAS...",
h@"https://mycompanystorage.blob.core.chinacloudapi.cn/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。
在此示例中，Azure Blob Storage中存储了包含以下内容的 JSON 文件：
{
"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.chinacloudapi.cn/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 记录跨越多行。
相关内容
有关映射语法的详细信息，请参阅数据映射。