Menyerap dari penyimpanan

Perintah .ingest into menyerap data ke dalam tabel dengan "menarik" data dari satu atau beberapa file penyimpanan cloud. Misalnya, perintah dapat mengambil 1000 blob dalam format CSV dari Azure Blob Storage, mengurainya, dan menyerapnya bersama-sama menjadi satu tabel target. Data ditambahkan ke tabel tanpa memengaruhi data yang ada, dan tanpa memodifikasi skema tabel.

Catatan

Metode penyerapan ini ditujukan untuk eksplorasi dan prototipe. Jangan gunakan dalam skenario produksi atau volume tinggi.

Izin

Anda harus memiliki setidaknya izin Table Ingestor untuk menjalankan perintah ini.

Sintaks

.ingest [async] intotableTableNameSourceDataLocator [with(IngestionPropertyName=IngestionPropertyValue [, ...] )]

Pelajari selengkapnya tentang konvensi sintaksis.

Parameter

Nama	Jenis	Diperlukan	Deskripsi
async	string		Jika ditentukan, perintah akan segera kembali dan melanjutkan penyerapan di latar belakang. Hasil perintah mencakup OperationId nilai yang kemudian dapat digunakan dengan .show operation perintah untuk mengambil status dan hasil penyelesaian penyerapan.
TableName	string	✔️	Nama tabel untuk menyerap data. Nama tabel selalu relatif terhadap database dalam konteks. Jika tidak ada objek pemetaan skema yang disediakan, skema database dalam konteks digunakan.
SourceDataLocator	string	✔️	Daftar string koneksi penyimpanan tunggal atau yang dipisahkan koma. String koneksi tunggal harus merujuk ke satu file yang dihosting oleh akun penyimpanan. Penyerapan beberapa file dapat dilakukan dengan menentukan beberapa string koneksi, atau dengan menyerap dari kueritabel eksternal.

Catatan

Sebaiknya gunakan literal string yang dikaburkan untuk SourceDataPointer. Layanan ini akan menggosok kredensial dalam jejak internal dan pesan kesalahan.

Properti penyerapan

Penting

• Dalam data penyerapan antrean di-batch menggunakan properti Penyerapan. Semakin banyak properti pemetaan penyerapan yang berbeda yang digunakan, seperti nilai ConstValue yang berbeda, semakin terfragmentasi penyerapannya, yang dapat menyebabkan penurunan performa.

Tabel berikut mencantumkan properti yang didukung oleh Azure Data Explorer, menjelaskannya, dan memberikan contoh:

Properti	Deskripsi	Contoh
ingestionMapping	Nilai string yang menunjukkan cara memetakan data dari file sumber ke kolom aktual dalam tabel. Tentukan nilai format dengan jenis pemetaan yang relevan. Lihat pemetaan data.	with (format="json", ingestionMapping = "[{\"column\":\"rownumber\", \"Properties\":{\"Path\":\"$.RowNumber\"}}, {\"column\":\"rowguid\", \"Properties\":{\"Path\":\"$.RowGuid\"}}]") (tidak digunakan lagi: avroMapping, csvMapping, jsonMapping)
ingestionMappingReference	Nilai string yang menunjukkan cara memetakan data dari file sumber ke kolom aktual dalam tabel menggunakan objek kebijakan pemetaan yang diberi nama. Tentukan nilai format dengan jenis pemetaan yang relevan. Lihat pemetaan data.	with (format="csv", ingestionMappingReference = "Mapping1") (tidak digunakan lagi: avroMappingReference, csvMappingReference, jsonMappingReference)
creationTime	Nilai tanggalwaktu (diformat sebagai string ISO8601) untuk digunakan pada saat pembuatan jangkauan data yang diserap. Jika tidak ditentukan, nilai saat ini (now()) akan digunakan. Mengesampingkan default berguna saat menyerap data yang lebih lama, sehingga kebijakan retensi akan diterapkan dengan benar. Ketika ditentukan, pastikan properti Lookback dalam Kebijakan penggabungan jangkauan efektif milik tabel target selaras dengan nilai yang ditentukan.	with (creationTime="2017-02-13")
extend_schema	Nilai Boolean yang, jika ditentukan, menginstruksikan perintah untuk memperpanjang skema tabel (defaults ke false). Opsi ini hanya berlaku untuk perintah .append dan .set-or-append. Satu-satunya ekstensi skema yang diizinkan, memiliki kolom tambahan yang ditambahkan ke tabel di akhir.	Jika skema tabel asli adalah (a:string, b:int), ekstensi skema yang valid akan menjadi (a:string, b:int, c:datetime, d:string), tetapi (a:string, c:datetime) tidak akan valid
folder	Untuk perintah ingest-from-query, folder ditetapkan ke tabel. Jika tabel sudah ada, properti ini akan menimpa folder tabel.	with (folder="Tables/Temporary")
format	Format data (lihat format data yang didukung).	with (format="csv")
ingestIfNotExists	Nilai string yang, jika ditentukan, mencegah penyerapan berhasil jika tabel sudah memiliki data yang ditandai dengan tag ingest-by: dengan nilai yang sama. Ini memastikan penyerapan data tidak dapat diubah. Untuk informasi selengkapnya, lihat ingest-by: tag.	Properti with (ingestIfNotExists='["Part0001"]', tags='["ingest-by:Part0001"]') menunjukkan bahwa jika data dengan tag ingest-by:Part0001 telah ada, maka jangan menyelesaikan penyerapan saat ini. Jika belum ada, penyerapan baru ini harus memiliki set tag ini (jika penyerapan di masa depan mencoba untuk menyerap data yang sama lagi.)
ignoreFirstRecord	Nilai Boolean yang, jika diatur ke true, menunjukkan bahwa penyerapan harus mengabaikan baris pertama setiap file. Properti ini berguna untuk file dalam CSV dan format serupa, jika baris pertama dalam file adalah nama kolom. Secara default, false diasumsikan.	with (ignoreFirstRecord=false)
policy_ingestiontime	Nilai Boolean yang, jika ditentukan, menjelaskan apakah akan mengaktifkan Kebijakan Waktu Penyerapan pada tabel yang dibuat oleh perintah ini. Defaultnya adalah true.	with (policy_ingestiontime=false)
recreate_schema	Nilai Boolean yang, jika ditentukan, menjelaskan apakah perintah dapat membuat ulang skema tabel. Properti ini hanya berlaku untuk perintah .set-or-replace. Properti ini lebih diutamakan daripada properti extend_schema jika keduanya ditetapkan.	with (recreate_schema=true)
tags	Daftar tag untuk dikaitkan dengan data yang terserap, diformat sebagai string JSON	with (tags="['Tag1', 'Tag2']")
validationPolicy	String JSON yang menunjukkan validasi mana yang akan dijalankan selama penyerapan data yang diwakili menggunakan format CSV. Lihat Penyerapan data untuk penjelasan tentang berbagai opsi.	with (validationPolicy='{"ValidationOptions":1, "ValidationImplications":1}') (ini sebenarnya adalah kebijakan default)
zipPattern	Gunakan properti ini saat menyerap data dari penyimpanan yang memiliki arsip ZIP. Ini adalah nilai string yang menunjukkan ekspresi reguler untuk digunakan saat memilih file mana dalam arsip ZIP yang akan diserap. Semua file lain dalam arsip akan diabaikan.	with (zipPattern="*.csv")

Autentikasi dan Otorisasi

Setiap string koneksi penyimpanan menunjukkan metode otorisasi yang akan digunakan untuk akses ke penyimpanan. Tergantung pada metode otorisasi, prinsipal mungkin perlu diberikan izin pada penyimpanan eksternal untuk melakukan penyerapan.

Tabel berikut mencantumkan metode autentikasi yang didukung dan izin yang diperlukan untuk menyerap data dari penyimpanan eksternal.

Metode autentikasi	Azure Blob Storage/Data Lake Storage Gen2	Data Lake Storage Gen1
Penyamaran	Pembaca Data Blob Penyimpanan.	Pembaca
Token Akses Bersama (SAS)	Daftar + Baca	Metode autentikasi ini tidak didukung di Gen1.
token akses Microsoft Entra
Kunci akses akun penyimpanan		Metode autentikasi ini tidak didukung di Gen1.
Identitas terkelola	Pembaca Data Blob Penyimpanan.	Pembaca

Mengembalikan

Hasil perintah adalah tabel dengan data yang sebanyak shard data ("jangkauan") yang dihasilkan oleh perintah. Jika tidak ada shard data yang dihasilkan, satu data akan ditampilkan dengan ID jangkauan kosong (bernilai nol).

Nama	Jenis	Deskripsi
ExtentId	guid	Pengidentifikasi unik untuk shard data yang dihasilkan oleh perintah.
ItemLoaded	string	Satu atau beberapa file penyimpanan yang terkait dengan data ini.
Durasi	timespan	Waktu yang diperlukan untuk menjalankan penyerapan.
HasErrors	bool	Apakah data ini mewakili kegagalan penyerapan atau tidak.
OperationId	guid	ID unik yang mewakili operasi. Dapat digunakan dengan perintah .show operation.

Catatan

Perintah ini tidak mengubah skema tabel yang sedang diserap. Jika perlu, data "dikonversi" ke dalam skema ini selama penyerapan, bukan sebaliknya (kolom tambahan diabaikan, dan kolom yang hilang diperlakukan sebagai nilai null).

Contoh

Azure Blob Storage dengan tanda tangan akses bersama

Contoh berikut menginstruksikan kluster Anda untuk membaca dua blob dari Azure Blob Storage sebagai file CSV, dan menyerap kontennya ke dalam tabel T. ... mewakili tanda tangan akses bersama Azure Storage (SAS) yang memberikan akses baca ke setiap blob. Perhatikan juga penggunaan string yang disamarkan (h di depan nilai string) untuk memastikan bahwa SAS tidak pernah direkam.

.ingest into table T (
    h'https://contoso.blob.core.windows.net/container/file1.csv?...',
    h'https://contoso.blob.core.windows.net/container/file2.csv?...'
)

Azure Blob Storage dengan identitas terkelola

Contoh berikut menunjukkan cara membaca file CSV dari Azure Blob Storage dan menyerap kontennya ke dalam tabel T menggunakan autentikasi identitas terkelola. Untuk informasi tambahan tentang metode autentikasi identitas terkelola, lihat Gambaran Umum Autentikasi Identitas Terkelola.

.ingest into table T ('https://StorageAccount.blob.core.windows.net/Container/file.csv;managed_identity=802bada6-4d21-44b2-9d15-e66b29e4d63e')

Azure Data Lake Storage Gen 2

Contoh berikut adalah untuk menyerap data dari Azure Data Lake Storage Gen 2 (ADLSv2). Info masuk yang digunakan di sini (...) adalah info masuk akun penyimpanan (kunci bersama), dan kami menggunakan penyamaran string hanya untuk bagian rahasia string koneksi.

.ingest into table T (
  'abfss://myfilesystem@contoso.dfs.core.windows.net/path/to/file1.csv;...'
)

Azure Data Lake Storage

Contoh berikut menyerap satu file dari Azure Data Lake Storage (ADLS). Ini menggunakan info masuk pengguna untuk mengakses ADLS (jadi tidak perlu memperlakukan URI penyimpanan sebagai yang berisi rahasia). Ini juga menunjukkan cara menentukan properti penyerapan.

.ingest into table T ('adl://contoso.azuredatalakestore.net/Path/To/File/file1.ext;impersonate')
  with (format='csv')

Amazon S3 dengan kunci akses

Contoh berikut menyerap satu file dari Amazon S3 menggunakan ID kunci akses dan kunci akses rahasia.

.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/path/to/file.csv;AwsCredentials=AKIAIOSFODNN7EXAMPLE,wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY')
  with (format='csv')

Amazon S3 dengan URL yang telah ditandatangani

Contoh berikut menyerap satu file dari Amazon S3 menggunakan URL yang telah ditetapkan sebelumnya.

.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/file.csv?<<pre signed string>>')
  with (format='csv')