Verwenden von LightIngest zum Erfassen von Daten in Azure Data Explorer

LightIngest ist ein Befehlszeilen-Hilfsprogramm für die Ad-hoc-Datenerfassung in Azure Data Explorer. Das Hilfsprogramm kann Quelldaten aus einem lokalen Ordner, einem Azure Blob Storage-Container oder einem Amazon S3-Bucket abrufen.

LightIngest ist besonders bei der Erfassung großer Datenmengen hilfreich, da die Erfassung zeitlich nicht beschränkt ist. LightIngest ist außerdem nützlich, wenn Sie Datensätze später anhand des Erstellungszeitpunkts und nicht anhand des Erfassungszeitpunkts abfragen möchten.

Ein Beispiel zum automatischen Generieren eines LightIngest-Befehls finden Sie unter Historische Daten erfassen.

Voraussetzungen

• LightIngest. Es gibt zwei Möglichkeiten, LightIngest zu erhalten:

  • Laden Sie LightIngest-Binärdateien für Ihr Betriebssystem herunter. Stellen Sie sicher, dass Sie die Binärdateien nach dem Download entpacken.

  • Installieren Sie LightIngest als .NET-Tool. Für diese Methode ist erforderlich, dass sie auf Ihrem Computer .NET SDK Version 6.0 oder höher installiert haben. Führen Sie dann den folgenden Befehl aus:

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

Ausführen von LightIngest

So führen Sie LightIngest aus:

1. Geben Sie an der Eingabeaufforderung LightIngest ein, gefolgt vom entsprechenden Befehlszeilenargument.

   Tipp

   Eine Liste der unterstützten Befehlszeilenargumente erhalten Sie durch Eingeben von LightIngest /help.

2. Geben Sie ingest- gefolgt von der Verbindungszeichenfolge für den Azure Data Explorer-Cluster ein, in dem die Datenerfassung verwaltet wird. Setzen Sie die Verbindungszeichenfolge in doppelte Anführungszeichen, und befolgen Sie die Spezifikation für Kusto-Verbindungszeichenfolgen.

   Zum Beispiel:

   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
   

Empfehlungen zur Leistung

• Um die Erfassungslast optimal zu verwalten und vorübergehende Fehler zu beheben, verwenden Sie den Erfassungsendpunkt unter https://ingest-{yourClusterNameAndRegion}.kusto.windows.net.

• Für eine optimale Erfassungsleistung ist die Rohdatengröße erforderlich, sodass in LightIngest die nicht komprimierte Größe der lokalen Dateien geschätzt werden kann. Allerdings kann die Größe der Rohdaten der komprimierten Blobs in LightIngest möglicherweise erst nach dem Herunterladen der Blobs korrekt geschätzt werden. Legen Sie daher bei der Erfassung von komprimierten Blobs die rawSizeBytes-Eigenschaft für die Blobmetadaten auf die nicht komprimierte Datengröße in Byte fest.

Befehlszeilenargumente

Für Azure-Blobs spezifische Funktionen

Bei Verwendung mit Azure-Blobs werden in LightIngest bestimmte Blob-Metadateneigenschaften verwendet, um den Erfassungsprozess zu erweitern.

Anwendungsbeispiele

In den folgenden Beispielen wird davon ausgegangen, dass Sie LightIngest-Binärdateien für Ihr Betriebssystem installiert haben. Wenn Sie LightIngest als .NET-Tool installiert haben, ersetzen Sie LightIngest durch LightIngest in den Beispielen.

Erfassen von historischen Daten mit der CreationTime-Eigenschaft

Wenn Sie Verlaufsdaten aus einem vorhandenen System in Azure Data Explorer laden, erhalten alle Datensätze dasselbe Erfassungsdatum. Sie können das Argument -creationTimePattern verwenden, um die Partitionierung Ihrer Daten basierend auf der Erstellungszeit und nicht der Erfassungszeit zu ermöglichen. Mit dem Argument -creationTimePattern wird die CreationTime-Eigenschaft aus dem Datei- oder Blobpfad extrahiert. Das Muster muss nicht den gesamten Elementpfad darstellen, sondern lediglich den Abschnitt, der den zu verwendenden Zeitstempel enthält.

Die Argumentwerte müssen Folgendes enthalten:

• Konstanter Text direkt vor dem Zeitstempelformat, in einfache Anführungszeichen eingeschlossen (Präfix)
• Zeitstempelformat in der standardmäßigen .NET-DateTime-Notation
• Konstanter Text direkt nach dem Zeitstempel (Suffix)

Beispiele

• Ein Blobname, der Datum und Uhrzeit im folgenden Format enthält: historicalvalues19840101.parquet. (Der Zeitstempel setzt sich aus vier Ziffern für das Jahr sowie jeweils zwei Ziffern für Monat und Tag zusammen.)

  Der Wert für das Argument -creationTimePattern ist Teil des Dateinamens: '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
  

• Bei einem Blob-URI, der sich auf eine hierarchische Ordnerstruktur bezieht (etwa https://storageaccount/mycontainer/myfolder/2002/12/01/blobname.extension):

  Der Wert für das Argument -creationTimePattern ist Teil der Ordnerstruktur: '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
  

Erfassen von Blobs mithilfe eines Speicherkontoschlüssels oder eines SAS-Tokens

• Erfassen von 10 Blobs unter dem angegebenen Speicherkonto ACCOUNT im Ordner DIR unter dem Container CONT und in Übereinstimmung mit dem Muster *.csv.gz
• Ziel ist die Datenbank DB, Tabelle TABLE, und die Erfassungszuordnung MAPPING, die im Ziel vorab erstellt wurde.
• Das Tool wartet, bis die Erfassungsvorgänge abgeschlossen wurden
• Beachten Sie die unterschiedlichen Optionen zum Angeben der Zieldatenbank und des Speicherkontoschlüssels im Vergleich zum SAS-Token

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

Erfassen aller Blobs in einem Container, ohne Headerzeilen

• Erfassen aller Blobs unter dem angegebenen Speicherkonto ACCOUNT im Ordner DIR1/DIR2 unter dem Container CONT und in Übereinstimmung mit dem Muster *.csv.gz
• Ziel ist die Datenbank DB, Tabelle TABLE, und die Erfassungszuordnung MAPPING, die im Ziel vorab erstellt wurde.
• Die Quellblobs enthalten eine Headerzeile. Daher wird das Tool angewiesen, den ersten Datensatz jedes Blobs zu ignorieren.
• Das Tool stellt die Daten für die Erfassung bereit und wartet nicht, bis die Erfassungsvorgänge abgeschlossen wurden

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

Erfassen aller JSON-Dateien unter einem Pfad

• Erfassen aller Dateien unter dem Pfad PATH in Übereinstimmung mit dem Muster *.json
• Ziel ist die Datenbank DB, Tabelle TABLE, und die Erfassungszuordnung wird in der lokalen Datei MAPPING_FILE_PATH definiert.
• Das Tool stellt die Daten für die Erfassung bereit und wartet nicht, bis die Erfassungsvorgänge abgeschlossen wurden

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

Erfassen von Dateien und Schreiben von Diagnosedateien für die Ablaufverfolgung

• Erfassen aller Dateien unter dem Pfad PATH in Übereinstimmung mit dem Muster *.json
• Ziel ist die Datenbank DB, Tabelle TABLE, und die Erfassungszuordnung wird in der lokalen Datei MAPPING_FILE_PATH definiert.
• Das Tool stellt die Daten für die Erfassung bereit und wartet nicht, bis die Erfassungsvorgänge abgeschlossen wurden
• Diagnosedateien für die Ablaufverfolgung werden lokal in den Ordner LOGS_PATH geschrieben

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"

Authentifizierung mit verwalteter Identität

LightIngest führt drei Aktionen durch, die verwaltete Identitäten zur Authentifizierung verwenden können. Die Verwendung der verwalteten Identität in jedem Schritt erfordert keine Verwendung der verwalteten Identität in anderen Schritten. Für jede Aktion wird das zugehörige Befehlszeilenargument angegeben.

• Herstellen einer Verbindung mit dem Kusto-Cluster: Um die Aufnahme in die Warteschlange zu stellen, verwendet das Tool eine Verbindungszeichenfolge. Verwenden Sie das Argument „-mi“, um eine verwaltete Identität anzugeben, die auf der Client-VM installiert ist, die Erfassungsberechtigungen in der Zieldatenbank hat.

• Herstellen einer Verbindung mit Azure Storage her zum Herunterzuladen von Blobs: Verwenden Sie „-ingestmi“, um eine verwaltete Identität anzugeben, die auf dem Kusto-Dienst mit Leseberechtigungen für den Speichercontainer installiert ist.

• Herstellen einer Verbindung mit Azure Storage zum Auflisten von Container-Blobs: Verwenden Sie das Argument „-storageMi“, um eine verwaltete Identität anzugeben, die auf dem virtuellen Clientcomputer mit Listenrechten für den Speichercontainer installiert ist. Wenn Sie diese Methode verwenden, jedoch nicht die vorherige (Herstellen einer Verbindung mit Azure Storage her zum Herunterzuladen von Blobs), muss die verwaltete Identität ebenfalls über Leserechte verfügen, und ein Token wird an den Kusto-Dienst übergeben, der für die Erfassung verwendet wird. Daher wird empfohlen, alle drei Argumente festzulegen.