Pozyskiwanie danych do usługi Azure Data Explorer przy użyciu narzędzia LightIngest

  • Artykuł

LightIngest to narzędzie wiersza polecenia do pozyskiwania danych ad hoc do usługi Azure Data Explorer. Narzędzie może ściągać dane źródłowe z folderu lokalnego, kontenera usługi Azure Blob Storage lub zasobnika Amazon S3.

LightIngest jest najbardziej przydatne, gdy chcesz pozyskać dużą ilość danych, ponieważ nie ma ograniczenia czasu na czas pozyskiwania. Jest to również przydatne, gdy chcesz później wykonywać zapytania dotyczące rekordów zgodnie z czasem ich utworzenia, a nie czasem pozyskiwania.

Aby zapoznać się z przykładem automatycznego generowania polecenia LightIngest, zobacz pozyskiwanie danych historycznych.

Uwaga

Maksymalny rozmiar pliku obsługiwany w pozyskiwaniu wynosi 6 GB. Zaleca się pozyskiwanie plików z zakresu od 100 MB do 1 GB.

Wymagania wstępne

Uruchamianie najjaśniejszego

Aby uruchomić lightIngest:

  1. W wierszu polecenia wprowadź LightIngest ciąg , a następnie odpowiedni argument wiersza polecenia.

    Porada

    Aby uzyskać listę obsługiwanych argumentów wiersza polecenia, wprowadź .LightIngest /help

  2. Wprowadź ingest- ciąg , a następnie parametry połączenia do klastra usługi Azure Data Explorer, który będzie zarządzać pozyskiwaniem danych. Należy ująć parametry połączenia w cudzysłowy i postępować zgodnie ze specyfikacją parametrów połączenia kusto.

    Na przykład:

    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

Zalecenia dotyczące wydajności

  • Aby jak najlepiej zarządzać obciążeniem pozyskiwania i odzyskiwać dane po błędach przejściowych, użyj punktu końcowego pozyskiwania w lokalizacji https://ingest-{yourClusterNameAndRegion}.kusto.windows.net.

  • Aby uzyskać optymalną wydajność pozyskiwania, wymagany jest rozmiar danych pierwotnych, dzięki czemu lightIngest może oszacować nieskompresowany rozmiar plików lokalnych. Jednak lightIngest może nie być w stanie poprawnie oszacować nieprzetworzonego rozmiaru skompresowanych obiektów blob bez uprzedniego ich pobrania. W związku z tym podczas pozyskiwania skompresowanych obiektów blob ustaw rawSizeBytes właściwość metadanych obiektu blob na nieskompresowany rozmiar danych w bajtach.

Argumenty wiersza polecenia

Argument Typ Opis Wymagane
string Usługa Kusto parametry połączenia określająca punkt końcowy usługi Kusto, który obsługuje pozyskiwanie. Ta wartość powinna być ujęta w cudzysłowy. ✔️
-database, -db string Docelowa nazwa bazy danych usługi Azure Data Explorer.
-Tabeli string Docelowa nazwa tabeli usługi Azure Data Explorer. ✔️
-sourcePath, -source string Lokalizacja danych źródłowych, które mogą być lokalną ścieżką pliku, głównym identyfikatorem URI kontenera obiektów blob platformy Azure lub identyfikatorem URI zasobnika Amazon S3. Jeśli dane są przechowywane w obiektach blob platformy Azure, identyfikator URI musi zawierać klucz konta magazynu lub sygnaturę dostępu współdzielonego (SAS). Jeśli dane znajdują się w zasobniku S3, identyfikator URI musi zawierać klucz poświadczeń. Zalecamy ujęcie tej wartości w cudzysłów podwójnych. Aby uzyskać więcej informacji, zobacz Storage connection strings (Parametry połączenia usługi Storage). Pass -sourcePath:; personifikuj się, aby wyświetlić listę elementów usługi Azure Storage z uprawnieniami użytkownika (autoryzacja monitu użytkownika). ✔️
-managedIdentity, -mi string Identyfikator klienta tożsamości zarządzanej (przypisanej przez użytkownika lub przypisaną przez system) do użycia na potrzeby nawiązywania połączenia. Użyj "system" dla tożsamości przypisanej przez system.
-ingestWithManagedIdentity, -imgestmi string Identyfikator klienta tożsamości zarządzanej (przypisanej przez użytkownika lub przypisaną przez system) do użycia na potrzeby nawiązywania połączenia. Użyj "system" dla tożsamości przypisanej przez system.
-connectToStorageWithUserAuth, -storageUserAuth string Uwierzytelnij się w usłudze magazynu źródła danych przy użyciu poświadczeń użytkownika. Opcje dla tej wartości to PROMPT lub DEVICE_CODE.
-connectToStorageLoginUri, -storageLoginUri string W przypadku -connectToStorageWithUserAuth ustawienia możesz opcjonalnie podać identyfikator URI logowania Tożsamość Microsoft Entra.
-Prefiks string Gdy dane źródłowe do pozyskiwania znajdują się w magazynie obiektów blob, ten prefiks adresu URL jest współużytkowany przez wszystkie obiekty blob, z wyjątkiem nazwy kontenera.
Jeśli na przykład dane są w MyContainer/Dir1/Dir2elemecie , prefiks powinien mieć Dir1/Dir2wartość . Zalecamy ujęcie tej wartości w cudzysłów podwójnych.
-Wzór string Wzorzec, według którego są wybierane pliki źródłowe/obiekty blob. Obsługuje symbole wieloznaczne. Na przykład "*.csv". Zalecamy ujęcie tej wartości w cudzysłów podwójnych.
-zipPattern string Wyrażenie regularne do użycia podczas wybierania plików w archiwum ZIP do pozyskiwania. Wszystkie inne pliki w archiwum zostaną zignorowane. Na przykład "*.csv". Zalecamy ujęcie tej wartości w cudzysłów podwójnych.
-format, -f string Format danych źródłowych. Musi być jednym z obsługiwanych formatów
-ingestionMappingPath, -mappingPath string Ścieżka do pliku lokalnego do mapowania kolumn pozyskiwania. Zobacz mapowania danych.
-ingestionMappingRef, -mappingRef string Nazwa mapowania kolumn pozyskiwania, które zostało wcześniej utworzone w tabeli. Zobacz mapowania danych.
-creationTimePattern string Po ustawieniu parametr jest używany do wyodrębniania właściwości CreationTime ze ścieżki pliku lub obiektu blob. Zobacz Jak pozyskiwać dane przy użyciu polecenia CreationTime.
-ignoreFirstRow, -ignoreFirst bool W przypadku ustawienia pierwszy rekord każdego pliku/obiektu blob jest ignorowany. Jeśli na przykład dane źródłowe mają nagłówki.
-Tag string Tagi do skojarzenia z pozyskanymi danymi. Dozwolone jest wiele wystąpień
-dontWait bool Jeśli jest ustawiona wartość true, nie czeka na ukończenie pozyskiwania. Przydatne podczas pozyskiwania dużych ilości plików/obiektów blob.
-compression, -cr double Wskazówka współczynnika kompresji. Przydatne podczas pozyskiwania skompresowanych plików/obiektów blob, aby ułatwić usłudze Azure Data Explorer ocenę rozmiaru nieprzetworzonych danych. Obliczony jako oryginalny rozmiar podzielony przez skompresowany rozmiar.
-limit, -l liczba całkowita W przypadku ustawienia ogranicza pozyskiwanie do pierwszych N plików.
-listOnly, -list bool W przypadku ustawienia wyświetla tylko elementy, które zostałyby wybrane do pozyskiwania.
-estTimeout liczba całkowita Limit czasu w minutach dla wszystkich operacji pozyskiwania. Wartość domyślna to 60.
-forceSync bool W przypadku ustawienia wymusza synchroniczne pozyskiwanie. Wartość domyślna to false.
-Interaktywne bool Jeśli ustawiono wartość false, nie wyświetla monitu o potwierdzenie argumentów. W przypadku nienadzorowanych przepływów i środowisk nieinterakcyjnych. Wartość domyślna to true.
-dataBatchSize liczba całkowita Ustawia łączny limit rozmiaru (MB, nieskompresowany) każdej operacji pozyskiwania.
-filesInBatch liczba całkowita Ustawia limit liczby plików/obiektów blob dla każdej operacji pozyskiwania.
-devTracing, -trace string W przypadku ustawienia dzienniki diagnostyczne są zapisywane w katalogu lokalnym (domyślnie RollingLogs w bieżącym katalogu lub można je zmodyfikować, ustawiając wartość przełącznika).

Możliwości specyficzne dla obiektu blob platformy Azure

W przypadku użycia z obiektami blob platformy Azure funkcja LightIngest używa niektórych właściwości metadanych obiektu blob do rozszerzania procesu pozyskiwania.

Właściwość metadanych Użycie
rawSizeBytes, kustoUncompressedSizeBytes W przypadku ustawienia zostanie zinterpretowana jako rozmiar danych nieskompresowanych
kustoCreationTime, kustoCreationTimeUtc Interpretowany jako sygnatura czasowa UTC. Jeśli zostanie ustawiona, zostanie użyta do zastąpienia czasu tworzenia w usłudze Kusto. Przydatne w scenariuszach wypełniania kopii zapasowych

Przykłady użycia

W poniższych przykładach założono, że zainstalowano pliki binarne LightIngest dla systemu operacyjnego. Jeśli narzędzie LightIngest zostało zainstalowane jako narzędzie platformy .NET, zastąp LightIngestLightIngest ciąg w przykładach.

Pozyskiwanie danych historycznych za pomocą właściwości CreationTime

Podczas ładowania danych historycznych z istniejącego systemu do usługi Azure Data Explorer wszystkie rekordy otrzymują tę samą datę pozyskiwania. Aby włączyć partycjonowanie danych przez czas tworzenia, a nie czas pozyskiwania, możesz użyć argumentu -creationTimePattern . Argument -creationTimePattern wyodrębnia CreationTime właściwość ze ścieżki pliku lub obiektu blob. Wzorzec nie musi odzwierciedlać całej ścieżki elementu— tylko sekcja zawierająca znacznik czasu, którego chcesz użyć.

Wartości argumentów muszą zawierać:

  • Stały tekst bezpośrednio poprzedzający format znacznika czasu ujęty w cudzysłów (prefiks)
  • Format znacznika czasu w standardowej notacji data/godzina platformy .NET
  • Stały tekst bezpośrednio po znaczniku czasu (sufiks).

Ważne

Podczas określania, że czas tworzenia powinien zostać zastąpiony, upewnij się, że Lookback właściwość w obowiązujących zasadach scalania zakresów tabeli docelowej jest zgodna z wartościami w ścieżkach plików lub obiektów blob.

Przykłady

  • Nazwa obiektu blob zawierającego datę/godzinę w następujący sposób: historicalvalues19840101.parquet (sygnatura czasowa to cztery cyfry dla roku, dwie cyfry miesiąca i dwie cyfry dla dnia miesiąca),

    Wartość argumentu -creationTimePattern jest częścią nazwy pliku: "'historicalvalues'yyyMdd'.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

  • W przypadku identyfikatora URI obiektu blob odwołującego się do struktury folderów hierarchicznych, takich jak https://storageaccount/mycontainer/myfolder/2002/12/01/blobname.extension,

    Wartość argumentu -creationTimePattern jest częścią struktury folderów: "'folder/'rrrrrr/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

Pozyskiwanie obiektów blob przy użyciu klucza konta magazynu lub tokenu SAS

  • Pozyskiwanie 10 obiektów blob na określonym koncie ACCOUNTmagazynu , w folderze , w kontenerze DIRCONTi dopasowywanie wzorca*.csv.gz
  • Miejsce docelowe to baza danych DB, tabela TABLE, a mapowanie MAPPING pozyskiwania jest wstępnie tworzone w miejscu docelowym
  • Narzędzie czeka na zakończenie operacji pozyskiwania
  • Zwróć uwagę na różne opcje określania docelowej bazy danych i klucza konta magazynu a tokenu 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

Pozyskiwanie wszystkich obiektów blob w kontenerze, a nie w tym wierszy nagłówka

  • Pozyskiwanie wszystkich obiektów blob na określonym koncie ACCOUNTmagazynu , w folderze , w kontenerze DIR1/DIR2CONTi dopasowywanie wzorca*.csv.gz
  • Miejsce docelowe to baza danych DB, tabela TABLE, a mapowanie MAPPING pozyskiwania jest wstępnie tworzone w miejscu docelowym
  • Źródłowe obiekty blob zawierają wiersz nagłówka, dlatego narzędzie jest instruowane, aby usunąć pierwszy rekord każdego obiektu blob
  • Narzędzie publikuje dane pozyskiwania i nie czeka na ukończenie operacji pozyskiwania
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

Pozyskiwanie wszystkich plików JSON ze ścieżki

  • Pozyskiwanie wszystkich plików w ścieżce PATH, zgodne ze wzorcem *.json
  • Miejsce docelowe to baza danych DB, tabela TABLE, a mapowanie pozyskiwania jest definiowane w pliku lokalnym MAPPING_FILE_PATH
  • Narzędzie publikuje dane pozyskiwania i nie czeka na ukończenie operacji pozyskiwania
LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"PATH"
  -pattern:*.json
  -format:json
  -mappingPath:"MAPPING_FILE_PATH"

Pozyskiwanie plików i zapisywanie plików śledzenia diagnostycznego

  • Pozyskiwanie wszystkich plików w ścieżce PATH, zgodne ze wzorcem *.json
  • Miejsce docelowe to baza danych DB, tabela TABLE, a mapowanie pozyskiwania jest definiowane w pliku lokalnym MAPPING_FILE_PATH
  • Narzędzie publikuje dane pozyskiwania i nie czeka na ukończenie operacji pozyskiwania
  • Pliki śledzenia diagnostyki są zapisywane lokalnie w folderze 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"