Conectar-se ao pool dedicado do Azure Synapse Analytics

Este tutorial guia o senhor por todos os passos necessários para se conectar de Azure Databricks a Azure Synapse Analytics dedicado pool usando entidade de serviço, Azure serviço gerenciado Identity (MSI) e SQL Authentication. O conector do Azure Synapse usa três tipos de conexões de rede:

  • Driver Spark para o Azure Synapse

  • Spark driver e executor para Azure storage account

  • Azure Synapse para Azure storage account

Conector do Azure Synapse

Requisitos

Conclua essa tarefa antes de iniciar o tutorial:

Conecte-se ao Azure Synapse Analytics usando uma entidade de serviço

Os passos a seguir neste tutorial mostram aos senhores como se conectar ao Azure Synapse Analytics usando uma entidade de serviço.

o passo 1: Crie um Microsoft Entra ID entidade de serviço para o Azure Data Lake Storage Gen2

Para usar a entidade de serviço para se conectar ao Azure data lake Gen2, um usuário administrador deve criar um novo aplicativo Microsoft Entra ID (anteriormente conhecido como Azure Active Directory). Se o senhor já tiver uma entidade de serviço Microsoft Entra ID disponível, pule para o passo 3. Para criar uma entidade de serviço Microsoft Entra ID, siga estas instruções:

  1. Faça login no portal do Azure.

  2. Se o senhor tiver acesso a vários locatários, inscrições ou diretórios, clique no ícone Diretórios + inscrição (diretório com filtro) no menu superior para alternar para o diretório no qual deseja provisionar a entidade de serviço.

  3. Pesquise e selecione Microsoft Entra ID.

  4. Em gerenciar, clique em App registrations (Registros de aplicativos) > New registration (Novo registro).

  5. Em Nome, insira o nome do aplicativo.

  6. Na seção Tipos de account suportados, selecione a conta somente neste diretório organizacional (Single tenant).

  7. Clique em Registrar.

(Opcional) o passo 2: Crie um Microsoft Entra ID entidade de serviço para o Azure Synapse Analytics

Opcionalmente, o senhor pode criar uma entidade de serviço dedicada ao site Azure Synapse Analytics, repetindo as instruções do passo 1. Se o senhor não criar um conjunto separado de credenciais de entidade de serviço, a conexão usará a mesma entidade de serviço para se conectar ao data lake Gen2 do Azure e ao Azure Synapse Analytics.

o passo 3: Crie um segredo de cliente para sua entidade de serviço Azure data lake Gen2 (e Azure Synapse Analytics)

  1. Em Gerenciar, clique em Certificados & secrets

  2. Em Client secrets (Segredos do cliente ) tab, clique em New client secret (Novo segredo do cliente).

  3. No painel Adicionar um segredo do cliente, em Descrição, insira uma descrição para o segredo do cliente.

  4. Em Expira, selecione um período de expiração para o segredo do cliente e clique em Adicionar.

  5. Copie e armazene o valor do segredo do cliente em um local seguro, pois esse segredo do cliente é a senha do seu aplicativo.

  6. Na página Visão geral da página do aplicativo, na seção Essentials, copie os seguintes valores:

    • ID da aplicação (cliente)

    • ID do diretório (tenant)

Observação

Se o senhor criou um conjunto de credenciais de entidade de serviço para Azure Synapse Analytics, siga os passos novamente para criar um segredo de cliente.

o passo 4: Conceder à entidade de serviço acesso a Azure Data Lake Storage Gen2

O senhor concede acesso ao recurso de armazenamento atribuindo funções à sua entidade de serviço. Neste tutorial, o senhor atribui o Storage Blob Data Contributor à(s) entidade(s) de serviço(s) em seu Azure Data Lake Storage Gen2 account. Talvez seja necessário atribuir outras funções, dependendo dos requisitos específicos.

  1. No portal Azure, acesse o serviço Storage account (Conta de armazenamento ).

  2. Selecione um armazenamento Azure account para usar.

  3. Clique em Controle de acesso (IAM).

  4. Clique em + Add (Adicionar ) e selecione Add role assignment (Adicionar atribuição de função ) no menu dropdown.

  5. Defina o campo Select como o nome do aplicativo Microsoft Entra ID que o senhor criou no passo 1 e defina Role como Storage Blob Data Contributor.

  6. Clique em Salvar.

Observação

Se o senhor criou um conjunto de credenciais de entidade de serviço para Azure Synapse Analytics, siga os passos novamente para conceder acesso à entidade de serviço no site Azure Data Lake Storage Gen2.

o passo 5: Criar um mestre key em Azure Synapse Analytics dedicado pool

Conecte-se ao pool dedicado do Azure Synapse Analytics e crie uma chave mestra, caso não tenha feito isso antes.

CREATE MASTER KEY ENCRYPTION BY PASSWORD = '<Password>'

o passo 6: Conceder permissões à entidade de serviço no site Azure Synapse Analytics dedicado pool

Conecte-se ao pool dedicado do Azure Synapse Analytics e crie um usuário externo para a entidade de serviço que se conectará ao Azure Synapse Analytics:

CREATE USER <serviceprincipal> FROM EXTERNAL PROVIDER

Observação

O nome da entidade de serviço deve corresponder àquele criado no passo 2 (ou no passo 1 se o senhor não tiver criado uma entidade de serviço dedicada para Azure Synapse Analytics).

Conceda permissões à entidade de serviço para ser um db_owner executando o comando abaixo:

sp_addrolemember 'db_owner', '<serviceprincipal>'

Conceda as permissões necessárias para poder inserir em uma tabela existente:

GRANT ADMINISTER DATABASE BULK OPERATIONS TO <serviceprincipal>
GRANT INSERT TO <serviceprincipal>

(Opcional) Conceda as permissões necessárias para poder inserir em uma nova tabela:

GRANT CREATE TABLE TO <serviceprincipal>
GRANT ALTER ON SCHEMA ::dbo TO <serviceprincipal>

o passo 7: Exemplo de sintaxe: consulta e gravação de dados em Azure Synapse Analytics

O senhor pode consultar Synapse em Scala, Python, SQL, e R. Os exemplos de código a seguir usam a chave de armazenamento account e encaminham as credenciais de armazenamento de Azure Databricks para Synapse.

Os exemplos de código a seguir mostram que você precisa:

  • Configure o armazenamento account acesse key na sessão do Notebook

  • Definir as credenciais da entidade de serviço para o armazenamento Azure account

  • Defina um conjunto separado de credenciais de entidade de serviço para Azure Synapse Analytics (se não for definido, o conector usará as credenciais Azure storage account )

  • Obter alguns dados de uma tabela do Azure Synapse

  • Carregar dados de uma consulta do Azure Synapse

  • Aplique algumas transformações aos dados e, em seguida, use a fonte de dados API para gravar os dados de volta em outra tabela no Azure Synapse

  import org.apache.spark.sql.DataFrame

// Set up the storage account access key in the notebook session
conf.spark.conf.set(
  "fs.azure.account.key.<your-storage-account-name>.dfs.core.windows.net",
  "<your-storage-account-access-key>")

// Define the service principal credentials for the Azure storage account
spark.conf.set("fs.azure.account.auth.type", "OAuth")
spark.conf.set("fs.azure.account.oauth.provider.type",  "org.apache.hadoop.fs.azurebfs.oauth2.ClientCredsTokenProvider")
spark.conf.set("fs.azure.account.oauth2.client.id", "<ApplicationId>")
spark.conf.set("fs.azure.account.oauth2.client.secret", "<SecretValue>")
spark.conf.set("fs.azure.account.oauth2.client.endpoint", "https://login.microsoftonline.com/<DirectoryId>/oauth2/token")

// Define a separate set of service principal credentials for Azure Synapse Analytics (If not defined, the connector will use the Azure storage account credentials)
spark.conf.set("spark.databricks.sqldw.jdbc.service.principal.client.id", "<ApplicationId>")
spark.conf.set("spark.databricks.sqldw.jdbc.service.principal.client.secret", "<SecretValue>")

// Get some data from an Azure Synapse table
val df: DataFrame = spark.read
  .format("com.databricks.spark.sqldw")
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>")
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")
  .option("enableServicePrincipalAuth", "true")
  .option("dbTable", "dbo.<your-table-name>")
  .load()

// Load data from an Azure Synapse query
val df1: DataFrame = spark.read
  .format("com.databricks.spark.sqldw")
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>")
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")
  .option("enableServicePrincipalAuth", "true")
  .option("query", "select * from dbo.<your-table-name>")
  .load()

// Apply some transformations to the data, then use the
// Data Source API to write the data back to another table in Azure Synapse
df1.write
  .format("com.databricks.spark.sqldw")
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>")
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")
  .option("enableServicePrincipalAuth", "true")
  .option("dbTable", "dbo.<new-table-name>")
  .save()

Os exemplos de código a seguir mostram que você precisa:

  • Configure o armazenamento account acesse key na sessão do Notebook

  • Definir as credenciais da entidade de serviço para o armazenamento Azure account

  • Definir um conjunto separado de credenciais de entidade de serviço para Azure Synapse Analytics

  • Obter alguns dados de uma tabela do Azure Synapse

  • Carregar dados de uma consulta do Azure Synapse

  • Aplique algumas transformações aos dados e, em seguida, use a fonte de dados API para gravar os dados de volta em outra tabela no Azure Synapse

Os exemplos de código a seguir mostram que você precisa:

  • Definir as credenciais da entidade de serviço para o armazenamento Azure account

  • Definir um conjunto separado de credenciais de entidade de serviço para Azure Synapse Analytics

  • Configure o armazenamento account acesse key na sessão do Notebook

  • Ler uso de dados SQL

  • Escrever uso de dados SQL

# Define the Service Principal credentials for the Azure storage account
fs.azure.account.auth.type OAuth
fs.azure.account.oauth.provider.type org.apache.hadoop.fs.azurebfs.oauth2.ClientCredsTokenProvider
fs.azure.account.oauth2.client.id <application-id>
fs.azure.account.oauth2.client.secret <service-credential>
fs.azure.account.oauth2.client.endpoint https://login.microsoftonline.com/<directory-id>/oauth2/token

## Define a separate set of service principal credentials for Azure Synapse Analytics (If not defined, the connector will use the Azure storage account credentials)
spark.databricks.sqldw.jdbc.service.principal.client.id <application-id>
spark.databricks.sqldw.jdbc.service.principal.client.secret <service-credential>

# Set up the storage account access key in the notebook session
conf.SET fs.azure.account.key.<your-storage-account-name>.dfs.core.windows.net=<your-storage-account-access-key>

-- Read data using SQL
CREATE TABLE df
USING com.databricks.spark.sqldw
OPTIONS (
  url 'jdbc:sqlserver://<the-rest-of-the-connection-string>',
  'enableServicePrincipalAuth' 'true',
  dbtable 'dbo.<your-table-name>',
  tempDir 'abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>'
);

-- Write data using SQL
-- Create a new table, throwing an error if a table with the same name already exists:
CREATE TABLE df1
USING com.databricks.spark.sqldw
OPTIONS (
  url 'jdbc:sqlserver://<the-rest-of-the-connection-string>',
  'enableServicePrincipalAuth' 'true',
  dbTable 'dbo.<new-table-name>',
  tempDir 'abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>'
)
AS SELECT * FROM df1

Os exemplos de código a seguir mostram que você precisa:

  • Configure o armazenamento account acesse key no conf. de sessão do Notebook

  • Definir as credenciais da entidade de serviço para o armazenamento Azure account

  • Defina um conjunto separado de credenciais de entidade de serviço para Azure Synapse Analytics (se não for definido, o conector usará as credenciais Azure storage account )

  • Obter alguns dados de uma tabela do Azure Synapse

  • Aplique algumas transformações aos dados e, em seguida, use a fonte de dados API para gravar os dados de volta em outra tabela no Azure Synapse

# Load SparkR
library(SparkR)

# Set up the storage account access key in the notebook session conf
conf <- sparkR.callJMethod(sparkR.session(), "conf")
sparkR.callJMethod(conf, "set", "fs.azure.account.key.<your-storage-account-name>.dfs.core.windows.net", "<your-storage-account-access-key>")

# Load SparkR
library(SparkR)
conf <- sparkR.callJMethod(sparkR.session(), "conf")

# Define the service principal credentials for the Azure storage account
sparkR.callJMethod(conf, "set", "fs.azure.account.auth.type", "OAuth")
sparkR.callJMethod(conf, "set", "fs.azure.account.oauth.provider.type",  "org.apache.hadoop.fs.azurebfs.oauth2.ClientCredsTokenProvider")
sparkR.callJMethod(conf, "set", "fs.azure.account.oauth2.client.id", "<ApplicationId>")
sparkR.callJMethod(conf, "set", "fs.azure.account.oauth2.client.secret", "<SecretValue>")
sparkR.callJMethod(conf, "set", "fs.azure.account.oauth2.client.endpoint", "https://login.microsoftonline.com/<DirectoryId>/oauth2/token")

# Define a separate set of service principal credentials for Azure Synapse Analytics (If not defined, the connector will use the Azure storage account credentials)
sparkR.callJMethod(conf, "set", "spark.databricks.sqldw.jdbc.service.principal.client.id", "<ApplicationId>")
sparkR.callJMethod(conf, "set", "spark.databricks.sqldw.jdbc.service.principal.client.secret", "SecretValue>")

# Get some data from an Azure Synapse table
df <- read.df(
  source = "com.databricks.spark.sqldw",
  url = "jdbc:sqlserver://<the-rest-of-the-connection-string>",
  tempDir = "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>",
  enableServicePrincipalAuth = "true",
  dbTable = "dbo.<your-table-name>")

# Load data from an Azure Synapse query.
df <- read.df(
  source = "com.databricks.spark.sqldw",
  url = "jdbc:sqlserver://<the-rest-of-the-connection-string>",
  tempDir = "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>",
  enableServicePrincipalAuth = "true",
  query = "Select * from dbo.<your-table-name>")

# Apply some transformations to the data, then use the
# Data Source API to write the data back to another table in Azure Synapse
write.df(
  df,
  source = "com.databricks.spark.sqldw",
  url = "jdbc:sqlserver://<the-rest-of-the-connection-string>",
  tempDir = "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>",
  enableServicePrincipalAuth = "true",
  dbTable = "dbo.<new-table-name>")

Solução de problemas

As seções a seguir discutem as mensagens de erro que você pode encontrar e seus possíveis significados.

a credencial da entidade de serviço não existe como um usuário 

com.microsoft.sqlserver.jdbc.SQLServerException: Login failed for user '<token-identified principal>'

O erro anterior provavelmente significa que a credencial da entidade de serviço não existe como um usuário no site Synapse analítica workspace.

Execute o seguinte comando no site Azure Synapse Analytics dedicado pool para criar um usuário externo:

CREATE USER <serviceprincipal> FROM EXTERNAL PROVIDER

A credencial da entidade de serviço não tem permissões suficientes SELECT 

com.microsoft.sqlserver.jdbc.SQLServerException: The SELECT permission was denied on the object 'TableName', database 'PoolName', schema 'SchemaName'. [ErrorCode = 229] [SQLState = S0005]

O erro anterior provavelmente significa que a credencial da entidade de serviço não tem permissões SELECT suficientes no pool dedicado do Azure Synapse Analytics.

Execute o seguinte comando no site Azure Synapse Analytics dedicado pool para conceder permissões SELECT:

GRANT SELECT TO <serviceprincipal>

A credencial da entidade de serviço não tem permissão para usar COPY 

com.microsoft.sqlserver.jdbc.SQLServerException: User does not have permission to perform this action. [ErrorCode = 15247] [SQLState = S0001]

O erro anterior provavelmente significa que a credencial da entidade de serviço não tem permissões suficientes no pool dedicado do Azure Synapse Analytics para usar COPY. A entidade de serviço requer permissões diferentes, dependendo das operações (inserir em uma tabela existente ou inserir em uma nova tabela). Certifique-se de que a entidade de serviço tenha as permissões necessárias do Azure Synapse.

Observação

A entidade de serviço não é um db_owner do pool dedicado do Azure Synapse Analytics.

Execute o seguinte comando no site Azure Synapse Analytics dedicado pool para conceder permissões db_owner:

sp_addrolemember 'db_owner', 'serviceprincipal'

Não há chave mestra no pool dedicado 

com.microsoft.sqlserver.jdbc.SQLServerException: Please create a master key in the database or open the master key in the session before performing this operation. [ErrorCode = 15581] [SQLState = S0006]

O erro anterior provavelmente significa que não há um key mestre no Azure Synapse Analytics dedicado pool.

Crie uma chave mestra no Azure Synapse Analytics para corrigir esse problema.

A credencial da entidade de serviço não tem permissões de gravação suficientes 

com.microsoft.sqlserver.jdbc.SQLServerException: CREATE EXTERNAL TABLE AS SELECT statement failed as the path name '' could not be used for export. Please ensure that the specified path is a directory which exists or can be created, and that files can be created in that directory. [ErrorCode = 105005] [SQLState = S0001]

O erro anterior provavelmente significa que: