Remarque
L’accès à cette page requiert une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page requiert une autorisation. Vous pouvez essayer de modifier des répertoires.
Utilisez l’API de lecture de table OneLake pour lire des lignes d’une table Delta Lake ou Apache Iceberg dans OneLake.
Pour lire les données de la table, envoyez une requête pour lancer une session de lecture. L’API renvoie un ou plusieurs flux de résultats indépendants en fonction de la taille des données à retourner. Votre application peut télécharger ces flux en parallèle, ce qui lui permet de lire plus rapidement de grands volumes de données de tables. Après avoir téléchargé les streams, traitez leurs lots d’enregistrements Apache Arrow pour assembler le résultat complet.
L’API lit la table à partir d’un moment cohérent, donc chaque flux de résultats contient des données provenant du même instantané, même si la table change pendant la lecture. Il applique également l’autorisation OneLake, la sécurité au niveau des lignes (RLS) et la sécurité au niveau des colonnes (CLS) pour l’appelant authentifié. Cela signifie que votre application ne reçoit que les lignes et colonnes auxquelles l’appelant est autorisé à accéder, sans avoir à reproduire ces contrôles de sécurité dans son propre code.
Important
L’API de lecture de table OneLake est actuellement en aperçu public. Les fonctionnalités et le comportement peuvent changer avant la disponibilité générale.
Prerequisites
- Complétez les prérequis de l’API à table partagée et les étapes d’authentification.
- Un client HTTP capable de traiter un flux IPC Apache Arrow sans mettre en mémoire tampon la réponse complète.
1. Envoyer une requête pour les lignes d’un tableau
Envoyez une POST requête à la route /read de la table pour démarrer une session de lecture.
Construisez l’URL de la requête en remplaçant les espaces réservés par les identifiants de l’espace de travail, de l’élément, du schéma et de la table que vous souhaitez lire.
POST <TableReadBaseUrl>/v1.0/workspaces/<WorkspaceID>/items/<ItemID>/schemas/<SchemaName>/tables/<TableName>/read Authorization: Bearer <BearerToken>Incluez les options de lecture que votre demande exige dans la demande. Utilisez l’option
columnspour indiquer quelles colonnes renvoyer.Sauvegardez tous les identifiants de flux opaques de la réponse réussie. Un résultat important peut être réparti sur plusieurs flux. Vous devez récupérer chaque flux pour obtenir toutes les lignes.
La réponse ouvre une session de lecture à partir d’un instantané cohérent des versions de la table nécessaires à votre requête. Chaque flux issu de cette réponse utilise la même capture.
2. Télécharger chaque flux de résultats
Utilisez chaque identifiant de flux de la réponse pour récupérer sa partie correspondante du résultat de lecture de la table.
Une séance de lecture expire après 60 minutes. Récupérez tous les flux avant la fin de la session. Si vous vous arrêtez après avoir récupéré seulement quelques flux, vous n’obtiendrez pas le résultat complet.
Pour chaque identifiant de flux dans la réponse d’allocation, envoyez une requête authentifiée
GET.GET <TableReadBaseUrl>/v1.0/workspaces/<WorkspaceID>/items/<ItemID>/schemas/<SchemaName>/tables/<TableName>/readStream/<StreamID> Authorization: Bearer <BearerToken>Ouvrez le corps de réponse avec un lecteur de flux IPC Apache Arrow.
Traitez les lots d’enregistrements au fur et à mesure qu’ils arrivent. Le streaming des lots évite de charger le résultat complet en mémoire.
Répétez la demande pour chaque identifiant de flux et combinez les résultats selon le modèle de traitement de votre application.
Chaque /readStream réponse est un flux indépendant d’IPC Apache Arrow. Utilisez la bibliothèque Apache Arrow pour votre langage applicatif afin de lire les lots d’enregistrements de chaque réponse. Pour plus d’informations sur le format de flux, voir Sérialisation et communication interprocessus (IPC).
Le corps de réponse contient les données brutes du flux IPC Apache Arrow, y compris les informations de schéma nécessaires à l’interprétation des lots d’enregistrements. Ne vous fiez pas à l’ordre des lignes, ni ne supposez que la position d’un flux dans la réponse détermine sa position dans le résultat complet.
Comprendre la sécurité OneLake pour l’API de lecture de tables
L’API renforce la sécurité OneLake en utilisant l’identité que représente votre jeton porteur :
- Si vous n’avez pas la permission de consulter le tableau, le service renvoie une réponse non trouvée.
- Si la sécurité au niveau des lignes (RLS) exclut toutes les lignes auxquelles vous avez accès, la requête réussit mais renvoie une réponse Arrow vide.
- Si vous utilisez une projection de colonnes avec caractère générique, la réponse inclut uniquement les colonnes que la sécurité au niveau des colonnes (CLS) vous autorise à consulter.
- Si vous demandez explicitement une colonne que vous ne pouvez pas consulter, le service renvoie une réponse non trouvée.
Comme les tables et colonnes non autorisées retournent des réponses non trouvées, n’utilisez pas une réponse non trouvée pour déterminer si une ressource existe.
Considérations et limites
- L’API de lecture de table ne prend pas en charge les raccourcis interrégionaux.
- On te facture pour l’opération
POST /read. Récupérer des données en utilisant/readStreamn’émet pas d’événement de facturation séparé pour la lecture de table. Pour plus d’informations, voir Consommation d’API de Table Read.