Lue OneLake-taulukkotiedot (esikatselu)

Käytä OneLake-taulun lukurajapintaa lukeaksesi rivejä Delta Lake- tai Apache Iceberg -taulukosta OneLakessa.

Taulukon tietojen lukemiseksi lähetä yksi pyyntö lukusession aloittamiseksi. API palauttaa yhden tai useamman riippumattoman tulosvirran palautettavan datan koon mukaan. Sovelluksesi voi ladata nämä virrat rinnakkain, mikä auttaa sitä lukemaan suuria määriä taulukkodataa nopeammin. Kun olet ladannut striimit, käsittele heidän Apache Arrow -levyeränsä kokoaaksesi kokonaistuloksen.

API lukee taulukon johdonmukaisesta ajankohdasta, joten jokainen tulosvirta sisältää dataa samasta snapshotista, vaikka taulukko muuttuisi lukemisen aikana. Se myös valvoo OneLake-valtuutusta, rivitason tietoturvaa (RLS) ja sarakketason turvallisuutta (CLS) todennetulle soittajalle. Tämä tarkoittaa, että sovelluksesi vastaanottaa vain ne rivit ja sarakkeet, joihin soittajalla on oikeus päästä, ilman että tarvitsee toistaa näitä turvakontrolleja omassa koodissaan.

Tärkeää

OneLake-taulun lukurajapinta on tällä hetkellä julkisessa esikatselussa. Ominaisuudet ja käyttäytyminen voivat muuttua ennen yleistä saatavuutta.

Edellytykset

1. Lähetä pyyntö taulukkoriveistä

Lähetä POST pyyntö taulukon /read reitille aloittaaksesi lukusession.

  1. Rakenna pyyntö-URL korvaamalla paikkamerkinnät työtilan, kohteen, skeeman ja taulukon tunnisteilla, joita haluat lukea.

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

  2. Sisällytä hakemuksesi vaatimat lukuvaihtoehdot pyyntöön. Käytä vaihtoehtoa columns määrittääksesi, mitkä sarakkeet palautetaan.

  3. Tallenna kaikki läpinäkymättömät virran tunnisteet onnistuneesta vastauksesta. Suuri tulos voi jakautua useiden virtojen kesken. Sinun täytyy hakea jokainen striimi saadaksesi kaikki rivit.

Vastaus aloittaa lukusession johdonmukaisen tilannekuvan yli niistä taulukon versioista, joita pyyntösi vaatii. Jokainen tämän vastauksen striimi käyttää samaa snapshotia.

2. Lataa jokainen tulosvirta

Käytä kutakin virran tunnistetta vastauksesta hakeaksesi vastaavan osan taulukon lukutulosta.

Lukusessio päättyy 60 minuutin kuluttua. Hae kaikki striimit ennen istunnon päättymistä. Jos lopetat haettuasi vain joitakin striimejä, et saa koko tulosta.

  1. Jokaiselle virran tunnisteelle allokointivastauksessa lähetä todennettu GET pyyntö.

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

  2. Avaa vastausrunko Apache Arrow IPC -striimauslukijalla.

  3. Käsittele asiakirjaerät sitä mukaa kun ne saapuvat. Eräiden suoratoisto välttää koko tuloksen lataamisen muistiin.

  4. Toista pyyntö jokaiselle virtatunnisteelle ja yhdistä tulokset sovelluksesi käsittelymallin mukaan.

Tärkeää

Vastaus 200 OK tarkoittaa, että virran vastaus on alkanut, ei että kaikki data olisi vastaanotettu. Jatka vastausrungon lukemista ja käsittele HTTP-siirtovirheitä sekä nuolien dekoodausvirheitä. Jos yhteys nollautuu tai HTTP-asiakas raportoi keskeneräisen vastauksen, käsittele kyseinen virta epäonnistuneena, vaikka olisit jo saanut kelvolliset tietueerät.

Jokainen /readStream vastaus on itsenäinen Apache Arrow IPC -virta. Käytä sovelluskielen Apache Arrow -kirjastoa lukeaksesi jokaisen vastauksen tietueerät. Lisätietoja virtamuodosta löytyy kohdasta Serialisointi ja prosessien välinen viestintä (IPC).

Vastausrunko sisältää raakaa Apache Arrow IPC -virran dataa, mukaan lukien skeematiedot, joita tarvitaan tietueeräiden tulkintaan. Älä luota rivijärjestykseen tai oleta, että virran sijainti vastauksessa määrittää sen sijainnin kokonaistuloksessa.

Ymmärrä OneLake-tietoturva taulukkolukurajapinnalle

API valvoo OneLake-turvallisuutta käyttämällä identiteettiä, jota kantaja-tokenisi edustaa:

  • Jos sinulla ei ole lupaa nähdä taulukkoa, palvelu palauttaa löytämättömän vastauksen.
  • Jos rivitason turvallisuus (RLS) suodattaa jokaisen katsomasi rivin, pyyntö onnistuu, mutta palauttaa tyhjän nuolivastauksen.
  • Jos käytät villikortti-sarakkeiden projektiota, vastaus sisältää vain ne sarakkeet, joita sarakketason turvallisuus (CLS) sallii sinun nähdä.
  • Jos pyydät nimenomaisesti sarakkeen, jota et voi nähdä, palvelu palauttaa löytämättömän vastauksen.

Koska luvattomat taulukot ja sarakkeet palauttavat löytämättömiä vastauksia, älä käytä löytämätöntä vastausta selvittääksesi, onko resurssi olemassa.

Huomioitavat asiat ja rajoitukset

  • Taulukon lukurajapinta ei tue alueiden välisiä pikanäppäimiä.
  • Sinut laskutetaan POST /read leikkauksesta. Datan hakeminen ei /readStream aiheuta erillistä taulukkolukutapahtumaa. Lisätietoja löytyy osoitteesta Taulukkoluku API:n kulutus.
  • Viimeksi päivitetty