使用 OneLake 的 table read API 來讀取 OneLake 中 Delta Lake 或 Apache Iceberg 表格的列。
要讀取資料表資料，先發送一個請求以啟動讀取工作階段。 API 會根據需要回傳的資料大小，回傳一個或多個獨立的結果串流。 你的應用程式可以平行下載這些資料流，幫助它更快地讀取大量資料表資料。 下載資料流後，處理其 Apache Arrow 記錄批次，以組成完整結果。
API 從一致的時間點讀取資料表，因此每個結果串流都包含同一快照的資料，即使資料表在讀取過程中有所變動。 同時也強制執行 OneLake 授權、列級安全（RLS）及欄位級安全（CLS），以保護已認證的呼叫者。 這表示您的應用程式只會接收呼叫者被授權存取的列與欄，無需在自身程式碼中重現這些安全控制。
Important
OneLake 表格閱讀 API 目前處於 公開預覽階段。 功能與行為可能會在正式上市前改變。
先決條件
- 完成 共享資料表的 API 前置條件與認證步驟。
- 一個 HTTP 用戶端，能處理 Apache Arrow IPC 串流而不緩衝完整回應。
1. 發送資料表列請求
向資料表的/read路由發送POST請求以啟動讀取會話。
將佔位符替換為你想要讀取之工作區、項目、結構描述和資料表的識別碼，以建構請求 URL。
POST <TableReadBaseUrl>/v1.0/workspaces/<WorkspaceID>/items/<ItemID>/schemas/<SchemaName>/tables/<TableName>/read Authorization: Bearer <BearerToken>請在申請中包含申請所需的閱讀選項。 使用
columns指定要回傳哪些欄位的選項。儲存所有成功回應時的不透明串流識別碼。 一個大型結果可能會分散在多個串流中。 你必須取回每條串流，才能接收所有列。
此回應會根據涵蓋您要求所需資料表版本的一致快照，啟動讀取工作階段。 這個回應的每個串流都使用相同的快照。
2. 下載所有結果資料流
利用回應中的每個串流識別碼來取得對應的資料表讀取結果部分。
讀取工作時間在 60 分鐘後結束。 在會話結束前取得所有串流。 如果你在只擷取了部分串流後就停止，就無法收到完整結果。
對於配置回應中的每個串流識別碼，發送一個經過認證的
GET請求。GET <TableReadBaseUrl>/v1.0/workspaces/<WorkspaceID>/items/<ItemID>/schemas/<SchemaName>/tables/<TableName>/readStream/<StreamID> Authorization: Bearer <BearerToken>使用 Apache Arrow IPC 串流讀取器開啟回應主體。
在記錄批次到達時立即處理。 串流批次可以避免將完整結果載入記憶體。
對每個串流識別碼重複請求，並依照你應用程式的處理模型將結果合併。
每個 /readStream 回應都是獨立的 Apache Arrow IPC 串流。 使用你的應用程式語言的 Apache Arrow 函式庫來讀取每個回應的記錄批次。 欲了解更多關於串流格式的資訊，請參見序列化與進程間通訊（IPC）。
回應本體包含原始的 Apache Arrow IPC 串流資料，包括解讀記錄批次所需的結構資訊。 不要依賴列序，也不要假設串流在回應中的位置就決定了它在完整結果中的位置。
了解 OneLake 的 table read API 安全性
API 透過使用持有人令牌所代表的身份來強制執行 OneLake 的安全：
- 如果你沒有權限查看表格，服務會回傳「找不到」回應。
- 如果資料列層級安全性（RLS）篩除了你可檢視的所有資料列，該請求仍會成功，但會傳回空的 Arrow 回應。
- 若您使用萬用字元欄位投影，回應只會包含欄位層級安全性（CLS）允許您檢視的欄位。
- 如果你明確請求無法查看的欄位，服務會回傳「找不到」回應。
由於未授權的資料表和欄位會回傳未找到的回應，請不要使用未找到的回應來判斷資源是否存在。
考慮事項與限制條件
- tableread API 不支援跨區域捷徑。
- 你需支付
POST /read作業的費用。 使用/readStream擷取資料時，不會產生獨立的資料表讀取計費事件。 欲了解更多資訊，請參閱 表格讀取 API 使用量。