Pengantar API pemasang/pelepasan file di Azure Synapse Analytics

Tim Azure Synapse Studio membuat dua API pemasangan/pelepasan baru dalam paket Microsoft Spark Utilities (mssparkutils). Anda dapat menggunakan API ini untuk memasang penyimpanan jarak jauh (Azure Blob Storage atau Azure Data Lake Storage Gen2) ke semua node yang berfungsi (node driver dan node pekerja). Setelah penyimpanan dipasang, Anda dapat menggunakan API file lokal untuk mengakses data seolah-olah disimpan dalam sistem file lokal. Untuk informasi selengkapnya, lihat Pengantar Utilitas Microsoft Spark.

Artikel ini menunjukkan kepada Anda cara menggunakan API pemasangan/pelepasan di ruang kerja Anda. Anda akan mempelajari:

• Cara memasang Azure Data Lake Storage Gen2 atau Blob Storage.
• Cara mengakses file di bagian titik pemasangan melalui API sistem file lokal.
• Cara mengakses file di bagian titik pemasangan menggunakan mssparktuils fs API.
• Cara mengakses file di bagian titik pemasangan menggunakan Spark read API.
• Cara melepaskan titik pemasangan.

Peringatan

Pemasangan berbagi file Azure dinonaktifkan untuk sementara. Anda dapat menggunakan pemasangan Data Lake Storage Gen2 atau Azure Blob Storage sebagai gantinya, seperti yang dijelaskan di bagian berikutnya.

Penyimpanan Azure Data Lake Storage Gen1 tidak didukung. Anda dapat memigrasikan ke Data Lake Storage Gen2 dengan mengikuti panduan migrasi Azure Data Lake Storage Gen1 ke Gen2 sebelum menggunakan API pemasangan.

Penyimpanan pemasangan

Bagian ini mengilustrasikan cara memasang Data Lake Storage Gen2 langkah demi langkah sebagai contoh. Pemasangan Blob Storage juga berfungsi serupa.

Contoh mengasumsikan bahwa Anda memiliki satu akun Data Lake Storage Gen2 bernama storegen2. Akun ini memiliki satu kontainer bernama mycontainer yang ingin Anda pasang /test di kumpulan Spark Anda.

Untuk memasang kontainer yang disebut mycontainer, mssparkutils pertama-tama perlu memeriksa apakah Anda memiliki izin untuk mengakses kontainer. Saat ini, Azure Synapse Analytics mendukung tiga metode autentikasi untuk operasi pemasangan pemicu: linkedService, accountKey, dan sastoken.

Pasang dengan menggunakan layanan tertaut (disarankan)

Kami merekomendasikan pemasangan pemicu melalui layanan tertaut. Metode ini menghindari kebocoran keamanan, karena mssparkutils tidak menyimpan nilai rahasia atau autentikasi itu sendiri. Sebagai gantinya, mssparkutils selalu mengambil nilai autentikasi dari layanan tertaut untuk meminta data blob dari penyimpanan jarak jauh.

Anda dapat membuat layanan tertaut untuk Data Lake Storage Gen2 atau Blob Storage. Saat ini, Azure Synapse Analytics mendukung dua metode autentikasi saat Anda membuat layanan tertaut:

• Membuat layanan tertaut dengan menggunakan kunci akun

  

• Membuat layanan tertaut dengan menggunakan identitas terkelola

  

Penting

• Jika Layanan Tertaut yang dibuat di atas ke Azure Data Lake Storage Gen2 menggunakan titik akhir privat terkelola (dengan URI dfs), maka kita perlu membuat titik akhir privat terkelola sekunder lainnya menggunakan opsi Azure Blob Storage (dengan URI blob) untuk memastikan bahwa kode fsspec/adlfs internal dapat tersambung menggunakan antarmuka BlobServiceClient.
• Jika titik akhir privat terkelola sekunder tidak dikonfigurasi dengan benar, maka kita akan melihat pesan kesalahan seperti ServiceRequestError: Tidak dapat tersambung ke host [storageaccountname].blob.core.windows.net:443 ssl:True [Nama atau layanan tidak diketahui]

Catatan

Jika Anda membuat layanan tertaut menggunakan identitas terkelola sebagai metode autentikasi, pastikan bahwa file MSI ruang kerja memiliki peran Kontributor Data Blob Storage dari kontainer yang dipasang.

Setelah berhasil membuat layanan tertaut, Anda dapat dengan memasang kontainer secara mudah ke kumpulan Spark Anda dengan kode Python berikut:

mssparkutils.fs.mount( 
    "abfss://mycontainer@<accountname>.dfs.core.windows.net", 
    "/test", 
    {"linkedService": "mygen2account"} 
) 

Catatan

Anda mungkin perlu mengimpor mssparkutils jika kode tidak tersedia:

from notebookutils import mssparkutils 

Kami tidak menyarankan Anda memasang folder akar, apa pun metode autentikasi yang Anda gunakan.

Parameter pemasangan:

• fileCacheTimeout: Blob akan di-cache di folder sementara lokal selama 120 detik secara default. Selama waktu ini, blobfuse tidak akan memeriksa apakah file sudah diperbarui atau tidak. Parameter dapat diatur untuk mengubah waktu habis default. Ketika beberapa klien memodifikasi file secara bersamaan, untuk menghindari inkonsistensi antara file lokal dan jarak jauh, sebaiknya persingkat waktu cache, atau bahkan mengubahnya menjadi 0, dan selalu mendapatkan file terbaru dari server.
• batas waktu: Batas waktu operasi pemasangan adalah 120 detik secara default. Parameter dapat diatur untuk mengubah waktu habis default. Ketika ada terlalu banyak pelaksana atau ketika waktu pemasangan habis, sebaiknya tingkatkan nilainya.
• cakupan: Parameter cakupan digunakan untuk menentukan cakupan pemasangan. Nilai defaultnya adalah "pekerjaan." Jika cakupan diatur ke "pekerjaan," pemasangan hanya terlihat oleh kluster saat ini. Jika cakupan diatur ke "ruang kerja", pemasangan terlihat oleh semua buku catatan di ruang kerja saat ini, dan titik pemasangan secara otomatis dibuat jika tidak ada. Tambahkan parameter yang sama ke API unmount untuk melepas titik pemasangan. Pemasangan tingkat ruang kerja hanya didukung untuk autentikasi layanan tertaut.

Anda dapat menggunakan parameter ini seperti ini:

mssparkutils.fs.mount(
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",
    "/test",
    {"linkedService":"mygen2account", "fileCacheTimeout": 120, "timeout": 120}
)

Memasang melalui token tanda tangan akses bersama atau kunci akun

Selain memasang melalui layanan tertaut, mssparkutils mendukung secara eksplisit penerusan kunci akun atau token tanda tangan akses bersama (SAS) sebagai parameter untuk memasang target.

Untuk alasan keamanan, sebaiknya simpan kunci akun atau token SAS di Azure Key Vault (seperti yang ditunjukkan cuplikan layar contoh berikut). Lalu, Anda dapat mengambil kunci atau token tersebut menggunakan mssparkutil.credentials.getSecret API. Untuk informasi selengkapnya, lihat Mengelola kunci akun penyimpanan dengan Key Vault dan Azure CLI (lama).

Berikut kode sampelnya.

from notebookutils import mssparkutils  

accountKey = mssparkutils.credentials.getSecret("MountKV","mySecret")  
mssparkutils.fs.mount(  
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",  
    "/test",  
    {"accountKey":accountKey}
) 

Catatan

Untuk alasan keamanan, jangan simpan info masuk dalam kode.

Mengakses file di bawah titik pemasangan dengan menggunakan mssparkutils fs API

Tujuan utama operasi pemasangan adalah memungkinkan pelanggan mengakses data yang disimpan di akun penyimpanan jarak jauh dengan menggunakan API sistem file lokal. Anda juga dapat mengakses data dengan menggunakan mssparkutils fs API dengan jalur yang dipasang sebagai parameter. Format jalur yang digunakan di sini sedikit berbeda.

Dengan asumsi Anda telah memasang mycontainer kontainer Data Lake Storage Gen2 ke /test menggunakan API pemasangan. Saat mengakses data melalui API sistem file lokal:

• Untuk versi Spark kurang dari atau sama dengan 3.3, format jalurnya adalah /synfs/{jobId}/test/{filename}.
• Untuk versi Spark yang lebih besar dari atau sama dengan 3.4, format jalurnya adalah /synfs/notebook/{jobId}/test/{filename}.

Sebaiknya gunakan untuk mendapatkan jalur yang mssparkutils.fs.getMountPath() akurat:

path = mssparkutils.fs.getMountPath("/test")

Catatan

Saat Anda memasang penyimpanan dengan workspace cakupan, titik pemasangan dibuat di /synfs/workspace bawah folder . Dan Anda perlu menggunakan mssparkutils.fs.getMountPath("/test", "workspace") untuk mendapatkan jalur yang akurat.

Saat Anda ingin mengakses data dengan menggunakan mssparkutils fs API, format jalurnya seperti ini: synfs:/notebook/{jobId}/test/{filename}. Anda dapat melihat bahwa synfs digunakan sebagai skema dalam kasus ini, bukan sebagai bagian dari jalur yang dipasang. Tentu saja, Anda juga dapat menggunakan skema sistem file lokal untuk mengakses data. Contohnya,file:/synfs/notebook/{jobId}/test/{filename}.

Tiga contoh berikut menunjukkan cara mengakses file dengan jalur titik pemasangan dengan menggunakan mssparkutils fs.

• Membuat daftar direktori:

  mssparkutils.fs.ls(f'file:{mssparkutils.fs.getMountPath("/test")}') 
  

• Membaca konten file:

  mssparkutils.fs.head(f'file:{mssparkutils.fs.getMountPath("/test")}/myFile.csv') 
  

• Membuat direktori:

  mssparkutils.fs.mkdirs(f'file:{mssparkutils.fs.getMountPath("/test")}/myDir') 
  

Akses file di bagian titik pemasangan menggunakan Spark read API.

Anda dapat memberikan parameter untuk mengakses data melalui API baca Spark. Format jalur di sini sama saat Anda menggunakan mssparkutils fs API.

Membaca file dari akun penyimpanan Data Lake Storage Gen2 yang dipasang

Contoh berikut mengasumsikan bahwa akun penyimpanan Data Lake Storage Gen2 sudah dipasang, lalu Anda membaca file dengan menggunakan jalur pemasangan:

%%pyspark 

df = spark.read.load(f'file:{mssparkutils.fs.getMountPath("/test")}/myFile.csv', format='csv') 
df.show() 

Catatan

Saat memasang penyimpanan menggunakan layanan tertaut, Anda harus selalu secara eksplisit mengatur konfigurasi layanan tertaut spark sebelum menggunakan skema synfs untuk mengakses data. Lihat penyimpanan ADLS Gen2 dengan layanan tertaut untuk detailnya.

Membaca file dari akun Blob Storage yang terpasang

Jika Anda memasang akun Blob Storage dan ingin mengaksesnya dengan menggunakan mssparkutils atau Spark API, Anda harus mengonfigurasikan secara eksplisit token SAS melalui konfigurasi Spark sebelum mencoba memasang kontainer dengan menggunakan API pemasangan:

1. Untuk mengakses akun Blob Storage dengan menggunakan mssparkutils atau Spark API setelah pemasangan pemicu, perbarui konfigurasi Spark seperti yang ditunjukkan pada contoh kode berikut. Anda dapat melewati langkah ini jika ingin mengakses konfigurasi Spark hanya dengan menggunakan API file lokal setelah pemasangan.

   blob_sas_token = mssparkutils.credentials.getConnectionStringOrCreds("myblobstorageaccount") 
   
   spark.conf.set('fs.azure.sas.mycontainer.<blobStorageAccountName>.blob.core.windows.net', blob_sas_token) 
   

2. Buat myblobstorageaccount layanan tertaut, dan pasang akun Blob Storage dengan menggunakan layanan tertaut:

   %%spark 
   mssparkutils.fs.mount( 
       "wasbs://mycontainer@<blobStorageAccountName>.blob.core.windows.net", 
       "/test", 
       Map("linkedService" -> "myblobstorageaccount") 
   ) 
   

3. Pasang kontainer Blob Storage, lalu baca file dengan menggunakan jalur pemasangan melalui API file lokal:

       # mount the Blob Storage container, and then read the file by using a mount path
       with open(mssparkutils.fs.getMountPath("/test") + "/myFile.txt") as f:
       print(f.read())
   

4. Baca data dari kontainer Blob Storage yang dipasang melalui API baca Spark:

   %%spark
   // mount blob storage container and then read file using mount path
   val df = spark.read.text(f'file:{mssparkutils.fs.getMountPath("/test")}/myFile.txt')
   df.show()
   

Melepas titik pemasangan

Gunakan kode berikut untuk melepas titik pemasangan Anda (/test dalam contoh ini):

mssparkutils.fs.unmount("/test") 

Pembatasan yang diketahui

• Mekanisme pelepasan tidak otomatis. Saat eksekusi aplikasi selesai, Anda harus memanggil API yang dilepas secara eksplisit dalam kode Anda untuk melepas titik pemasangan agar dapat melepas ruang disk. Jika tidak, titik pemasangan masih akan ada di node setelah eksekusi aplikasi selesai.

• Pemasangan akun penyimpanan Data Lake Storage Gen1 tidak didukung untuk saat ini.

Langkah berikutnya

• Memulai menggunakan Azure Synapse Analytics
• Memantau ruang kerja Synapse
• Pengantar Utilitas Microsoft Spark