Menggunakan LightIngest untuk menyerap data ke Azure Data Explorer

  • Artikel

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

Jalankan LightIngest

Untuk menjalankan LightIngest:

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

    Tip

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

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

    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 Jenis Deskripsi Diperlukan
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 Data Explorer Azure 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 "system" untuk identitas yang ditetapkan sistem.
-ingestWithManagedIdentity, -imgestmi string ID klien identitas terkelola (ditetapkan pengguna atau ditetapkan sistem) untuk digunakan untuk menyambungkan. Gunakan "system" untuk identitas yang ditetapkan sistem.
-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 Microsoft Entra ID.
-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 Saat diatur, digunakan untuk mengekstrak properti CreationTime dari file atau jalur blob. Lihat Cara menyerap data menggunakan CreationTime.
-ignoreFirstRow, -ignoreFirst bool Jika diatur, catatan pertama 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.
-kompresi, -cr double 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 bilangan bulat Jika diatur, membatasi penyerapan ke file N pertama.
-listOnly, -list bool Jika diatur, hanya menampilkan item yang akan dipilih untuk diserap.
-ingestTimeout bilangan bulat Waktu habis dalam menit untuk semua penyelesaian operasi penyerapan. 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 bilangan bulat Mengatur batas ukuran total (MB, tidak dikompresi) dari setiap operasi penyerapan.
-filesInBatch bilangan bulat 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 sakelar).

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 pengisian ulang

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 Jangkauan 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 , dalam folder DIR, di bawah kontainer CONT, dan cocok dengan pola *.csv.gz
  • Tujuannya adalah database DB, tabel TABLE, dan pemetaan MAPPING penyerapan dibuat sebelumnya pada tujuan
  • Alat ini 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 , dalam folder DIR1/DIR2, di bawah kontainer CONT, dan cocok dengan pola *.csv.gz
  • Tujuannya adalah database DB, tabel TABLE, dan pemetaan MAPPING penyerapan dibuat sebelumnya pada tujuan
  • Blob sumber berisi baris header, sehingga alat 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
  • Tujuannya 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
  • Tujuannya 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"