Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Usa l'API di lettura delle tabelle OneLake per leggere righe da una tabella Delta Lake o Apache Iceberg in OneLake.
Per leggere i dati della tabella, invia una richiesta per avviare una sessione di lettura. L'API restituisce uno o più flussi di risultati indipendenti in base alla dimensione dei dati da restituire. La tua applicazione può scaricare questi flussi in parallelo, il che le aiuta a leggere più rapidamente grandi volumi di dati di tabelle. Dopo aver scaricato gli stream, elabora i loro lotti di record Apache Arrow per assemblare il risultato completo.
L'API legge la tabella da un punto coerente nel tempo, quindi ogni flusso di risultati contiene dati dalla stessa istantanea, anche se la tabella cambia durante la lettura in corso. Applica inoltre l'autorizzazione OneLake, la sicurezza a livello di riga (RLS) e la sicurezza a livello di colonna (CLS) per il chiamante autenticato. Ciò significa che la tua applicazione riceve solo le righe e le colonne a cui il chiamante è autorizzato ad accedere, senza dover riprodurre questi controlli di sicurezza nel proprio codice.
Importante
L'API di lettura delle tabelle OneLake è attualmente in anteprima pubblica. Le funzionalità e il comportamento potrebbero cambiare prima della disponibilità generale.
Prerequisiti
- Completa i prerequisiti dell'API a tabelle condivise e i passaggi di autenticazione.
- Un client HTTP che può elaborare un flusso IPC Apache Arrow senza bufferare la risposta completa.
1. Inviare una richiesta per le righe delle tabelle
Invia una richiesta POST all'endpoint della tabella /read per avviare una sessione di lettura.
Costruisci l'URL della richiesta sostituendo i segnaposto con gli identificatori per l'area di lavoro, l'elemento, lo schema e la tabella che vuoi leggere.
POST <TableReadBaseUrl>/v1.0/workspaces/<WorkspaceID>/items/<ItemID>/schemas/<SchemaName>/tables/<TableName>/read Authorization: Bearer <BearerToken>Includi le opzioni di lettura richieste dalla tua domanda nella richiesta. Usa l'opzione
columnsper specificare quali colonne restituire.Salva ogni identificatore di flusso opaco della risposta riuscita. Un risultato di grandi dimensioni potrebbe essere suddiviso in più flussi. Devi recuperare ogni flusso per ottenere tutte le righe.
La risposta avvia una sessione di lettura su un'istantanea coerente delle versioni delle tabelle necessarie per la tua richiesta. Ogni flusso da questa risposta utilizza lo stesso snapshot.
2. Scarica ogni flusso di risultati
Usa ogni identificatore di flusso dalla risposta per recuperare la sua parte corrispondente del risultato della lettura della tabella.
Una sessione di lettura scade dopo 60 minuti. Recupera tutti i flussi prima che la sessione scada. Se ti fermi dopo aver recuperato solo alcuni stream, non riceverai il risultato completo.
Per ogni identificatore di flusso nella risposta all'allocazione, invia una richiesta autenticata
GET.GET <TableReadBaseUrl>/v1.0/workspaces/<WorkspaceID>/items/<ItemID>/schemas/<SchemaName>/tables/<TableName>/readStream/<StreamID> Authorization: Bearer <BearerToken>Apri il corpo della risposta con un lettore di flusso IPC Apache Arrow.
Elabora i lotti di record man mano che arrivano. Lo streaming dei lotti evita di caricare il risultato completo in memoria.
Ripeti la richiesta per ogni identificatore di flusso e combina i risultati secondo il modello di elaborazione della tua applicazione.
Ogni /readStream risposta è un flusso IPC indipendente di Apache Arrow. Usa la libreria Apache Arrow come linguaggio applicativo per leggere i lotti di record da ogni risposta. Per maggiori informazioni sul formato dello stream, vedi Serializzazione e comunicazione interprocessi (IPC).
Il corpo della risposta contiene i dati grezzi del flusso IPC di Apache Arrow, incluse le informazioni dello schema necessarie per interpretare i lotti di record. Non affidarti all'ordine delle righe, né presumere che la posizione di un flusso nella risposta determini la sua posizione nel risultato completo.
Comprendi la sicurezza OneLake per l'API di lettura di tabella
L'API garantisce la sicurezza OneLake utilizzando l'identità che rappresenta il tuo token portante:
- Se non hai il permesso di visualizzare la tabella, il servizio restituisce una risposta non trovata.
- Se la sicurezza a livello di riga (RLS) filtra ogni riga che puoi visualizzare, la richiesta ha successo ma restituisce una risposta Arrow vuota.
- Se usi una proiezione wildcard di colonne, la risposta include solo le colonne che la sicurezza a livello di colonna (CLS) ti consente di visualizzare.
- Se richiedi esplicitamente una colonna che non puoi visualizzare, il servizio restituisce una risposta di errore "non trovato".
Poiché tabelle e colonne non autorizzate restituiscono risposte non trovate, non usare una risposta non trovata per determinare se una risorsa esiste.
Considerazioni e limitazioni
- L'API di lettura delle tabelle non supporta i collegamenti tra regioni.
- Ti viene addebitata l'operazione
POST /read. Il recupero dei dati utilizzando/readStreamnon genera un evento di fatturazione distinto per la lettura della tabella. Per maggiori informazioni, vedi Consumo API di lettura di tabelle.