Прием .ingest
Применимо: ✅Microsoft Fabric✅Azure Data Explorer
Команда .ingest into прием данных в таблицу путем извлечения данных из одного или нескольких облачных файлов хранилища.
Например, команда может получить 1000 CSV-объектов, отформатированных из хранилища BLOB-объектов Azure, проанализировать их и объединить их в одну целевую таблицу.
Данные добавляются в таблицу, не затрагивая существующие записи и не изменяя схему таблицы.
Заметка
Этот метод приема предназначен для изучения и прототипирования. Не используйте его в рабочих или больших сценариях.
Заметка
Этот метод приема предназначен для изучения и прототипирования. Не используйте его в рабочих или больших сценариях. Дополнительные сведения о параметрах приема см. в обзоре приема данных.
Разрешения
Для выполнения этой команды необходимо иметь по крайней мере разрешения на таблицы Ingestor.
Синтаксис
.ingest [async] intotableTableNameSourceDataLocator [with(IngestionPropertyName=IngestionPropertyValue [, ...] )]
Дополнительные сведения о соглашениях синтаксиса.
Параметры
Заметка
Мы рекомендуем использовать
Свойства приема
Важный
Вприема данных в очереди
В следующей таблице перечислены и описываются поддерживаемые свойства и приведены примеры:
| Свойство | Описание | Пример |
|---|---|---|
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 |
Значение datetime (отформатировано как строка 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 |
Для команд приема из запроса папка, назначаемая таблице. Если таблица уже существует, это свойство переопределяет папку таблицы. | with (folder="Tables/Temporary") |
format |
Формат данных (см. поддерживаемые форматы данных). | with (format="csv") |
ingestIfNotExists |
Строковое значение, которое, если указано, не позволяет приему успешно завершиться, если в таблице уже есть данные с тегом 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") |
Проверка подлинности и авторизация
Каждая строка подключения к хранилищу указывает метод авторизации, используемый для доступа к хранилищу. В зависимости от метода авторизации субъекту может потребоваться предоставить разрешения на внешнее хранилище для приема.
В следующей таблице перечислены поддерживаемые методы проверки подлинности и разрешения, необходимые для приема данных из внешнего хранилища.
| Метод проверки подлинности | Хранилище BLOB-объектов Azure / Data Lake Storage 2-го поколения | Data Lake Storage 1-го поколения |
|---|---|---|
| олицетворения |
Средство чтения данных BLOB-объектов хранилища | Читатель |
| маркера общего доступа (SAS) |
Список и чтение | Этот метод проверки подлинности не поддерживается в 1-м поколениях. |
| маркера доступа Microsoft Entra | ||
| ключ доступа к учетной записи хранения | Этот метод проверки подлинности не поддерживается в 1-м поколениях. | |
| Управляемое удостоверение | Средство чтения данных BLOB-объектов хранилища | Читатель |
Возвращает
Результатом команды является таблица с таким количеством записей, как и сегменты данных ("экстенты"), созданные командой. Если сегменты данных не были созданы, то одна запись возвращается с пустым идентификатором экстентов (нулевое значение).
| Имя | Тип | Описание |
|---|---|---|
| ExtentId | guid |
Уникальный идентификатор сегмента данных, созданного командой. |
| ItemLoaded | string |
Один или несколько файлов хранилища, связанных с этой записью. |
| Длительность | timespan |
Сколько времени потребовалось для приема. |
| HasErrors | bool |
Указывает, представляет ли эта запись сбой приема. |
| OperationId | guid |
Уникальный идентификатор, представляющий операцию. Можно использовать с командой .show operation. |
Заметка
Эта команда не изменяет схему приема таблицы. При необходимости данные "принудятся" к этой схеме во время приема, а не наоборот (дополнительные столбцы игнорируются и отсутствующие столбцы обрабатываются как значения NULL).
Примеры
Хранилище BLOB-объектов Azure с подписанным URL-адресом
В следующем примере база данных будет считывать два больших двоичных объекта из хранилища BLOB-объектов Azure в виде CSV-файлов и отправлять их содержимое в таблицу T.
... представляет подписанный URL-адрес службы хранилища Azure (SAS), который предоставляет доступ для чтения к каждому большому двоичному объекту. Скрытые строки (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 с помощью проверки подлинности управляемого удостоверения. Проверка подлинности использует идентификатор управляемого удостоверения (идентификатор объекта), назначенный хранилищу BLOB-объектов Azure в Azure. Дополнительные сведения см. в статье Создание управляемого удостоверения для контейнеров хранилища.
.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')