Оператор externaldata

Оператор externaldata возвращает таблицу, схема которой определена в самом запросе и данные которой считываются из артефакта внешнего хранилища, например большого двоичного объекта в Хранилище BLOB-объектов Azure или файла в Azure Data Lake Storage.

Примечание

Оператор externaldata поддерживает определенный набор служб хранилища, как указано в разделе Строки подключения к хранилищу.

Примечание

Оператор externaldata поддерживает ключ подписанного URL-адреса (SAS), ключ доступа и методы проверки подлинности маркера Microsoft Entra. Дополнительные сведения см. в статье Методы проверки подлинности хранилища.

Примечание

Используйте оператор , externaldata чтобы получить небольшие ссылочные таблицы размером до 100 МБ из артефакта внешнего хранилища. Оператор не предназначен для больших объемов данных. Чтобы получить большие объемы внешних данных, рекомендуется принимать внешние данные в 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 возвращает таблицу данных заданной схемы, данные которой были проанализированы из указанного артефакта хранилища, указанного строка подключения хранилища.

Примеры

Получение списка идентификаторов пользователей, хранящихся в Хранилище BLOB-объектов Azure

В следующем примере показано, как найти все записи в таблице, столбец которой UserID попадает в известный набор идентификаторов, которые хранятся (по одной на строку) во внешнем файле хранилища. Так как формат данных не указан, обнаруженный формат данных имеет значение 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-файл, хранящийся в Хранилище BLOB-объектов Azure со следующим содержимым:

{
  "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 состоит из нескольких строк.

Дополнительные сведения о синтаксисе сопоставления см. в статье о сопоставлениях данных.