Pular para o conteúdo principal

Conectar-se ao pool dedicado do Azure Synapse Analytics

Este tutorial guia o senhor por todas as etapas necessárias 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​

As etapas a seguir neste tutorial mostram ao senhor como se conectar ao Azure Synapse Analytics usando uma entidade de serviço.

Etapa 1: Criar uma entidade de serviço Microsoft Entra ID 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 a Etapa 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) Etapa 2: Crie uma entidade de serviço Microsoft Entra ID para o Azure Synapse Analytics​

Opcionalmente, o senhor pode criar uma entidade de serviço dedicada ao Azure Synapse Analytics repetindo as instruções da Etapa 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.

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

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

Etapa 4: Conceder acesso à entidade de serviço ao 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 na etapa 1 e defina Role como Storage Blob Data Contributor .
  6. Clique em Salvar .
nota

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

Etapa 5: Criar um key mestre em Azure Synapse Analytics dedicado pool​

Conecte-se ao site Azure Synapse Analytics dedicado pool e crie um site mestre key, caso o senhor não o tenha feito antes.

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

Etapa 6: Conceder permissões à entidade de serviço no pool dedicado do Azure Synapse Analytics​

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:

SQL
CREATE USER <serviceprincipal> FROM EXTERNAL PROVIDER
nota

O nome da entidade de serviço deve corresponder àquele criado na Etapa 2 (ou na Etapa 1, se o senhor tiver pulado a criação de uma entidade de serviço dedicada para o Azure Synapse Analytics).

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

SQL
sp_addrolemember 'db_owner', '<serviceprincipal>'

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

SQL
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:

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

Etapa 7: Exemplo de sintaxe: consultar e gravar dados no 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.

The following code examples show you have to:

  • Set up the storage account access key in the notebook session
  • Define the service principal credentials for the Azure storage account
  • Define a separate set of service principal credentials for Azure Synapse Analytics (If not defined, the connector will use the Azure storage account credentials)
  • Get some data from an Azure Synapse table
  • Load data from an Azure Synapse query
  • Apply some transformations to the data, then use the Data Source API to write the data back to another table in Azure Synapse
Scala
  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()

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:

SQL
CREATE USER <serviceprincipal> FROM EXTERNAL PROVIDER

A credencial da entidade de serviço não tem permissões suficientes no site 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:

SQL
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.

nota

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 :

SQL
sp_addrolemember 'db_owner', 'serviceprincipal'

Nenhum mestre key no dedicado pool​

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 um mestre key em 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:

Última atualização em