Kredensial aman dengan layanan tertaut menggunakan mssparkutils
Mengakses data dari sumber eksternal adalah pola umum. Kecuali sumber data eksternal memungkinkan akses anonim, kemungkinan Anda perlu mengamankan koneksi Anda dengan string kredensial, rahasia, atau koneksi.
Azure Synapse Analytics menggunakan passthrough Microsoft Entra secara default untuk autentikasi antar sumber daya. Jika Anda perlu terhubung ke sumber daya menggunakan kredensial lain, gunakan mssparkutils secara langsung. Paket mssparkutils menyederhanakan proses pengambilan token SAS, token Microsoft Entra, string koneksi, dan rahasia yang disimpan dalam layanan tertaut atau dari Azure Key Vault.
Passthrough Microsoft Entra menggunakan izin yang ditetapkan kepada Anda sebagai pengguna di ID Microsoft Entra, daripada izin yang ditetapkan ke Synapse atau perwakilan layanan terpisah. Misalnya, jika Anda ingin menggunakan passthrough Microsoft Entra untuk mengakses blob di akun penyimpanan, maka Anda harus pergi ke akun penyimpanan tersebut dan menetapkan peran kontributor blob untuk diri Anda sendiri.
Saat mengambil rahasia dari Azure Key Vault, sebaiknya buat layanan tertaut ke Azure Key Vault Anda. Pastikan bahwa identitas layanan terkelola ruang kerja (MSI) Synapse memiliki hak istimewa Secret Get di Azure Key Vault Anda. Synapse akan mengautentikasi ke Azure Key Vault menggunakan identitas layanan terkelola ruang kerja Synapse. Jika Anda terhubung langsung ke Azure Key Vault tanpa layanan tertaut, Anda akan mengautentikasi menggunakan kredensial Microsoft Entra pengguna Anda.
Untuk informasi selengkapnya, lihat layanan tertaut.
Penggunaan
mssparkutils membantu untuk token dan rahasia
Fungsi ini menampilkan dokumentasi bantuan untuk manajemen rahasia dan token di Synapse.
mssparkutils.credentials.help()
mssparkutils.credentials.help()
Console.WriteLine(TokenLibrary.help());
Dapatkan hasil:
getToken(audience: String, name: String): returns AAD token for a given audience, name (optional)
isValidToken(token: String): returns true if token hasn't expired
getConnectionStringOrCreds(linkedService: String): returns connection string or credentials for the linked service
getFullConnectionString(linkedService: String): returns full connection string with credentials for the linked service
getPropertiesAll(linkedService: String): returns all the properties of the linked service
getSecret(akvName: String, secret: String, linkedService: String): returns AKV secret for a given AKV linked service, akvName, secret key using workspace MSI
getSecret(akvName: String, secret: String): returns AKV secret for a given akvName, secret key using user credentials
getSecretWithLS(linkedService: String, secret: String): returns AKV secret for a given linked service, secret key
putSecret(akvName: String, secretName: String, secretValue: String): puts AKV secret for a given akvName, secretName
putSecret(akvName: String, secretName: String, secretValue: String, linkedService: String): puts AKV secret for a given akvName, secretName
putSecretWithLS(linkedService: String, secretName: String, secretValue: String): puts AKV secret for a given linked service, secretName
Mengakses Azure Data Lake Storage Gen2
Penyimpanan Primer ADLS Gen2
Mengakses file dari Azure Data Lake Storage utama menggunakan passthrough Microsoft Entra untuk autentikasi secara default dan tidak memerlukan penggunaan eksplisit mssparkutils. Identitas yang digunakan dalam autentikasi passthrough berbeda berdasarkan beberapa faktor. Secara default, notebook interaktif dijalankan menggunakan identitas pengguna, tetapi dapat diubah ke identitas layanan terkelola ruang kerja (MSI). Pekerjaan batch dan eksekusi notebook yang tidak interaktif menggunakan MSI Ruang Kerja.
val df = spark.read.csv("abfss://<CONTAINER>@<ACCOUNT>.dfs.core.windows.net/<FILE PATH>")
display(df.limit(10))
df = spark.read.csv('abfss://<CONTAINER>@<ACCOUNT>.dfs.core.windows.net/<FILE PATH>')
display(df.limit(10))
Penyimpanan ADLS Gen2 dengan layanan tertaut
Azure Synapse Analytics memberikan pengalaman layanan tertaut terintegrasi saat menyambungkan ke Azure Data Lake Storage Gen2. Layanan tertaut dapat dikonfigurasi untuk mengautentikasi menggunakan Kunci Akun, Perwakilan Layanan, Identitas Terkelola, atau Kredensial.
Ketika metode autentikasi layanan tertaut diatur ke Kunci Akun, layanan tertaut akan mengautentikasi menggunakan kunci akun penyimpanan yang disediakan, meminta kunci SAS, dan secara otomatis menerapkannya ke permintaan penyimpanan menggunakan LinkedServiceBasedSASProvider.
Synapse memungkinkan pengguna untuk mengatur layanan yang terhubung untuk akun penyimpanan tertentu. Dengan ini, membaca/menulis data dari beberapa akun penyimpanan dapat dilakukan dalam aplikasi/kueri spark tunggal. Setelah kita mengatur spark.storage.synapse.{ source_full_storage_account_name}.linkedServiceName untuk setiap akun penyimpanan yang akan digunakan, Synapse mencari tahu layanan tertaut mana yang digunakan untuk operasi baca/tulis tertentu. Namun, jika pekerjaan spark kami hanya berurusan dengan akun penyimpanan tunggal, kita dapat cukup menghilangkan nama akun penyimpanan dan menggunakan spark.storage.synapse.linkedServiceName
val sc = spark.sparkContext
val source_full_storage_account_name = "teststorage.dfs.core.windows.net"
spark.conf.set(s"spark.storage.synapse.$source_full_storage_account_name.linkedServiceName", "<LINKED SERVICE NAME>")
sc.hadoopConfiguration.set(s"fs.azure.account.auth.type.$source_full_storage_account_name", "SAS")
sc.hadoopConfiguration.set(s"fs.azure.sas.token.provider.type.$source_full_storage_account_name", "com.microsoft.azure.synapse.tokenlibrary.LinkedServiceBasedSASProvider")
val df = spark.read.csv("abfss://<CONTAINER>@<ACCOUNT>.dfs.core.windows.net/<FILE PATH>")
display(df.limit(10))
%%pyspark
# Set the required configs
source_full_storage_account_name = "teststorage.dfs.core.windows.net"
spark.conf.set(f"spark.storage.synapse.{source_full_storage_account_name}.linkedServiceName", "<lINKED SERVICE NAME>")
sc._jsc.hadoopConfiguration().set(f"fs.azure.account.auth.type.{source_full_storage_account_name}", "SAS")
sc._jsc.hadoopConfiguration().set(f"fs.azure.sas.token.provider.type.{source_full_storage_account_name}", "com.microsoft.azure.synapse.tokenlibrary.LinkedServiceBasedSASProvider")
# Python code
df = spark.read.csv('abfss://<CONTAINER>@<ACCOUNT>.dfs.core.windows.net/<DIRECTORY PATH>')
df.show()
Ketika metode autentikasi layanan tertaut diatur ke Identitas Terkelola atau Perwakilan Layanan, layanan tertaut akan menggunakan token Identitas Terkelola atau Perwakilan Layanan dengan penyedia LinkedServiceBasedTokenProvider.
val sc = spark.sparkContext
val source_full_storage_account_name = "teststorage.dfs.core.windows.net"
spark.conf.set(s"spark.storage.synapse.$source_full_storage_account_name.linkedServiceName", "<LINKED SERVICE NAME>")
sc.hadoopConfiguration.set(s"fs.azure.account.oauth.provider.type.$source_full_storage_account_name", "com.microsoft.azure.synapse.tokenlibrary.LinkedServiceBasedTokenProvider")
val df = spark.read.csv("abfss://<CONTAINER>@<ACCOUNT>.dfs.core.windows.net/<FILE PATH>")
display(df.limit(10))
%%pyspark
# Python code
source_full_storage_account_name = "teststorage.dfs.core.windows.net"
spark.conf.set(f"spark.storage.synapse.{source_full_storage_account_name}.linkedServiceName", "<LINKED SERVICE NAME>")
sc._jsc.hadoopConfiguration().set(f"fs.azure.account.oauth.provider.type.{source_full_storage_account_name}", "com.microsoft.azure.synapse.tokenlibrary.LinkedServiceBasedTokenProvider")
df = spark.read.csv('abfss://<CONTAINER>@<ACCOUNT>.dfs.core.windows.net/<DIRECTORY PATH>')
df.show()
Penyimpanan ADLS Gen2 tanpa layanan tertaut
Koneksi ke penyimpanan ADLS Gen2 secara langsung dengan menggunakan kunci SAS. ConfBasedSASProvider Gunakan dan berikan kunci SAS ke spark.storage.synapse.sas pengaturan konfigurasi. Token SAS dapat diatur pada tingkat kontainer, tingkat akun, atau global. Kami tidak menyarankan pengaturan kunci SAS di tingkat global, karena pekerjaan tidak akan dapat membaca/menulis dari lebih dari satu akun penyimpanan.
Konfigurasi SAS per kontainer penyimpanan
%%spark
sc.hadoopConfiguration.set("fs.azure.account.auth.type.<ACCOUNT>.dfs.core.windows.net", "SAS")
sc.hadoopConfiguration.set("fs.azure.sas.token.provider.type", "com.microsoft.azure.synapse.tokenlibrary.ConfBasedSASProvider")
spark.conf.set("spark.storage.synapse.<CONTAINER>.<ACCOUNT>.dfs.core.windows.net.sas", "<SAS KEY>")
val df = spark.read.csv("abfss://<CONTAINER>@<ACCOUNT>.dfs.core.windows.net/<FILE PATH>")
display(df.limit(10))
%%pyspark
sc._jsc.hadoopConfiguration().set("fs.azure.account.auth.type.<ACCOUNT>.dfs.core.windows.net", "SAS")
sc._jsc.hadoopConfiguration().set("fs.azure.sas.token.provider.type", "com.microsoft.azure.synapse.tokenlibrary.ConfBasedSASProvider")
spark.conf.set("spark.storage.synapse.<CONTAINER>.<ACCOUNT>.dfs.core.windows.net.sas", "<SAS KEY>")
df = spark.read.csv('abfss://<CONTAINER>@<ACCOUNT>.dfs.core.windows.net/<FILE PATH>')
display(df.limit(10))
Konfigurasi SAS per akun penyimpanan
%%spark
sc.hadoopConfiguration.set("fs.azure.account.auth.type.<ACCOUNT>.dfs.core.windows.net", "SAS")
sc.hadoopConfiguration.set("fs.azure.sas.token.provider.type", "com.microsoft.azure.synapse.tokenlibrary.ConfBasedSASProvider")
spark.conf.set("spark.storage.synapse.<ACCOUNT>.dfs.core.windows.net.sas", "<SAS KEY>")
val df = spark.read.csv("abfss://<CONTAINER>@<ACCOUNT>.dfs.core.windows.net/<FILE PATH>")
display(df.limit(10))
%%pyspark
sc._jsc.hadoopConfiguration().set("fs.azure.account.auth.type.<ACCOUNT>.dfs.core.windows.net", "SAS")
sc._jsc.hadoopConfiguration().set("fs.azure.sas.token.provider.type", "com.microsoft.azure.synapse.tokenlibrary.ConfBasedSASProvider")
spark.conf.set("spark.storage.synapse.<ACCOUNT>.dfs.core.windows.net.sas", "<SAS KEY>")
df = spark.read.csv('abfss://<CONTAINER>@<ACCOUNT>.dfs.core.windows.net/<FILE PATH>')
display(df.limit(10))
Konfigurasi SAS dari semua akun penyimpanan
%%spark
sc.hadoopConfiguration.set("fs.azure.account.auth.type", "SAS")
sc.hadoopConfiguration.set("fs.azure.sas.token.provider.type", "com.microsoft.azure.synapse.tokenlibrary.ConfBasedSASProvider")
spark.conf.set("spark.storage.synapse.sas", "<SAS KEY>")
val df = spark.read.csv("abfss://<CONTAINER>@<ACCOUNT>.dfs.core.windows.net/<FILE PATH>")
display(df.limit(10))
%%pyspark
sc._jsc.hadoopConfiguration().set("fs.azure.account.auth.type", "SAS")
sc._jsc.hadoopConfiguration().set("fs.azure.sas.token.provider.type", "com.microsoft.azure.synapse.tokenlibrary.ConfBasedSASProvider")
spark.conf.set("spark.storage.synapse.sas", "<SAS KEY>")
df = spark.read.csv('abfss://<CONTAINER>@<ACCOUNT>.dfs.core.windows.net/<FILE PATH>')
display(df.limit(10))
Penyimpanan ADLS Gen2 dengan Azure Key Vault
Sambungkan ke penyimpanan ADLS Gen2 menggunakan token SAS yang disimpan di rahasia Azure Key Vault.
%%spark
sc.hadoopConfiguration.set("fs.azure.account.auth.type", "SAS")
sc.hadoopConfiguration.set("fs.azure.sas.token.provider.type", "com.microsoft.azure.synapse.tokenlibrary.AkvBasedSASProvider")
spark.conf.set("spark.storage.synapse.akv", "<AZURE KEY VAULT NAME>")
spark.conf.set("spark.storage.akv.secret", "<SECRET KEY>")
val df = spark.read.csv("abfss://<CONTAINER>@<ACCOUNT>.dfs.core.windows.net/<FILE PATH>")
display(df.limit(10))
%%pyspark
sc._jsc.hadoopConfiguration().set("fs.azure.account.auth.type", "SAS")
sc._jsc.hadoopConfiguration().set("fs.azure.sas.token.provider.type", "com.microsoft.azure.synapse.tokenlibrary.AkvBasedSASProvider")
spark.conf.set("spark.storage.synapse.akv", "<AZURE KEY VAULT NAME>")
spark.conf.set("spark.storage.akv.secret", "<SECRET KEY>")
df = spark.read.csv('abfss://<CONTAINER>@<ACCOUNT>.dfs.core.windows.net/<FILE PATH>')
display(df.limit(10))
TokenLibrary untuk layanan tertaut lainnya
Untuk terhubung ke layanan tertaut lainnya, Anda dapat melakukan panggilan langsung ke TokenLibrary.
getConnectionString()
Untuk mengambil string koneksi, gunakan fungsi getConnectionString dan berikan nama layanan tertaut.
%%spark
// retrieve connectionstring from mssparkutils
mssparkutils.credentials.getFullConnectionString("<LINKED SERVICE NAME>")
%%pyspark
# retrieve connectionstring from mssparkutils
mssparkutils.credentials.getFullConnectionString("<LINKED SERVICE NAME>")
%%csharp
// retrieve connectionstring from TokenLibrary
using Microsoft.Spark.Extensions.Azure.Synapse.Analytics.Utils;
string connectionString = TokenLibrary.GetConnectionString(<LINKED SERVICE NAME>);
Console.WriteLine(connectionString);
getPropertiesAll()
getPropertiesAll adalah fungsi pembantu yang tersedia di Scala dan Python untuk mendapatkan semua properti layanan tertaut
%%pyspark
import json
# retrieve connectionstring from mssparkutils
json.loads(mssparkutils.credentials.getPropertiesAll("<LINKED SERVICE NAME>"))
Output akan terlihat seperti
{
'AuthType': 'Key',
'AuthKey': '[REDACTED]',
'Id': None,
'Type': 'AzureBlobStorage',
'Endpoint': 'https://storageaccount.blob.core.windows.net/',
'Database': None
}
GetSecret()
Untuk mengambil rahasia yang disimpan dari Azure Key Vault, kami sarankan Anda membuat layanan tertaut ke Azure Key Vault di dalam ruang kerja Synapse. Identitas layanan terkelola ruang kerja Synapse harus diberikan izin GET Secrets ke Azure Key Vault. Layanan tertaut akan menggunakan identitas layanan terkelola untuk menyambungkan ke layanan Azure Key Vault untuk mengambil rahasia. Jika tidak, menyambungkan langsung ke Azure Key Vault akan menggunakan kredensial Microsoft Entra pengguna. Dalam hal ini, pengguna harus diberikan izin Get Secret di Azure Key Vault.
Di cloud pemerintah, berikan nama domain yang sepenuhnya memenuhi syarat dari keyvault.
mssparkutils.credentials.getSecret("<AZURE KEY VAULT NAME>", "<SECRET KEY>" [, <LINKED SERVICE NAME>])
Untuk mengambil rahasia dari Azure Key Vault, gunakan fungsi mssparkutils.credentials.getSecret().
mssparkutils.credentials.getSecret("<AZURE KEY VAULT NAME>", "<SECRET KEY>", "<LINKED SERVICE NAME>")
mssparkutils.credentials.getSecret("<AZURE KEY VAULT NAME>", "<SECRET KEY>", "<LINKED SERVICE NAME>")
using Microsoft.Spark.Extensions.Azure.Synapse.Analytics.Utils;
string connectionString = TokenLibrary.GetSecret("<AZURE KEY VAULT NAME>", "<SECRET KEY>", "<LINKED SERVICE NAME>");
Console.WriteLine(connectionString);
Koneksi layanan tertaut didukung dari runtime Spark
Meskipun Azure Synapse Analytics mendukung berbagai koneksi layanan tertaut (dari alur dan produk Azure lainnya), tidak semuanya didukung dari runtime Spark. Berikut adalah daftar layanan tertaut yang didukung:
- Penyimpanan Blob Azure
- Layanan Azure AI
- Azure Cosmos DB
- Azure Data Explorer
- Azure Database untuk MySQL
- Azure Database untuk PostgreSQL
- Azure Data Lake Store (Gen1)
- Azure Key Vault
- Pembelajaran Mesin Azure
- Azure Purview
- Database Azure SQL
- Gudang Data Azure SQL (Khusus dan Tanpa Server)
- Azure Storage
mssparkutils.credentials.getToken()
Ketika Anda memerlukan token pembawa OAuth untuk mengakses layanan secara langsung, Anda dapat menggunakan metode ini getToken . Sumber daya berikut ini didukung:
| Nama Layanan | String literal yang akan digunakan dalam panggilan API |
|---|---|
| Azure Storage | Storage |
| Azure Key Vault | Vault |
| Manajemen Azure | AzureManagement |
| Gudang Data Azure SQL (Khusus dan Tanpa Server) | DW |
| Azure Synapse | Synapse |
| Azure Data Lake Store | DataLakeStore |
| Azure Data Factory | ADF |
| Azure Data Explorer | AzureDataExplorer |
| Azure Database untuk MySQL | AzureOSSDB |
| Azure Database untuk MariaDB | AzureOSSDB |
| Azure Database untuk PostgreSQL | AzureOSSDB |
Akses layanan tertaut yang tidak didukung dari runtime Spark
Metode berikut untuk mengakses layanan tertaut tidak didukung dari runtime Spark:
- Meneruskan argumen ke layanan tertaut berparameter
- Koneksi dengan Identitas terkelola yang ditetapkan pengguna (UAMI)
- Identitas Terkelola yang Ditetapkan Sistem tidak didukung pada sumber daya Keyvault
- Untuk koneksi Azure Cosmos DB, akses berbasis kunci saja didukung. Akses berbasis token tidak didukung.
Saat menjalankan notebook atau pekerjaan Spark, permintaan untuk mendapatkan token/rahasia menggunakan layanan tertaut mungkin gagal dengan pesan kesalahan yang menunjukkan 'BadRequest'. Ini sering disebabkan oleh masalah konfigurasi dengan layanan tertaut. Jika Anda melihat pesan kesalahan ini, silakan periksa konfigurasi layanan tertaut Anda. Jika Anda memiliki pertanyaan, silakan hubungi Dukungan Microsoft Azure di portal Azure.
Konten terkait
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk