Прием из хранилища
Область применения: ✅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')