Использование LightIngest для приема данных в Azure Data Explorer

LightIngest — это программа командной строки для приема нерегламентированных данных в Azure Data Explorer. Служебная программа может извлекать исходные данные из локальной папки, контейнера хранилища BLOB-объектов Azure или контейнера Amazon S3.

LightIngest является наиболее полезным, если требуется принять большое количество данных, так как время приема не ограничивается. Это также полезно, если вы хотите позднее запрашивать записи в зависимости от времени их создания, а не времени их приема.

Пример автоматического создания команды LightIngest см . в журнале данных.

Примечание.

Максимальный размер принимаемого файла составляет 6 ГБ. Для приема мы советуем файлы размером от 100 МБ до 1 ГБ.

Необходимые компоненты

LightIngest. Получить LightIngest одним из двух способов:
- Скачайте двоичные файлы LightIngest для операционной системы. Распакуйте двоичные файлы после скачивания.
- Установите LightIngest в качестве средства .NET. Этот метод требует установки пакета SDK для .NET версии 6.0 или более поздней версии на компьютере. Затем выполните следующую команду:
```
dotnet tool install -g Microsoft.Azure.Kusto.LightIngest
```

Примечание.

Рекомендуется использовать команды приема в очереди, так как они не требуют установки программного обеспечения.

Запуск LightIngest

Чтобы запустить LightIngest, выполните следующую команду:

В командной строке введите LightIngest, затем соответствующий аргумент командной строки.

Совет

Чтобы получить список поддерживаемых аргументов командной строки, введите LightIngest /help.
Введите ingest-, затем строку подключения к кластеру Azure Data Explorer, который управляет приемом данных. Заключите строку подключения в двойные кавычки и следуйте указаниям спецификации строк подключения Kusto.

Например:
```
LightIngest "https://ingest-{Cluster name and region}.kusto.windows.net;Fed=True" -db:{Database} -table:Trips -source:"https://{Account}.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}" -pattern:"*.csv.gz" -format:csv -limit:2 -ignoreFirst:true -cr:10.0 -dontWait:true
```

Аргументы командной строки

Аргумент	Type	Описание	Обязательное поле
	`string`	Строка подключения Kusto, указывающий конечную точку Kusto, которая обрабатывает прием. Заключите это значение в двойные кавычки.	✔️
-база данных, -db	`string`	Целевое имя базы данных Azure Data Explorer.
-table	`string`	Целевое имя таблицы Azure Data Explorer.	✔️
-sourcePath, -source	`string`	Расположение исходных данных, которые могут быть локальным путем к файлу, корневым URI контейнера BLOB-объектов Azure или URI контейнера Amazon S3. Если данные хранятся в БОЛЬШИХ двоичных объектах Azure, URI должен включать ключ учетной записи хранения или подписанный URL-адрес (SAS). Если данные входят в контейнер S3, универсальный код ресурса (URI) должен содержать ключ учетных данных. Заключите это значение в двойные кавычки. Дополнительные сведения см. в строка подключения хранилища. Pass -sourcePath:; Олицетворения для перечисления элементов хранилища Azure с разрешениями пользователя (авторизация запроса пользователя).	✔️
-managedIdentity, -mi	`string`	Идентификатор клиента управляемого удостоверения (назначаемого пользователем или назначаемого системой) для подключения. Используйте system для удостоверения, назначаемого системой.
-azCli	`bool`	Если задано, для проверки подлинности в службе Kusto используется Azure CLI. Azure CLI должен быть установлен и выполнен вход в систему.
-ingestWithManagedIdentity, -ingestmi	`string`	Идентификатор клиента управляемого удостоверения (назначаемого пользователем или назначаемого системой) в службе Kusto для скачивания из хранилища. Используйте system для удостоверения, назначаемого системой.
-connectToStorageWithManagedIdentity, -storageMi	`string`	Идентификатор клиента управляемого удостоверения (назначаемого пользователем или назначаемого системой) на стороне клиента для перечисления из хранилища.
-connectToStorageWithUserAuth (подключиться к хранилищу с проверкой подлинности пользователя), -storageUserAuth (проверка подлинности пользователя хранилища)	`string`	Проверка подлинности в службе хранилища источников данных с учетными данными пользователя. Параметры этого значения имеют `PROMPT` или `DEVICE_CODE`.
-connectToStorageLoginUri, -storageLoginUri	`string`	Если `-connectToStorageWithUserAuth` задано, вы можете при желании указать унифицированный идентификатор ресурса (URI) для входа в систему Microsoft Entra ID.
-prefix	`string`	Если исходные данные для приема находятся в хранилище BLOB-объектов, этот префикс URL-адресов будет совместно использоваться всеми BLOB-объектами, за исключением имени контейнера. Например, если данные находятся в `MyContainer/Dir1/Dir2`, префикс должен иметь значение `Dir1/Dir2`. Заключите это значение в двойные кавычки.
-pattern	`string`	Шаблон, по которому выбираются исходные файлы и BLOB. Поддерживает подстановочные знаки. Например, `"*.csv"`. Заключите это значение в двойные кавычки.
-zipPattern	`string`	Регулярное выражение, используемое при выборе файлов в ZIP-архиве для приема. Все остальные файлы в архиве игнорируются. Например, `"*.csv"`. Заключите это значение в двойные кавычки.
-формат, -f	`string`	Формат исходных данных. Необходимо использовать один из поддерживаемых форматов
-ingestionMappingPath, -mappingPath	`string`	Путь к локальному файлу для сопоставления столбцов приема. Дополнительные сведения см. в разделе о сопоставлении данных.
-ingestionMappingRef, -mappingRef	`string`	Имя сопоставления столбцов загрузки данных, которое вы ранее создали в таблице. Дополнительные сведения см. в разделе о сопоставлении данных.
-creationTimePattern	`string`	Если задано, используется для извлечения свойства CreationTime из пути к файлу или BLOB-объекту. См. инструкции по приему данных с помощью `CreationTime`.
-ignoreFirstRow, -ignoreFirst	`bool`	Если задано, первая запись каждого файла или блоба игнорируется. Например, если исходные данные имеют заголовки.
-tag	`string`	Теги, связываемые с принятыми данными. Разрешено несколько вхождений
-dontWait	`bool`	Если задано значение `true`, не ожидает завершения приема. Полезно при приеме больших объемов файлов и двоичных объектов.
-compression, -cr	двойной точности	Указание коэффициента сжатия. Полезно при приеме сжатых файлов и двоичных объектов, чтобы помочь Azure Data Explorer оценить объем исходных данных. Вычисляется как исходный размер, разделенный сжатым размером.
-limit, -l	integer	Если задано, ограничивает прием до первых N-файлов .
-listOnly, -list	`bool`	Если задано, отображаются только элементы, которые будут выбраны для приема.
-ingestTimeout	integer	Время ожидания для выполнения всех операций приема (в минутах). По умолчанию — `60`.
-forceSync	`bool`	Если задано, инициирует синхронный прием данных. По умолчанию — `false`.
-интерактивный	`bool`	Если задано значение `false`, не запрашивает подтверждение аргументов. Для автоматических потоков и неинтерактивных сред. По умолчанию — `true`.
-dataBatchSize	integer	Задает общий размер (МБ, несжатый) каждой операции приема.
-filesInBatch	integer	Устанавливает ограничение на количество файлов и блобов для каждой операции загрузки.
-devTracing, -trace	`string`	Если задано, журналы диагностики записываются в локальный каталог (по умолчанию `RollingLogs` в текущем каталоге или могут быть изменены, задав значение переключателя).

Возможности, связанные с BLOB-объектами Azure

При использовании LightIngest с объектами blob Azure некоторые свойства метаданных BLOB-объектов используются для улучшения процесса интеграции.

Свойство метаданных	Использование
`rawSizeBytes`, `kustoUncompressedSizeBytes`	Если задано, LightIngest интерпретирует эти свойства как несжатый размер данных
`kustoCreationTime`, `kustoCreationTimeUtc`	LightIngest интерпретирует эти свойства как метку времени UTC. Если это значение установлено, эти свойства используются для переопределения времени создания в Kusto. Эта функция полезна для сценариев резервного заполнения

Примеры использования

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

Прием исторических данных с помощью свойства CreationTime

При загрузке исторических данных из существующей системы в Azure Data Explorer все записи получают одну и ту же дату приема. Чтобы секционировать данные по времени создания вместо времени приема, используйте -creationTimePattern аргумент. Аргумент -creationTimePattern извлекает свойство CreationTime из пути к файлу или BLOB-объекту. Шаблон не должен отражать весь путь к элементу, только раздел, который заключает метку времени, которую вы хотите использовать.

Значения аргумента должны включать:

Постоянный текст непосредственно перед форматом метки времени, заключенный в одинарные кавычки (префикс)
Формат метки времени в стандартной нотации .NET DateTime
Постоянный текст сразу после метки времени (суффикс).

Внимание

Если указать, что время создания должно быть переопределено, убедитесь Lookback , что свойство в действующей политике слияния целевой таблицы соответствует значениям в пути к файлу или BLOB-объектам.

Примеры

Имя BLOB-объекта, содержащего дату и время: historicalvalues19840101.parquet (отметка времени содержит четыре цифры для обозначения года, две цифры для обозначения месяца и две цифры для обозначения дня),

Значение аргумента -creationTimePattern является частью имени файла: "'historicalvalues'yyyyMMdd'.parquet'"
```
LightIngest "https://ingest-{Cluster name and region}.kusto.windows.net;Fed=True" -db:{Database} -table:Trips -source:"https://{Account}.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}" -creationTimePattern:"'historicalvalues'yyyyMMdd'.parquet'"
 -pattern:"*.parquet" -format:parquet -limit:2 -cr:10.0 -dontWait:true
```
Для URI BLOB-объекта, который ссылается на иерархическую структуру папок, например https://storageaccount/mycontainer/myfolder/2002/12/01/blobname.extension,

Значение аргумента -creationTimePattern является частью структуры папок: "'folder/'yyyy/MM/dd'/blob'"
```
  LightIngest "https://ingest-{Cluster name and region}.kusto.windows.net;Fed=True" -db:{Database} -table:Trips -source:"https://{Account}.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}" -creationTimePattern:"'mycontainer/myfolder/'yyyy/MM/dd'/'"
   -pattern:"*.csv.gz" -format:csv -limit:2 -ignoreFirst:true -cr:10.0 -dontWait:true
```

Импорт блобов с помощью ключа учетной записи хранилища или маркера SAS

Прием 10 BLOB-объектов в указанной учетной записи хранения ACCOUNT: в папке DIR в контейнере CONT и в соответствии с шаблоном *.csv.gz
Назначением является база данных DB, таблица TABLE, а сопоставление приема MAPPING создано в месте назначения
Средство ожидает завершения операций приема
Обратите внимание на различные параметры для указания целевой базы данных и ключа учетной записи хранения или маркера SAS

LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"https://ACCOUNT.blob.core.windows.net/{ROOT_CONTAINER};{StorageAccountKey}"
  -prefix:"DIR"
  -pattern:*.csv.gz
  -format:csv
  -mappingRef:MAPPING
  -limit:10

LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True;Initial Catalog=DB"
  -table:TABLE
  -source:"https://ACCOUNT.blob.core.windows.net/{ROOT_CONTAINER}?{SAS token}"
  -prefix:"DIR"
  -pattern:*.csv.gz
  -format:csv
  -mappingRef:MAPPING
  -limit:10

Прием всех BLOB-объектов в контейнере, кроме строк заголовков

Прием всех BLOB-объектов в указанной учетной записи хранения ACCOUNT: в папке DIR1/DIR2 в контейнере CONT и в соответствии с шаблоном *.csv.gz
Назначением является база данных DB, таблица TABLE, а сопоставление приема MAPPING создано в месте назначения
Исходные BLOB-объекты содержат строку заголовка, поэтому средство должно удалить первую запись каждого BLOB-объекта
Средство отправляет данные для приема и не ожидает завершения операций приема

LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"https://ACCOUNT.blob.core.windows.net/{ROOT_CONTAINER}?{SAS token}"
  -prefix:"DIR1/DIR2"
  -pattern:*.csv.gz
  -format:csv
  -mappingRef:MAPPING
  -ignoreFirstRow:true

Прием всех JSON-файлов из пути

Импорт всех файлов в пути PATH, которые соответствуют шаблону *.json
Задайте назначение для базы данных DB, таблицы TABLEи определите сопоставление приема в локальном файле MAPPING_FILE_PATH
Средство отправляет данные для приема и не ожидает завершения операций приема

LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"PATH"
  -pattern:*.json
  -format:json
  -mappingPath:"MAPPING_FILE_PATH"

Поглощение файлов и запись файлов трассировки для диагностики

Импорт всех файлов в пути PATH, которые соответствуют шаблону *.json
Задайте назначение для базы данных DB, таблицы TABLEи определите сопоставление приема в локальном файле MAPPING_FILE_PATH
Средство отправляет данные для приема и не ожидает завершения операций приема
Записывайте файлы трассировки диагностики локально в папке LOGS_PATH

LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"PATH"
  -pattern:*.json
  -format:json
  -mappingPath:"MAPPING_FILE_PATH"
  -trace:"LOGS_PATH"

Аутентификация на основе управляемых удостоверений

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

Подключитесь к кластеру Kusto: чтобы очередь приема, средство использует строка подключения. Используйте аргумент "-mi", чтобы указать управляемое удостоверение, установленное на клиентской виртуальной машине с привилегиями приема в целевой базе данных.
Подключитесь к служба хранилища Azure, чтобы скачать большие двоичные объекты: используйте "-ingestmi", чтобы указать управляемое удостоверение, установленное в службе Kusto, которая имеет права чтения в контейнере хранилища.
Подключитесь к служба хранилища Azure для перечисления больших двоичных объектов контейнеров: используйте аргумент "-storageMi", чтобы указать управляемое удостоверение, установленное на клиентской виртуальной машине с правами списка в контейнере хранилища. Если этот метод используется, но не предыдущий (подключение к хранилищу Azure для скачивания больших двоичных объектов), управляемое удостоверение должно иметь права чтения, а также маркер передается службе Kusto для приема. Задайте все три аргумента.

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2025-11-18