OneLake-Tabellendaten lesen (Vorschau)

Verwenden Sie die OneLake-Tabellenlese-API, um Zeilen aus einer Delta Lake- oder Apache-Iceberg-Tabelle in OneLake zu lesen.

Um die Tabellendaten zu lesen, senden Sie eine Anfrage, um eine Lesesitzung zu starten. Die API liefert basierend auf der Größe der zurückgegebenen Daten einen oder mehrere unabhängige Ergebnisströme. Ihre Anwendung kann diese Streams parallel herunterladen, was ihr hilft, große Mengen an Tabellendaten schneller auszulesen. Nach dem Herunterladen der Streams verarbeiten Sie deren Apache Arrow Record Batches, um das vollständige Ergebnis zusammenzusetzen.

Die API liest die Tabelle von einem konsistenten Zeitpunkt aus, sodass jeder Ergebnisstrom Daten aus demselben Snapshot enthält, selbst wenn sich die Tabelle während des Lesens ändert. Es erzwingt außerdem die OneLake-Autorisierung, Zeilensicherheit (RLS) und Spaltensicherheit (CLS) für den authentifizierten Anrufer. Das bedeutet, dass Ihre Anwendung nur die Zeilen und Spalten erhält, auf die der Anrufer zugreifen darf, ohne diese Sicherheitskontrollen in ihrem eigenen Code reproduzieren zu müssen.

Important

Die OneLake-Tabellenlese-API befindet sich derzeit in der öffentlichen Vorschau. Features und Verhalten können sich vor der allgemeinen Verfügbarkeit ändern.

Voraussetzungen

• Erfüllen Sie die Voraussetzungen und Authentifizierungsschritte der geteilten Tabellen-API.
• Ein HTTP-Client, der einen Apache Arrow IPC-Stream verarbeiten kann, ohne die vollständige Antwort zu puffern.

1. Eine Anfrage für Tabellenzeilen senden

Sende eine POST Anfrage an die /read Route der Tabelle, um eine Lesesitzung zu starten.

1. Erstellen Sie die Anfrage-URL, indem Sie die Platzhalter durch die Identifikatoren für den Arbeitsbereich, das Element, das Schema und die Tabelle ersetzen, die Sie lesen möchten.

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

2. Fügen Sie die Leseoptionen ein, die Ihre Bewerbung verlangt, in die Anfrage. Verwenden Sie die columns Option, um anzugeben, welche Spalten zurückgegeben werden sollen.

3. Speichere jede undurchsichtige Stream-Identifikatorin aus der erfolgreichen Antwort. Ein großes Ergebnis könnte über mehrere Ströme verteilt werden. Du musst jeden Stream abrufen, um alle Zeilen zu empfangen.

Die Antwort beginnt eine Lesesitzung auf Basis eines konsistenten Schnappschusses der für Ihre Anfrage benötigten Tabellenversionen. Jeder Stream aus dieser Antwort verwendet denselben Snapshot.

2. Laden Sie jeden Ergebnisstream herunter

Verwenden Sie jede Stream-Identifikatorin aus der Antwort, um den entsprechenden Teil des Tabellenleseergebnisses abzurufen.

Eine Lesesitzung endet nach 60 Minuten. Rufe jeden Stream ab, bevor die Sitzung abläuft. Wenn du aufhörst, nachdem du nur einige Streams abgerufen hast, erhältst du nicht das vollständige Ergebnis.

1. Für jede Stream-Identifikatorin in der Zuweisungsantwort senden Sie eine authentifizierte GET Anfrage.

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

2. Öffnen Sie den Antwort-Body mit einem Apache Arrow IPC-Streamleser.

3. Verarbeiten Sie die Stapel von Datensätzen, sobald sie eintreffen. Das Streamen der Batchs verhindert, dass das vollständige Ergebnis in den Speicher geladen wird.

4. Wiederholen Sie die Anfrage für jede Stream-Identifikatorin und kombinieren Sie die Ergebnisse entsprechend dem Verarbeitungsmodell Ihrer Anwendung.

Jede /readStream Antwort ist ein unabhängiger Apache Arrow IPC-Stream. Verwenden Sie die Apache Arrow-Bibliothek für Ihre Anwendungssprache, um die Datensatz-Batches jeder Antwort auszulesen. Weitere Informationen zum Stromformat finden Sie unter Serialisierung und Interprozesskommunikation (IPC).

Der Antwortkörper enthält unverarbeitete Apache-Arrow-IPC-Stream-Daten, einschließlich der Schemainformationen, die zum Interpretieren der Datensatz-Batches erforderlich sind. Verlasse dich nicht auf die Reihenfolge oder gehe davon aus, dass die Position eines Streams in der Antwort seine Position im vollständigen Ergebnis bestimmt.

Verstehen Sie die OneLake-Sicherheit für die Table Read API

Die API erzwingt die Sicherheit von OneLake, indem sie die Identität verwendet, die Ihr Inhabertoken darstellt:

• Wenn Sie keine Berechtigung haben, die Tabelle anzusehen, gibt der Dienst eine Antwort "nicht gefunden" zurück.
• Wenn die Zeilensicherheit (RLS) jede sichtbare Zeile herausfiltert, ist die Anfrage erfolgreich, gibt aber eine leere Arrow-Antwort zurück.
• Wenn Sie eine Platzhalter-Spaltenprojektion verwenden, enthält die Antwort nur die Spalten, die Sie aufgrund der Spaltensicherheit auf Spaltenebene (CLS) anzeigen dürfen.
• Wenn Sie ausdrücklich eine Spalte anfordern, die Sie nicht anzeigen können, gibt der Dienst eine Antwort vom Typ „Nicht gefunden“ zurück.

Da unautorisierte Tabellen und Spalten nicht gefundene Antworten zurückgeben, sollten Sie keine nicht gefundene Antwort verwenden, um festzustellen, ob eine Ressource existiert.

Überlegungen und Einschränkungen

• Die Table Read API unterstützt keine regionenübergreifenden Verknüpfungen.
• Dir wird der POST /read Vorgang in Rechnung gestellt. Das Abrufen von Daten durch Verwendung /readStream erzeugt kein separates Tabellen-Leseabrechnungsereignis. Weitere Informationen finden Sie unter Table Read API Consumption.