Ανάγνωση δεδομένων πίνακα OneLake (έκδοση προεπισκόπησης)

Χρησιμοποιήστε το API ανάγνωσης πίνακα OneLake για να διαβάσετε γραμμές από έναν πίνακα Delta Lake ή Apache Iceberg στο OneLake.

Για να διαβάσετε δεδομένα πίνακα, στείλτε μία αίτηση για να ξεκινήσετε μια περίοδο λειτουργίας ανάγνωσης. Το API επιστρέφει μία ή περισσότερες ανεξάρτητες ροές αποτελεσμάτων με βάση το μέγεθος των δεδομένων που πρέπει να επιστραφούν. Η εφαρμογή σας μπορεί να κατεβάσει αυτές τις ροές παράλληλα, κάτι που τη βοηθά να διαβάζει μεγάλους όγκους δεδομένων πίνακα πιο γρήγορα. Μετά τη λήψη των ροών, επεξεργαστείτε τις παρτίδες εγγραφής Apache Arrow για να συγκεντρώσετε το πλήρες αποτέλεσμα.

Το API διαβάζει τον πίνακα από μια σταθερή χρονική στιγμή, επομένως κάθε ροή αποτελεσμάτων περιέχει δεδομένα από το ίδιο στιγμιότυπο, ακόμα κι αν ο πίνακας αλλάζει ενώ η ανάγνωση βρίσκεται σε εξέλιξη. Επιβάλλει επίσης εξουσιοδότηση OneLake, ασφάλεια σε επίπεδο γραμμής (RLS) και ασφάλεια σε επίπεδο στήλης (CLS) για τον καλούντα με έλεγχο ταυτότητας. Αυτό σημαίνει ότι η εφαρμογή σας λαμβάνει μόνο τις γραμμές και τις στήλες στις οποίες ο καλών είναι εξουσιοδοτημένος να έχει πρόσβαση, χωρίς να χρειάζεται να αναπαράγει αυτούς τους ελέγχους ασφαλείας στον δικό του κώδικα.

Σημαντικός

Το API ανάγνωσης πίνακα OneLake βρίσκεται αυτήν τη στιγμή σε δημόσια προεπισκόπηση. Οι δυνατότητες και η συμπεριφορά ενδέχεται να αλλάξουν πριν από τη γενική διαθεσιμότητα.

Προϋποθέσεις

1. Στείλτε ένα αίτημα για σειρές πίνακα

Στείλτε μια POST αίτηση στη δρομολόγηση του /read πίνακα για να ξεκινήσετε μια περίοδο λειτουργίας ανάγνωσης.

  1. Δημιουργήστε τη διεύθυνση URL αίτησης αντικαθιστώντας τα σύμβολα κράτησης θέσης με τα αναγνωριστικά για τον χώρο εργασίας, το στοιχείο, το σχήμα και τον πίνακα που θέλετε να διαβάσετε.

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

  2. Συμπεριλάβετε τις επιλογές ανάγνωσης που απαιτεί η αίτησή σας στο αίτημα. Χρησιμοποιήστε την columns επιλογή για να καθορίσετε ποιες στήλες θα επιστραφούν.

  3. Αποθηκεύστε κάθε αδιαφανές αναγνωριστικό ροής από την επιτυχή απόκριση. Ένα μεγάλο αποτέλεσμα μπορεί να χωριστεί σε πολλές ροές. Πρέπει να ανακτήσετε κάθε ροή για να λάβετε όλες τις σειρές.

Η απόκριση ξεκινά μια περίοδο λειτουργίας ανάγνωσης σε ένα συνεπές στιγμιότυπο των εκδόσεων του πίνακα που απαιτούνται για την αίτησή σας. Κάθε ροή από αυτήν την απόκριση χρησιμοποιεί το ίδιο στιγμιότυπο.

2. Κατεβάστε κάθε ροή αποτελεσμάτων

Χρησιμοποιήστε κάθε αναγνωριστικό ροής από την απόκριση για να ανακτήσετε το αντίστοιχο τμήμα του αποτελέσματος ανάγνωσης πίνακα.

Μια περίοδος ανάγνωσης λήγει μετά από 60 λεπτά. Ανακτήστε κάθε ροή πριν από τη λήξη της περιόδου λειτουργίας. Εάν σταματήσετε μετά την ανάκτηση μόνο ορισμένων ροών, δεν θα λάβετε το πλήρες αποτέλεσμα.

  1. Για κάθε αναγνωριστικό ροής στην απόκριση κατανομής, στείλτε ένα αίτημα με GET έλεγχο ταυτότητας.

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

  2. Ανοίξτε το σώμα απόκρισης με ένα πρόγραμμα ανάγνωσης ροής IPC Apache Arrow.

  3. Επεξεργαστείτε τις παρτίδες δίσκων καθώς φτάνουν. Η ροή των παρτίδων αποφεύγει τη φόρτωση του πλήρους αποτελέσματος στη μνήμη.

  4. Επαναλάβετε το αίτημα για κάθε αναγνωριστικό ροής και συνδυάστε τα αποτελέσματα σύμφωνα με το μοντέλο επεξεργασίας της εφαρμογής σας.

Κάθε /readStream απόκριση είναι μια ανεξάρτητη ροή Apache Arrow IPC. Χρησιμοποιήστε τη βιβλιοθήκη Apache Arrow για τη γλώσσα της εφαρμογής σας για να διαβάσετε τις παρτίδες εγγραφών από κάθε απόκριση. Για περισσότερες πληροφορίες σχετικά με τη μορφή ροής, ανατρέξτε στο θέμα Σειριοποίηση και επικοινωνία μεταξύ διεργασιών (IPC).

Το σώμα απόκρισης περιέχει ακατέργαστα δεδομένα ροής Apache Arrow IPC, συμπεριλαμβανομένων των πληροφοριών σχήματος που απαιτούνται για την ερμηνεία των παρτίδων εγγραφών. Μην βασίζεστε στη σειρά των γραμμών και μην υποθέτετε ότι η θέση μιας ροής στην απόκριση καθορίζει τη θέση της στο πλήρες αποτέλεσμα.

Κατανόηση της ασφάλειας OneLake για API ανάγνωσης πίνακα

Το API επιβάλλει την ασφάλεια OneLake χρησιμοποιώντας την ταυτότητα που αντιπροσωπεύει το διακριτικό κομιστή:

  • Εάν δεν έχετε δικαίωμα προβολής του πίνακα, η υπηρεσία επιστρέφει μια απάντηση που δεν βρέθηκε.
  • Εάν η ασφάλεια σε επίπεδο γραμμών (RLS) φιλτράρει κάθε γραμμή που μπορείτε να προβάλετε, η αίτηση είναι επιτυχής, αλλά επιστρέφει μια κενή απόκριση βέλους.
  • Εάν χρησιμοποιείτε προβολή στήλης μπαλαντέρ, η απόκριση περιλαμβάνει μόνο στήλες που σας επιτρέπει να προβάλετε η ασφάλεια σε επίπεδο στήλης (CLS).
  • Εάν ζητήσετε ρητά μια στήλη που δεν μπορείτε να προβάλετε, η υπηρεσία επιστρέφει μια απάντηση που δεν βρέθηκε.

Επειδή οι μη εξουσιοδοτημένοι πίνακες και στήλες επιστρέφουν αποκρίσεις που δεν βρέθηκαν, μην χρησιμοποιήσετε μια απόκριση που δεν βρέθηκε για να προσδιορίσετε εάν υπάρχει ένας πόρος.

Ζητήματα προς εξέταση και περιορισμοί

  • Το API ανάγνωσης πίνακα δεν υποστηρίζει συντομεύσεις μεταξύ περιοχών.
  • Χρεώνεστε για την POST /read επέμβαση. Η ανάκτηση δεδομένων με χρήση /readStream δεν εκπέμπει ξεχωριστό συμβάν χρέωσης ανάγνωσης πίνακα. Για περισσότερες πληροφορίες, ανατρέξτε στην ενότητα Ανάγνωση πίνακα Κατανάλωση API.
  • Τελευταία ενημέρωση στις