Mengelola lakehouse dengan REST API

Artikel ini membahas skenario umum untuk mengelola lakehouse secara terprogram dengan Microsoft Fabric REST API. Setiap bagian menunjukkan permintaan dan respons HTTP untuk tugas tertentu sehingga Anda dapat menyesuaikan pola dengan skrip atau aplikasi otomatisasi Anda.

Untuk spesifikasi lengkap — termasuk semua parameter, izin yang diperlukan, skema permintaan, dan kode kesalahan — lihat referensi REST API Lakehouse.

Prasyarat

Dapatkan token Microsoft Entra untuk layanan Fabric dan sertakan di Authorization header setiap permintaan.
Ganti {workspaceId} dan {lakehouseId} dalam contoh di bawah ini dengan nilai Anda sendiri.

Membuat, memperbarui, dan menghapus lakehouse

Contoh berikut menunjukkan cara memprovisikan lakehouse baru, mengganti namanya, mengambil propertinya (termasuk titik akhir analitik SQL yang disediakan secara otomatis), dan menghapusnya. Untuk daftar parameter lengkap dan contoh tambahan (seperti membuat lakehouse yang mendukung skema atau membuat dengan definisi), lihat referensi API Item Lakehouse.

Membuat lakehouse

Untuk membuat lakehouse di ruang kerja, kirim permintaan POST dengan nama tampilan. Fabric secara otomatis mengkonfigurasi titik akhir analitik SQL bersamaan dengan lakehouse.

Permintaan

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses
{ 
    "displayName": "demo"
}

Jawaban

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

Memperbarui lakehouse

Untuk mengganti nama lakehouse atau memperbarui deskripsinya, kirim permintaan PATCH dengan nilai baru.

Permintaan

PATCH https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}
{ 
    "displayName": "newname", 
    "description": "Item's New description" 
}

Jawaban

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

Mendapatkan properti lakehouse

Ambil metadata dari lakehouse, termasuk jalur OneLake dan string koneksi untuk titik akhir analitik SQL.

Permintaan

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

Jawaban

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

Menghapus lakehouse

Menghapus lakehouse akan menghapus metadata dan datanya. Pintasan dihapus, tetapi data di target pintasan dipertahankan.

Permintaan

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

Jawaban

Isi respons kosong.

Mencantumkan tabel di lakehouse

Untuk mengambil semua tabel Delta di lakehouse — misalnya, untuk membangun katalog data atau memvalidasi penyebaran — gunakan titik akhir Daftar Tabel. Untuk daftar parameter lengkap, lihat referensi API Tabel.

Permintaan

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

Jawaban

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

LIST Tables API mendukung penomoran halaman. Teruskan maxResults sebagai parameter kueri untuk mengontrol ukuran halaman. Respons mencakup elemen continuationUri yang dapat Anda panggil untuk mengambil halaman berikutnya.

Paginasi melalui daftar tabel besar

Permintaan

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

Jawaban

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

Memuat file ke dalam tabel Delta

Untuk mengonversi file CSV atau Parquet menjadi tabel Delta tanpa menulis kode Spark, gunakan LOAD Table API. Ini adalah setara terprogram dari fitur Muat ke Tabel di halaman beranda Lakehouse. Untuk daftar parameter lengkap, lihat referensi API Load Table.

Operasi ini bersifat asinkron. Ikuti langkah-langkah ini:

Unggah file ke bagian File lakehouse dengan menggunakan API OneLake.
Kirim permintaan beban.
Memeriksa status operasi sampai selesai.

Contoh berikut mengasumsikan file sudah diunggah.

Mengirimkan permintaan beban

Contoh ini memuat file CSV bernama demo.csv ke dalam tabel bernama demo, menggantikan data yang sudah ada. Atur mode ke Append untuk menambahkan baris sebagai gantinya. Atur pathType ke Folder untuk memuat semua file dalam folder.

Permintaan

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

Respons tidak menyertakan isi. Sebagai gantinya, header Location berisi URI yang Anda gunakan untuk memantau status operasi. URI mengikuti pola ini:

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

Periksa status operasi beban

Gunakan operationId dari Location header untuk memeriksa kemajuan:

Permintaan

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

Jawaban

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

Kemungkinan status operasi untuk pemuatan ke tabel:

1 - Operasi tidak dimulai
2 - Berjalan
3 - Berhasil
4 - Gagal

Menjalankan pemeliharaan tabel pada tabel Delta

Untuk mengoptimalkan tabel Delta — menerapkan pemadatan bin, V-Order, Z-Order, atau VACUUM — tanpa menggunakan Lakehouse Explorer, gunakan Table Maintenance API. Ini setara dengan fitur pemeliharaan tabel yang terprogram. Untuk daftar parameter lengkap, lihat referensi API Pemeliharaan Tabel.

Operasi ini bersifat asinkron. Ikuti langkah-langkah ini:

Kirim permintaan pemeliharaan tabel.
Memeriksa status operasi sampai selesai.

Mengirimkan permintaan pemeliharaan tabel

Contoh ini menerapkan pengoptimalan V-Order dan Z-Order pada tipAmount kolom, dan menjalankan VACUUM dengan periode retensi tujuh hari satu jam.

Permintaan

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

Respons tidak menyertakan isi. Header Location berisi URI yang Anda gunakan untuk memeriksa status dari operasi.

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

Titik akhir eksekusi dicakup lakehouse, tetapi polling instans pekerjaan menggunakan titik akhir pekerjaan item generik (/items/{itemId}/jobs/instances/{jobInstanceId}) berdasarkan desain.

Penting

Mengatur periode retensi yang lebih pendek dari tujuh hari berdampak pada Delta time travel dan dapat menyebabkan kegagalan pembaca atau kerusakan tabel jika snapshot atau file yang belum dikomit masih digunakan. Untuk alasan itu, pemeliharaan tabel di UI Fabric dan REST API menolak periode retensi di bawah tujuh hari secara default. Untuk mengizinkan interval yang lebih pendek, atur spark.databricks.delta.retentionDurationCheck.enabled ke false dalam pengaturan ruang kerja; pekerjaan pemeliharaan tabel kemudian gunakan konfigurasi tersebut selama eksekusi.

Monitor status pemeliharaan dari tabel

Gunakan operationId dari tajuk Location untuk memeriksa status tugas.

Permintaan

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

Rute polling ini sengaja menggunakan items daripada lakehouses.

Jawaban

{
    "id": "{operationId}",
    "itemId": "431e8d7b-4a95-4c02-8ccd-6faef5ba1bd7",
    "jobType": "TableMaintenance",
    "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
}

Status operasi yang mungkin untuk pemeliharaan tabel:

NotStarted - Pekerjaan tidak dimulai
InProgress - Pekerjaan sedang berlangsung
Selesai - Pekerjaan selesai
Gagal - Pekerjaan gagal
Dibatalkan - Pekerjaan dibatalkan
Duplikasi - Sebuah instance dari jenis job yang sama sudah berjalan dan instance job ini dilewatkan

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-02-24

Mengelola lakehouse dengan REST API

Prasyarat

Membuat, memperbarui, dan menghapus lakehouse

Membuat lakehouse

Memperbarui lakehouse

Mendapatkan properti lakehouse

Menghapus lakehouse

Mencantumkan tabel di lakehouse

Paginasi melalui daftar tabel besar

Memuat file ke dalam tabel Delta

Mengirimkan permintaan beban

Periksa status operasi beban

Menjalankan pemeliharaan tabel pada tabel Delta

Mengirimkan permintaan pemeliharaan tabel

Monitor status pemeliharaan dari tabel

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan: