Przeczytaj dane tabelowe OneLake (podgląd)

Użyj API czytania tabel OneLake, aby odczytać wiersze z tabeli Delta Lake lub Apache Iceberg w OneLake.

Aby odczytać dane tabelowe, wyślij jedno żądanie rozpoczęcia sesji odczytu. API zwraca jeden lub więcej niezależnych strumieni wyników w zależności od wielkości danych, które muszą zostać zwrócone. Twoja aplikacja może pobierać te strumienie równolegle, co pomaga szybciej odczytywać duże ilości danych tabelowych. Po pobraniu strumieni przetworz partie rekordów Apache Arrow, aby zebrać pełny wynik.

Interfejs API odczytuje tabelę z jednego, spójnego punktu w czasie, więc każdy strumień wyników zawiera dane z tej samej migawki, nawet jeśli tabela zmienia się w trakcie odczytu. Egzekwuje także autoryzację OneLake, bezpieczeństwo na poziomie wiersza (RLS) oraz bezpieczeństwo na poziomie kolumn (CLS) dla uwierzytelnionego wywołującego. Oznacza to, że Twoja aplikacja otrzymuje tylko te wiersze i kolumny, do których dzwoniący ma uprawnienia, bez konieczności odtwarzania tych zabezpieczeń w swoim kodzie.

Important

API czytania tabel OneLake jest obecnie dostępne w podglądzie publicznym. Funkcje i zachowanie mogą ulec zmianie przed ogólną dostępnością.

Wymagania wstępne

1. Wyślij zapytanie o wiersze tabeli

Wyślij żądanie POST do ścieżki /read tabeli, aby rozpocząć sesję odczytu.

  1. Utwórz adres URL żądania, zastępując symbole zastępcze identyfikatorami obszaru roboczego, elementu, schematu i tabeli, którą chcesz odczytać.

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

  2. Dołącz do wniosku opcje odczytu, których wymaga twoja aplikacja. Użyj columns opcji określenia, które kolumny zwracać.

  3. Zapisz każdy nieprzezroczysty identyfikator strumienia z udanej odpowiedzi. Duży wynik może być podzielony na kilka strumieni. Musisz pobrać każdy strumień, aby uzyskać wszystkie wiersze.

Odpowiedź rozpoczyna sesję odczytu na podstawie spójnej migawki wersji tabel potrzebnych do obsłużenia żądania. Każdy strumień z tej odpowiedzi korzysta z tej samej migawki.

2. Pobierz każdy strumień wyników

Użyj każdego identyfikatora strumienia z odpowiedzi, aby pobrać odpowiadającą mu część wyniku odczytu tabeli.

Sesja odczytu kończy się po 60 minutach. Pobierz każdy stream przed wygaśnięciem sesji. Jeśli przerwiesz po pobraniu tylko części strumieni, nie otrzymasz pełnego wyniku.

  1. Dla każdego identyfikatora strumienia w odpowiedzi alokacyjnej wyślij GET uwierzytelnione żądanie.

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

  2. Otwórz treść odpowiedzi za pomocą czytnika strumienia IPC Apache Arrow.

  3. Przetwarzaj partie płyt w momencie ich nadejścia. Strumieniowanie partii pozwala uniknąć ładowania całego wyniku do pamięci.

  4. Powtórz żądanie dla każdego identyfikatora strumienia i połącz wyniki zgodnie z modelem przetwarzania aplikacji.

Każda /readStream odpowiedź to niezależny strumień IPC w formacie Apache Arrow. Użyj biblioteki Apache Arrow jako języka aplikacji, aby odczytać partie rekordów z każdej odpowiedzi. Więcej informacji o formacie strumienia można znaleźć w artykule Serializacja i komunikacja międzyprocesowa (IPC).

Korpus odpowiedzi zawiera surowe dane strumieniowe IPC Apache Arrow, w tym informacje o schemacie potrzebne do interpretacji partii rekordów. Nie polegaj na kolejności wierszy ani nie zakładaj, że pozycja strumienia w odpowiedzi determinuje jego pozycję w pełnym wyniku.

Zrozum bezpieczeństwo OneLake dla API czytania tabel

API wymusza bezpieczeństwo OneLake, wykorzystując tożsamość, którą reprezentuje token nosiciela:

  • Jeśli nie masz uprawnień do wyświetlenia tabeli, usługa zwraca odpowiedź „Nie znaleziono”.
  • Jeśli zabezpieczenia na poziomie wierszy (RLS) odfiltrują wszystkie wiersze, do których masz dostęp, żądanie zakończy się powodzeniem, ale zwróci pustą odpowiedź w formacie Arrow.
  • Jeśli użyjesz projekcji kolumn z użyciem symbolu wieloznacznego, odpowiedź będzie zawierać tylko te kolumny, do których wyświetlania uprawnia zabezpieczenie na poziomie kolumn (CLS).
  • Jeśli jawnie zażądasz kolumny, do której nie masz dostępu, usługa zwróci odpowiedź „nie znaleziono”.

Ponieważ nieautoryzowane tabele i kolumny zwracają odpowiedzi nieznalezione, nie używaj odpowiedzi nieznalezionych do ustalenia, czy zasób istnieje.

Uwagi i ograniczenia

  • API do czytania tabel nie obsługuje skrótów międzyregionalnych.
  • Opłata jest naliczana za operację POST /read. Pobieranie danych przy użyciu /readStream nie generuje osobnego zdarzenia rozliczeniowego za odczyt tabeli. Więcej informacji można znaleźć w sekcji Table Read API consumption.
  • Last updated on