Udostępnij za pośrednictwem

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 w usłudze 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 o rekordy 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. Zaleceniem jest pozyskiwanie plików z zakresu od 100 MB do 1 GB.

Wymagania wstępne

Uruchamianie najaśniejszej

Aby uruchomić lightingest:

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

    Napiwek

    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. Dołącz parametry połączenia w cudzysłowy i postępuj zgodnie ze specyfikacją parametry 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 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 danych, 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 Type Opis Wymagania
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.
-stół string Docelowa nazwa tabeli usługi Azure Data Explorer. ✔️
-sourcePath, -source string Lokalizacja danych źródłowych, które mogą być ścieżką pliku lokalnego, 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 Parametry połączenia usługi Storage. Pass -sourcePath:; personifikuj , 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.
-azCli bool W przypadku ustawienia użyj interfejsu wiersza polecenia platformy Azure do uwierzytelniania w usłudze Kusto. Interfejs wiersza polecenia platformy Azure musi być zainstalowany i zalogowany.
-ingestWithManagedIdentity, -ingestmi string Identyfikator klienta tożsamości zarządzanej (przypisanej przez użytkownika lub przypisaną przez system) zainstalowanej w usłudze Kusto do pobrania z magazynu. Użyj "system" dla tożsamości przypisanej przez system.
-connectToStorageWithManagedIdentity, -storageMi string Identyfikator klienta tożsamości zarządzanej (przypisanej przez użytkownika lub przypisaną przez system) zainstalowanej po stronie klienta, aby wyświetlić listę z magazynu.
-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 logowania entra firmy Microsoft.
-przedrostek 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 wyłączeniem nazwy kontenera.
Jeśli na przykład dane mają wartość MyContainer/Dir1/Dir2, prefiks powinien mieć Dir1/Dir2wartość . Zalecamy ujęcie tej wartości w cudzysłów podwójnych.
-deseń 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 na potrzeby 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.
-znacznik string Tagi do skojarzenia z pozyskanymi danymi. Dozwolone jest wiele wystąpień
-dontWait bool Jeśli ustawiono 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 dotycząca współczynnika kompresji. Przydatne podczas pozyskiwania skompresowanych plików/obiektów blob, aby ułatwić usłudze Azure Data Explorer ocenę rozmiaru danych pierwotnych. Obliczany jako rozmiar oryginalny podzielony przez skompresowany rozmiar.
-limit, -l integer 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.
-ingestTimeout integer 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.
-interaktywny bool Jeśli jest ustawiona 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 integer Ustawia łączny limit rozmiaru (MB, nieskompresowany) każdej operacji pozyskiwania.
-filesInBatch integer 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 mogą być modyfikowane przez ustawienie wartości przełącznika).

Możliwości specyficzne dla obiektu blob platformy Azure

W przypadku użycia z obiektami blob platformy Azure 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 nieskompresowany rozmiar danych
kustoCreationTime, kustoCreationTimeUtc Interpretowany jako sygnatura czasowa UTC. Jeśli jest 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 .NET, zastąp element LightIngest w LightIngest 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ć:

  • Tekst stały bezpośrednio poprzedzający format znacznika czasu, ujęty w pojedyncze cudzysłowy (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, która zawiera datę/godzinę w następujący sposób: historicalvalues19840101.parquet (sygnatura czasowa to cztery cyfry dla roku, dwie cyfry miesiąca i dwie cyfry dnia miesiąca),

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

  • W przypadku identyfikatora URI obiektu blob, który odnosi się do struktury folderów hierarchicznych, takich jak https://storageaccount/mycontainer/myfolder/2002/12/01/blobname.extension,

    Wartość -creationTimePattern argumentu jest częścią struktury folderów: "'folder/'rry/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 w ramach określonego konta 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 na potrzeby pozyskiwania danych i nie czeka na zakoń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
  • Lokalizacja docelowa to baza danych DB, tabela TABLE, a mapowanie pozyskiwania jest definiowane w pliku lokalnym MAPPING_FILE_PATH
  • Narzędzie publikuje dane na potrzeby pozyskiwania danych i nie czeka na zakoń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
  • Lokalizacja docelowa to baza danych DB, tabela TABLE, a mapowanie pozyskiwania jest definiowane w pliku lokalnym MAPPING_FILE_PATH
  • Narzędzie publikuje dane na potrzeby pozyskiwania danych i nie czeka na zakoń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"

Uwierzytelnianie przy użyciu tożsamości zarządzanej

Istnieją trzy akcje lightIngest wykonuje, które mogą używać tożsamości zarządzanej do uwierzytelniania. Użycie tożsamości zarządzanej w każdym kroku nie wymaga użycia tożsamości zarządzanej w innych krokach. Dla każdej akcji jest podany powiązany argument wiersza polecenia.

  • Połącz się z klastrem Kusto: aby utworzyć kolejkę pozyskiwania, narzędzie używa parametry połączenia. Użyj argumentu "-mi", aby określić tożsamość zarządzaną zainstalowaną na maszynie wirtualnej klienta, która ma uprawnienia pozyskiwania w docelowej bazie danych.

  • Połącz się z usługą Azure Storage, aby pobrać obiekty blob: użyj polecenia "-ingestmi", aby określić tożsamość zarządzaną zainstalowaną w usłudze Kusto, która ma uprawnienia do odczytu w kontenerze magazynu.

  • Połącz się z usługą Azure Storage, aby wyświetlić listę obiektów blob kontenera: użyj argumentu "-storageMi", aby określić tożsamość zarządzaną zainstalowaną na maszynie wirtualnej klienta z uprawnieniami listy w kontenerze magazynu. Jeśli używasz tej metody, ale nie poprzedniej (połącz się z usługą Azure Storage w celu pobrania obiektów blob), tożsamość zarządzana musi również mieć uprawnienia do odczytu, a token zostanie przekazany do usługi Kusto, która będzie używana do pozyskiwania. Dlatego zaleca się ustawienie wszystkich trzech argumentów.