Menggunakan LightIngest untuk menyerap data ke Azure Data Explorer

Artikel
07/16/2024

LightIngest adalah utilitas baris perintah untuk penyerapan data ad-hoc ke Azure Data Explorer. Utilitas dapat menarik data sumber dari folder lokal, kontainer penyimpanan blob Azure, atau wadah Amazon S3.

LightIngest paling berguna ketika Anda ingin menyerap sejumlah besar data, karena tidak ada batasan waktu pada durasi penyerapan. Ini juga berguna ketika Anda ingin nanti mengkueri rekaman sesuai dengan waktu pembuatannya, dan bukan waktu mereka diserap.

Untuk contoh cara membuat perintah LightIngest secara otomatis, lihat menyerap data historis.

Catatan

Penyerapan mendukung ukuran file maksimum 6 GB. Rekomendasinya adalah menyerap file antara 100 MB dan 1 GB.

Prasyarat

Lightingest. Ada dua cara untuk mendapatkan LightIngest:
- Unduh biner LightIngest untuk sistem operasi Anda. Pastikan untuk membuka zip biner setelah diunduh.
- Instal LightIngest sebagai alat .NET. Metode ini mengharuskan Anda menginstal .NET SDK versi 6.0 atau yang lebih tinggi di komputer Anda. Kemudian, jalankan perintah berikut:
```
dotnet tool install -g Microsoft.Azure.Kusto.LightIngest
```

Jalankan LightIngest

Untuk menjalankan LightIngest:

Pada prompt perintah, masukkan LightIngest diikuti oleh argumen baris perintah yang relevan.

Tip

Untuk daftar argumen baris perintah yang didukung, masukkan LightIngest /help.

Enter ingest- diikuti dengan string koneksi ke kluster Azure Data Explorer yang akan mengelola penyerapan. Sertakan string koneksi dalam tanda kutip ganda dan ikuti spesifikasi Kusto string koneksi s.

Contohnya:

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

Rekomendasi performa

Untuk mengelola beban penyerapan dan memulihkan dari kesalahan sementara, gunakan titik akhir penyerapan di https://ingest-{yourClusterNameAndRegion}.kusto.windows.net.
Untuk performa penyerapan yang optimal, ukuran data mentah diperlukan sehingga LightIngest dapat memperkirakan ukuran file lokal yang tidak dikompresi. Namun, LightIngest mungkin tidak dapat memperkirakan ukuran mentah blob terkompresi dengan benar tanpa terlebih dahulu mengunduhnya. Oleh karena itu, saat menyerap blob terkompresi, atur rawSizeBytes properti pada metadata blob ke ukuran data yang tidak dikompresi dalam byte.

Argumen baris perintah

Argumen	Tipe	Deskripsi	Wajib diisi
	`string`	Kusto string koneksi menentukan titik akhir Kusto yang menangani penyerapan. Nilai ini harus diapit dengan tanda kutip ganda.	✔️
-database, -db	`string`	Nama database Azure Data Explorer target.
-meja	`string`	Nama tabel Azure Data Explorer target.	✔️
-sourcePath, -source	`string`	Lokasi data sumber, yang dapat berupa jalur file lokal, URI akar kontainer blob Azure, atau URI wadah Amazon S3. Jika data disimpan dalam blob Azure, URI harus menyertakan kunci akun penyimpanan atau Tanda Tangan Akses Bersama (SAS). Jika data berada dalam wadah S3, URI harus menyertakan kunci kredensial. Sebaiknya sertakan nilai ini dalam tanda kutip ganda. Untuk informasi selengkapnya, lihat String koneksi penyimpanan. Pass -sourcePath:; meniru daftar item penyimpanan Azure dengan izin pengguna (otorisasi permintaan pengguna).	✔️
-managedIdentity, -mi	`string`	ID klien identitas terkelola (ditetapkan pengguna atau ditetapkan sistem) untuk digunakan untuk menyambungkan. Gunakan "sistem" untuk identitas yang ditetapkan sistem.
-azCli	`bool`	Jika diatur, menggunakan Azure CLI untuk mengautentikasi ke layanan Kusto. Azure CLI harus diinstal dan masuk.
-ingestWithManagedIdentity, -ingestmi	`string`	ID klien identitas terkelola (ditetapkan pengguna atau ditetapkan sistem) yang diinstal pada layanan Kusto untuk diunduh dari penyimpanan. Gunakan "sistem" untuk identitas yang ditetapkan sistem.
-connectToStorageWithManagedIdentity, -storageMi	`string`	ID klien identitas terkelola (ditetapkan pengguna atau ditetapkan sistem) yang diinstal di sisi klien ke daftar dari penyimpanan.
-connectToStorageWithUserAuth, -storageUserAuth	`string`	Autentikasi ke layanan penyimpanan sumber data dengan kredensial pengguna. Opsi untuk nilai ini adalah `PROMPT` atau `DEVICE_CODE`.
-connectToStorageLoginUri, -storageLoginUri	`string`	Jika `-connectToStorageWithUserAuth` diatur, Anda dapat secara opsional menyediakan URI masuk ID Microsoft Entra.
-awalan	`string`	Ketika data sumber untuk diserap berada di penyimpanan blob, awalan URL ini dibagikan oleh semua blob, tidak termasuk nama kontainer. Misalnya, jika data berada di `MyContainer/Dir1/Dir2`, maka awalannya harus `Dir1/Dir2`. Sebaiknya sertakan nilai ini dalam tanda kutip ganda.
-pola	`string`	Pola di mana file/blob sumber dipilih. Mendukung kartubebas. Contohnya,`"*.csv"`. Sebaiknya sertakan nilai ini dalam tanda kutip ganda.
-zipPattern	`string`	Ekspresi reguler untuk digunakan saat memilih file mana dalam arsip ZIP yang akan diserap. Semua file lain dalam arsip akan diabaikan. Contohnya,`"*.csv"`. Sebaiknya sertakan nilai ini dalam tanda kutip ganda.
-format, -f	`string`	Format data sumber. Harus salah satu format yang didukung
-ingestionMappingPath, -mappingPath	`string`	Jalur ke file lokal untuk pemetaan kolom penyerapan. Lihat pemetaan data.
-ingestionMappingRef, -mappingRef	`string`	Nama pemetaan kolom penyerapan yang sebelumnya dibuat pada tabel. Lihat pemetaan data.
-creationTimePattern	`string`	Ketika diatur, digunakan untuk mengekstrak properti CreationTime dari file atau jalur blob. Lihat Cara menyerap data menggunakan `CreationTime`.
-ignoreFirstRow, -ignoreFirst	`bool`	Jika diatur, rekaman pertama dari setiap file/blob diabaikan. Misalnya, jika data sumber memiliki header.
-tag	`string`	Tag untuk dikaitkan dengan data yang diserap. Beberapa kemunculan diizinkan
-dontWait	`bool`	Jika diatur ke `true`, tidak menunggu penyelesaian penyerapan. Berguna saat menyerap file/blob dalam jumlah besar.
-compression, -cr	ganda	Petunjuk rasio kompresi. Berguna saat menyerap file/blob terkompresi untuk membantu Azure Data Explorer menilai ukuran data mentah. Dihitung sebagai ukuran asli dibagi dengan ukuran terkompresi.
-limit, -l	Integer	Jika diatur, membatasi penyerapan ke file N pertama.
-listOnly, -list	`bool`	Jika diatur, hanya menampilkan item yang akan dipilih untuk penyerapan.
-ingestTimeout	Integer	Waktu habis dalam hitungan menit untuk semua penyerapan penyerapan operasi. Default ke `60`.
-forceSync	`bool`	Jika diatur, memaksa penyerapan sinkron. Default ke `false`.
-interaktif	`bool`	Jika diatur ke `false`, tidak meminta konfirmasi argumen. Untuk alur tanpa pengawas dan lingkungan non-interaktif. Defaultnya adalah `true`.
-dataBatchSize	Integer	Mengatur batas ukuran total (MB, tidak dikompresi) dari setiap operasi penyerapan.
-filesInBatch	Integer	Mengatur batas jumlah file/blob dari setiap operasi penyerapan.
-devTracing, -trace	`string`	Jika diatur, log diagnostik ditulis ke direktori lokal (secara default, `RollingLogs` di direktori saat ini, atau dapat dimodifikasi dengan mengatur nilai pengalihan).

Kemampuan khusus blob Azure

Saat digunakan dengan blob Azure, LightIngest menggunakan properti metadata blob tertentu untuk menambah proses penyerapan.

Properti metadata	Penggunaan
`rawSizeBytes`, `kustoUncompressedSizeBytes`	Jika diatur, akan ditafsirkan sebagai ukuran data yang tidak dikompresi
`kustoCreationTime`, `kustoCreationTimeUtc`	Ditafsirkan sebagai tanda waktu UTC. Jika diatur, akan digunakan untuk mengambil alih waktu pembuatan di Kusto. Berguna untuk skenario backfilling

Contoh penggunaan

Contoh berikut mengasumsikan Anda telah menginstal biner LightIngest untuk sistem operasi Anda. Jika Anda telah menginstal LightIngest sebagai alat .NET, ganti LightIngest dengan LightIngest dalam contoh.

Menyerap data historis dengan properti CreationTime

Saat Anda memuat data historis dari sistem yang ada ke Azure Data Explorer, semua rekaman menerima tanggal penyerapan yang sama. Untuk mengaktifkan partisi data Anda dengan waktu pembuatan dan bukan waktu penyerapan, Anda dapat menggunakan -creationTimePattern argumen . Argumen -creationTimePattern mengekstrak CreationTime properti dari file atau jalur blob. Pola tidak perlu mencerminkan seluruh jalur item, hanya bagian yang menyertakan tanda waktu yang ingin Anda gunakan.

Nilai argumen harus mencakup:

Teks konstanta segera mendahului format tanda waktu, diapit dalam tanda kutip tunggal (awalan)
Format tanda waktu, dalam notasi DateTime .NET standar
Teks konstanta segera mengikuti tanda waktu (akhiran).

Penting

Saat menentukan bahwa waktu pembuatan harus ditimpa, pastikan Lookback properti dalam kebijakan penggabungan Tingkat efektif tabel target selaras dengan nilai dalam jalur file atau blob Anda.

Contoh

Nama blob yang berisi tanggalwaktu sebagai berikut: historicalvalues19840101.parquet (tanda waktu adalah empat digit untuk tahun tersebut, dua digit untuk bulan tersebut, dan dua digit untuk hari dalam sebulan),

Nilai untuk -creationTimePattern argumen adalah bagian dari nama file: "'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

Untuk URI blob yang mengacu pada struktur folder hierarkis, seperti https://storageaccount/mycontainer/myfolder/2002/12/01/blobname.extension,

Nilai untuk -creationTimePattern argumen adalah bagian dari struktur folder: "'folder/'yyyy/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

Menyerap blob menggunakan kunci akun penyimpanan atau token SAS

Serap 10 blob di bawah akun ACCOUNTpenyimpanan tertentu , di folder DIR, di bawah kontainer CONT, dan cocok dengan pola *.csv.gz
Tujuan adalah database DB, tabel TABLE, dan pemetaan MAPPING penyerapan dibuat sebelumnya pada tujuan
Alat menunggu hingga operasi penyerapan selesai
Perhatikan berbagai opsi untuk menentukan database target dan kunci akun penyimpanan vs. token 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

Menyerap semua blob dalam kontainer, tidak termasuk baris header

Serap semua blob di bawah akun ACCOUNTpenyimpanan tertentu , di folder DIR1/DIR2, di bawah kontainer CONT, dan cocok dengan pola *.csv.gz
Tujuan adalah database DB, tabel TABLE, dan pemetaan MAPPING penyerapan dibuat sebelumnya pada tujuan
Blob sumber berisi baris header, sehingga alat ini diinstruksikan untuk menghilangkan rekaman pertama setiap blob
Alat ini memposting data untuk penyerapan dan tidak menunggu operasi penyerapan selesai

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

Menyerap semua file JSON dari jalur

Serap semua file di bawah jalur PATH, cocok dengan pola *.json
Tujuan adalah database DB, tabel TABLE, dan pemetaan penyerapan ditentukan dalam file lokal MAPPING_FILE_PATH
Alat ini memposting data untuk penyerapan dan tidak menunggu operasi penyerapan selesai

LightIngest "https://ingest-{ClusterAndRegion}.kusto.windows.net;Fed=True"
  -database:DB
  -table:TABLE
  -source:"PATH"
  -pattern:*.json
  -format:json
  -mappingPath:"MAPPING_FILE_PATH"

Menyerap file dan menulis file pelacakan diagnostik

Serap semua file di bawah jalur PATH, cocok dengan pola *.json
Tujuan adalah database DB, tabel TABLE, dan pemetaan penyerapan ditentukan dalam file lokal MAPPING_FILE_PATH
Alat ini memposting data untuk penyerapan dan tidak menunggu operasi penyerapan selesai
File pelacakan diagnostik ditulis secara lokal di bawah folder 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"

Mengautentikasi dengan identitas terkelola

Ada tiga tindakan yang dilakukan LightIngest yang dapat menggunakan identitas terkelola untuk autentikasi. Penggunaan identitas terkelola di setiap langkah tidak memerlukan penggunaan identitas terkelola dalam langkah lain. Untuk setiap tindakan, argumen baris perintah terkait diberikan.

Sambungkan ke kluster Kusto: Untuk mengantre penyerapan, alat ini menggunakan string koneksi. Gunakan argumen "-mi" untuk menentukan identitas terkelola yang diinstal pada VM klien yang memiliki hak istimewa penyerapan dalam database target.
Menyambungkan ke Azure Storage untuk mengunduh blob: Gunakan "-ingestmi" untuk menentukan identitas terkelola yang diinstal pada layanan Kusto yang memiliki hak istimewa baca pada kontainer penyimpanan.
Menyambungkan ke Azure Storage untuk mencantumkan blob kontainer: Gunakan argumen "-storageMi" untuk menentukan identitas terkelola yang diinstal pada VM klien yang memiliki hak istimewa daftar pada kontainer penyimpanan. Jika Anda menggunakan metode ini tetapi bukan metode sebelumnya (menyambungkan ke penyimpanan Azure untuk mengunduh blob), identitas terkelola juga harus memiliki hak istimewa baca dan token akan diteruskan ke layanan Kusto yang akan digunakan untuk penyerapan. Oleh karena itu disarankan untuk mengatur ketiga argumen.

Bagikan melalui