您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

通过使用 TokenLibrary 的链接服务保护凭据

访问来自外部源的数据是一种常见的模式。 除非外部数据源允许匿名访问,否则很可能需要使用凭据、机密或连接字符串来保护连接。

Synapse 默认使用 Azure Active Directory (AAD) 传递进行资源之间的身份验证。 如果需要使用其他凭据连接到资源,请直接使用 TokenLibrary。 TokenLibrary 简化了检索存储在链接服务或 Azure Key Vault 中的 SAS 令牌、AAD 令牌、连接字符串和机密的过程。

从 Azure Key Vault 检索机密时,建议为 Azure Key Vault 创建链接服务。 确保 Synapse 工作区托管服务标识 (MSI) 对你的 Azure Key Vault 具有机密获取特权。 Synapse 将使用 Synapse 工作区托管服务标识向 Azure Key Vault 进行身份验证。 如果没有链接服务而直接连接到 Azure Key Vault,将使用用户 Azure Active Directory 凭据进行身份验证。

有关详细信息,请参阅链接服务

使用情况

TokenLibrary.help()

此函数可显示 TokenLibrary 的帮助文档。

TokenLibrary.help()
TokenLibrary.help()
Console.WriteLine(TokenLibrary.help());

Azure Data Lake Storage Gen2 的 TokenLibrary

ADLS Gen2 主存储

访问 Azure Data Lake Storage 中的文件时,默认使用 Azure Active Directory 传递进行身份验证,不需要显式使用 TokenLibrary。

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 Data Lake Storage Gen2 时,Synapse 提供集成的链接服务体验。 可以将链接服务配置为使用帐户密钥、服务主体、托管标识或凭据进行身份验证。

当链接服务身份验证方法设置为“帐户密钥”时,链接服务将使用提供的存储帐户密钥进行身份验证,请求 SAS 密钥,并使用 LinkedServiceBasedSASProvider 将其自动应用于存储请求。

val sc = spark.sparkContext
spark.conf.set("spark.storage.synapse.linkedServiceName", "<LINKED SERVICE NAME>")
spark.conf.set("fs.azure.account.auth.type", "SAS")
spark.conf.set("fs.azure.sas.token.provider.type", "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
# Python code
spark.conf.set("spark.storage.synapse.linkedServiceName", "<lINKED SERVICE NAME>")
spark.conf.set("fs.azure.account.auth.type", "SAS")
spark.conf.set("fs.azure.sas.token.provider.type", "com.microsoft.azure.synapse.tokenlibrary.LinkedServiceBasedSASProvider")

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

df.show()

如果将链接服务身份验证方法设置为“托管标识”或“服务主体”,则链接服务会将托管标识或服务主体令牌用于 LinkedServiceBasedTokenProvider 提供程序。

val sc = spark.sparkContext
spark.conf.set("spark.storage.synapse.linkedServiceName", "<LINKED SERVICE NAME>")
spark.conf.set("fs.azure.account.oauth.provider.type", "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
spark.conf.set("spark.storage.synapse.linkedServiceName", "<lINKED SERVICE NAME>")
spark.conf.set("fs.azure.account.oauth.provider.type", "com.microsoft.azure.synapse.tokenlibrary.LinkedServiceBasedTokenProvider")

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

df.show()

ADLS Gen2 存储(无链接服务)

使用 SAS 密钥直接连接到 ADLS Gen2 存储时,会使用 ConfBasedSASProvider 并向 spark.storage.synapse.sas 配置设置提供 SAS 密钥。

%%spark
spark.conf.set("fs.azure.account.auth.type", "SAS")
spark.conf.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

spark.conf.set("fs.azure.account.auth.type", "SAS")
spark.conf.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))

ADLS Gen2 存储与 Azure Key Vault

使用存储在 Azure Key Vault 机密中的 SAS 令牌连接到 ADLS Gen2 存储。

%%spark
spark.conf.set("fs.azure.account.auth.type", "SAS")
spark.conf.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
spark.conf.set("fs.azure.account.auth.type", "SAS")
spark.conf.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()

若要检索连接字符串,请使用 getConnectionString 函数并传入链接服务名称。

%%spark
// retrieve connectionstring from TokenLibrary

import com.microsoft.azure.synapse.tokenlibrary.TokenLibrary

val connectionString: String = TokenLibrary.getConnectionString("<LINKED SERVICE NAME>")
println(connectionString)
%%pyspark
# retrieve connectionstring from TokenLibrary

from pyspark.sql import SparkSession

sc = SparkSession.builder.getOrCreate()
token_library = sc._jvm.com.microsoft.azure.synapse.tokenlibrary.TokenLibrary
connection_string = token_library.getConnectionString("<LINKED SERVICE NAME>")
print(connection_string)
%%csharp
// retrieve connectionstring from TokenLibrary

using Microsoft.Spark.Extensions.Azure.Synapse.Analytics.Utils;

string connectionString = TokenLibrary.GetConnectionString(<LINKED SERVICE NAME>);
Console.WriteLine(connectionString);

getConnectionStringAsMap()

getConnectionStringAsMap 是 Scala 和 Python 中提供的 helper 函数,用于分析连接字符串中 key=value 对中的特定值,例如

DefaultEndpointsProtocol=https;AccountName=<ACCOUNT NAME>;AccountKey=<ACCOUNT KEY>

使用 getConnectionStringAsMap 函数,传递密钥以返回值。 在上面的连接字符串示例中,

TokenLibrary.getConnectionStringAsMap("DefaultEndpointsProtocol")

将返回

"https"

// Linked services can be used for storing and retrieving credentials (e.g, account key)
// Example connection string (for storage): "DefaultEndpointsProtocol=https;AccountName=<accountname>;AccountKey=<accountkey>"
import com.microsoft.azure.synapse.tokenlibrary.TokenLibrary

val accountKey: String = TokenLibrary.getConnectionStringAsMap("<LINKED SERVICE NAME">).get("<KEY NAME>")
println(accountKey)
# Linked services can be used for storing and retrieving credentials (e.g, account key)
# Example connection string (for storage): "DefaultEndpointsProtocol=https;AccountName=<accountname>;AccountKey=<accountkey>"
from pyspark.sql import SparkSession

sc = SparkSession.builder.getOrCreate()
token_library = sc._jvm.com.microsoft.azure.synapse.tokenlibrary.TokenLibrary
accountKey = token_library.getConnectionStringAsMap("<LINKED SERVICE NAME>").get("<KEY NAME>")
print(accountKey)

getSecret()

若要检索存储在 Azure Key Vault 中的机密,建议在 Synapse 工作区内创建到 Azure Key Vault 的链接服务。 需要向 Synapse 工作区托管服务标识授予对 Azure Key Vault 的 GET Secrets 权限。 链接服务将使用托管服务标识来连接到 Azure Key Vault 服务,以检索机密。 否则,直接连接到 Azure Key Vault 将使用用户的 Azure Active Directory (AAD) 凭据。 在这种情况下,需要向用户授予 Azure Key Vault 中的“获取机密”权限。

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

若要从 Azure Key Vault 检索机密,请使用 TokenLibrary.getSecret() 函数。

import com.microsoft.azure.synapse.tokenlibrary.TokenLibrary

val connectionString: String = TokenLibrary.getSecret("<AZURE KEY VAULT NAME>", "<SECRET KEY>", "<LINKED SERVICE NAME>")
println(connectionString)
import sys
from pyspark.sql import SparkSession

sc = SparkSession.builder.getOrCreate()
token_library = sc._jvm.com.microsoft.azure.synapse.tokenlibrary.TokenLibrary

connection_string = token_library.getSecret("<AZURE KEY VAULT NAME>", "<SECRET KEY>", "<LINKED SERVICE NAME>")
print(connection_string)
using Microsoft.Spark.Extensions.Azure.Synapse.Analytics.Utils;

string connectionString = TokenLibrary.getSecret("<AZURE KEY VAULT NAME>", "<SECRET KEY>", "<LINKED SERVICE NAME>");
Console.WriteLine(connectionString);

后续步骤