Azure Synapse Analytics 専用プールへの接続

このチュートリアルでは、サービスプリンシパル、Azure マネージドサービス Identity (MSI)、およびSQL 認証を用いて、Azure DatabricksからAzure Synapse Analytics専用プールに接続するために必要なすべてのステップを説明します。Azure Synapse コネクタでは、次の 3 種類のネットワーク接続が使用されます。

Spark ドライバーから Azure Synapse への接続
SparkドライバーとエグゼキューターからAzureストレージアカウントへの接続
Azure Synapse から Azure ストレージアカウントへの接続

要件

チュートリアルを開始する前に、次のタスクを完了してください。

Azure Databricks ワークスペースを作成します。クイックスタート: Azure Databricks ワークスペースを作成するを参照してください。
Azure Synapse Analytics ワークスペースを作成します。クイックスタート: Synapse ワークスペースを作成するを参照してください
専用 SQL プールを作成します。クイックスタート: Azure portal を使用して専用 SQL プールを作成するを参照してください
Azure Databricks と Azure Synapse Analytics の間の接続用に、ステージング Azure Data Lake Storage Gen2 を作成します。

サービスプリンシパルを使用してAzure Synapse Analyticsに接続する

このチュートリアルの次のステップでは、サービスプリンシパルを使用して Azure Synapse Analytics に接続する方法を示します。

ステップ 1: Azure Data Lake Storage Gen2のためのMicrosoft Entra ID サービスプリンシパルを作成する

サービスプリンシパルを使用して Azure データレイク Gen2 に接続するには、管理者ユーザーが新しい Microsoft Entra ID (旧称 Azure Active Directory) アプリケーションを作成する必要があります。すでに Microsoft Entra ID サービスプリンシパルをお持ちの場合は、 ステップ 3 に進んでください。 Microsoft Entra ID サービスプリンシパルを作成するには、次の手順に従います。

Azure portal にサインインします。
複数のテナント、サブスクリプション、またはディレクトリにアクセスできる場合は、トップメニューの ディレクトリ + サブスクリプション (フィルター付きディレクトリ) アイコンをクリックして、サービスプリンシパルをプロビジョニングするディレクトリに切り替えます。
Microsoft Entra ID を検索して選択します。
管理で、アプリの登録 > 新規登録 をクリックします。
名前に、アプリケーションの名前を入力します。
サポートされているアカウントの種類 セクションで、この組織ディレクトリ内のアカウントのみ (Single テナント) を選択します。
登録をクリックします。

(省略可能) ステップ 2: Azure Synapse AnalyticsのためのMicrosoft Entra ID サービスプリンシパルの作成

オプションで、ステップ 1 の手順を繰り返すことで、 Azure Synapse Analytics 専用のサービスプリンシパルを作成できます。サービスプリンシパルクレデンシャルの個別のセットを作成しない場合、接続は同じサービスプリンシパルを使用して Azure データレイク Gen2 と Azure Synapse Analyticsに接続します。

ステップ 3: Azure のデータレイク Gen2 (and Azure Synapse Analytics) サービスプリンシパルのクライアントシークレットを作成する

管理で、証明書とシークレットをクリックします
クライアントシークレット タブで、新しいクライアントシークレットをクリックします。
クライアントシークレットの追加ペインの説明に、クライアントシークレットの説明を入力します。
有効期限 で、クライアントシークレットの有効期限を選択し、追加をクリックします。
クライアントシークレットの Value をコピーして安全な場所に保存します (このクライアントシークレットはアプリケーションのパスワードです)。
アプリケーションページの概要ページの要点セクションで、次の値をコピーします。
- アプリケーション (クライアント) ID
- ディレクトリ (テナント) ID

注：

Azure Synapse Analyticsのサービスプリンシパル認証情報のセットを作成した場合は、再度ステップに従ってクライアントシークレットを作成します。

ステップ 4: サービスプリンシパルに Azure Data Lake Storage Gen2へのアクセス権を付与する

ストレージリソースへのアクセス権を付与するには、サービスプリンシパルにロールを割り当てます。このチュートリアルでは、 Storage Blob Data Contributor を Azure Data Lake Storage Gen2 アカウントのサービスプリンシパルに割り当てます。特定の要件に応じて、他のロールを割り当てる必要がある場合があります。

Azure portal で、 ストレージアカウント サービスに移動します。
使用する Azure ストレージアカウントを選択します。
アクセス制御(IAM)をクリックします。
+ 追加をクリックし、ドロップダウンメニューからロールの割り当てを追加を選択します。
選択フィールドをステップ 1 で作成した Microsoft Entra ID アプリケーション名に設定し、ロールを ストレージ BLOB データ共同作成者に設定します。
保存をクリックします。

注：

Azure Synapse Analyticsのサービスプリンシパルクレデンシャルのセットを作成した場合は、再度ステップに従って、Azure Data Lake Storage Gen2上のサービスプリンシパルへのアクセス権を付与します。

ステップ 5:Azure Synapse Analytics 専用プールにマスターキーを作成する

Azure Synapse Analytics 専用プールに接続し、マスターキーを作成します (まだ作成していない場合)。

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

ステップ 6: Azure Synapse Analytics専用プール内のサービスプリンシパルにアクセス許可を付与する

Azure Synapse Analytics専用プールに接続し、 Azure Synapse Analyticsに接続するサービスプリンシパルの外部ユーザーを作成します。

CREATE USER <serviceprincipal> FROM EXTERNAL PROVIDER

注：

サービスプリンシパルの名前は、ステップ 2 ( Azure Synapse Analytics専用のサービスプリンシパルの作成をスキップした場合はステップ 1) で作成した名前と一致する必要があります。

サービスプリンシパルに db_owner になる権限を付与するには、次のコマンドを実行します。

sp_addrolemember 'db_owner', '<serviceprincipal>'

既存のテーブルに挿入するために必要な権限を付与します。

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

(オプション)新しいテーブルに挿入するために必要な権限を付与します。

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

ステップ 7: 構文の例: Azure Synapse Analyticsでデータをクエリして書き込む

Synapse のクエリは、Scala、Python、SQL、R で行うことができます。次のコード例では、ストレージアカウントキーを使用し、ストレージ資格情報を Azure Databricks から Synapse に転送します。

次のコード例は、次のことを行う必要があることを示しています。

ノートブックセッションでストレージアカウントのアクセスキーを設定する
Azure storage アカウントのサービスプリンシパル credentials を定義します
Azure Synapse Analytics に対してサービスプリンシパル資格情報の個別のセットを定義します (定義されていない場合、コネクタは Azure storage アカウント資格情報を使用します)
Azure Synapse テーブルからデータを取得する
Azure Synapse クエリからデータを読み込む
データにいくつかの変換を適用し、データソースAPIを使用してデータを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()

次のコード例は、次のことを行う必要があることを示しています。

ノートブックセッションでストレージアカウントのアクセスキーを設定する
Azure storage アカウントのサービスプリンシパル credentials を定義します
Azure Synapse Analytics に対してサービスプリンシパルクレデンシャルの個別のセットを定義します
Azure Synapse テーブルからデータを取得する
Azure Synapse クエリからデータを読み込む
データにいくつかの変換を適用し、データソースAPIを使用してデータをAzure Synapse内の別のテーブルに書き戻します

次のコード例は、次のことを行う必要があることを示しています。

Azure storage アカウントのサービスプリンシパル credentials を定義します
Azure Synapse Analytics に対してサービスプリンシパルクレデンシャルの個別のセットを定義します
ノートブックセッションでストレージアカウントのアクセスキーを設定する
SQLを使用したデータの読み取り
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

次のコード例は、次のことを行う必要があることを示しています。

ノートブックセッションの conf でストレージアカウントのアクセスキーを設定します
Azure storage アカウントのサービスプリンシパル credentials を定義します
Azure Synapse Analytics に対してサービスプリンシパル資格情報の個別のセットを定義します (定義されていない場合、コネクタは Azure storage アカウント資格情報を使用します)
Azure Synapse テーブルからデータを取得する
データにいくつかの変換を適用し、データソースAPIを使用してデータを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>")

トラブルシューティング

次のセクションでは、発生する可能性のあるエラーメッセージとその考えられる意味について説明します。

サービスプリンシパル credential がユーザーとして存在しません

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

上記のエラーは、サービスプリンシパルクレデンシャルが Synapse アナリティクスワークスペースにユーザーとして存在しないことを意味している可能性があります。

Azure Synapse Analytics 専用プールで次のコマンドを実行して、外部ユーザーを作成します。

CREATE USER <serviceprincipal> FROM EXTERNAL PROVIDER

サービスプリンシパル credential に十分な`SELECT`アクセス許可がありません

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

上記のエラーは、サービスプリンシパルクレデンシャルに Azure Synapse Analytics 専用プールに十分な SELECT アクセス許可がないことを意味している可能性があります。

Azure Synapse Analytics 専用プールで次のコマンドを実行して、SELECT アクセス許可を付与します。

GRANT SELECT TO <serviceprincipal>

サービスプリンシパル credential には、`COPY`を使用する権限がありません

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

上記のエラーは、サービスプリンシパル credential に、COPY を使用するための十分なアクセス許可が Azure Synapse Analytics 専用プールにないことを意味している可能性があります。サービスプリンシパルには、操作 (既存のテーブルへの挿入または新しいテーブルへの挿入) に応じて異なるアクセス許可が必要です。サービスプリンシパルに必要なAzure Synapse権限があることを確認します。

注：

サービスプリンシパルは、Azure Synapse Analytics専用プールのdb_owner ではありません。

Azure Synapse Analytics 専用プールで次のコマンドを実行して、 db_owner アクセス許可を付与します。

sp_addrolemember 'db_owner', 'serviceprincipal'

専用プールにマスターキーがありません

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]

上記のエラーは、Azure Synapse Analytics 専用プールにマスターキーが存在しないことを意味している可能性があります。

この問題を解決するには、Azure Synapse Analytics でマスターキーを作成します。

サービスプリンシパル credential に十分な書き込み権限がありません

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]

上記のエラーは、おそらく次のことを意味します。

サービスプリンシパルクレデンシャルに、PolyBase の書き込み操作に対する十分なアクセス許可がありません

サービスプリンシパルが、外部データソースオプションを使用した PolyBase に必要な Azure Synapse 権限を持っていることを確認します。
ステージングストレージアカウントには、Azure Data Lake Storage Gen2 機能がありません。

Azure Blob Storage は、Azure Data Lake Storage Gen2 機能を使用してアップグレードできます。
サービスプリンシパル/マネージドサービス ID には、 Azure Data Lake Storage Gen2に対する "Storage Blob Data Contributor" ロールがありません。
その他のトラブルシューティングについては、Azure Blob Storage に対して CETAS 操作を行うときのエラー 105005を参照してください。

Azure Synapse Analytics 専用プールへの接続

要件

サービスプリンシパル を使用してAzure Synapse Analyticsに接続する

ステップ 1: Azure Data Lake Storage Gen2のためのMicrosoft Entra ID サービスプリンシパルを作成する

(省略可能) ステップ 2: Azure Synapse AnalyticsのためのMicrosoft Entra ID サービスプリンシパルの作成

ステップ 3: Azure のデータレイク Gen2 (and Azure Synapse Analytics) サービスプリンシパルのクライアント シークレットを作成する

ステップ 4: サービスプリンシパルに Azure Data Lake Storage Gen2へのアクセス権を付与する

ステップ 5:Azure Synapse Analytics 専用プール にマスター キーを作成する

ステップ 6: Azure Synapse Analytics専用プール内のサービスプリンシパルにアクセス許可を付与する

ステップ 7: 構文の例: Azure Synapse Analyticsでデータをクエリして書き込む

トラブルシューティング

サービスプリンシパル credential がユーザーとして存在しません

サービスプリンシパル credential に十分なSELECTアクセス許可がありません

サービスプリンシパル credential には、COPYを使用する権限がありません

専用プールにマスター キーがありません

サービスプリンシパル credential に十分な書き込み権限がありません

サービスプリンシパルを使用してAzure Synapse Analyticsに接続する

ステップ 3: Azure のデータレイク Gen2 (and Azure Synapse Analytics) サービスプリンシパルのクライアントシークレットを作成する

ステップ 5:Azure Synapse Analytics 専用プールにマスターキーを作成する

サービスプリンシパル credential に十分な`SELECT`アクセス許可がありません

サービスプリンシパル credential には、`COPY`を使用する権限がありません

専用プールにマスターキーがありません