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

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.

Wymagania wstępne

• Najjaśniejszy. Uzyskaj LightIngest na jeden z dwóch sposobów:

  • Pobierz pliki binarne LightIngest dla systemu operacyjnego. Pamiętaj, aby rozpakować pliki binarne po pobraniu.

  • Zainstaluj narzędzie LightIngest jako narzędzie .NET. Ta metoda wymaga zainstalowania na maszynie zestawu .NET SDK w wersji 6.0 lub nowszej. Następnie uruchom następujące polecenie:

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

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-, a następnie parametry połączenia dla klastra usługi Azure Data Explorer, który 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, lightIngest potrzebuje nieprzetworzonego rozmiaru danych, aby 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

Możliwości specyficzne dla obiektu blob platformy Azure

Korzystając z LightIngest z obiektami blob Azure, używa się pewnych właściwości metadanych blobów w celu usprawnienia procesu pozyskiwania.

Przykłady użycia

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

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 podzielić dane na partycje według czasu tworzenia zamiast czasu pozyskiwania, użyj 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, a jedynie tę część, która obejmuje znacznik czasu, którego zamierzasz 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).

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 dostępu do 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

• Wczytaj wszystkie pliki w ścieżce PATH, które pasują do wzorca *.json
• Ustaw lokalizację docelową na bazę danych DB, tabelę TABLEi zdefiniuj mapowanie pozyskiwania 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"

Pobieranie plików i zapisywanie plików diagnostycznych

• Wczytaj wszystkie pliki w ścieżce PATH, które pasują do wzorca *.json
• Ustaw lokalizację docelową na bazę danych DB, tabelę TABLEi zdefiniuj mapowanie pozyskiwania w pliku lokalnym MAPPING_FILE_PATH
• Narzędzie publikuje dane na potrzeby pozyskiwania danych i nie czeka na zakończenie operacji pozyskiwania
• Zapisz pliki śledzenia diagnostyki 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

LightIngest wykonuje trzy akcje, 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łączenia z usługą Azure Storage w celu pobrania obiektów blob), to nadana tożsamość zarządzana musi mieć również uprawnienia do odczytu. Token zostaje przekazany do usługi Kusto, aby został użyty do importowania danych. Ustaw wszystkie trzy argumenty.