Adatok exportálása felhőtárhelyre

Cikk
01/18/2024

Végrehajt egy lekérdezést, és az első eredményhalmazt egy külső felhőbeli tárolóra írja, amelyet egy tárolási kapcsolati karakterlánc határoz meg.

Engedélyek

A parancs futtatásához legalább adatbázis-megjelenítői engedélyekkel kell rendelkeznie.

Syntax

.export [async] [compressed] toOutputDataFormat(StorageConnectionString [, ...] ) [with(PropertyName=PropertyValue [, ...] )] <|Lekérdezés

További információ a szintaxis konvenciókról.

Paraméterek

Név	Típus	Kötelező	Leírás
`async`	`string`		Ha meg van adva, a parancs aszinkron módban fut. Lásd : aszinkron mód.
`compressed`	`string`		Ha meg van adva, a kimeneti tároló összetevői fájlokként `.gz` lesznek tömörítve. A Parquet-fájlok beépülő modulként való tömörítéséhez tekintse meg a `compressionType`támogatott tulajdonságot .
OutputDataFormat	`string`	✔️	A parancs által írt tárolási összetevők adatformátumát jelzi. Támogatott értékek: `csv`, `tsv`, `json`és `parquet`.
StorageConnectionString	`string`		Egy vagy több tárolási kapcsolati sztring jelzi, hogy melyik tárolóba kell írni az adatokat. A méretezhető írásokhoz több tároló kapcsolati karakterlánc is megadható. Minden ilyen kapcsolati karakterlánc meg kell adnia a tárolóba való íráshoz használandó hitelesítő adatokat. Ha például Azure Blob Storage ír, a hitelesítő adatok lehetnek a tárfiók kulcsa, vagy egy megosztott hozzáférési kulcs (SAS) a blobok olvasására, írására és listázására vonatkozó engedélyekkel.
PropertyName, PropertyValue	`string`		Kulcs-érték tulajdonságpárok vesszővel tagolt listája. Tekintse meg a támogatott tulajdonságokat.

Megjegyzés

Javasoljuk, hogy exportálja az adatokat olyan tárolóba, amely ugyanabban a régióban található, mint maga a fürt. Ide tartoznak az exportált adatok is, amelyek más régiókban lévő felhőszolgáltatásba továbbíthatók. Az írásokat helyileg kell elvégezni, míg az olvasás távolról is történhet.

Támogatott tulajdonságok

Tulajdonság	Típus	Description
`includeHeaders`	`string`	Kimenet esetén `csv`/`tsv` az oszlopfejlécek létrehozását szabályozza. Lehet az egyik `none` (alapértelmezett; nincs fejlécsor kiadva), `all` (fejlécsort bocsát ki minden tárolási összetevőbe), vagy `firstFile` (csak az első tárolási összetevőbe bocsát ki fejlécsort).
`fileExtension`	`string`	A tárolási összetevő "bővítmény" részét jelzi (például `.csv` vagy `.tsv`). Ha tömörítést használ, `.gz` a hozzáfűzés is hozzá van adva.
`namePrefix`	`string`	Egy előtagot jelöl, amely hozzáadható az egyes létrehozott tárolóösszetevők nevéhez. Véletlenszerű előtagot használunk, ha nincs meghatározva.
`encoding`	`string`	A szöveg kódolását jelzi: `UTF8NoBOM` (alapértelmezett) vagy `UTF8BOM`.
`compressionType`	`string`	A használandó tömörítés típusát jelzi. A lehetséges értékek: `gzip` és `snappy`. Az alapértelmezett szint a `gzip`. `snappy` formátumhoz `parquet` (opcionálisan) használható.
`distribution`	`string`	Terjesztési tipp (`single`, `per_node`, `per_shard`). Ha az érték egyenlő `single`, egyetlen szál ír a tárolóba. Ellenkező esetben exportálja az írásokat az összes olyan csomópontról, amely párhuzamosan hajtja végre a lekérdezést. Lásd a beépülő modul operátorának kiértékelését. Alapértelmezés szerint a értékre van kapcsolva `per_shard`.
`persistDetails`	`bool`	Azt jelzi, hogy a parancsnak meg kell őriznie az eredményeit (lásd a jelzőt `async` ). `true` Alapértelmezés szerint az aszinkron futtatás, de kikapcsolható, ha a hívónak nincs szüksége az eredményekre. `false` Alapértelmezés szerint szinkron végrehajtásban van, de ezekben is be lehet kapcsolni.
`sizeLimit`	`long`	Egyetlen írandó tárolási összetevő bájtban megadott méretkorlátja (tömörítés előtt). Érvényes tartomány: 100 MB (alapértelmezett) és 4 GB között.
`parquetRowGroupSize`	`int`	Csak akkor releváns, ha az adatformátum Parquet. Szabályozza a sorcsoport méretét az exportált fájlokban. Az alapértelmezett sorcsoportméret 100 000 rekord.
`distributed`	`bool`	Az elosztott exportálás letiltása/engedélyezése. A hamis értékre állítás egyenértékű a terjesztési tippel `single` . Alapértelmezett érték: true (igaz).
`parquetDatetimePrecision`	`string`	Megadja az értékek Parquetbe való `datetime` exportálásához használandó pontosságot. A lehetséges értékek ezredmásodpercben és mikroszekundumban vannak. Az alapértelmezett érték ezredmásodperc.

Hitelesítés és engedélyezés

A hitelesítési módszer a megadott kapcsolati karakterlánc alapul, és a szükséges engedélyek a hitelesítési módszertől függően változnak.

Az alábbi táblázat a támogatott hitelesítési módszereket és az adatok külső tárolóba tártípusonkénti exportálásához szükséges engedélyeket sorolja fel.

Hitelesítési módszer	Azure Blob Storage/Data Lake Storage Gen2	Data Lake Storage Gen1
Megszemélyesítés	Storage-blobadatok közreműködője	Közreműködő
Közös hozzáférésű (SAS) jogkivonat	Írás	Írás
Microsoft Entra hozzáférési jogkivonat	Nincs szükség további engedélyekre	Nincs szükség további engedélyekre
Tárfiók hozzáférési kulcsa	Nincs szükség további engedélyekre	Nincs szükség további engedélyekre

Válaszok

A parancsok egy táblát adnak vissza, amely leírja a létrehozott tárolási összetevőket. Minden rekord egyetlen összetevőt ír le, és tartalmazza az összetevő tárolási útvonalát, valamint azt, hogy hány rekordot tárol.

Elérési út	NumRecords
http://storage1.blob.core.windows.net/containerName/export_1_d08afcae2f044c1092b279412dcb571b.csv	10
http://storage1.blob.core.windows.net/containerName/export_2_454c0f1359e24795b6529da8a0101330.csv	15

Aszinkron mód

Ha a async jelölő meg van adva, a parancs aszinkron módban fut. Ebben a módban a parancs azonnal visszaad egy műveletazonosítót, és az adatok exportálása a háttérben folytatódik a befejezésig. A parancs által visszaadott műveletazonosítóval nyomon követhető a művelet állapota és végső soron az eredményei a következő parancsokkal:

.show operations: Folyamat nyomon követése.
.show operation details: Befejezési eredmények lekérése.

A sikeres befejezés után például lekérheti az eredményeket a következővel:

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

Példák

Ebben a példában a Kusto futtatja a lekérdezést, majd exportálja a lekérdezés által létrehozott első rekordhalmazt egy vagy több tömörített CSV-blobba, akár 1 GB tömörítés előtt. Az oszlopnévfeliratok az egyes blobok első soraként lesznek hozzáadva.

.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"

Hibák az exportálási parancsok során

Az exportálási parancsok a végrehajtás során átmenetileg meghiúsulhatnak. A folyamatos exportálás automatikusan újra megkísérli a parancsot. A normál exportálási parancsok (exportálás a tárolóba, exportálás külső táblába) nem hajtanak végre újrapróbálkozást.

Ha az exportálási parancs sikertelen, a már a tárolóba írt összetevők nem törlődnek. Ezek az összetevők a tárolóban maradnak. Ha a parancs sikertelen, feltételezzük, hogy az exportálás hiányos, még akkor is, ha néhány összetevő meg lett írva.
A parancs befejezésének és a sikeres befejezéskor exportált összetevők nyomon követésének legjobb módja a és .show operation details a .show operations parancsok használata.

Tárolási hibák

Alapértelmezés szerint az exportálási parancsok úgy vannak elosztva, hogy sok egyidejű írási lehetőség legyen a tárolóba. Az eloszlás szintje az exportálási parancs típusától függ:

A normál .export parancs alapértelmezett eloszlása a per_shard, ami azt jelenti, hogy minden olyan mérték , amely adatokat tartalmaz az írás egyidejű exportálásához a tárolóba.
A külső táblaparancsokra való exportálás alapértelmezett eloszlása a per_node, ami azt jelenti, hogy az egyidejűség a fürt csomópontjainak száma.

Ha a mértékek/csomópontok száma nagy, az a tárterület nagy terheléséhez vezethet, ami tárolási szabályozáshoz vagy átmeneti tárolási hibákhoz vezethet. A következő javaslatok megoldhatják ezeket a hibákat (prioritás szerint):

Növelje az exportálási parancsnak vagy a külső tábladefiníciónak biztosított tárfiókok számát (a terhelés egyenletesen oszlik el a fiókok között).
Csökkentse az egyidejűséget a terjesztési tipp per_node beállításával (lásd a parancstulajdonságokat).
Csökkentse az exportált csomópontok számának egyidejűségét, ha az ügyfélkérés tulajdonságotquery_fanout_nodes_percent a kívánt egyidejűségre (a csomópontok százalékára) állítja. A tulajdonság az exportálási lekérdezés részeként állítható be. A következő parancs például a tárolóba egyidejűleg írt csomópontok számát a fürtcsomópontok 50%-ára korlátozza:
```
.export async  to csv
    ( h@"https://storage1.blob.core.windows.net/containerName;secretKey" ) 
    with
    (
        distribution="per_node"
    ) 
    <| 
    set query_fanout_nodes_percent = 50;
    ExportQuery
```
Az egyes csomópontokon exportált szálak számának egyidejűségének csökkentése szegmensenkénti exportáláskor az ügyfélkérés tulajdonságánakquery_fanout_threads_percent a kívánt egyidejűségre (a szálak százalékára) való beállításával. A tulajdonság az exportálási lekérdezés részeként állítható be. A következő parancs például 50%-ra korlátozza a tárolóba egyidejűleg írt szálak számát az egyes fürtcsomópontokon:
```
.export async  to csv
    ( h@"https://storage1.blob.core.windows.net/containerName;secretKey" ) 
    with
    (
        distribution="per_shard"
    ) 
    <| 
    set query_fanout_threads_percent = 50;
    ExportQuery
```
Particionált külső táblába való exportálás esetén a tulajdonságok beállítása csökkentheti az spread/concurrency egyidejűséget (lásd a parancstulajdonságok részleteit.
Ha egyik fenti munka sem működik, a tulajdonság false (hamis) értékre állításával teljesen letilthatja a distributed terjesztést. Ezt azonban nem javasoljuk, mivel ez jelentősen befolyásolhatja a parancs teljesítményét.

Engedélyezési hibák

Az exportálási parancsok hitelesítési vagy engedélyezési hibái akkor fordulhatnak elő, ha a tárolási kapcsolati karakterlánc megadott hitelesítő adatok nem írhatók a tárolóba. Ha az exportálási parancshoz felhasználó által delegált SAS-jogkivonatot használ impersonate , a Storage Blob-adatok közreműködője szerepkör szükséges a tárfiókba való íráshoz. További információ: Tárolási kapcsolati sztringek.

Adattípusok leképezése

Parquet-adattípusok leképezése

Exportáláskor a Kusto-adattípusok parquet-adattípusokra vannak leképezve az alábbi szabályok használatával:

Kusto-adattípus	Parquet-adattípus	Parquet Annotation	Megjegyzések
`bool`	`BOOLEAN`
`datetime`	`INT64`	TIMESTAMP_MICROS
`dynamic`	`BYTE_ARRAY`	UTF-8	Szerializálva JSON-sztringként
`guid`	`BYTE_ARRAY`	UTF-8
`int`	`INT32`
`long`	`INT64`
`real`	`DOUBLE`
`string`	`BYTE_ARRAY`	UTF-8
`timespan`	`INT64`		Kullancsként (100 nanoszekundumos egység) tárolva
`decimal`	`FIXED_LENGTH_BYTE_ARRAY`	DECIMÁLIS