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


Прием из хранилища

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

Команда .ingest into принимает данные в таблицу путем извлечения данных из одного или нескольких файлов облачного хранилища. Например, команда может получать 1000 больших двоичных объектов в формате CSV из службы хранилища больших двоичных объектов Azure, анализировать их и принимать их вместе в одну целевую таблицу. Данные добавляются в таблицу, не затрагивая существующие записи, не изменяя схему таблицы.

Примечание.

Этот метод приема предназначен для изучения и прототипирования. Не используйте его в рабочих или больших сценариях.

Разрешения

Для выполнения этой команды необходимо иметь по крайней мере разрешения Ingestor таблицы.

Синтаксис

.ingest [async] into table TableName SourceDataLocator [with ( IngestionPropertyName = IngestionPropertyValue [, ...] )]

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

Параметры

Имя (название) Type Обязательно Описание
async string Если задано, команда возвращается немедленно и продолжает прием в фоновом режиме. Результаты команды включают OperationId значение, которое затем можно использовать с .show operation командой для получения состояния завершения приема и результатов.
TableName string ✔️ Имя таблицы, в которую следует принять данные. Имя таблицы всегда относительно базы данных в контексте. Если объект сопоставления схем не указан, используется схема базы данных в контексте.
SourceDataLocator string ✔️ Один или разделенный запятыми список строка подключения хранилища. Одна строка подключения должна ссылаться на отдельный файл, размещенный в учетной записи хранения. Прием нескольких файлов можно сделать путем указания нескольких строка подключения или приема из запроса внешней таблицы.

Примечание.

Мы рекомендуем использовать запутированные строковые литералы для SourceDataLocator. Служба будет скрабовывать учетные данные во внутренних трассировках и сообщениях об ошибках.

Свойства приема

Внимание

Данные приема в очереди пакетируются с помощью свойств приема. Чем больше уникальных свойств сопоставления приема, таких как различные значения ConstValue, тем больше фрагментировано прием становится, что может привести к снижению производительности.

В следующей таблице перечислены и описываются поддерживаемые свойства и приведены примеры:

Свойство Description Пример
ingestionMapping Строковое значение, которое описывает сопоставление данных из исходного файла с фактическими столбцами в таблице. Определяет значение format с использованием соответствующего типа сопоставления. Дополнительные сведения см. в разделе о сопоставлении данных. with (format="json", ingestionMapping = "[{\"column\":\"rownumber\", \"Properties\":{\"Path\":\"$.RowNumber\"}}, {\"column\":\"rowguid\", \"Properties\":{\"Path\":\"$.RowGuid\"}}]")
(Не рекомендуется: avroMapping, csvMapping, jsonMapping.)
ingestionMappingReference Строковое значение, которое описывает сопоставление данных из исходного файла с фактическими столбцами в таблице через именованный объект политики сопоставления. Определяет значение format с использованием соответствующего типа сопоставления. Дополнительные сведения см. в разделе о сопоставлении данных. with (format="csv", ingestionMappingReference = "Mapping1")
(Не рекомендуется: avroMappingReference, csvMappingReference, jsonMappingReference.)
creationTime Значение даты и времени (в формате строки ISO8601), которое будет указано как время создания принятых экстентов данных. Если не указано, используется текущее значение (now()). Переопределение по умолчанию полезно при приеме старых данных, чтобы политика хранения применялась правильно. Если указано, убедитесь, что свойство Lookback в действующей политике объединения экстентов целевой таблицы соответствует указанному значению. with (creationTime="2017-02-13")
extend_schema Логическое значение, которое (при наличии) указывает команде расширить схему таблицы (по умолчанию имеет значение false). Этот параметр применяется только в командах .append и .set-or-append. Только разрешенные расширения схемы содержат больше столбцов, добавленных в таблицу в конце. Если исходной для таблицы является схема (a:string, b:int), расширение схемы (a:string, b:int, c:datetime, d:string) будет допустимым, а (a:string, c:datetime) — нет.
folder Для команд ingest-from-query указывает папку, которая будет сопоставлена с таблицей. Если таблица уже существует, это свойство переопределяет папку таблицы. with (folder="Tables/Temporary")
format Формат данных (см. поддерживаемые форматы данных). with (format="csv")
ingestIfNotExists Строковое значение, которое (при наличии) запрещает считать прием успешным, если в таблице уже есть данные с тегом ingest-by: и идентичным значением. Это гарантирует идемпотентность приема данных. Дополнительные сведения см. в разделе о тегах ingest-by:. Свойства with (ingestIfNotExists='["Part0001"]', tags='["ingest-by:Part0001"]') указывают, что, если данные с тегом ingest-by:Part0001 уже существуют, завершать текущий прием не следует. Если данные еще не существуют, для нового приема нужно установить этот тег (на случай, если при следующем приеме будет попытка принять те же данные).
ignoreFirstRecord Логическое значение. Вариант true означает, что при приеме следует игнорировать первую запись каждого файла. Это свойство удобно при работе с файлами в формате CSV (и аналогичных), где первая запись в файле содержит имена столбцов. По умолчанию предполагается значение false. with (ignoreFirstRecord=false)
policy_ingestiontime Логическое значение, которое (при наличии) указывает, следует ли включить политику времени приема для таблицы, созданной этой командой. Значение по умолчанию — true. with (policy_ingestiontime=false)
recreate_schema Логическое значение, которое (при наличии) разрешает команде воссоздать схему таблицы. Это свойство применимо только к команде .set-or-replace. Это свойство имеет приоритет над свойством extend_schema, если заданы оба свойства. with (recreate_schema=true)
tags Список тегов, которые нужно связать с полученными данными, в формате строки JSON. with (tags="['Tag1', 'Tag2']")
TreatGzAsUncompressed Логическое значение, указывающее true, что файлы с расширением .gz не сжимаются. Этот флаг иногда требуется при приеме из Amazon AWS S3. with (treatGzAsUncompressed=true)
validationPolicy Строка JSON, указывающая, какие проверки выполняются во время приема данных, представленных в формате CSV. Описание разных вариантов см. в разделе Прием данных. with (validationPolicy='{"ValidationOptions":1, "ValidationImplications":1}') (это политика по умолчанию)
zipPattern Это свойство используется при приеме данных из хранилища, содержащего ZIP-архив. Это строковое значение содержит регулярное выражение для выбора принимаемых файлов из ZIP-архива. Все остальные файлы в архиве игнорируются. with (zipPattern="*.csv")

Проверка подлинности и авторизация

Каждый строка подключения хранилища указывает метод авторизации, используемый для доступа к хранилищу. В зависимости от метода авторизации субъекту может потребоваться предоставить разрешения на внешнее хранилище для приема.

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

Authentication method Хранилище BLOB-объектов Azure / Data Lake Storage 2-го поколения Azure Data Lake Storage 1-го поколения
Олицетворение Читатель данных больших двоичных объектов хранилища Читатель
Маркер общего доступа (SAS) Список и чтение Этот метод проверки подлинности не поддерживается в 1-м поколениях.
Маркер доступа Microsoft Entra
Ключ доступа к учетной записи хранения Этот метод проверки подлинности не поддерживается в 1-м поколениях.
Управляемое удостоверение Читатель данных больших двоичных объектов хранилища Читатель

Возвраты

Результатом выполнения команды является таблица с записями, количество которых соответствует количеству сегментов данных ("экстентов"), созданных командой. Если сегментов данных не было создано, возвращается одна запись с пустым идентификатором экстента (с нулевым значением).

Имя. Тип Описание
ExtentId guid Уникальный идентификатор сегмента данных, созданного командой.
ItemLoaded string Один или несколько файлов хранилища, связанных с этой записью.
Duration timespan Как долго выполняется прием данных.
HasErrors bool Указывает, представляет ли эта запись ошибку приема или нет.
OperationId guid Уникальный идентификатор, представляющий операцию. Можно использовать с командой .show operation.

Примечание.

Эта команда не изменяет схему приема таблицы. При необходимости данные преобразуются в эту схему во время приема, а не наоборот (дополнительные столбцы игнорируются, а отсутствующие столбцы обрабатываются как значения NULL).

Примеры

Хранилище BLOB-объектов Azure с подписанным URL-адресом

В следующем примере база данных будет считывать два больших двоичных объекта из Хранилище BLOB-объектов Azure в виде CSV-файлов и отправлять их содержимое в таблицуT. ... представляет собой подписанный URL-адрес (SAS) службы хранилища Azure, который предоставляет доступ на чтение к каждому большому двоичному объекту. Обратите внимание также на использование замаскированных строк (h перед строковыми значениями), чтобы гарантировать, что SAS никогда не будет записываться.

.ingest into table T (
    h'https://contoso.blob.core.windows.net/container/file1.csv?...',
    h'https://contoso.blob.core.windows.net/container/file2.csv?...'
)

Хранилище BLOB-объектов Azure с управляемым удостоверением

В следующем примере показано, как считывать CSV-файл из Хранилище BLOB-объектов Azure и отправлять его содержимое в таблицу T с помощью проверки подлинности управляемого удостоверения. Дополнительные сведения о методе проверки подлинности управляемого удостоверения см. в разделе "Обзор проверки подлинности управляемого удостоверения".

.ingest into table T ('https://StorageAccount.blob.core.windows.net/Container/file.csv;managed_identity=802bada6-4d21-44b2-9d15-e66b29e4d63e')

Azure Data Lake Storage 2-го поколения

Ниже приведен пример приема данных из Azure Data Lake Storage 2-го поколения (ADLSv2). Учетные данные, используемые здесь, (...) — это учетные данные учетной записи хранения (общий ключ), и мы используем маскировку строк только для секретной части строки подключения.

.ingest into table T (
  'abfss://myfilesystem@contoso.dfs.core.windows.net/path/to/file1.csv;...'
)

Azure Data Lake Storage

В следующем примере выполняется прием одного файла из Azure Data Lake Storage (ADLS). Он использует учетные данные пользователя для доступа к ADLS (поэтому нет необходимости обрабатывать универсальный код ресурса (URI) хранилища, содержащий секрет). Здесь также показано, как указать свойства приема.

.ingest into table T ('adl://contoso.azuredatalakestore.net/Path/To/File/file1.ext;impersonate')
  with (format='csv')

Amazon S3 с ключом доступа

В следующем примере выполняется прием одного файла из Amazon S3 с помощью идентификатора ключа доступа и секретного ключа доступа.

.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/path/to/file.csv;AwsCredentials=AKIAIOSFODNN7EXAMPLE,wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY')
  with (format='csv')

Amazon S3 с предварительно заданным URL-адресом

В следующем примере выполняется прием одного файла из Amazon S3 с помощью предварительного URL-адреса.

.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/file.csv?<<pre signed string>>')
  with (format='csv')