Eksportowanie danych do magazynu w chmurze

Artykuł
12/01/2024

Dotyczy: ✅Microsoft Fabric ✅Azure Data Explorer

Wykonuje zapytanie i zapisuje pierwszy zestaw wyników w zewnętrznym magazynie w chmurze określonym przez parametry połączenia magazynu.

Uprawnienia

Aby uruchomić to polecenie, musisz mieć co najmniej uprawnienia przeglądarki baz danych.

Składnia

.export[] [asynccompressed] toOutputDataFormat( StorageConnectionString [, ...] ) [with(PropertyName=PropertyValue [, ...] ] )<|Zapytanie

Dowiedz się więcej na temat konwencji składni.

Parametry

Nazwisko	Type	Wymagania	opis
`async`	`string`		Jeśli zostanie określony, polecenie jest uruchamiane w trybie asynchronicznym. Zobacz tryb asynchroniczny.
`compressed`	`string`		Jeśli zostanie określony, artefakty magazynu wyjściowego są kompresowane jako `.gz` pliki. Zobacz obsługiwaną `compressionType`właściwość kompresowania plików Parquet jako snappy.
OutputDataFormat	`string`	✔️	Wskazuje format danych artefaktów magazynu napisanych przez polecenie . Obsługiwane wartości to: `csv`, , `tsvjson`i `parquet`.
StorageConnectionString	`string`		Co najmniej jeden parametry połączenia magazynu wskazujący, do którego magazynu mają być zapisywane dane. Dla skalowalnych zapisów można określić więcej niż jeden parametr połączenia magazynu. Każda taka parametry połączenia musi wskazywać poświadczenia do użycia podczas zapisywania w magazynie. Na przykład podczas zapisywania w usłudze Azure Blob Storage poświadczenia mogą być kluczem konta magazynu lub kluczem dostępu współdzielonego (SAS) z uprawnieniami do odczytu, zapisu i wyświetlania listy obiektów blob.
PropertyName, PropertyValue	`string`		Rozdzielona przecinkami lista par właściwości klucz-wartość. Zobacz obsługiwane właściwości.

Uwaga

Zdecydowanie zalecamy eksportowanie danych do magazynu, który znajduje się w tym samym regionie co sama baza danych. Obejmuje to dane wyeksportowane, aby można je było przenieść do innej usługi w chmurze w innych regionach. Operacje zapisu powinny być wykonywane lokalnie, podczas gdy operacje odczytu mogą odbywać się zdalnie.

Obsługiwane właściwości

Właściwość	Type	opis
`includeHeaders`	`string`	W przypadku `csv`/`tsv` danych wyjściowych steruje generowaniem nagłówków kolumn. Może być jednym z `none` (domyślnie; bez emitowanych wierszy nagłówka), `all` (emitować wiersz nagłówka do każdego artefaktu magazynu) lub `firstFile` (emitować wiersz nagłówka tylko do pierwszego artefaktu magazynu).
`fileExtension`	`string`	Wskazuje część "extension" artefaktu magazynu (na przykład `.csv` lub `.tsv`). Jeśli jest używana kompresja, `.gz` również jest dołączana.
`namePrefix`	`string`	Wskazuje prefiks do dodania do każdej wygenerowanej nazwy artefaktu magazynu. W przypadku pozostawienia nieokreślonego prefiksu jest używany losowy prefiks.
`encoding`	`string`	Wskazuje, jak zakodować tekst: `UTF8NoBOM` (wartość domyślna) lub `UTF8BOM`.
`compressionType`	`string`	Wskazuje typ kompresji do użycia. Możliwe wartości to `gzip` lub `snappy`. Wartość domyślna to `gzip`. `snappy` może (opcjonalnie) służyć do formatowania `parquet` .
`distribution`	`string`	Wskazówka dystrybucji (`single`, `per_node`, `per_shard`). Jeśli wartość jest `single`równa , pojedynczy wątek zapisuje w magazynie. W przeciwnym razie wyeksportuj zapisy ze wszystkich węzłów wykonujących zapytanie równolegle. Zobacz ocena operatora wtyczki. Wartość domyślna to `per_shard`.
`persistDetails`	`bool`	Wskazuje, że polecenie powinno utrwalić wyniki (zobacz `async` flagę). Wartość domyślna to `true` w uruchomieniach asynchronicznych, ale można je wyłączyć, jeśli obiekt wywołujący nie wymaga wyników). Wartości domyślne w `false` wykonaniach synchronicznych, ale można je również włączyć.
`sizeLimit`	`long`	Limit rozmiaru w bajtach pojedynczego artefaktu magazynu zapisanego przed kompresją. Prawidłowy zakres: 100 MB (wartość domyślna) do 4 GB.
`parquetRowGroupSize`	`int`	Dotyczy tylko wtedy, gdy format danych to Parquet. Steruje rozmiarem grupy wierszy w wyeksportowanych plikach. Domyślny rozmiar grupy wierszy to 100 000 rekordów.
`distributed`	`bool`	Wyłącz lub włącz eksport rozproszony. Ustawienie wartości false jest równoważne `single` wskazówce dystrybucji. Ustawieniem domyślnym jest true.
`parquetDatetimePrecision`	`string`	Określa precyzję, która ma być używana podczas eksportowania `datetime` wartości do parquet. Możliwe wartości to milisekundy i mikrosekundy. Wartość domyślna to milisekunda.

Uwierzytelnianie i autoryzacja

Metoda uwierzytelniania jest oparta na podanych parametry połączenia, a wymagane uprawnienia różnią się w zależności od metody uwierzytelniania.

W poniższej tabeli wymieniono obsługiwane metody uwierzytelniania oraz uprawnienia wymagane do eksportowania danych do magazynu zewnętrznego według typu magazynu.

Metoda uwierzytelniania	Azure Blob Storage / Data Lake Storage Gen2	Data Lake Storage Gen1
Personifikacja	Współautor danych w usłudze Blob Storage	Współautor
Token dostępu współdzielonego (SAS)	Write	Write
Token dostępu firmy Microsoft Entra	Nie są wymagane żadne dodatkowe uprawnienia	Nie są wymagane żadne dodatkowe uprawnienia
Klucz dostępu do konta magazynu	Nie są wymagane żadne dodatkowe uprawnienia	Nie są wymagane żadne dodatkowe uprawnienia

Zwraca

Polecenia zwracają tabelę opisjącą wygenerowane artefakty magazynu. Każdy rekord opisuje pojedynczy artefakt i zawiera ścieżkę magazynu do artefaktu oraz liczbę przechowywanych rekordów.

Ścieżka	Liczbarekordów
http://storage1.blob.core.windows.net/containerName/export_1_d08afcae2f044c1092b279412dcb571b.csv	10
http://storage1.blob.core.windows.net/containerName/export_2_454c0f1359e24795b6529da8a0101330.csv	15

Tryb asynchroniczny

Jeśli flaga async jest określona, polecenie jest wykonywane w trybie asynchronicznym. W tym trybie polecenie zwraca natychmiast z identyfikatorem operacji, a eksport danych będzie kontynuowany w tle do momentu ukończenia. Identyfikator operacji zwrócony przez polecenie może służyć do śledzenia postępu i ostatecznie jego wyników za pomocą następujących poleceń:

.show operations: Śledzenie postępu.
.show operation details: Pobieranie wyników ukończenia.

Na przykład po pomyślnym zakończeniu możesz pobrać wyniki przy użyciu:

.show operation f008dc1e-2710-47d8-8d34-0d562f5f8615 details

Przykłady

W tym przykładzie usługa Kusto uruchamia zapytanie, a następnie eksportuje pierwszy zestaw rekordów utworzony przez zapytanie do co najmniej jednego skompresowanego obiektu blob CSV, do 1 GB przed kompresją. Etykiety nazw kolumn są dodawane jako pierwszy wiersz dla każdego obiektu blob.

.export
  async compressed
  to csv (
    h@"https://storage1.blob.core.windows.net/containerName;secretKey",
    h@"https://storage1.blob.core.windows.net/containerName2;secretKey"
  ) with (
    sizeLimit=1000000000,
    namePrefix="export",
    includeHeaders="all",
    encoding="UTF8NoBOM"
  )
  <| 
  Logs | where id == "1234"

Błędy podczas eksportowania poleceń

Polecenia eksportu mogą się nie powieść podczas wykonywania. eksport ciągły automatycznie ponawia próbę polecenia. Regularne polecenia eksportu (eksportowanie do magazynu, eksportowanie do tabeli zewnętrznej) nie wykonują żadnych ponownych prób.

Gdy polecenie eksportu zakończy się niepowodzeniem, artefakty, które zostały już zapisane w magazynie, nie zostaną usunięte. Te artefakty pozostają w magazynie. Jeśli polecenie zakończy się niepowodzeniem, załóżmy, że eksport jest niekompletny, nawet jeśli niektóre artefakty zostały zapisane.
Najlepszym sposobem śledzenia zarówno ukończenia polecenia, jak i artefaktów wyeksportowanych po pomyślnym zakończeniu jest użycie .show operations poleceń i .show operation details .

Błędy magazynu

Domyślnie polecenia eksportu są dystrybuowane w taki sposób, że w magazynie może istnieć wiele współbieżnych zapisów. Poziom dystrybucji zależy od typu polecenia eksportu:

Domyślną dystrybucją zwykłego .export polecenia jest per_shard, co oznacza, że wszystkie zakresy zawierające dane do eksportowania zapisu do magazynu jednocześnie.
Domyślną dystrybucją eksportu do poleceń tabeli zewnętrznej jest per_node, co oznacza, że współbieżność to liczba węzłów.

Gdy liczba zakresów/węzłów jest duża, może to prowadzić do dużego obciążenia magazynu, co powoduje ograniczenie przepustowości magazynu lub przejściowe błędy magazynu. Następujące sugestie mogą przezwyciężyć te błędy (według kolejności priorytetu):

Zwiększ liczbę kont magazynu dostarczonych do polecenia eksportu lub do zewnętrznej definicji tabeli. Obciążenie jest równomiernie rozłożone między kontami.
Zmniejsz współbieżność, ustawiając wskazówkę dystrybucji na per_node (zobacz właściwości polecenia).
Zmniejsz współbieżność liczby węzłów eksportu, ustawiając właściwośćquery_fanout_nodes_percent żądania klienta na żądaną współbieżność (procent węzłów). Właściwość można ustawić jako część zapytania eksportu. Na przykład następujące polecenie ogranicza liczbę węzłów zapisu w magazynie jednocześnie do 50% węzłów:
```
.export async  to csv
    ( h@"https://storage1.blob.core.windows.net/containerName;secretKey" ) 
    with
    (
        distribution="per_node"
    ) 
    <| 
    set query_fanout_nodes_percent = 50;
    ExportQuery
```
Zmniejsz współbieżność liczby wątków eksportowanych w każdym węźle podczas korzystania z eksportu na fragmenty, ustawiając właściwośćquery_fanout_threads_percent żądania klienta na żądaną współbieżność (procent wątków). Właściwość można ustawić jako część zapytania eksportu. Na przykład następujące polecenie ogranicza liczbę wątków zapisu w magazynie jednocześnie do 50% w każdym z węzłów:
```
.export async  to csv
    ( h@"https://storage1.blob.core.windows.net/containerName;secretKey" ) 
    with
    (
        distribution="per_shard"
    ) 
    <| 
    set query_fanout_threads_percent = 50;
    ExportQuery
```
W przypadku eksportowania do partycjonowanej tabeli zewnętrznej ustawienie spread/concurrency właściwości może zmniejszyć współbieżność (zobacz szczegóły we właściwościach polecenia.
Jeśli żadna z poprzednich zaleceń nie działa, można całkowicie wyłączyć dystrybucję, ustawiając właściwość distributed na false. Nie zalecamy jednak tego robić, ponieważ może to znacząco wpłynąć na wydajność poleceń.

Błędy autoryzacji

Błędy uwierzytelniania lub autoryzacji podczas eksportowania poleceń mogą wystąpić, gdy poświadczenia podane w magazynie parametry połączenia nie mogą zapisywać w magazynie. Jeśli używasz impersonate lub tokenu sygnatury dostępu współdzielonego delegowanego przez użytkownika dla polecenia eksportu, rola Współautor danych obiektu blob usługi Storage jest wymagana do zapisu na koncie magazynu. Aby uzyskać więcej informacji, zobacz Parametry połączenia usługi Storage.

Mapowanie typów danych

Mapowanie typów danych Parquet

Podczas eksportowania typy danych Usługi Kusto są mapowane na typy danych Parquet przy użyciu następujących reguł:

Typ danych Kusto	Typ danych Parquet	Adnotacja Parquet	Komentarze
`bool`	`BOOLEAN`
`datetime`	`INT64`	TIMESTAMP_MICROS
`dynamic`	`BYTE_ARRAY`	UTF-8	Serializowany jako ciąg JSON
`guid`	`BYTE_ARRAY`	UTF-8
`int`	`INT32`
`long`	`INT64`
`real`	`DOUBLE`
`string`	`BYTE_ARRAY`	UTF-8
`timespan`	`INT64`		Przechowywane jako znaczniki (liczba jednostek 100-nanosekundowych)
`decimal`	`FIXED_LENGTH_BYTE_ARRAY`	DZIESIĘTNY

Udostępnij za pośrednictwem

Eksportowanie danych do magazynu w chmurze

Uprawnienia

Składnia

Parametry

Obsługiwane właściwości

Uwierzytelnianie i autoryzacja

Zwraca

Tryb asynchroniczny

Przykłady

Błędy podczas eksportowania poleceń

Błędy magazynu

Błędy autoryzacji

Mapowanie typów danych

Mapowanie typów danych Parquet

Opinia

Dodatkowe zasoby

Udostępnij za pośrednictwem

Eksportowanie danych do magazynu w chmurze

Uprawnienia

Składnia

Parametry

Obsługiwane właściwości

Uwierzytelnianie i autoryzacja

Zwraca

Tryb asynchroniczny

Przykłady

Błędy podczas eksportowania poleceń

Błędy magazynu

Błędy autoryzacji

Mapowanie typów danych

Mapowanie typów danych Parquet

Powiązana zawartość

Opinia

Dodatkowe zasoby