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

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

Prerequisites

• หากต้องการใช้ 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 ต่อไปนี้เพื่อดําเนินการสร้าง แก้ไข และลบเลคเฮ้าส์ภายในพื้นที่ทํางาน สําหรับพารามิเตอร์ API โดยละเอียดและตัวอย่างคําขอ โปรดดูเอกสารสร้าง Lakehouse REST API

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

Request:

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

Response:

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

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

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

Request:

PATCH https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/aaaabbbb-0000-cccc-1111-dddd2222eeee 
{ 
    "displayName": "newname", 
    "description": "Item's New description" 
} 

Response:

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

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

Request:

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

Response:

{ 
    "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" 
        } 
    } 
}

ลบเลคเฮ้าส์

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

Request:

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

Response:Empty

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

Request:

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

Response:

{ 
    "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 ความต่อเนื่องที่สามารถใช้เพื่อรับหน้าถัดไปของผลลัพธ์

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

Request:

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

Response:

{ 
    "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

Request:

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 มี URI ดังนี้: https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}/operations/bbbbcccc-1111-dddd-2222-eeee3333ffff guid bbbbcccc-1111-dddd-2222-eeee3333ffff คือ ID การดําเนินการเพื่อคิวรีสถานะของการเรียกใช้โหลดไปยังการดําเนินการตารางตามที่อธิบายไว้ในส่วนถัดไป

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

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

Request:

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

Response:

{ 
    "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 กับการเก็บข้อมูลเจ็ดวันและหนึ่งชั่วโมง

Request:

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

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

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

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

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

Request:

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

Response:

{
    "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 - อินสแตนซ์ของชนิดงานเดียวกันกําลังรันอยู่แล้ว และข้ามอินสแตนซ์ของงานนี้

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

• โหลดไปยังคุณลักษณะ Table Lakehouse
• ใช้คุณลักษณะการบํารุงรักษาตารางเพื่อจัดการตาราง delta ใน Fabric
• การปรับตาราง Delta Lake ให้เหมาะสมและ V-Order