Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
Gunakan API pembacaan tabel OneLake untuk membaca baris dari tabel Delta Lake atau Apache Iceberg di OneLake.
Untuk membaca data tabel, kirim satu permintaan untuk memulai sesi baca. API mengembalikan satu atau lebih aliran hasil independen berdasarkan ukuran data yang perlu dikembalikan. Aplikasi Anda dapat mengunduh aliran ini secara paralel, yang membantunya membaca volume besar data tabel lebih cepat. Setelah mengunduh stream, proses batch record Apache Arrow-nya untuk menyusun hasil lengkap.
API membaca tabel dari titik waktu yang konsisten, sehingga setiap aliran hasil berisi data dari snapshot yang sama, meskipun tabel berubah saat pembacaan sedang berlangsung. Aplikasi ini juga menegakkan otorisasi OneLake, keamanan tingkat baris (RLS), dan keamanan tingkat kolom (CLS) untuk penelepon yang telah diautentikasi. Ini berarti aplikasi Anda hanya menerima baris dan kolom yang diizinkan diakses oleh penelpon, tanpa perlu mereproduksi kontrol keamanan ini dalam kode sendiri.
Important
API pembacaan tabel OneLake saat ini dalam pratinjau publik. Fitur dan perilaku mungkin berubah sebelum ketersediaan umum.
Prasyarat
- Lengkapi prasyarat API tabel bersama dan langkah-langkah otentikasi.
- Klien HTTP yang dapat memproses aliran Apache Arrow IPC tanpa membuffer seluruh respons.
1. Kirim permintaan untuk baris tabel
Kirim POST permintaan ke rute tabel /read untuk memulai sesi baca.
Bangun URL permintaan dengan mengganti placeholder dengan pengenal untuk workspace, item, skema, dan tabel yang ingin Anda baca.
POST <TableReadBaseUrl>/v1.0/workspaces/<WorkspaceID>/items/<ItemID>/schemas/<SchemaName>/tables/<TableName>/read Authorization: Bearer <BearerToken>Sertakan opsi baca yang diperlukan aplikasi Anda dalam permintaan. Gunakan opsi
columnsuntuk menentukan kolom mana yang akan dikembalikan.Simpan setiap pengenal aliran yang tidak transparan dari respons yang berhasil. Hasil yang besar dapat dibagi ke dalam beberapa aliran. Anda harus mengambil setiap stream untuk mendapatkan semua baris.
Respons memulai sesi baca melalui snapshot konsisten dari versi tabel yang dibutuhkan untuk permintaan Anda. Setiap aliran dari respons ini menggunakan snapshot yang sama.
2. Unduh setiap aliran hasil
Gunakan setiap pengenal aliran dari respons untuk mengambil bagian yang sesuai dari hasil bacaan tabel.
Sesi membaca berakhir setelah 60 menit. Ambil setiap stream sebelum sesi berakhir. Jika Anda berhenti setelah hanya mengambil beberapa stream, Anda tidak akan mendapatkan hasil lengkap.
Untuk setiap pengenal aliran dalam respons alokasi, kirim permintaan yang telah diautentikasi
GET.GET <TableReadBaseUrl>/v1.0/workspaces/<WorkspaceID>/items/<ItemID>/schemas/<SchemaName>/tables/<TableName>/readStream/<StreamID> Authorization: Bearer <BearerToken>Buka bodi respons menggunakan pembaca aliran IPC Apache Arrow.
Proses batch rekaman data saat batch tersebut diterima. Streaming batch menghindari memuat hasil lengkap ke memori.
Ulangi permintaan untuk setiap pengenal aliran dan gabungkan hasilnya sesuai dengan model pemrosesan aplikasi Anda.
Setiap respons /readStream merupakan stream IPC Apache Arrow yang berdiri sendiri. Gunakan pustaka Apache Arrow untuk bahasa aplikasi Anda guna membaca batch rekaman dari setiap respons. Untuk informasi lebih lanjut tentang format aliran, lihat Serialisasi dan komunikasi antarproses (IPC).
Isi respons berisi data mentah Apache Arrow IPC stream, termasuk informasi skema yang diperlukan untuk menginterpretasikan batch rekaman. Jangan bergantung pada urutan baris, atau asumsikan posisi aliran dalam respons menentukan posisinya dalam hasil lengkap.
Memahami keamanan OneLake untuk API pembacaan tabel
API menegakkan keamanan OneLake dengan menggunakan identitas yang diwakili oleh token pembawa Anda:
- Jika Anda tidak memiliki izin untuk melihat tabel, layanan akan mengembalikan respons yang tidak ditemukan.
- Jika keamanan tingkat baris (RLS) menyaring semua baris yang dapat Anda lihat, permintaan berhasil tetapi mengembalikan respons Arrow yang kosong.
- Jika Anda menggunakan proyeksi kolom wildcard, respons hanya mencakup kolom yang diizinkan untuk Anda lihat oleh keamanan tingkat kolom (CLS).
- Jika Anda secara eksplisit meminta kolom yang tidak dapat Anda lihat, layanan akan mengembalikan respons "tidak ditemukan".
Karena tabel dan kolom yang tidak sah mengembalikan respons yang tidak ditemukan, jangan gunakan respons yang tidak ditemukan untuk menentukan apakah sumber daya itu ada.
Pertimbangan dan keterbatasan
- API pembacaan tabel tidak mendukung pintasan lintas wilayah.
- Kamu akan ditagih untuk operasi
POST /read. Mengambil data menggunakan/readStreamtidak memicu peristiwa penagihan pembacaan tabel yang terpisah. Untuk informasi lebih lanjut, lihat konsumsi API pembacaan tabel.