แชร์ผ่าน

จัดการ lakehouse ใน Microsoft Fabric ด้วย REST API

  • บทความ

Microsoft Fabric Rest API ให้บริการจุดสิ้นสุดการบริการสําหรับการดําเนินการ CRUD ของรายการ Fabric การดําเนินการต่อไปนี้สามารถใช้ได้สําหรับเลคเฮ้าส์:

การดำเนินการ คำอธิบาย
สร้าง สร้างเลคเฮ้าส์ภายในพื้นที่ทํางาน จุดสิ้นสุดการวิเคราะห์ SQL ยังได้รับการเตรียมใช้งานพร้อมกับเลคเฮ้าส์
Update อัปเดตชื่อของเลคเฮ้าส์และจุดสิ้นสุดการวิเคราะห์ SQL
Delete ลบเลคเฮ้าส์และจุดสิ้นสุดการวิเคราะห์ SQL ที่เกี่ยวข้อง
รับคุณสมบัติ รับคุณสมบัติของเลคเฮ้าส์และจุดสิ้นสุดการวิเคราะห์ SQL
ตารางรายการ แสดงตารางในเลคเฮ้าส์
การโหลดตาราง สร้างตารางส่วนที่แตกต่างจากไฟล์และโฟลเดอร์ CSV และ parquet
การบํารุงรักษาตาราง ใช้การกระชับช่องเก็บ V-Order และการลบไฟล์ที่ไม่ถูกเฟรนซ์และเก่า

ข้อกำหนดเบื้องต้น

  • หากต้องการใช้ Fabric REST API ก่อนอื่นคุณต้องได้รับโทเค็น Microsoft Entra สําหรับ Fabric service จากนั้นใช้โทเค็นนั้นในส่วนหัวการรับรองความถูกต้องของการเรียกใช้ API

  • Microsoft Fabric Rest API กําหนดจุดสิ้นสุดแบบรวมสําหรับการดําเนินการ ปลายทางคือhttps://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items ตัวแทนข้อความ {workspaceId} และ {lakehouseId} ควรถูกแทนที่ด้วยค่าที่เหมาะสมเมื่อออกคําสั่งที่เป็นแบบอย่างในบทความนี้

เลคเฮ้าส์ CRUD

ใช้ API ต่อไปนี้เพื่อดําเนินการสร้าง แก้ไข และลบเลคเฮ้าส์ภายในพื้นที่ทํางาน

สร้างเลคเฮ้าส์

ขอร้อง:

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items 
{ 
    "displayName": "demo", 
    "type": "Lakehouse" 
}

การตอบสนอง:

{
    "id": "56c6dedf-2640-43cb-a412-84faad8ad648", 
    "type": "Lakehouse", 
    "displayName": "demo", 
    "description": "", 
    "workspaceId": "fc67689a-442e-4d14-b3f8-085076f2f92f" 
}

ปรับปรุงเลคเฮ้าส์

ปรับปรุงคําอธิบาย และเปลี่ยนชื่อของเลคเฮ้าส์

ขอร้อง:

PATCH https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/dc39f96a-47d7-4c2d-9358-740f50c0aa31 
{ 
    "displayName": "newname", 
    "description": "Item's New description" 
}

การตอบสนอง:

{ 
    "id": "56c6dedf-2640-43cb-a412-84faad8ad648", 
    "type": "Lakehouse", 
    "displayName": "newname", 
    "description": "", 
    "workspaceId": "fc67689a-442e-4d14-b3f8-085076f2f92f" 
}

รับคุณสมบัติเลคเฮ้าส์

ขอร้อง:

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}

การตอบสนอง:

{ 
    "id": "daaa77c7-9ef4-41fc-ad3c-f192604424f5", 
    "type": "Lakehouse", 
    "displayName": "demo", 
    "description": "", 
    "workspaceId": "bee6c118-c2aa-4900-9311-51546433bbb8", 
    "properties": { 
        "oneLakeTablesPath": "https://onelake.dfs.fabric.microsoft.com/{workspaceId}/{lakehouseId}/Tables", 
        "oneLakeFilesPath": "https://onelake.dfs.fabric.microsoft.com/{workspaceId}/{lakehouseId}/Files", 
        "sqlEndpointProperties": { 
            "connectionString": "A1bC2dE3fH4iJ5kL6mN7oP8qR9-C2dE3fH4iJ5kL6mN7oP8qR9sT0uV-datawarehouse.pbidedicated.windows.net", 
            "id": "0dfbd45a-2c4b-4f91-920a-0bb367826479", 
            "provisioningStatus": "Success" 
        } 
    } 
}

ลบเลคเฮ้าส์

เมื่อคุณลบเลคเฮ้าส์ เมตาดาต้าของวัตถุและข้อมูลจะถูกลบ การอ้างอิงทางลัดจะถูกลบออก แต่ข้อมูลถูกเก็บไว้ที่เป้าหมาย

ขอร้อง:

DELETE https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{lakehouseId}

การตอบสนอง: ว่างเปล่า

แสดงตารางในเลคเฮ้าส์

ขอร้อง:

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/tables

การตอบสนอง:

{ 
    "continuationToken": null, 
    "continuationUri": null, 
    "data": [ 
        { 
            "type": "Managed", 
            "name": "demo1", 
            "location": "abfss://c522396d-7ac8-435d-8d77-442c3ff21295@onelake.dfs.fabric.microsoft.com/{workspaceId}/Tables/demo1", 
            "format": "delta" 
        } 
    ] 
}

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

ตัวอย่างการแบ่งหน้า

ขอร้อง:

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/tables?maxResults=1

การตอบสนอง:

{ 
    "continuationToken": "+RID:~HTsuAOseYicH-GcAAAAAAA==#RT:1#TRC:1#ISV:2#IEO:65567#QCF:8#FPC:AgKfAZ8BnwEEAAe8eoA=", 
    "continuationUri": "https://api.fabric.microsoft.com:443/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/tables?continuationToken=%2BRID%3A~HTsuAOseYicH-GcAAAAAAA%3D%3D%23RT%3A1%23TRC%3A1%23ISV%3A2%23IEO%3A65567%23QCF%3A8%23FPC%3AAgKfAZ8BnwEEAAe8eoA%3D", 
    "data": [ 
        { 
            "type": "Managed", 
            "name": "nyctaxismall", 
            "location": "abfss://bee6c118-c2aa-4900-9311-51546433bbb8@onelake.dfs.fabric.microsoft.com/daaa77c7-9ef4-41fc-ad3c-f192604424f5/Tables/nyctaxismall", 
            "format": "delta" 
        } 
    ] 
}

โหลดไปยังตาราง

API นี้เพิ่มขีดความสามารถของคุณลักษณะโหลดไปยังทะเลสาบตาราง ด้วย API นี้คุณสามารถโหลดไฟล์ CSV และ parquet ไปยังตารางทะเลสาบเดลต้าใหม่หรือที่มีอยู่ในทะเลสาบ

API นี้เป็นแบบอะซิงโครนัส ดังนั้นจึงจําเป็นต้องใช้สามขั้นตอน:

  1. อัปโหลดไฟล์และโฟลเดอร์ไปยังส่วนไฟล์ของ Lakehouse โดยใช้ OneLake API
  2. ส่งการโหลดไปยังตารางคําขอ API
  3. ติดตามสถานะของการดําเนินการจนกว่าจะเสร็จสมบูรณ์

ส่วนต่อไปนี้ถือว่ามีการอัปโหลดไฟล์แล้ว

โหลดไปยังตารางคําขอ API

พารามิเตอร์ mode สนับสนุน overwrite และ append การดําเนินการ pathType พารามิเตอร์ที่ระบุถ้าโหลดไฟล์แต่ละไฟล์หรือไฟล์ทั้งหมดจากโฟลเดอร์ที่ระบุ ทั้ง CSV และ parquet ได้รับการสนับสนุนเป็นพารามิเตอร์ไฟล์format

ตัวอย่างนี้อัปโหลดไฟล์ CSV ที่demo.csvชื่อว่า ลงในตารางที่มีอยู่ที่มีชื่อว่าdemo

ขอร้อง:

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/tables/demo/load 
{ 
    "relativePath": "Files/demo.csv", 
    "pathType": "File", 
    "mode": "overwrite", 
    "formatOptions": 
    { 
        "header": "true", 
        "delimiter": ",", 
        "format": "CSV" 
    } 
}

ส่วนหัวการตอบสนองประกอบด้วย URI เพื่อทําการสํารวจสถานะของการดําเนินการแบบอะซิงโครนัส URI อยู่ใน ตัวแปร Location ของส่วนหัวการตอบสนอง

ตัวแปร Location มี URI ดังนี้: https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/operations/32ad6d2a-82bb-420d-bb57-4620c8860373 guid 32ad6d2a-82bb-420d-bb57-4620c8860373 คือ ID การดําเนินการเพื่อคิวรีสถานะของการเรียกใช้โหลดไปยังการดําเนินการตารางตามที่อธิบายไว้ในส่วนถัดไป

การตรวจสอบการโหลดไปยังการดําเนินการตาราง

หลังจากจับ operationId จากการตอบสนองของคําขอ API โหลดไปยังตาราง ให้ดําเนินการตามคําขอต่อไปนี้:

ขอร้อง:

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/operations/{operationId}

การตอบสนอง:

{ 
    "Status": 3, 
    "CreatedTimeUtc": "", 
    "LastUpdatedTimeUtc": "", 
    "PercentComplete": 100, 
    "Error": null 
}

สถานะการดําเนินการที่เป็นไปได้สําหรับการโหลดไปยังตาราง:

  • 1 - การดําเนินการที่ไม่ได้เริ่มต้น
  • 2 - วิ่ง
  • 3 - ความสําเร็จ
  • 4 - ล้มเหลว

การบํารุงรักษาตาราง

API นี้เพิ่มขีดความสามารถของคุณลักษณะการบํารุงรักษาตารางของ Lakehouse ด้วย API นี้ คุณสามารถใช้การกระชับช่องเก็บ V-Order และล้างข้อมูลไฟล์เก่าที่ไม่อนุมานได้

API นี้เป็นแบบอะซิงโครนัส ดังนั้นจึงจําเป็นต้องใช้สองขั้นตอน:

  1. ส่งคําขอ API การบํารุงรักษาตาราง
  2. ติดตามสถานะของการดําเนินการจนกว่าจะเสร็จสมบูรณ์

คําขอ API การบํารุงรักษาตาราง

ตัวอย่างนี้เรียกใช้งานการบํารุงรักษาตารางที่ใช้ V-Order กับตาราง ในขณะที่ยังใช้ Z-Order กับ tipAmount คอลัมน์และดําเนินการ VACUUM กับการเก็บข้อมูลเจ็ดวันและหนึ่งชั่วโมง

ขอร้อง:

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances?jobType=TableMaintenance
{
    "executionData": {
        "tableName": "{table_name}",
        "optimizeSettings": {
            "vOrder": "true",
            "zOrderBy": [
                "tipAmount"
            ]
        },
        "vacuumSettings": {
            "retentionPeriod": "7.01:00:00"
        }
    }
}

ส่วนหัวการตอบสนองประกอบด้วย URI เพื่อทําการสํารวจสถานะของการดําเนินการแบบอะซิงโครนัส URI อยู่ใน ตัวแปร Location ของส่วนหัวการตอบสนอง

ตัวแปร Location มี URI ดังนี้: https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances/f2d65699-dd22-4889-980c-15226deb0e1b guid f2d65699-dd22-4889-980c-15226deb0e1b เป็น ID การดําเนินการเพื่อคิวรีสถานะของการดําเนินการบํารุงรักษาตารางที่กําลังทํางานอยู่ ตามที่อธิบายไว้ในส่วนถัดไป

การตรวจสอบการดําเนินการบํารุงรักษาตาราง

หลังจากจับ operationId จากการตอบสนองของคําขอ API โหลดไปยังตาราง ดําเนินการตามคําขอต่อไปนี้:

ขอร้อง:

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{lakehouseId}/jobs/instances/{operationId}

การตอบสนอง:

{
    "parameters": {
        "workspaceId": "{workspaceId}",
        "itemId": "{lakehouseId}",
        "jobInstanceId": "{operationId}"
    },
    "responses": {
        "200": {
            "body": {
                "id": "{operationId}",
                "itemId": "431e8d7b-4a95-4c02-8ccd-6faef5ba1bd7",
                "jobType": "DefaultJob",
                "invokeType": "Manual",
                "status": "Completed",
                "rootActivityId": "8c2ee553-53a4-7edb-1042-0d8189a9e0ca",
                "startTimeUtc": "2023-04-22T06:35:00.7812154",
                "endTimeUtc": "2023-04-22T06:35:00.8033333",
                "failureReason": null
            }
        }
    }
}

สถานะการดําเนินการที่เป็นไปได้สําหรับการบํารุงรักษาตาราง:

  • NotStarted - งานที่ไม่ได้เริ่มต้น
  • InProgress - งานที่กําลังดําเนินการ
  • เสร็จสมบูรณ์แล้ว - งานเสร็จสมบูรณ์
  • ล้มเหลว - งานล้มเหลว
  • ยกเลิก - งานที่ยกเลิกแล้ว
  • Deduped - อินสแตนซ์ของชนิดงานเดียวกันกําลังรันอยู่แล้ว และข้ามอินสแตนซ์ของงานนี้

เนื้อหาที่เกี่ยวข้อง