OneLake tablo verilerini okuyun (önizleme)

OneLake'te Delta Lake veya Apache Iceberg tablolarından satır okumak için OneLake tablo okuma API'sini kullanın.

Tablo verilerini okumak için, bir okuma oturumu başlatmak için bir talep gönderin. API, geri dönmesi gereken verinin boyutuna göre bir veya daha fazla bağımsız sonuç akışı döndürür. Uygulamanız bu akışları paralel olarak indirebilir, bu da büyük hacimli tablo verilerini daha hızlı okumasına yardımcı olur. Akışları indirdikten sonra, Apache Arrow kayıt partilerini işleyerek tam sonucu bir araya getirin.

API, tabloyu tutarlı bir zaman noktasından okur, böylece her sonuç akışı aynı anlık görüntüden veri içerir, okuma devam ederken tablo değişse bile. Ayrıca, doğrulanmış arayan için OneLake yetkilendirmesi, satır düzeyinde güvenlik (RLS) ve sütun düzeyinde güvenliği (CLS) uygular. Bu, uygulamanızın yalnızca arayanın erişebileceği satır ve sütunları aldığı anlamına gelir, bu güvenlik kontrollerini kendi kodunda yeniden üretmesine gerek kalmaz.

Önemli

OneLake tablo okuma API'si şu anda halka açık önizleme aşamasında. Özellikler ve davranışlar genel kullanılabilirlik öncesinde değişebilir.

Prerequisites

1. Tablo satırları için bir talep gönderin

Bir okuma oturumu başlatmak için tablonun POST yoluna bir /read istek gönderin.

  1. Okumak istediğiniz çalışma alanı, öğe, şema ve tabloya ait tanımlayıcılarla yer tutucuları değiştirerek istek URL’sini oluşturun.

    POST <TableReadBaseUrl>/v1.0/workspaces/<WorkspaceID>/items/<ItemID>/schemas/<SchemaName>/tables/<TableName>/read
Authorization: Bearer <BearerToken>

  2. Başvurunuzun gerektirdiği okuma seçeneklerini talebe dahil edin. Hangi sütunların geri döneceğini belirtmek için seçeneği columns kullanın.

  3. Başarılı yanıttaki tüm opak akış tanımlayıcılarını kaydet. Büyük bir sonuç birden fazla akışa bölünebilir. Tüm satırları almak için her akışı geri almalısınız.

Yanıt, isteğiniz için gerekli olan tablo sürümlerinin tutarlı anlık görüntüsüne dayalı olarak bir okuma oturumu başlatır. Bu yanıttan gelen her akış aynı anlık görüntüyü kullanır.

2. Her sonuç akışını indirin

Yanıttaki her akış tanımlayıcısını kullanarak tablo okuma sonucunun karşılık gelen kısmını elde edin.

Okuma oturumu 60 dakika sonra sona erer. Oturum bitmeden önce tüm akışları alın. Yalnızca bazı akışları aldıktan sonra işlemi durdurursanız, sonucun tamamını alamazsınız.

  1. Tahsis yanıtındaki her akış tanımlayıcısı için, kimlik doğrulamalı GET bir talep gönderin.

    GET <TableReadBaseUrl>/v1.0/workspaces/<WorkspaceID>/items/<ItemID>/schemas/<SchemaName>/tables/<TableName>/readStream/<StreamID>
Authorization: Bearer <BearerToken>

  2. Yanıt gövdesini Apache Arrow IPC akış okuyucusuyla açın.

  3. Kayıt gruplarını ulaştıkça işleyin. Toplu akış yapmak, tüm sonucu belleğe yüklemeyi engeller.

  4. Her akış tanımlayıcısı için talebi tekrarlayın ve sonuçları uygulamanızın işlem modeline göre birleştirin.

Her /readStream yanıt bağımsız bir Apache Arrow IPC akışıdır. Her yanıttan kayıt gruplarını okumak için uygulama diliniz için Apache Arrow kütüphanesini kullanın. Akış formatı hakkında daha fazla bilgi için Serileştirme ve süreçlerarası iletişim (IPC) bölümünü inceleyebilirsiniz.

Yanıt gövdesi, kayıt partilerini yorumlamak için gereken şema bilgisi dahil olmak üzere ham Apache Arrow IPC akışı verilerini içerir. Satır sırasına güvenmeyin ya da bir akışın yanıttaki konumunun tam sonuçtaki konumunu belirlediğini varsaymayın.

Table Read API için OneLake güvenliğini Anlayın

API, taşıyıcı tokenınızın temsil ettiği kimlik kullanarak OneLake güvenliğini sağlar:

  • Tabloyu görüntüleme izniniz yoksa, hizmet bulunamayan bir yanıt gönderir.
  • Eğer satır düzeyindeki güvenlik (RLS), görüntüleyebileceğiniz tüm satırları filtrelerse, istek başarılı olur ancak boş bir Arrow yanıtı döndürür.
  • Eğer joker sütun projeksiyonu kullanırsanız, yanıt yalnızca sütun düzeyindeki güvenliğin (CLS) görüntülemenize izin verdiği sütunları içerir.
  • Görüntüleyemediğiniz bir sütunu özellikle talep ederseniz, hizmet bulunamadı yanıtı döndürür.

Yetkisiz tablolar ve sütunlar bulunmamış yanıtlar döndürdüğünden, bir kaynağın var olup olmadığını belirlemek için bulunmamış yanıtı kullanmayın.

Dikkat edilmesi gerekenler ve sınırlamalar

  • Tablo okuma API'si bölgeler arası kısayolları desteklemiyor.
  • POST /read işlemi için ücretlendirilirsiniz. /readStream kullanarak veri alma, ayrı bir tablo okuma faturalandırma olayı oluşturmaz. Daha fazla bilgi için Tablo okuma API tüketimi sayfasına bakınız.
  • Last updated on