Menggunakan LightIngest untuk menyerap data ke Azure Data Explorer

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. Dapatkan LightIngest dengan salah satu dari dua cara:
- 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
```

Catatan

Pertimbangkan untuk menggunakan perintah penyerapan yang diantrekan karena tidak memerlukan penginstalan perangkat lunak.

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.

Masukkan ingest- diikuti oleh string koneksi ke kluster Azure Data Explorer yang 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, LightIngest membutuhkan ukuran data mentah sehingga 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. Sertakan nilai ini dalam 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. 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).	✔️
-identitasTerkelola, -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`. Sertakan nilai ini dalam tanda kutip ganda.
-pola	`string`	Pola pemilihan file sumber dan blob. Mendukung kartubebas. Contohnya,`"*.csv"`. 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 diabaikan. Contohnya,`"*.csv"`. 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 Anda buat 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 (abaikanBarisPertama), -ignoreFirst (abaikanPertama)	`bool`	Jika diatur, rekaman pertama dari setiap file atau 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 dan blob dalam jumlah besar.
-kompresi, -cr	ganda	Petunjuk rasio kompresi. Berguna saat menyerap file dan 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 dan objek blob dari setiap operasi penyerapan data.
-devTracing, -penelusuran	`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 Anda menggunakan LightIngest dengan blob Azure, ia menggunakan properti metadata blob tertentu untuk meningkatkan proses penyerapan.

Properti metadata	Penggunaan
`rawSizeBytes`, `kustoUncompressedSizeBytes`	Jika diatur, LightIngest menginterpretasikan properti ini sebagai ukuran data yang tidak dikompresi
`kustoCreationTime`, `kustoCreationTimeUtc`	LightIngest menafsirkan properti ini sebagai tanda waktu UTC. Jika diatur, ia menggunakan properti ini untuk mengambil alih waktu pembuatan di Kusto. Fitur ini berguna untuk skenario pengisian ulang

Contoh penggunaan

Contoh berikut mengasumsikan Anda menginstal biner LightIngest untuk sistem operasi Anda. Jika Anda 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 mendapatkan tanggal penyerapan yang sama. Untuk mempartisi data Anda dengan waktu pembuatan alih-alih waktu penyerapan, gunakan -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 Anda menentukan bahwa waktu pembuatan harus ditimpa, pastikan Lookback properti dalam kebijakan penggabungan Extents yang efektif di tabel target selaras dengan nilai di 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 dengan 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

Memasukkan semua file di bawah jalur PATH yang cocok dengan pola *.json
Atur tujuan ke database DB, tabel TABLE, dan tentukan pemetaan penyerapan 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"

Memasukkan file dan menulis file pelacakan diagnostik

Memasukkan semua file di bawah jalur PATH yang cocok dengan pola *.json
Atur tujuan ke database DB, tabel TABLE, dan tentukan pemetaan penyerapan dalam file lokal MAPPING_FILE_PATH
Alat ini memposting data untuk penyerapan dan tidak menunggu operasi penyerapan selesai
Menulis file pelacakan diagnostik 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

LightIngest melakukan tiga tindakan 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 yang sebelumnya (terhubung ke penyimpanan Azure untuk mengunduh blob), identitas terkelola harus memiliki hak istimewa baca juga dan token diteruskan ke layanan Kusto yang akan digunakan untuk penyerapan. Atur ketiga argumen.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-11-18