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

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

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

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

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

• LightIngest. Существует два способа получения LightIngest:

  • Скачайте двоичные файлы LightIngest для операционной системы. Распакуйте двоичные файлы после скачивания.

  • Установите LightIngest в качестве средства .NET. Этот метод требует установки пакета SDK для .NET версии 6.0 или более поздней версии на компьютере. Затем выполните следующую команду:

    dotnet tool install -g Microsoft.Azure.Kusto.LightIngest
    

Запуск 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-объекта в качестве размера несжатых данных в байтах.

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

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

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

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

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

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

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

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

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

Примеры

• Имя 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"

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

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

• Подключитесь к кластеру Kusto: чтобы очередь приема, средство использует строка подключения. Используйте аргумент "-mi", чтобы указать управляемое удостоверение, установленное на клиентской виртуальной машине с привилегиями приема в целевой базе данных.

• Подключитесь к служба хранилища Azure, чтобы скачать большие двоичные объекты: используйте "-ingestmi", чтобы указать управляемое удостоверение, установленное в службе Kusto, которая имеет права чтения в контейнере хранилища.

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