Notitie
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen u aan te melden of mappen te wijzigen.
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen om mappen te wijzigen.
Gebruik de OneLake-tabel read API om rijen uit een Delta Lake- of Apache Iceberg-tabel in OneLake te lezen.
Om tabelgegevens te lezen, stuur je één verzoek om een leessessie te starten. De API levert één of meer onafhankelijke resultaatstromen terug op basis van de grootte van de data die moet worden teruggegeven. Je applicatie kan deze stromen parallel downloaden, wat helpt om grote hoeveelheden tabelgegevens sneller te lezen. Na het downloaden van de streams verwerk je hun Apache Arrow-recordbatches om het volledige resultaat samen te stellen.
De API leest de tabel vanaf een consistent tijdstip, zodat elke resultaatstroom gegevens bevat uit dezelfde snapshot, zelfs als de tabel verandert terwijl de lezing bezig is. Het handhaaft ook OneLake-autorisatie, row-level security (RLS) en column-level security (CLS) voor de geauthenticeerde beller. Dit betekent dat uw applicatie alleen de rijen en kolommen ontvangt waar de aanroeper toegang toe heeft, zonder dat deze beveiligingsmaatregelen in eigen code hoeven te worden gereproduceerd.
Important
De OneLake-API voor het lezen van tabellen is momenteel in openbare proefversie. Functies en gedrag kunnen veranderen vóór algemene beschikbaarheid.
Prerequisites
- Voltooi de vereisten voor de gedeelde tabel API en authenticatiestappen.
- Een HTTP-client die een Apache Arrow IPC-stroom kan verwerken zonder het volledige antwoord te bufferen.
1. Stuur een verzoek voor tabelrijen
Stuur een POST verzoek naar de /read route van de tabel om een leessessie te starten.
Bouw de verzoek-URL door de plaatshouders te vervangen door de identifiers voor de werkruimte, het item, het schema en de tabel die je wilt lezen.
POST <TableReadBaseUrl>/v1.0/workspaces/<WorkspaceID>/items/<ItemID>/schemas/<SchemaName>/tables/<TableName>/read Authorization: Bearer <BearerToken>Voeg de leesopties op die je aanvraag vereist. Gebruik de
columnsoptie om aan te geven welke kolommen je moet teruggeven.Sla elke ondoorzichtige stroomidentificatie op van de succesvolle respons. Een groot resultaat kan over meerdere stromen worden verdeeld. Je moet elke stroom ophalen om alle rijen te krijgen.
Het antwoord initieert een leessessie op basis van een consistente momentopname van de tabelversies die nodig zijn voor uw aanvraag. Elke stream uit deze reactie gebruikt dezelfde snapshot.
2. Download iedere resultaatstroom
Gebruik elke stream-identifier uit het antwoord om het bijbehorende deel van het leesresultaat van de tabel op te halen.
Een leessessie verloopt na 60 minuten. Haal elke stream op voordat de sessie afloopt. Als je stopt nadat je slechts enkele streams hebt opgehaald, ontvang je niet het volledige resultaat.
Voor elke stream-identifier in de allocatierespons stuur je een geauthenticeerd
GETverzoek.GET <TableReadBaseUrl>/v1.0/workspaces/<WorkspaceID>/items/<ItemID>/schemas/<SchemaName>/tables/<TableName>/readStream/<StreamID> Authorization: Bearer <BearerToken>Open de responstekst met een Apache Arrow IPC-streamlezer.
Verwerk de recordbatches zodra ze binnenkomen. Het streamen van de batches voorkomt dat het volledige resultaat in het geheugen wordt geladen.
Herhaal het verzoek voor elke stream-identificatie en combineer de resultaten volgens het verwerkingsmodel van je applicatie.
Elke /readStream reactie is een onafhankelijke Apache Arrow IPC-stream. Gebruik de Apache Arrow-bibliotheek voor je applicatietaal om de recordbatches van elke reactie te lezen. Voor meer informatie over het stroomformaat, zie Serialisatie en interprocescommunicatie (IPC).
De responsbody bevat ruwe Apache Arrow IPC-stroomgegevens, inclusief de schema-informatie die nodig is om de recordbatches te interpreteren. Vertrouw niet op de rijvolgorde, of ga er niet van uit dat de positie van een stroom in de respons zijn positie in het volledige resultaat bepaalt.
Begrijp OneLake-beveiliging voor table read API
De API handhaaft OneLake-beveiliging door gebruik te maken van de identiteit die je bearer token vertegenwoordigt:
- Als je geen toestemming hebt om de tabel te bekijken, geeft de service een niet-gevonden antwoord terug.
- Als beveiliging op rijniveau (RLS) alle rijen die voor je zichtbaar zijn wegfiltert, slaagt het verzoek, maar retourneert het een lege Arrow-respons.
- Als je een wildcard-kolomprojectie gebruikt, bevat de respons alleen kolommen die column-level security (CLS) je toestaat te bekijken.
- Als je expliciet een kolom aanvraagt die je niet kunt bekijken, geeft de dienst een niet-gevonden antwoord terug.
Omdat ongeautoriseerde tabellen en kolommen niet-gevonden antwoorden teruggeven, gebruik geen niet-gevonden antwoord om te bepalen of een bron bestaat.
Overwegingen en beperkingen
- De table read API ondersteunt geen cross-region snelkoppelingen.
- Er worden kosten in rekening gebracht voor de
POST /readbewerking. Het ophalen van data met behulp/readStreamgenereert geen aparte table read facturing-gebeurtenis. Voor meer informatie, zie Table read API consumption.