LightIngest gebruiken om gegevens op te nemen in Azure Data Explorer

Artikel
01/23/2024

LightIngest is een opdrachtregelprogramma voor ad-hocgegevensopname in Azure Data Explorer. Het hulpprogramma kan brongegevens ophalen uit een lokale map, een Azure Blob Storage-container of een Amazon S3-bucket.

LightIngest is het handigst als u een grote hoeveelheid gegevens wilt opnemen, omdat er geen tijdsbeperking is voor de opnameduur. Het is ook handig als u later een query wilt uitvoeren op records op basis van het tijdstip waarop ze zijn gemaakt en niet op het tijdstip waarop ze zijn opgenomen.

Zie Historische gegevens opnemen voor een voorbeeld van het automatisch genereren van een LightIngest-opdracht.

Notitie

Opname ondersteunt een maximale bestandsgrootte van 6 GB. Het wordt aanbevolen om bestanden tussen 100 MB en 1 GB op te nemen.

Vereisten

LightIngest. Er zijn twee manieren om LightIngest te verkrijgen:
- Download binaire lightIngest-bestanden voor uw besturingssysteem. Zorg ervoor dat u de binaire bestanden na het downloaden uitpakt.
- Installeer LightIngest als een .NET-hulpprogramma. Voor deze methode moet .NET SDK versie 6.0 of hoger op uw computer zijn geïnstalleerd. Voer vervolgens de volgende opdracht uit:
```
dotnet tool install -g Microsoft.Azure.Kusto.LightIngest
```

LightIngest uitvoeren

LightIngest uitvoeren:

Voer bij de opdrachtprompt in LightIngest , gevolgd door het relevante opdrachtregelargument.

Tip

Voer in LightIngest /helpvoor een lijst met ondersteunde opdrachtregelargumenten.

Voer iningest-, gevolgd door de verbindingsreeks naar het Azure Data Explorer-cluster dat de opname beheert. Plaats de verbindingsreeks tussen dubbele aanhalingstekens en volg de kusto-verbindingsreeksspecificatie.

Bijvoorbeeld:

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

Aanbevelingen voor prestaties

Als u de opnamebelasting zo goed mogelijk wilt beheren en tijdelijke fouten wilt herstellen, gebruikt u het opname-eindpunt op https://ingest-{yourClusterNameAndRegion}.kusto.windows.net.
Voor optimale opnameprestaties is de grootte van onbewerkte gegevens nodig, zodat LightIngest de niet-gecomprimeerde grootte van lokale bestanden kan schatten. LightIngest kan de onbewerkte grootte van gecomprimeerde blobs echter niet correct schatten zonder ze eerst te downloaden. Stel daarom bij het opnemen van gecomprimeerde blobs de rawSizeBytes eigenschap voor de metagegevens van de blob in op niet-gecomprimeerde gegevensgrootte in bytes.

Opdrachtregelargumenten

Argument	Type	Beschrijving	Vereist
	`string`	Een Kusto-verbindingsreeks waarin het Kusto-eindpunt wordt opgegeven dat de opname verwerkt. Deze waarde moet tussen dubbele aanhalingstekens staan.	✔️
-database, -db	`string`	De naam van de doeldatabase van Azure Data Explorer.
-Tabel	`string`	De naam van de azure-doeltabel Data Explorer.	✔️
-sourcePath, -source	`string`	De locatie van de brongegevens. Dit kan een lokaal bestandspad, de hoofd-URI van een Azure-blobcontainer of de URI van een Amazon S3-bucket zijn. Als de gegevens zijn opgeslagen in Azure-blobs, moet de URI de sleutel van het opslagaccount of de Shared Access Signature (SAS) bevatten. Als de gegevens zich in een S3-bucket bevinden, moet de URI de referentiesleutel bevatten. We raden u aan deze waarde tussen dubbele aanhalingstekens te plaatsen. Zie Opslagverbindingsreeksen voor meer informatie. Pass -sourcePath:; imiteren om Azure-opslagitems met gebruikersmachtigingen weer te geven (autorisatie van gebruikersprompt).	✔️
-managedIdentity, -mi	`string`	Client-id van de beheerde identiteit (door de gebruiker toegewezen of door het systeem toegewezen) die moet worden gebruikt om verbinding te maken. Gebruik 'systeem' voor door het systeem toegewezen identiteit.
-ingestWithManagedIdentity, -imgestmi	`string`	Client-id van de beheerde identiteit (door de gebruiker toegewezen of door het systeem toegewezen) die moet worden gebruikt om verbinding te maken. Gebruik 'systeem' voor door het systeem toegewezen identiteit.
-connectToStorageWithUserAuth, -storageUserAuth	`string`	Verifieer met gebruikersreferenties bij de gegevensbronopslagservice. De opties voor deze waarde zijn `PROMPT` of `DEVICE_CODE`.
-connectToStorageLoginUri, -storageLoginUri	`string`	Als `-connectToStorageWithUserAuth` is ingesteld, kunt u desgewenst een Microsoft Entra ID aanmeldings-URI opgeven.
-Voorvoegsel	`string`	Wanneer de op te nemen brongegevens zich in blobopslag bevinden, wordt dit URL-voorvoegsel gedeeld door alle blobs, met uitzondering van de containernaam. Als de gegevens zich bijvoorbeeld in `MyContainer/Dir1/Dir2`bevinden, moet het voorvoegsel zijn `Dir1/Dir2`. We raden u aan deze waarde tussen dubbele aanhalingstekens te plaatsen.
-Patroon	`string`	Patroon waarmee bronbestanden/blobs worden gekozen. Ondersteunt jokertekens. Bijvoorbeeld `"*.csv"`. We raden u aan deze waarde tussen dubbele aanhalingstekens te plaatsen.
-zipPatroon	`string`	Reguliere expressie die moet worden gebruikt bij het selecteren van de bestanden in een ZIP-archief om op te nemen. Alle andere bestanden in het archief worden genegeerd. Bijvoorbeeld `"*.csv"`. We raden u aan deze waarde tussen dubbele aanhalingstekens te plaatsen.
-format, -f	`string`	Brongegevensindeling. Moet een van de ondersteunde indelingen zijn
-ingestionMappingPath, -mappingPath	`string`	Een pad naar een lokaal bestand voor toewijzing van opnamekolommen. Zie gegevenstoewijzingen.
-ingestionMappingRef, -mappingRef	`string`	De naam van een opnamekolomtoewijzing die eerder in de tabel is gemaakt. Zie gegevenstoewijzingen.
-creationTimePattern	`string`	Indien ingesteld, wordt gebruikt om de eigenschap CreationTime uit het bestand of blobpad te extraheren. Zie Gegevens opnemen met behulp van `CreationTime`.
-ignoreFirstRow, -ignoreFirst	`bool`	Als dit is ingesteld, wordt de eerste record van elk bestand/blob genegeerd. Bijvoorbeeld als de brongegevens headers bevatten.
-Tag	`string`	Tags die moeten worden gekoppeld aan de opgenomen gegevens. Meerdere exemplaren zijn toegestaan
-dontWait	`bool`	Als dit is ingesteld op `true`, wacht niet totdat de opname is voltooid. Handig bij het opnemen van grote hoeveelheden bestanden/blobs.
-compressie, -cr	double	Hint voor compressieverhouding. Handig bij het opnemen van gecomprimeerde bestanden/blobs om Azure Data Explorer te helpen de grootte van onbewerkte gegevens te beoordelen. Berekend als oorspronkelijke grootte gedeeld door gecomprimeerde grootte.
-limit, -l	geheel getal	Als deze optie is ingesteld, wordt de opname beperkt tot de eerste N-bestanden .
-listOnly, -list	`bool`	Als deze optie is ingesteld, worden alleen de items weergegeven die voor opname zijn geselecteerd.
-ingestTimeout	geheel getal	Time-out in minuten voor het voltooien van alle opnamebewerkingen. De standaardwaarde is `60`.
-forceSync	`bool`	Indien ingesteld, dwingt synchrone opname. De standaardwaarde is `false`.
-Interactieve	`bool`	Als dit is ingesteld op `false`, wordt niet om bevestiging van argumenten gevraagd. Voor stromen zonder toezicht en niet-interactieve omgevingen. De standaardinstelling is `true`.
-dataBatchSize	geheel getal	Hiermee stelt u de totale groottelimiet (MB, niet-gecomprimeerd) van elke opnamebewerking in.
-filesInBatch	geheel getal	Hiermee stelt u de limiet voor het aantal bestanden/blob's van elke opnamebewerking in.
-devTracing, -trace	`string`	Als dit is ingesteld, worden diagnostische logboeken naar een lokale map geschreven (standaard `RollingLogs` in de huidige map, of kunnen worden gewijzigd door de switchwaarde in te stellen).

Azure Blob-specifieke mogelijkheden

Bij gebruik met Azure-blobs gebruikt LightIngest bepaalde eigenschappen van blobmetagegevens om het opnameproces te verbeteren.

Eigenschap Metagegevens	Gebruik
`rawSizeBytes`, `kustoUncompressedSizeBytes`	Indien ingesteld, wordt geïnterpreteerd als de niet-gecomprimeerde gegevensgrootte
`kustoCreationTime`, `kustoCreationTimeUtc`	Geïnterpreteerd als UTC-tijdstempel. Indien ingesteld, wordt gebruikt om de aanmaaktijd in Kusto te overschrijven. Handig voor backfilling-scenario's

Gebruiksvoorbeelden

In de volgende voorbeelden wordt ervan uitgegaan dat u binaire lightIngest-bestanden voor uw besturingssysteem hebt geïnstalleerd. Als u LightIngest hebt geïnstalleerd als een .NET-hulpprogramma, vervangt u LightIngestLightIngest door in de voorbeelden.

Historische gegevens opnemen met de eigenschap CreationTime

Wanneer u historische gegevens uit een bestaand systeem laadt naar Azure Data Explorer, ontvangen alle records dezelfde opnamedatum. Als u het partitioneren van uw gegevens wilt inschakelen op basis van aanmaaktijd en niet op opnametijd, kunt u het -creationTimePattern argument gebruiken. Met -creationTimePattern het argument wordt de CreationTime eigenschap uit het bestand of het blobpad geëxtraheerd. Het patroon hoeft niet het hele itempad weer te geven, alleen de sectie met de tijdstempel die u wilt gebruiken.

De argumentwaarden moeten het volgende bevatten:

Constante tekst direct voorafgaand aan de tijdstempelnotatie, tussen enkele aanhalingstekens (voorvoegsel)
De tijdstempelindeling, in standaard .NET DateTime-notatie
Constante tekst direct na het tijdstempel (achtervoegsel).

Belangrijk

Wanneer u opgeeft dat de aanmaaktijd moet worden overschreven, moet u ervoor zorgen dat de Lookback eigenschap in het effectieve samenvoegbeleid van de doeltabel is afgestemd op de waarden in uw bestand of blobpaden.

Voorbeelden

Een blobnaam die de datum/tijd als volgt bevat: historicalvalues19840101.parquet (het tijdstempel is vier cijfers voor het jaar, twee cijfers voor de maand en twee cijfers voor de dag van de maand),

De waarde voor -creationTimePattern argument maakt deel uit van de bestandsnaam: "'historicalvalues'yyyyyMMMdd'.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

Voor een blob-URI die verwijst naar hiërarchische mapstructuur, zoals https://storageaccount/mycontainer/myfolder/2002/12/01/blobname.extension,

De waarde voor -creationTimePattern argument maakt deel uit van de mapstructuur: 'folder/'jjjj/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

Blobs opnemen met behulp van een opslagaccountsleutel of een SAS-token

10 blobs opnemen onder het opgegeven opslagaccount ACCOUNT, in map DIR, onder container CONTen overeenkomend met het patroon *.csv.gz
Doel is database DB, tabel TABLEen de opnametoewijzing MAPPING wordt vooraf gemaakt op het doel
Het hulpprogramma wacht totdat de opnamebewerkingen zijn voltooid
Let op de verschillende opties voor het opgeven van de doeldatabase en opslagaccountsleutel versus 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

Alle blobs in een container opnemen, exclusief veldnamenrijen

Alle blobs opnemen onder het opgegeven opslagaccount ACCOUNT, in map DIR1/DIR2, onder container CONTen overeenkomend met het patroon *.csv.gz
Doel is database DB, tabel TABLEen de opnametoewijzing MAPPING wordt vooraf gemaakt op het doel
Bron-blobs bevatten headerregel, dus het hulpprogramma wordt geïnstrueerd om de eerste record van elke blob te verwijderen
Het hulpprogramma plaatst de gegevens voor opname en wacht niet tot de opnamebewerkingen zijn voltooid

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

Alle JSON-bestanden van een pad opnemen

Alle bestanden opnemen onder pad PATH, overeenkomend met het patroon *.json
Doel is database DB, tabel TABLEen de opnametoewijzing is gedefinieerd in het lokale bestand MAPPING_FILE_PATH
Het hulpprogramma plaatst de gegevens voor opname en wacht niet tot de opnamebewerkingen zijn voltooid

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

Bestanden opnemen en diagnostische traceringsbestanden schrijven

Alle bestanden opnemen onder pad PATH, overeenkomend met het patroon *.json
Doel is database DB, tabel TABLEen de opnametoewijzing is gedefinieerd in het lokale bestand MAPPING_FILE_PATH
Het hulpprogramma plaatst de gegevens voor opname en wacht niet tot de opnamebewerkingen zijn voltooid
Diagnostische traceringsbestanden worden lokaal geschreven onder map 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"

Delen via