Akses oneLake dan API

  • Artikel

Penting

Microsoft Fabric saat ini dalam PRATINJAU. Informasi ini berkaitan dengan produk prarilis yang mungkin dimodifikasi secara substansial sebelum dirilis. Microsoft tidak memberikan jaminan, tersurat maupun tersirat, sehubungan dengan informasi yang diberikan di sini.

Gambaran Umum

Microsoft OneLake menyediakan akses terbuka ke semua item Fabric Anda melalui API dan SDK ADLS Gen2 yang ada. Anda dapat mengakses data Anda di OneLake melalui alat apa pun yang kompatibel dengan ADLS Gen2 hanya dengan menggunakan URI OneLake sebagai gantinya. Anda dapat mengunggah data ke lakehouse melalui Azure Storage Explorer, atau membaca tabel delta melalui pintasan dari Azure Databricks.

Karena OneLake adalah software as a service (SaaS), beberapa operasi, seperti mengelola izin atau memperbarui item, harus dilakukan melalui pengalaman Fabric, dan tidak dapat dilakukan melalui API ADLS Gen2. Daftar lengkap perubahan pada API ini dapat ditemukan di bagian 'Operasi API yang didukung'.

Sintaks URI

Karena OneLake ada di seluruh penyewa Microsoft Fabric, Anda dapat merujuk ke apa pun di penyewa Anda dengan ruang kerja, item, dan jalurnya:

https://onelake.dfs.fabric.microsoft.com/<workspace>/<item>.<itemtype>/<path>/<fileName>

Catatan

Karena nama item dapat digunakan kembali di beberapa jenis item, Anda harus menentukan jenis item dalam ekstensi. Misalnya, ".lakehouse" untuk lakehouse dan ".datawarehouse" untuk gudang.

OneLake juga mendukung referensi ruang kerja dan item dengan GUID. OneLake menetapkan GUID dan GUID tidak berubah, meskipun ruang kerja atau nama item berubah. Anda dapat menemukan GUID terkait untuk ruang kerja atau item Anda di URL di portal Fabric. Anda harus menggunakan GUID untuk ruang kerja dan item, dan tidak memerlukan jenis item.

https://onelake.dfs.fabric.microsoft.com/<workspaceGUID>/<itemGUID>/Files/test.csv

Saat mengadopsi alat untuk digunakan melalui OneLake alih-alih ADLS Gen2, gunakan pemetaan berikut:

  • Nama akun selalu 'onelake'.
  • Nama kontainer adalah nama ruang kerja Anda.
  • Jalur data dimulai pada item. Misalnya: '/mylakehouse.lakehouse/Files/'.

OneLake dan ADLS Gen2 Parity

Meskipun OneLake cocok dengan semua perilaku ADLS Gen2 sedapat mungkin, tidak setiap konsep di ADLS Gen2 memiliki korelasi langsung dengan OneLake. Bagian berikut menjelaskan bagaimana OneLake berbeda dari ADLS Gen2, dari header permintaan yang tidak didukung hingga perubahan header respons. Untuk informasi selengkapnya tentang API ADLS Gen2, lihat Azure Data Lake Storage Gen2 REST API.

Folder OneLake yang dilindungi

OneLake tidak mendukung pembuatan, pembaruan, atau penghapusan ruang kerja atau item melalui API ADLS Gen2. Hanya panggilan HEAD yang didukung di tingkat ruang kerja dan tingkat akun, karena Anda harus membuat perubahan pada penyewa Fabric dan ruang kerja Fabric di portal administrasi Fabric.

OneLake memang memberlakukan struktur item Fabric, yang berarti Anda tidak dapat membuat, membaca, memperbarui, atau menghapus (CRUD) folder tertentu, bahkan jika Anda adalah pemilik item atau ruang kerja. Anda harus melakukan operasi ini melalui pengalaman Fabric, seperti portal Fabric atau API manajemen Fabric. Folder yang dikelola fabric mencakup folder tingkat atas dalam item (misalnya, /MyLakehouse.lakehouse) dan tingkat folder pertama di dalamnya (misalnya, /MyLakehouse.lakehouse/Files dan /MyLakehouse.lakehouse/Tables).

Anda dapat melakukan operasi CRUD pada folder atau file apa pun yang dibuat dalam folder terkelola ini.

Header dan parameter permintaan yang tidak didukung

Bahkan dalam file dan folder yang dibuat pengguna dan dimiliki, OneLake membatasi beberapa operasi manajemen melalui API ADLS Gen2. Anda tidak dapat memperbarui izin, mengedit item atau ruang kerja, atau mengatur tingkat akses, karena operasi ini harus dikelola melalui Fabric.

OneLake akan menolak atau mengabaikan panggilan API jika berisi nilai header atau parameter yang tidak diizinkan. OneLake mengabaikan header jika header tidak mengubah perilaku panggilan, dan mengembalikan header yang ditolak di header respons 'x-ms-rejected-headers' baru. OneLake menolak permintaan yang berisi parameter kueri yang tidak diizinkan. OneLake tidak mengizinkan perilaku berikut dan header permintaan dan parameter URI terkait:

  • Mengatur kontrol akses
    • Parameter URI:
      • action: setAccessControl (Permintaan ditolak)
      • action: setAccessControlRecursive (Permintaan ditolak)
    • Judul permintaan:
      • x-ms-owner (Header diabaikan)
      • x-ms-group (Header diabaikan)
      • x-ms-permissions (Header diabaikan)
      • x-ms-group (Header diabaikan)
      • x-ms-acls (Header diabaikan)
  • Mengatur cakupan enkripsi
    • Judul permintaan:
      • x-ms-encryption-key (Header diabaikan)
      • x-ms-encryption-key (Header diabaikan)
      • x-ms-encryption-algorithm:AES256 (Header diabaikan)
  • Mengatur tingkat akses
    • Judul permintaan:
      • x-ms-access-tier (Header diabaikan)

Perbedaan header respons

Karena OneLake menggunakan model izin yang berbeda dari ADLS Gen2, ada perubahan pada header respons yang terkait dengan izin:

  • 'x-ms-owner' dan 'x-ms-group' selalu mengembalikan '$superuser', karena OneLake tidak memiliki pengguna atau grup.
  • 'x-ms-permissions' selalu mengembalikan '---------], karena OneLake tidak memiliki izin pengguna, grup, atau akses publik.
  • 'x-ms-acl' mengembalikan izin Fabric untuk pengguna panggilan yang dikonversi ke daftar kontrol akses POSIX (ACL), dalam bentuk 'rwx'

Authorization

Anda dapat mengautentikasi API OneLake menggunakan Microsoft Azure Active Directory (Azure AD) dengan melewati header otorisasi. Jika alat mendukung masuk ke akun Azure Anda untuk mengaktifkan passthrough AAD, Anda dapat memilih langganan apa pun - OneLake hanya memerlukan token AAD Anda dan tidak peduli dengan langganan Azure Anda.

Residensi data

OneLake saat ini tidak menjamin residensi data di wilayah tertentu saat menggunakan titik akhir global ('https://onelake.dfs.fabric.microsoft.com'). Saat Anda mengkueri data di wilayah yang berbeda dari wilayah ruang kerja Anda, ada kemungkinan data dapat meninggalkan wilayah Anda selama proses resolusi titik akhir. Jika Anda khawatir tentang residensi data, menggunakan titik akhir regional yang benar untuk ruang kerja Anda memastikan data Anda tetap berada di wilayahnya saat ini dan tidak melewati batas regional apa pun. Anda dapat menemukan titik akhir regional yang benar dengan memeriksa wilayah kapasitas tempat ruang kerja dilampirkan.

Semua titik akhir regional OneLake mengikuti format yang sama: 'https://< region-onelake.dfs.fabric.microsoft.com>'. Misalnya, ruang kerja yang melekat pada kapasitas di wilayah US Barat 2 akan dapat diakses melalui titik akhir regional 'https://westus-onelake.dfs.fabric.microsoft.com.

Sampel

Membuat file

Permintaan MENEMPATKAN https://onelake.dfs.fabric.microsoft.com/{workspace}/{item}.{itemtype}/Files/sample?resource=file
Header Authorization: Bearer <userAADToken>
Respons ResponseCode:201 Created
Header:
x-ms-version : 2021-06-08
x-ms-request-id : 272526c7-0995-4cc4-b04a-8ea3477bc67b
x-ms-content-crc64 : OAJ6r0dQWP0=
x-ms-request-server-encrypted : true
ETag : 0x8DA58EE365
Tubuh:

Langkah berikutnya

  • Integrasi OneLake dengan Azure Synapse Analytics