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

  • Статья

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

Примечание

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

Разрешения

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

Синтаксис

.ingest [async] intotableTableNameSourceDataLocator [with(IngestionPropertyName=IngestionPropertyValue [, ...] )]

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

Параметры

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

Примечание

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

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

Важно!

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

Свойство. Описание Пример
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']")
validationPolicy Строка JSON, указывающая, какие проверки следует выполнять во время приема данных, представленных в формате CSV. Описание разных вариантов см. в разделе Прием данных. with (validationPolicy='{"ValidationOptions":1, "ValidationImplications":1}') (эта политика используется по умолчанию)
zipPattern Это свойство используется при приеме данных из хранилища, содержащего ZIP-архив. Это строковое значение содержит регулярное выражение для выбора принимаемых файлов из ZIP-архива. Все остальные файлы в архиве будут игнорироваться. with (zipPattern="*.csv")

Аутентификация и авторизация

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

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

Метод проверки подлинности Хранилище 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')