Оператор externaldata

Область применения: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel

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

Примечание.

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

Примечание.

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

Синтаксис

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

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

Параметры

Имя (название)	Type	Обязательно	Описание
columnName, columnType	string	✔️	Список имен столбцов и их типов. Этот список определяет схему таблицы.
storageConnectionString	string	✔️	Хранилище строка подключения артефакта хранилища для запроса.
propertyName, propertyValue	string		Список необязательных поддерживаемых свойств , определяющих, как интерпретировать данные, полученные из хранилища.

Поддерживаемые свойства

Свойство	Type	Описание
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 .

Запрос иерархических форматов данных

Чтобы запросить иерархический формат данных, например AvroJSONParquet, или , ingestionMapping ORCнеобходимо указать в свойствах оператора. В этом примере есть 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 охватываются несколькими строками.

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