Azure Synapse Analytics でのファイルマウント API とファイルマウント解除 API の概要

[アーティクル]
10/25/2023

Azure Synapse Studio チームは、Microsoft Spark Utilities (mssparkutils) パッケージに 2 つの新しいマウントおよびマウント解除 API を構築しました。これらの API を使って、すべての作業ノード (ドライバーノードとワーカーノード) にリモートストレージ (Azure Blob Storage、Azure Data Lake Storage Gen2) をアタッチできます。ストレージを配置した後は、ローカルファイル API を使って、ローカルファイルシステムに格納されているかのようにデータにアクセスできます。詳細については、「Microsoft Spark Utilities の概要」をご覧ください。

この記事では、ワークスペースでマウントおよびマウント解除 API を使う方法について説明します。学習内容:

Data Lake Storage Gen2 または Blob Storage をマウントする方法。
ローカルファイルシステム API を使ってマウントポイントの下にあるファイルにアクセスする方法。
mssparktuils fs API を使ってマウントポイントの下にあるファイルにアクセスする方法。
Spark 読み取り API を使ってマウントポイントの下にあるファイルにアクセスする方法。
マウントポイントのマウントを解除する方法。

警告

Azure ファイル共有のマウントは、一時的に無効にされます。次のセクションで説明するように、代わりに Data Lake Storage Gen2 または Azure Blob Storage のマウントを使用できます。

Azure Data Lake Storage Gen1 ストレージはサポートされていません。マウント API を使う前に、Azure Data Lake Storage Gen1 から Gen2 への移行ガイダンスに関する記事に従って、Data Lake Storage Gen2 に移行できます。

ストレージをマウントする

このセクションでは、例として Data Lake Storage Gen2 をマウントする手順を示します。 Blob Storage のマウントも同様に機能します。

この例では、storegen2 という名前の 1 つの Data Lake Storage Gen2 アカウントがあるとします。そのアカウントには mycontainer という名前のコンテナーが 1 つあり、それを Spark プールの /test にマウントします。

Screenshot of a Data Lake Storage Gen2 storage account.

mycontainer という名前のコンテナーをマウントするには、mssparkutils で最初に、ユーザーがコンテナーにアクセスするためのアクセス許可を持っているかどうかを調べる必要があります。現在、Azure Synapse Analytics でトリガーマウント操作に対してサポートされている認証方法は、LinkedService、accountKey、sastoken の 3 つです。

リンクサービスを使ってマウントする (推奨)

リンクサービスによるトリガーマウントをお勧めします。この方法を使うと、mssparkutils でシークレットや認証値自体が格納されないため、セキュリティリークが避けられます。代わりに、mssparkutils は常にリンクサービスから認証値をフェッチして、リモートストレージに BLOB データを要求します。

Screenshot of linked services.

Data Lake Storage Gen2 または Blob Storage のリンクサービスを作成できます。現在、Azure Synapse Analytics では、リンクサービスを作成するときに 2 つの認証方法がサポートされています。

アカウントキーを使ってリンクサービスを作成する
マネージド ID を使ってリンクサービスを作成する

重要

上記で作成した Azure Data Lake Storage Gen2 への Linked Service がマネージドプライベートエンドポイント (dfs URI を使用) を使用する場合、内部の fsspec/adlfs コードが BlobServiceClient インターフェイスを使用して接続できるように、Azure Blob Storage オプション (BLOB URI を使用) を使用した別のセカンダリマネージドプライベートエンドポイントを作成する必要があります。
セカンダリマネージドプライベートエンドポイントが正しく構成されていない場合、ServiceRequestError: Cannot connect to host [storageaccountname].blob.core.windows.net:443 ssl:True [Name or service not known] のようなエラーメッセージが表示されます

Screenshot of creating a managed private end-point to an ADLS Gen2 storage using blob endpoint.

Note

認証方法としてマネージド ID を使ってリンクサービスを作成する場合は、ワークスペースの MSI ファイルに、マウントされるコンテナーのストレージ BLOB データ共同作成者ロールがあることを確認します。

リンクサービスを正常に作成したら、次の Python コードを使って、コンテナーを Spark プールに簡単にマウントできます。

mssparkutils.fs.mount( 
    "abfss://mycontainer@<accountname>.dfs.core.windows.net", 
    "/test", 
    {"LinkedService":"mygen2account"} 
)

注意

mssparkutils を使用できない場合、それをインポートすることが必要な場合があります。

from notebookutils import mssparkutils

マウントパラメーター:

fileCacheTimeout: BLOB は、ローカルの一時フォルダーに既定で 120 秒間キャッシュされます。この間、blobfuse では、ファイルが最新であるかどうかの確認は行われません。必要に応じて、パラメーターの指定により既定のタイムアウト時間を変更できます。複数のクライアントから同時にファイルの変更操作が行われる場合は、ローカルファイルとリモートファイルとの間に不整合が発生するのを避けるために、キャッシュ時間を短縮するか 0 に設定し、常にサーバーから最新のファイルが取得されるようにすることをお勧めします。
timeout: マウント操作のタイムアウトは、既定で 120 秒です。必要に応じて、パラメーターの指定により既定のタイムアウト時間を変更できます。 Executor が多すぎる場合や、マウントのタイムアウトが発生する場合は、値を大きくすることをお勧めします。
scope: scope パラメーターは、マウントのスコープを指定する場合に使います。既定値は "job" です。スコープが "job" に設定されている場合、マウントは現在のクラスターにのみ表示されます。スコープが "workspace" に設定されている場合、マウントは現在のワークスペース内にあるすべてのノートブックに表示されます。また、マウントポイントは、なければ自動的に作成されます。マウントポイントをマウント解除するには、同じパラメーターをマウント解除 API に追加します。ワークスペースレベルのマウントは、リンクサービス認証でのみサポートされます。

これらのパラメーターの使用例を示します。

mssparkutils.fs.mount(
   "abfss://mycontainer@<accountname>.dfs.core.windows.net",
   "/test",
   {"linkedService":"mygen2account", "fileCacheTimeout": 120, "timeout": 120}
)

使用する認証方法に関係なく、ルートフォルダーをマウントすることはお勧めしません。

Shared Access Signature トークンまたはアカウントキーを使ってマウントする

リンクサービスによるマウントだけでなく、mssparkutils では、アカウントキーまたは Shared Access Signature (SAS) トークンをパラメーターとして明示的に渡してターゲットをマウントすることがサポートされています。

セキュリティ上の理由から、アカウントキーまたは SAS トークンを Azure Key Vault に格納することをお勧めします (次に示すスクリーンショットはその例です)。その後、mssparkutil.credentials.getSecret API を使って取得できます。詳細については、「Key Vault と Azure CLI を使用してストレージアカウントキーを管理する (レガシ)」を参照してください。

Screenshot that shows a secret stored in a key vault.

コード例を次に示します。

from notebookutils import mssparkutils  

accountKey = mssparkutils.credentials.getSecret("MountKV","mySecret")  
mssparkutils.fs.mount(  
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",  
    "/test",  
    {"accountKey":accountKey}
)

注意

セキュリティ上の理由から、資格情報をコードに格納しないでください。

mssparkutils fs API を使ってマウントポイントの下にあるファイルにアクセスする

マウント操作の主な目的は、ユーザーがローカルファイルシステムの API を使って、リモートストレージアカウントに格納されているデータにアクセスできるようすることです。また、mssparkutils fs API を使用し、マウントされたパスをパラメーターで指定して、データにアクセスすることもできます。ここで使用するパスの形式は少し異なります。

マウント API を使って、Data Lake Storage Gen2 コンテナー mycontainer を /test にマウントしたとします。ローカルファイルシステム API を使ってそのデータにアクセスするときは、パスの形式は次のようになります。

/synfs/{jobId}/test/{filename}

正確なパスを取得するには、mssparkutils.fs.getMountPath() を使うことをお勧めします。

path = mssparkutils.fs.getMountPath("/test") # equals to /synfs/{jobId}/test

mssparkutils fs API を使ってデータにアクセスするときのパスの形式は、次のようになります。

synfs:/{jobId}/test/{filename}

この場合の synfs は、マウントされたパスの一部ではなく、スキーマとして使われていることがわかります。

次の 3 つの例では、mssparkutils fs を使ってマウントポイントパスでファイルにアクセスする方法を示します。これらの例の 49 は、mssparkutils.env.getJobId() の呼び出しから取得した Spark ジョブ ID です。

ディレクトリのリストを取得します。
```
mssparkutils.fs.ls("synfs:/49/test") 
```

ファイルの内容を読み取ります。

mssparkutils.fs.head("synfs:/49/test/myFile.txt")

ディレクトリを作成します。

mssparkutils.fs.mkdirs("synfs:/49/test/newdir")

Spark 読み取り API を使ってマウントポイントの下にあるファイルにアクセスする

Spark 読み取り API を使って、データにアクセスするためのパラメーターを指定できます。ここでのパス形式は、mssparkutils fs API を使うときと同じです。

synfs:/{jobId}/test/{filename}

マウントされた Data Lake Storage Gen2 ストレージアカウントからファイルを読み取る

次の例では、Data Lake Storage Gen2 ストレージアカウントが既にマウントされているものとし、マウントパスを使ってファイルを読み取ります。

%%pyspark 

df = spark.read.load("synfs:/49/test/myFile.csv", format='csv') 
df.show()

Note

リンクサービスを使ってストレージをマウントする場合、データへのアクセスに synfs スキーマを使うには、必ず spark リンクサービス構成を明示的に設定する必要があります。詳細については、リンクサービスの ADLS Gen2 ストレージに関するセクションを参照してください。

マウントされた Blob Storage アカウントからファイルを読み取る

Blob Storage アカウントをマウントした場合に、mssparkutils または Spark API を使ってそれにアクセスするには、マウント API を使ってコンテナーをマウントする前に、Spark の構成で SAS トークンを明示的に構成する必要があります。

トリガーマウントの後で mssparkutils または Spark API を使って Blob Storage アカウントにアクセスするには、次のコード例に示すように Spark の構成を更新します。マウントの後でローカルファイル API だけを使って Spark の構成にアクセスする場合は、このステップをバイパスできます。
```
blob_sas_token = mssparkutils.credentials.getConnectionStringOrCreds("myblobstorageaccount") 

spark.conf.set('fs.azure.sas.mycontainer.<blobStorageAccountName>.blob.core.windows.net', blob_sas_token) 
```

リンクサービス myblobstorageaccount を作成し、リンクサービスを使用して Blob Storage アカウントをマウントします。

%%spark 
mssparkutils.fs.mount( 
    "wasbs://mycontainer@<blobStorageAccountName>.blob.core.windows.net", 
    "/test", 
    Map("LinkedService" -> "myblobstorageaccount") 
)

Blob Storage コンテナーをマウントした後、ローカルファイル API でマウントパスを使ってファイルを読み取ります。

    # mount the Blob Storage container, and then read the file by using a mount path
    with open("/synfs/64/test/myFile.txt") as f:
    print(f.read())

Spark 読み取り API を使って、マウントされた Blob Storage コンテナーからデータを読み取ります。

%%spark
// mount blob storage container and then read file using mount path
val df = spark.read.text("synfs:/49/test/myFile.txt")
df.show()

マウントパスのマウントを解除する

マウントポイント (この例では /test) をマウント解除するには、次のコードを使います。

mssparkutils.fs.unmount("/test")

既知の制限事項

mssparkutils fs help 関数では、マウントとマウント解除の部分に関する説明がまだ追加されていません。
マウント解除メカニズムは自動ではありません。アプリケーションの実行が完了したときに、マウントポイントをマウント解除してディスク領域を解放するには、コードでマウント解除 API を明示的に呼び出す必要があります。そうしないと、マウントポイントは、アプリケーションの実行が完了した後もノードに存在します。
Data Lake Storage Gen1 ストレージアカウントのマウントは現在サポートされていません。

Azure Synapse Analytics でのファイルマウント API とファイルマウント解除 API の概要

ストレージをマウントする

リンクサービスを使ってマウントする (推奨)

Shared Access Signature トークンまたはアカウントキーを使ってマウントする

mssparkutils fs API を使ってマウントポイントの下にあるファイルにアクセスする

Spark 読み取り API を使ってマウントポイントの下にあるファイルにアクセスする

マウントされた Data Lake Storage Gen2 ストレージアカウントからファイルを読み取る

マウントされた Blob Storage アカウントからファイルを読み取る

マウントパスのマウントを解除する

既知の制限事項

次のステップ

その他のリソース

Azure Synapse Analytics でのファイル マウント API とファイル マウント解除 API の概要

ストレージをマウントする

リンク サービスを使ってマウントする (推奨)

Shared Access Signature トークンまたはアカウント キーを使ってマウントする

mssparkutils fs API を使ってマウント ポイントの下にあるファイルにアクセスする

Spark 読み取り API を使ってマウント ポイントの下にあるファイルにアクセスする

マウントされた Data Lake Storage Gen2 ストレージ アカウントからファイルを読み取る

マウントされた Blob Storage アカウントからファイルを読み取る

マウント パスのマウントを解除する

既知の制限事項

次のステップ

その他のリソース

Azure Synapse Analytics でのファイルマウント API とファイルマウント解除 API の概要

リンクサービスを使ってマウントする (推奨)

Shared Access Signature トークンまたはアカウントキーを使ってマウントする

mssparkutils fs API を使ってマウントポイントの下にあるファイルにアクセスする

Spark 読み取り API を使ってマウントポイントの下にあるファイルにアクセスする

マウントされた Data Lake Storage Gen2 ストレージアカウントからファイルを読み取る

マウントパスのマウントを解除する