อ่านข้อมูลตาราง OneLake (ตัวอย่าง)

ใช้ OneLake table read API เพื่ออ่านแถวจากตาราง Delta Lake หรือ Apache Iceberg ใน OneLake

หากต้องการอ่านข้อมูลตาราง ให้ส่งคําขอหนึ่งครั้งเพื่อเริ่มเซสชันการอ่าน API จะส่งคืนสตรีมผลลัพธ์อิสระหนึ่งชุดหรือมากกว่าตามขนาดของข้อมูลที่ต้องการส่งคืน แอปพลิเคชันของคุณสามารถดาวน์โหลดสตรีมเหล่านี้พร้อมกัน ซึ่งช่วยให้อ่านข้อมูลตารางจํานวนมากได้รวดเร็วขึ้น หลังจากดาวน์โหลดสตรีมแล้ว ให้ประมวลผลชุดบันทึก Apache Arrow ของพวกเขาเพื่อประกอบผลลัพธ์ที่สมบูรณ์

API จะอ่านตารางจากจุดเวลาที่สอดคล้องกัน ดังนั้นทุกสตรีมผลลัพธ์จะมีข้อมูลจาก snapshot เดียวกัน แม้ว่าตารางจะเปลี่ยนแปลงระหว่างการอ่าน นอกจากนี้ยังบังคับใช้การอนุญาต OneLake, ความปลอดภัยระดับแถว (RLS) และความปลอดภัยระดับคอลัมน์ (CLS) สําหรับผู้โทรที่ได้รับการยืนยันตัวตน ซึ่งหมายความว่าแอปพลิเคชันของคุณจะได้รับเฉพาะแถวและคอลัมน์ที่ผู้โทรได้รับอนุญาตให้เข้าถึง โดยไม่ต้องทําซ้ําการควบคุมความปลอดภัยเหล่านี้ในโค้ดของตัวเอง

Important

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. บันทึกตัวระบุสตรีมที่ไม่โปร่งใสทั้งหมดจากการตอบกลับที่สําเร็จ ผลลัพธ์ขนาดใหญ่อาจถูกแบ่งออกเป็นหลายสตรีม คุณต้องดึงทุกสตรีมเพื่อรับทุกแถว

การตอบกลับจะเริ่มเซสชันการอ่านผ่าน snapshot ที่สอดคล้องกันของเวอร์ชันตารางที่จําเป็นสําหรับคําขอของคุณ ทุกสตรีมจากการตอบสนองนี้ใช้สแนปช็อตเดียวกัน

2. ดาวน์โหลดทุกสตรีมผลลัพธ์

ใช้แต่ละตัวระบุสตรีมจากการตอบกลับเพื่อดึงส่วนที่เกี่ยวข้องของผลลัพธ์การอ่านตาราง

เซสชันอ่านจะหมดอายุหลังจาก 60 นาที ดึงสตรีมทุกสตรีมก่อนที่เซสชันจะหมดอายุ หากคุณหยุดหลังจากดึงข้อมูลเพียงบางส่วน คุณจะไม่ได้รับผลลัพธ์ที่สมบูรณ์

  1. สําหรับแต่ละตัวระบุสตรีมในคําตอบการจัดสรร ให้ส่งคําขอที่ผ่านการตรวจสอบ GET สิทธิ์

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

  2. เปิดตัวการตอบสนองด้วยเครื่องอ่านสตรีม Apache Arrow IPC

  3. ประมวลผลชุดบันทึกเมื่อมาถึง การสตรีมชุดงานจะช่วยหลีกเลี่ยงการโหลดผลลัพธ์ทั้งหมดลงในหน่วยความจํา

  4. ทําซ้ําคําขอสําหรับตัวระบุสตรีมทุกตัวและรวมผลลัพธ์ตามโมเดลการประมวลผลของแอปพลิเคชันของคุณ

แต่ละ /readStream การตอบกลับเป็นสตรีม IPC ของ Apache Arrow ที่เป็นอิสระ ใช้ไลบรารี Apache Arrow สําหรับภาษาแอปพลิเคชันของคุณเพื่ออ่านชุดบันทึกจากแต่ละคําตอบ สําหรับข้อมูลเพิ่มเติมเกี่ยวกับรูปแบบสตรีม โปรดดูที่ การเรียงลําดับและการสื่อสารระหว่างกระบวนการ (IPC)

เนื้อหาการตอบกลับประกอบด้วยข้อมูลสตรีม IPC ของ Apache Arrow ดิบ รวมถึงข้อมูลสคีมาที่จําเป็นสําหรับการตีความชุดบันทึก อย่าพึ่งพาลําดับแถว หรือคิดว่าตําแหน่งของสตรีมในคําตอบเป็นตัวกําหนดตําแหน่งของมันในผลลัพธ์ทั้งหมด

ทําความเข้าใจความปลอดภัยของ OneLake สําหรับ API อ่านตาราง

API นี้บังคับใช้ความปลอดภัยของ OneLake โดยใช้ตัวตนที่โทเค็นแบร์ของคุณแทน:

  • หากคุณไม่มีสิทธิ์ในการดูตาราง บริการจะส่งคืนการตอบกลับที่ไม่พบ
  • หากความปลอดภัยระดับแถว (RLS) กรองทุกแถวที่คุณสามารถดูได้ คําขอจะสําเร็จแต่จะคืนค่าการตอบกลับแบบลูกศรว่างเปล่า
  • หากคุณใช้การฉายภาพคอลัมน์แบบสัญลักษณ์แทน การตอบกลับจะรวมเฉพาะคอลัมน์ที่ความปลอดภัยระดับคอลัมน์ (CLS) อนุญาตให้คุณดูเท่านั้น
  • หากคุณร้องขอคอลัมน์ที่ไม่สามารถดูได้โดยตรง บริการจะส่งคืนการตอบกลับที่ไม่พบ

เนื่องจากตารางและคอลัมน์ที่ไม่ได้รับอนุญาตจะส่งคืนคําตอบที่ไม่พบ อย่าใช้การตอบกลับที่ไม่พบเพื่อกําหนดว่ามีทรัพยากรหรือไม่

ข้อควรพิจารณาและข้อจำกัด

  • API การอ่านตารางไม่รองรับทางลัดข้ามภูมิภาค
  • คุณถูกเรียกเก็บเงินสําหรับการผ่าตัดPOST /read การดึงข้อมูลโดยใช้ จะไม่ /readStream ทําให้เกิดเหตุการณ์การเรียกเก็บเงินแบบอ่านตารางแยกต่างหาก สําหรับข้อมูลเพิ่มเติม ดูที่ การใช้ API อ่านตาราง
  • อัปเดตล่าสุดเมื่อ