Поделиться через

Оператор внешних данных

Область применения: ✅Microsoft Fabric

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

Note

Оператор externaldata поддерживает следующее:

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

Note

Оператор externaldata поддерживает следующее:

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

Note

externaldata Используйте оператор для получения небольших ссылочных таблиц размером до 100 МБ из артефакта внешнего хранилища. Оператор не предназначен для больших томов данных. Чтобы получить большие объемы внешних данных, рекомендуется принять внешние данные в Log Analytics в качестве пользовательских журналов. Этот оператор не поддерживается, если общедоступная конечная точка артефакта хранилища находится за брандмауэром.

Syntax

externaldatacolumnName( [ ...] : [ propertyName...]],

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

Parameters

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

[! WARN] По соображениям безопасности убедитесь, что учетные данные не указаны свойством storageConnectionString . Если запросу нужно указать учетные данные, используйте параметры запроса , чтобы указать всю строку подключения.

Например, предположим, что запрос включает параметр запроса, который называется URI значениями в хранилище BLOB-объектов, запрос будет выглядеть следующим образом:

declare query_parameters(URI:string);
externaldata(x:string)[URI]

Если это невозможно (например, вы используете клиент, который не поддерживает параметры запроса), обязательно используйте запутированные строковые литералы.

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

Property Type Description
format string Формат данных. Если не указано, предпринята попытка определить формат данных из расширения файла. Значение по умолчанию — CSV. Поддерживаются все форматы данных приема.
ignoreFirstRecord bool Если задано значение true, первая запись в каждом файле игнорируется. Это свойство полезно при запросе CSV-файлов с заголовками.
ingestionMapping string Указывает, как сопоставить данные из исходного файла с фактическими столбцами в результирующем наборе операторов. Дополнительные сведения см. в разделе о сопоставлении данных.

Note

Этот оператор не принимает входные данные конвейера.

Стандартные ограничения запросов также применяются к внешним запросам данных.

Returns

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

Examples

В следующем примере показано, как найти все записи в таблице, столбец которой UserID попадает в известный набор идентификаторов, удерживаемых (по одной строке) во внешнем файле хранилища, хранящейся в хранилище BLOB-объектов Azure. Так как формат данных не указан, обнаруженный формат данных является TXT.

Users
| where UserID in ((externaldata (UserID:string) [
    @"https://storageaccount.blob.core.windows.net/storagecontainer/users.txt;managed_identity=..."
    ]))
| ...

В следующем примере выполняется запрос нескольких файлов данных, хранящихся во внешнем хранилище.

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

Приведенный выше пример можно рассматривать как быстрый способ запроса нескольких файлов данных без определения внешней таблицы.

Note

Секционирование данных не распознается оператором externaldata .

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

Связанный контент

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

  • Last updated on