Livy API を使用して、ユーザー資格情報を使用して Spark セッションジョブを送信および実行する

適用対象:✅ Fabric Data Engineering および Data Science

Fabric Livy API を使用すると、Fabric ポータルを利用せずに、Spark バッチジョブやセッションジョブをリモートクライアントから直接 Fabric の Spark コンピュートに送信できます。この記事では、Lakehouse を作成し、Microsoft Entra トークンで認証し、Livy API エンドポイントを検出し、Spark セッションジョブを送信して監視します。

前提条件

Fabric Premium または試用版の容量を Lakehouse とともに使用する
Livy API のテナント管理者設定を有効にする
Jupyter Notebook サポート、PySpark、Microsoft Authentication Library (MSAL) for Python を使用した Visual Studio Code などのリモートクライアント
Microsoft Entra アプリトークンのいずれか。 Microsoft ID プラットフォーム
または、Microsoft Entra SPN (サービスプリンシパル) トークン。 Microsoft Entra ID

REST API クライアントを選択する

curl などのツールや HTTP ライブラリを使用した任意の言語など、HTTP 要求をサポートする任意のクライアントから Livy API を操作できます。この記事の例では、Jupyter Notebooks、PySpark、および Python の Microsoft Authentication Library (MSAL) と共に Visual Studio Code を使用します。

Livy API 要求を承認する方法

Livy API を使用するには、Microsoft Entra IDを使用して要求を認証する必要があります。次の 2 つの承認方法を使用できます。

Entra SPN トークン (サービスプリンシパル):アプリケーションは、クライアントシークレットや証明書などの資格情報を使用して、それ自体として認証します。この方法は、ユーザーの操作が不要な自動化されたプロセスやバックグラウンドサービスに適しています。
Entra アプリトークン (委任): アプリケーションは、サインインしているユーザーの代わりに動作します。この方法は、認証されたユーザーのアクセス許可を持つリソースにアプリケーションがアクセスする場合に適しています。

シナリオに最も適した承認方法を選択し、以下の対応するセクションに従います。

Microsoft Entra SPN トークンを使用して Livy API 要求を承認する方法

Livy API を含むFabric API を操作するには、まずMicrosoft Entra アプリケーションを作成し、シークレットを作成し、コードでそのシークレットを使用する必要があります。 Fabricに対して API 呼び出しを実行するには、アプリケーションを登録して適切に構成する必要があります。詳細については、「 Microsoft Entra ID

アプリの登録を作成したら、クライアントシークレットを作成します。
クライアントシークレットを作成するときは、必ず値をコピーしてください。これはコードの後半で必要になりますが、シークレットを再度表示することはできません。コード内のシークレットに加えて、アプリケーション (クライアント) ID とディレクトリ (テナント ID) も必要です。
次に、サービスプリンシパルをワークスペースに追加します。
アプリケーション (クライアント) ID または名前を使用してMicrosoft Entra アプリケーションを検索し、ワークスペースに追加し、サービスプリンシパルに共同作成者アクセス許可があることを確認します。

Entra アプリトークンを使用して Livy API 要求を承認する方法

Livy API を含むFabric API を操作するには、まずMicrosoft Entra アプリケーションを作成し、トークンを取得する必要があります。 Fabricに対して API 呼び出しを実行するには、アプリケーションを登録して適切に構成する必要があります。詳細については、「 Microsoft ID プラットフォームを参照してください。

Livy API ジョブを実行するには、次の Microsoft Entra のスコープ権限が必要です。

Microsoft Entra 管理センターにおける Livy API のアクセス許可を示すスクリーンショット

必要なスコープ

Scope	説明
`Lakehouse.Execute.All`	Fabric lakehouses で操作を実行します。
`Lakehouse.Read.All`	lakehouse メタデータを読み取ります。
`Code.AccessFabric.All`	Microsoft Fabricへのアクセストークンの取得を許可します。すべての Livy API 操作に必要です。
`Code.AccessStorage.All`	OneLake と Azure ストレージへのアクセストークンの取得を許可します。レイクハウス内のデータの読み取りと書き込みに必要です。

オプションコード.* スコープ

これらのスコープは、Spark ジョブが実行時に対応するAzure サービスにアクセスする必要がある場合にのみ追加します。

Scope	説明	いつ使用するか
`Code.AccessAzureKeyvault.All`	Azure Key Vaultへのアクセストークンの取得を許可します。	Spark コードは、Azure Key Vaultからシークレット、キー、または証明書を取得します。
`Code.AccessAzureDataLake.All`	Azure Data Lake Storage Gen1へのアクセストークンの取得を許可します。	Spark コードは、Azure Data Lake Storage Gen1 アカウントから読み取りまたは書き込みを行います。
`Code.AccessAzureDataExplorer.All`	Azure Data Explorer (Kusto) へのアクセストークンの取得を許可します。	Spark コードは、Azure Data Explorer クラスターに対してクエリを実行したり、データを取り込んだりします。
`Code.AccessSQL.All`	Azure SQLへのアクセストークンの取得を許可します。	Spark コードは、Azure SQL データベースに接続する必要があります。

アプリケーションを登録するときは、アプリケーション (クライアント) ID とディレクトリ (テナント) ID の両方が必要です。

Microsoft Entra 管理センターにある Livy API アプリの概要を示すスクリーンショット

Livy API を呼び出す認証済みユーザーは、API とデータソース項目の両方が共同作成者ロールで配置されているワークスペースメンバーである必要があります。詳細については、「ワークスペースへのアクセス権をユーザーに付与する」を参照してください。

Livy API の Code.* スコープについて

Livy API を介して Spark ジョブを実行すると、 Code.* スコープによって、認証されたユーザーに代わって Spark ランタイムがアクセスできる外部サービスが制御されます。 2 つ必要です。残りは、ワークロードに応じてオプションです。

必要なコード.* スコープ

Scope	説明
`Code.AccessFabric.All`	Microsoft Fabricへのアクセストークンの取得を許可します。すべての Livy API 操作に必要です。
`Code.AccessStorage.All`	OneLake と Azure ストレージへのアクセストークンの取得を許可します。レイクハウス内のデータの読み取りと書き込みに必要です。

省略可能なコード.*スコープ

これらのスコープは、Spark ジョブが実行時に対応するAzure サービスにアクセスする必要がある場合にのみ追加します。

Scope	説明	いつ使用するか
`Code.AccessAzureKeyvault.All`	Azure Key Vaultへのアクセストークンの取得を許可します。	Spark コードは、Azure Key Vaultからシークレット、キー、または証明書を取得します。
`Code.AccessAzureDataLake.All`	Azure Data Lake Storage Gen1へのアクセストークンの取得を許可します。	Spark コードは、Azure Data Lake Storage Gen1 アカウントから読み取りまたは書き込みを行います。
`Code.AccessAzureDataExplorer.All`	Azure Data Explorer (Kusto) へのアクセストークンの取得を許可します。	Spark コードは、Azure Data Explorer クラスターに対してクエリを実行したり、データを取り込んだりします。
`Code.AccessSQL.All`	Azure SQLへのアクセストークンの取得を許可します。	Spark コードは、Azure SQL データベースに接続する必要があります。

注

Lakehouse.Execute.AllスコープとLakehouse.Read.All スコープも必要ですが、Code.* ファミリには含まれません。 Fabric Lakehouse 内での操作の実行およびメタデータの読み取りのために、それぞれの権限を付与します。

Fabric Livy API エンドポイントを検出する方法

Livy エンドポイントにアクセスするには、レイクハウスアーティファクトが必要です。レイクハウスが作成されると、Livy API エンドポイントを設定パネル内に配置できます。

Livy API のエンドポイントは、次のパターンに従います。

https://api.fabric.microsoft.com/v1/workspaces/><ws_id>/lakehouses/<lakehouse_id>/livyapi/versions/2023-12-01/

URL には、選択した内容に応じて、<sessions> または <batches> が追加されます。

Livy API Swagger ファイルをダウンロードする

Livy API の完全な swagger ファイルは、ここで入手できます。

同時実行性の高いセッション

高コンカレンシー (HC) のサポートにより、クライアントが複数の独立した実行コンテキスト ( 高コンカレンシーセッションと呼ばれる) を取得できるようにすることで、Spark の同時実行を同時に行うことができます。

各 HC セッションは、Spark REPL (読み取りEval-Print ループ) にマップされる論理実行コンテキストを表します。異なる HC セッションで送信された Spark ステートメントは、同時に実行できます。

これにより、次のことができます。

HC セッション間での並列実行
予測可能なリソース使用量
同時要求間の分離
要求ごとに新しいセッションを作成する場合と比べてオーバーヘッドが低い

すべての要求に対して 1 つのセッションを使用すると、ステートメントが順番に実行されます。各リクエストに対して新しいセッションを作成すると、不要なオーバーヘッドとリソースの非効率な活用をもたらします。

注

HC セッションの取得は冪等性ではありません。同じ sessionTag を持つ複数の取得要求は、同じ基になる Livy セッションによってサポートされている場合でも、異なる HC セッション ID を返します。

コード例を使用した詳細なチュートリアルについては、「Get started with the Livy API for Fabric High Concurrency Sessionsを参照してください。概念の概要については、Fabric Livy API での高度なコンカレンシーのサポートを参照してください。

Livy API ジョブを送信する

Livy API のセットアップが完了したら、バッチジョブまたはセッションジョブを送信できます。

"Fabric"環境との統合

既定では、この Livy API セッションはワークスペースの既定のスタータープールに対して実行されます。または、Fabric Environments Microsoft Fabric で環境を作成、構成、および使用して、Livy API セッションがこれらの Spark ジョブに使用する Spark プールをカスタマイズすることもできます。

Livy Spark セッションで Fabric 環境を使用するには、json を更新してこのペイロードを含めます。

create_livy_session = requests.post(livy_base_url, headers = headers, json={
    "conf" : {
        "spark.fabric.environmentDetails" : "{\"id\" : \""EnvironmentID""}"}
    }
)

Livy Spark バッチセッションで Fabric 環境を使用するには、次に示すように json ペイロードを更新します。

payload_data = {
"name":"livybatchdemo_with"+ newlakehouseName,
"file":"abfss://YourABFSPathToYourPayload.py", 
"conf": {
    "spark.targetLakehouse": "Fabric_LakehouseID",
    "spark.fabric.environmentDetails" : "{\"id\" : \""EnvironmentID"\"}"  # Replace "EnvironmentID" with your environment ID, or remove this line to use starter pools instead of an environment
    }
}

要求履歴を監視する方法

監視ハブを使用して以前の Livy API の送信を確認し、送信エラーをデバッグできます。

Apache Livy REST API ドキュメント
Fabric 容量の管理者設定を開始する
Microsoft Fabric における Apache Spark ワークスペースの管理設定
Microsoft ID プラットフォーム
Microsoft Entraアクセス許可と同意の概要
Fabric REST API スコープ
Apache Spark の監視の概要
Apache Spark アプリケーションの詳細

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-04-10