مشاركة عبر

تأمين بيانات الاعتماد مع الخدمات المرتبطة باستخدام mssparkutils

يُعد الوصول إلى البيانات من مصادر خارجية نمطًا شائعًا. إن لم يسمح مصدر البيانات الخارجي بالوصول المجهول، فقد تحتاج إلى تأمين اتصالك من خلال بيانات الاعتماد أو البيانات السرية أو سلسلة اتصال.

يستخدم Azure Synapse Analytics تمرير Microsoft Entra بشكل افتراضي للمصادقة بين الموارد. إذا كنت بحاجة إلى الاتصال بمورد باستخدام بيانات اعتماد أخرى، فاستخدم mssparkutils مباشرة. تبسط حزمة mssparkutils عملية استرداد رموز SAS المميزة ورمز Microsoft Entra المميزة سلسلة الاتصال والأسرار المخزنة في خدمة مرتبطة أو من Azure Key Vault.

تستخدم معاينة Microsoft Entra الأذونات المعينة لك كمستخدم في معرف Microsoft Entra، بدلا من الأذونات المعينة إلى Synapse أو كيان خدمة منفصل. على سبيل المثال، إذا كنت تريد استخدام Microsoft Entra passthrough للوصول إلى كائن ثنائي كبير الحجم في حساب تخزين، فيجب عليك الانتقال إلى حساب التخزين هذا وتعيين دور مساهم كائن ثنائي كبير الحجم لنفسك.

عند استعادة البيانات السرية من Azure Key Vault، نوصي بإنشاء خدمة مرتبطة بتطبيق Azure Key Vault. تأكد من امتلاك هوية الخدمة المدارة لمساحة عمل Synapse على امتيازات الحصول على البيانات السرية في Azure Key Vault. سيصادق Synapse على Azure Key Vault باستخدام هوية الخدمة المدارة لمساحة عمل Synapse. إذا قمت بالاتصال مباشرة ب Azure Key Vault دون خدمة مرتبطة، فصادق باستخدام بيانات اعتماد المستخدم Microsoft Entra.

لمزيد من المعلومات، راجع الخدمات المرتبطة.

الاستخدام

تعليمات mssparkutils للرمز المميزة والأسرار

تعرض هذه الدالة وثائق التعليمات لإدارة الأسرار والرموز المميزة في Synapse.

mssparkutils.credentials.help()

mssparkutils.credentials.help()

Console.WriteLine(TokenLibrary.help());

الحصول على النتيجة:

 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

الوصول إلى Azure Data Lake Storage Gen2

تخزين ADLS Gen2 الأساسي

يستخدم الوصول إلى الملفات من Azure Data Lake Storage الأساسي تمرير Microsoft Entra للمصادقة بشكل افتراضي ولا يتطلب الاستخدام الصريح ل mssparkutils. تختلف الهوية المستخدمة في مصادقة المرور استنادا إلى بعض العوامل. بشكل افتراضي، يتم تنفيذ دفاتر الملاحظات التفاعلية باستخدام هوية المستخدم، ولكن يمكن تغييرها إلى هوية الخدمة المدارة لمساحة العمل (MSI). تستخدم المهام الدفعية وعمليات التنفيذ غير التفاعلية لدفتر الملاحظات Workspace MSI.

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))

تخزين ADLS Gen2 مع الخدمات المرتبطة

يوفر Azure Synapse Analytics تجربة خدمات مرتبطة متكاملة عند الاتصال ب Azure Data Lake Storage Gen2. يمكن تكوين الخدمات المرتبطة للمصادقة باستخدام مفتاح حساب أو كيان الخدمة أو الهوية المدارة أو بيانات الاعتماد.

عند تعيين أسلوب مصادقة الخدمة المرتبطة إلى مفتاح الحساب، تصادق الخدمة المرتبطة باستخدام مفتاح حساب التخزين المتوفر، وتطلب مفتاح SAS، وتطبقه تلقائيا على طلب التخزين باستخدام LinkedServiceBasedSASProvider.

يسمح Synapse للمستخدمين بتعيين الخدمة المرتبطة لحساب تخزين معين. وهذا يجعل من الممكن قراءة/كتابة البيانات من حسابات تخزين متعددة في تطبيق/استعلام spark واحد. بمجرد تعيين spark.storage.synapse.{source_full_storage_account_name}.linkedServiceName كل حساب تخزين سيتم استخدامه، يحدد Synapse الخدمة المرتبطة التي سيتم استخدامها لعملية قراءة/كتابة معينة. ومع ذلك إذا كانت وظيفة spark تتعامل فقط مع حساب تخزين واحد، يمكننا حذف اسم حساب التخزين واستخدام spark.storage.synapse.linkedServiceName.

إشعار

لا يمكن تغيير أسلوب المصادقة لحاوية تخزين ABFS الافتراضية.

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()

عند تعيين أسلوب مصادقة الخدمة المرتبطة إلى الهوية المدارة أو كيان الخدمة، تستخدم الخدمة المرتبطة الهوية المدارة أو الرمز المميز لمدير الخدمة مع موفر 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()

تعيين إعدادات المصادقة من خلال تكوين spark

يمكن أيضا تحديد إعدادات المصادقة من خلال تكوينات spark، بدلا من تشغيل عبارات spark. يجب أن تكون جميع تكوينات spark مسبوقة مع spark. ويجب أن تكون جميع تكوينات hadoop مسبوقة ب spark.hadoop..

اسم تكوين Spark قيمة التكوين
spark.storage.synapse.teststorage.dfs.core.windows.net.linkedServiceName اسم الخدمة المرتبطة
spark.hadoop.fs.azure.account.oauth.provider.type.teststorage.dfs.core.windows.net microsoft.azure.synapse.tokenlibrary.LinkedServiceBasedTokenProvider

تخزين ADLS Gen2 بدون خدمات مرتبطة

اتصل بتخزين ADLS Gen2 مباشرة باستخدام مفتاح SAS. ConfBasedSASProvider استخدم وقم بتوفير مفتاح SAS لإعداد spark.storage.synapse.sas التكوين. يمكن تعيين رموز SAS المميزة على مستوى الحاوية أو مستوى الحساب أو العمومي. لا نوصي بتعيين مفاتيح SAS على المستوى العمومي، حيث لن تتمكن المهمة من القراءة/الكتابة من أكثر من حساب تخزين واحد.

تكوين SAS لكل حاوية تخزين

%%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))

تكوين SAS لكل حساب تخزين

%%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))

تكوين SAS لجميع حسابات التخزين

%%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))

استخدام MSAL للحصول على الرموز المميزة (باستخدام بيانات اعتماد التطبيق المخصصة)

عند تكوين برنامج تشغيل تخزين ABFS لاستخدام MSAL مباشرة للمصادقات، لا يقوم الموفر بتخزين الرموز المميزة مؤقتا. يمكن أن يؤدي هذا إلى مشكلات في الموثوقية. نوصي باستخدام ClientCredsTokenProvider هو جزء من Synapse Spark.

%%spark
val source_full_storage_account_name = "teststorage.dfs.core.windows.net"
sc.hadoopConfiguration.set("fs.azure.sas.token.provider.type", "com.microsoft.azure.synapse.tokenlibrary.ClientCredsTokenProvider")
spark.conf.set("fs.azure.account.oauth2.client.id.$source_full_storage_account_name", "<Entra AppId>")
spark.conf.set("fs.azure.account.oauth2.client.secret.$source_full_storage_account_name", "<Entra app secret>")
spark.conf.set("fs.azure.account.oauth2.client.endpoint.$source_full_storage_account_name", "https://login.microsoftonline.com/<tenantid>")

val df = spark.read.csv("abfss://<CONTAINER>@<ACCOUNT>.dfs.core.windows.net/<FILE PATH>")

display(df.limit(10))

%%pyspark
source_full_storage_account_name = "teststorage.dfs.core.windows.net"
sc._jsc.hadoopConfiguration().set("fs.azure.sas.token.provider.type", "com.microsoft.azure.synapse.tokenlibrary.ClientCredsTokenProvider")
spark.conf.set(f"fs.azure.account.oauth2.client.id.{source_full_storage_account_name}.linkedServiceName", "<Entra AppId>")
spark.conf.set(f"fs.azure.account.oauth2.client.secret.{source_full_storage_account_name}.linkedServiceName", "<Entra app secret>")
spark.conf.set(f"fs.azure.account.oauth2.client.endpoint.{source_full_storage_account_name}.linkedServiceName", "https://login.microsoftonline.com/<tenantid>")

df = spark.read.csv('abfss://<CONTAINER>@<ACCOUNT>.dfs.core.windows.net/<FILE PATH>')
display(df.limit(10))

تخزين ADLS Gen2 مع رمز SAS المميز (من Azure Key Vault)

اتصل بتخزين ADLS Gen2 باستخدام رمز SAS المخزن في البيانات السرية لتطبيق 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 للخدمات المرتبطة الأخرى

للاتصال بالخدمات المرتبطة الأخرى، يمكنك إجراء مكالمة مباشرة إلى TokenLibrary

الحصول على سلسلة الاتصال()

لاسترداد سلسلة الاتصال، استخدم الدالة getConnectionString وقم بتمرير اسم الخدمة المرتبطة.

%%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 هي دالة مساعدة متوفرة في Scala وPython للحصول على جميع خصائص الخدمة المرتبطة

%%pyspark
import json
# retrieve connectionstring from mssparkutils

json.loads(mssparkutils.credentials.getPropertiesAll("<LINKED SERVICE NAME>"))

سيبدو الإخراج مثل

{
    'AuthType': 'Key',
    'AuthKey': '[REDACTED]',
    'Id': None,
    'Type': 'AzureBlobStorage',
    'Endpoint': 'https://storageaccount.blob.core.windows.net/',
    'Database': None
}

GetSecret()

لاستعادة بيانات سرية مخزنة من Azure Key Vault، نوصي بإنشاء خدمة مرتبطة بتطبيق Azure Key Vault ضمن مساحة عمل Synapse. ستحتاج هوية الخدمة المدارة لمساحة عمل Synapse إلى منح إذن GET Secrets إلى Azure Key Vault. وستستخدم الخدمة المرتبطة هوية الخدمة المدارة للاتصال بخدمة Azure Key Vault لاسترداد البيانات السرية. وإلا، فإن الاتصال مباشرة ب Azure Key Vault سيستخدم بيانات اعتماد Microsoft Entra للمستخدم. وفي هذه الحالة، سيحتاج المستخدم إلى منح أذونات للحصول على بيانات سرية في Azure Key Vault.

في السحب الحكومية، قم بتوفير اسم المجال المؤهل بالكامل ل keyvault.

mssparkutils.credentials.getSecret("<AZURE KEY VAULT NAME>", "<SECRET KEY>" [, <LINKED SERVICE NAME>])

لاسترداد سر من Azure Key Vault، استخدم الدالة 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);

اتصالات الخدمة المرتبطة المدعومة من وقت تشغيل Spark

بينما يدعم Azure Synapse Analytics اتصالات الخدمة المرتبطة المختلفة (من المسارات ومنتجات Azure الأخرى)، لا يتم دعمها جميعا من وقت تشغيل Spark. فيما يلي قائمة بالخدمات المرتبطة المدعومة:

  • Azure Blob Storage
  • خدماتالذكاء الاصطناعي في Azure
  • Azure Cosmos DB
  • Azure Data Explorer ‏(Kusto)
  • قاعدة بيانات Azure لـ MySQL
  • قاعدة بيانات Azure لـ PostgreSQL
  • Azure Data Lake Store (Gen1)
  • Azure Key Vault
  • Azure Machine Learning  
  • Azure Purview
  • قاعدة بيانات Azure SQL
  • مستودع بيانات Azure SQL (مخصص وبلا خادم)
  • تخزين Azure

mssparkutils.credentials.getToken()

عندما تحتاج إلى رمز مميز لحامل OAuth للوصول إلى الخدمات مباشرة، يمكنك استخدام getToken الأسلوب . يتم دعم الموارد التالية:

اسم الخدمة سلسلة حرفية لاستخدامها في استدعاء واجهة برمجة التطبيقات
Azure Storage Storage
Azure Key Vault Vault
Azure Management AzureManagement
Azure SQL Data Warehouse (Dedicated and Serverless) DW
Azure Synapse Synapse
Azure Data Lake Store DataLakeStore
Azure Data Factory ADF
Azure Data Explorer AzureDataExplorer

الوصول إلى الخدمة المرتبطة غير المدعومة من وقت تشغيل Spark

الطرق التالية للوصول إلى الخدمات المرتبطة غير مدعومة من وقت تشغيل Spark:

  • تمرير الوسيطات إلى خدمة مرتبطة ذات معلمات
  • الاتصالات بالهويات المدارة المعينة من قبل المستخدم (UAMI)
  • الحصول على الرمز المميز للحامل إلى مورد Keyvault عند تشغيل دفتر الملاحظات / SparkJobDefinition كهوية مدارة
    • كبديل، بدلا من الحصول على رمز مميز للوصول، يمكنك إنشاء خدمة مرتبطة ب Keyvault والحصول على السر من دفتر الملاحظات / مهمة الدفعة
  • بالنسبة لاتصالات Azure Cosmos DB، يتم دعم الوصول المستند إلى المفتاح وحده. الوصول المستند إلى الرمز المميز غير مدعوم.

أثناء تشغيل دفتر ملاحظات أو مهمة Spark، قد تفشل طلبات الحصول على رمز مميز / سر باستخدام خدمة مرتبطة برسالة خطأ تشير إلى "BadRequest". غالبا ما يحدث هذا بسبب مشكلة في التكوين مع الخدمة المرتبطة. إذا رأيت رسالة الخطأ هذه، فيرجى التحقق من تكوين الخدمة المرتبطة. إذا كانت لديك أي أسئلة، فاتصل بدعم Microsoft Azure في مدخل Microsoft Azure.

المحتوى ذو الصلة

  • Last updated on