Share via

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

  • Статья

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

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

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

Примечание

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

Предварительные требования

Запуск LightIngest

Чтобы запустить LightIngest, выполните приведенные далее действия.

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

    Совет

    Чтобы получить список поддерживаемых аргументов командной строки, введите LightIngest /help.

  2. Введите 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

Рекомендации по производительности

  • Для оптимального управления нагрузкой приема и восстановления после временных ошибок используйте конечную точку приема по адресу https://ingest-{yourClusterNameAndRegion}.kusto.windows.net.

  • Для оптимальной производительности приема необходим размер необработанных данных, поэтому LightIngest может оценить размер несжатых локальных файлов. Однако LightIngest может неправильно оценить исходный размер сжатых BLOB-объектов до их загрузки. Поэтому при приеме сжатых BLOB-объектов задайте свойство rawSizeBytesв метаданных BLOB-объекта в качестве размера несжатых данных в байтах.

аргументов командной строки;

Аргумент Тип Описание Обязательно
string Строка подключения Kusto, указывающий конечную точку Kusto, которая обрабатывает прием. Это значение должно быть заключено в двойные кавычки. ✔️
-database, -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 для удостоверения, назначаемого системой.
-ingestWithManagedIdentity, -imgestmi string Идентификатор клиента управляемого удостоверения (назначаемого пользователем или системой), используемого для подключения. Используйте system для удостоверения, назначаемого системой.
-connectToStorageWithUserAuth, -storageUserAuth string Проверка подлинности в службе хранилища источника данных с учетными данными пользователя. Для этого значения используются PROMPT параметры или DEVICE_CODE.
-connectToStorageLoginUri, -storageLoginUri string Если -connectToStorageWithUserAuth параметр задан, при необходимости можно указать Microsoft Entra ID URI входа.
-prefix string Если исходные данные для приема находятся в хранилище BLOB-объектов, этот префикс URL-адресов будет совместно использоваться всеми BLOB-объектами, за исключением имени контейнера.
Например, если данные находятся в MyContainer/Dir1/Dir2, префикс должен иметь значение Dir1/Dir2. Рекомендуется заключать это значение в двойные кавычки.
-pattern string Шаблон, по которому выбираются исходные файлы и BLOB-объекты. Поддерживает подстановочные знаки. Например, "*.csv". Рекомендуется заключать это значение в двойные кавычки.
-zipPattern string Регулярное выражение, используемое при выборе файлов в ZIP-архиве для приема. Все остальные файлы в архиве будут игнорироваться. Например, "*.csv". Рекомендуется заключать это значение в двойные кавычки.
-format, -f string Формат исходных данных. Необходимо использовать один из поддерживаемых форматов
-ingestionMappingPath, -mappingPath string Путь к локальному файлу для сопоставления столбцов приема. Дополнительные сведения см. в разделе о сопоставлении данных.
-ingestionMappingRef, -mappingRef string Имя сопоставления столбца приема, созданного ранее в таблице. Дополнительные сведения см. в разделе о сопоставлении данных.
-creationTimePattern string Если задано, используется для извлечения свойства CreationTime из пути к файлу или BLOB-объекту. См . раздел Прием данных с помощью CreationTime.
-ignoreFirstRow, -ignoreFirst bool Если задано значение , первая запись каждого файла или большого двоичного объекта игнорируется. Например, если исходные данные имеют заголовки.
-tag string Теги, связываемые с принятыми данными. Разрешено несколько вхождений
-dontWait bool Если задано значение true, не ожидает завершения приема. Полезно при приеме больших объемов файлов или BLOB-объектов.
-compression, -cr double Указание коэффициента сжатия. Полезно при приеме сжатых файлов и BLOB-объектов, чтобы помочь Azure Data Explorer оценить размер необработанных данных. Вычисляется как исходный размер, разделенный на сжатый размер.
-limit, -l Целое число Если этот параметр задан, ограничивает прием до первых N файлов.
-listOnly, -list bool Если задано значение , отображает только те элементы, которые были выбраны для приема.
-ingestTimeout Целое число Время ожидания для выполнения всех операций приема (в минутах). По умолчанию — 60.
-forceSync bool Если задано, инициирует синхронный прием данных. По умолчанию — false.
-Интерактивная bool Если задано значение false, не запрашивает подтверждение аргументов. Для автоматических потоков и неинтерактивных сред. По умолчанию — true.
-dataBatchSize Целое число Задает общий размер (МБ, без сжатия) каждой операции приема.
-filesInBatch Целое число Задает ограничение количества файлов и BLOB-объектов для каждой операции приема.
-devTracing, -trace string Если этот параметр задан, журналы диагностики записываются в локальный каталог (по умолчанию RollingLogs в текущем каталоге или могут быть изменены, задав значение параметра).

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

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

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

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

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

Прием исторических данных с помощью свойства 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

Прием BLOB-объектов с помощью ключа учетной записи хранения или маркера 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"