Fabric 用 NotebookUtils 資格情報ユーティリティ

資格情報ユーティリティを使用して、アクセストークンを取得し、Azure Key Vault のシークレットを管理できます。 notebookutils.credentials モジュールは、トークン取得用の Microsoft Entra ID とシークレット管理用の Azure Key Vault と統合されているため、コードで資格情報を公開することなく、Azure リソースに安全に接続できます。

資格情報ユーティリティは、Python、PySpark、Scala、および R ノートブックで使用できます。このページの例では、Python をプライマリ言語として使用し、Scala と R に相当するものをパブリック API でサポートする場所を示します。

Important

ノートブックコードでシークレットや資格情報を直接ハードコーディングしないでください。常に Azure Key Vault を使用して機密性の高い値を格納し、実行時に notebookutils.credentials.getSecretで取得します。

制約と安全性

資格情報ユーティリティを使用する前に、次の制約に注意してください。

トークンの有効期限 – トークンは一定期間後に期限切れになります。実行時間の長い操作の場合は、有効期限が切れる前に新しいトークンを要求する更新ロジックを実装します。
サービスプリンシパルスコープの制限 – サービスプリンシパルで実行する場合、 pbi 対象ユーザーのトークンのスコープは、ユーザー ID と比較して制限されます。
完全なスコープの MSAL – サービスプリンシパルの下に完全なファブリックサービススコープが必要な場合は、 getTokenの代わりに MSAL 認証を使用します。
シークレットの編集 – ノートブックの出力は、誤って公開されないようにシークレット値を自動的に編集します。
Key Vault のアクセス許可 – シークレットにアクセスまたは格納するには、Azure Key Vault に対する適切なアクセス許可 (読み取り用に取得、書き込み用に設定) が必要です。
対象ユーザーの変更 – トークン対象ユーザーのスコープは、時間の経過と同時に進化する可能性があります。ドキュメントで現在のスコープを確認します。

次のコマンドを実行して、使用可能なメソッドの概要を取得します。

notebookutils.credentials.help()

notebookutils.credentials.help()

notebookutils.credentials.help()

次の表に、使用可能な資格情報の方法を示します。

メソッド	署名	説明
`getToken`	`getToken(audience: String): String`	指定した対象ユーザーの Microsoft Entra トークンを返します。
`getSecret`	`getSecret(akvName: String, secret: String): String`	指定した Azure Key Vault からシークレットの値を返します。
`putSecret`	`putSecret(akvName: String, secretName: String, secretValue: String): String`	指定した Azure Key Vault にシークレットを格納します。このメソッドは、パブリック Scala API では使用できません。
`isValidToken`	`isValidToken(token: String): Boolean`	指定されたトークンが有効であり、有効期限が切れていないかどうかを確認します。このメソッドは、パブリック Scala API では使用できません。

トークンを取得する

getToken は、特定の対象ユーザーの Microsoft Entra トークンを返します。次の表に、現在使用可能な対象ユーザーキーを示します。

対象ユーザーキー	資源	利用シーン
`storage`	Azure Storage	ADLS Gen2 と Blob Storage にアクセスする
`pbi`	Power BI	Power BI と Fabric REST API の呼び出し
`keyvault`	Azure Key Vault	Key Vault シークレットを取得する
`kusto`	Synapse RTA KQL DB	Azure データエクスプローラーに接続する

トークンを取得するには、以下のコマンドを実行します。

notebookutils.credentials.getToken('audience Key')

notebookutils.credentials.getToken("audience Key")

notebookutils.credentials.getToken("audience Key")

トークン使用例

返されたトークンを使用して、さまざまな Azure サービスに対する認証を行うことができます。

Azure Storage

storage_token = notebookutils.credentials.getToken('storage')

Power BI と Fabric REST API

import requests

pbi_token = notebookutils.credentials.getToken('pbi')

headers = {
    'Authorization': f'Bearer {pbi_token}',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.powerbi.com/v1.0/myorg/datasets',
    headers=headers
)

if response.status_code == 200:
    datasets = response.json()
    print(f"Found {len(datasets['value'])} datasets")

Azure Data Explorer (Kusto)

kusto_token = notebookutils.credentials.getToken('kusto')

Azure Key Vault

keyvault_token = notebookutils.credentials.getToken('keyvault')

Azure SDK でトークンを使用する

Fabric ノートブックでは、 DefaultAzureCredential を直接サポートしていません。 NotebookUtils トークンを Azure SDK クライアントに渡す回避策として、カスタム資格情報クラスを使用できます。

from azure.core.credentials import AccessToken, TokenCredential
import jwt

class NotebookUtilsCredential(TokenCredential):
    """Custom credential that uses notebookutils tokens for Azure SDK."""

    def __init__(self, audience="storage"):
        self.audience = audience

    def get_token(self, *scopes, claims=None, tenant_id=None, **kwargs):
        token = notebookutils.credentials.getToken(self.audience)

        # Decode token to get expiration time
        token_json = jwt.decode(
            token, algorithms="RS256",
            options={"verify_signature": False}
        )

        return AccessToken(token, int(token_json.get("exp", 0)))

# Example: use with Azure Blob Storage
from azure.storage.blob import BlobServiceClient

account_url = "https://mystorageaccount.blob.core.windows.net"
credential = NotebookUtilsCredential(audience="storage")
blob_client = BlobServiceClient(account_url=account_url, credential=credential)

for container in blob_client.list_containers():
    print(f"Container: {container.name}")

ヒント

トークンは一定期間後に期限切れになります。ノートブックで長時間の操作を実行する場合は、更新ロジックを実装して、現在のトークンの有効期限が切れる前に新しいトークンを要求します。

考慮事項

対象ユーザーが時間の経過と共に変化する可能性があるため、 pbi を持つトークンスコープ。
notebookutils.credentials.getToken("pbi")を呼び出すと、ノートブックがサービスプリンシパルで実行されている場合、返されるトークンのスコープは制限されます。トークンには、完全な Fabric サービススコープがありません。ノートブックがユーザー ID で実行されている場合、トークンには完全な Fabric サービススコープが引き続き含まれますが、セキュリティが強化されると変更される可能性があります。トークンが完全な Fabric サービススコープを持っていることを確認するには、 notebookutils.credentials.getToken API の代わりに MSAL 認証を使用します。詳細については、「 Microsoft Entra ID を使用した認証」を参照してください。
サービスプリンシパル ID で対象ユーザーキーnotebookutils.credentials.getTokenを使用してpbiを呼び出すと、次のスコープを使用できます。
- Lakehouse.ReadWrite.All – Lakehouse アイテムへの読み取りと書き込みアクセス
- MLExperiment.ReadWrite.All – Machine Learning 実験項目への読み取りと書き込みアクセス
- MLModel.ReadWrite.All – Machine Learning モデル項目への読み取りと書き込みアクセス
- Notebook.ReadWrite.All ノートブックアイテムへの読み取りと書き込みアクセス
- SparkJobDefinition.ReadWrite.All – Spark ジョブ定義項目への読み取りと書き込みアクセス
- Workspace.ReadWrite.All – ワークスペースアイテムへの読み取りと書き込みアクセス
- Dataset.ReadWrite.All – データセットアイテムへの読み取りと書き込みアクセス

ヒント

サービスプリンシパルの下で追加の Fabric サービスまたはより広範なアクセス許可にアクセスする必要がある場合は、 msAL for Python を使用して、 getToken("pbi")に依存するのではなく、完全な Fabric サービススコープで直接認証します。

シークレットを取得する

getSecret は、特定の Azure Key Vault エンドポイントとシークレット名の Azure Key Vault シークレットを返します。この呼び出しでは、現在のユーザー資格情報を使用して Key Vault に対する認証が行われます。

notebookutils.credentials.getSecret('https://<name>.vault.azure.net/', 'secret name')

notebookutils.credentials.getSecret("https://<name>.vault.azure.net/", "secret name")

notebookutils.credentials.getSecret("https://<name>.vault.azure.net/", "secret name")

複数のシークレットを取得して接続文字列を構築したり、サービスを構成したりできます。

vault_url = "https://myvault.vault.azure.net/"

db_host = notebookutils.credentials.getSecret(vault_url, "db-host")
db_user = notebookutils.credentials.getSecret(vault_url, "db-user")
db_password = notebookutils.credentials.getSecret(vault_url, "db-password")

connection_string = f"Server={db_host};User={db_user};Password={db_password}"

注

ノートブックの出力では、セキュリティのためにシークレット値が自動的に編集されます。取得したシークレットを印刷または表示すると、出力には実際の値ではなく、編集されたプレースホルダーが表示されます。

完全修飾された Key Vault URL を https://<vault-name>.vault.azure.net/ 形式で使用します。 Key Vault と個々のシークレットにアクセスするための適切なアクセス許可が必要です。

セキュリティのベストプラクティス

Fabric ノートブックで資格情報を使用する場合は、次の推奨事項に従います。

すべての機密値を Azure Key Vault に格納します。 資格情報、接続文字列、または API キーをノートブックコードに直接埋め込むことはありません。
シークレット値をログに記録しないでください。 ノートブック出力の自動シークレットの編集に依存します。シークレットをファイルに書き込んだり、ノートブックパラメーターとして渡したりしないでください。
適切な対象ユーザーキーを使用します。 対象の Azure リソースに対象ユーザーキーを一致させるので、トークンには必要なアクセス許可のみが付与されます。
ID コンテキストについて理解します。 使用可能なトークンスコープが異なる可能性があるため、ノートブックがユーザー ID またはサービスプリンシパルのどちらで実行されるかを把握します。対話型コンテキストとパイプラインコンテキストの両方で認証をテストします。
トークンの有効期限を処理します。 トークンの有効期限が切れます。実行時間の長い操作の場合は、更新ロジックを実装して、現在のトークンの有効期限が切れる前に新しいトークンを要求します。
Key Vault のアクセスを制限します。 Key Vault に最低限必要なアクセス許可のみを付与します。 Azure Key Vault 診断ログを使用してシークレットアクセスを監査します。
可能な場合はマネージド ID を使用します。 マネージド ID を使用すると、資格情報を手動で管理する必要が減り、より安全な認証フローが提供されます。

シークレットを配置する

putSecret は、指定した Azure Key Vault にシークレットを格納します。シークレットが既に存在する場合は、値が更新されます。

notebookutils.credentials.putSecret('https://<name>.vault.azure.net/', 'secret name', 'secret value')

notebookutils.credentials.putSecret("https://<name>.vault.azure.net/", "secret name", "secret value")

シークレットを書き込むには、Azure Key Vault に対する適切なアクセス許可 (アクセス許可の設定) が必要です。

vault_url = "https://myvault.vault.azure.net/"

notebookutils.credentials.putSecret(vault_url, "api-key", "my-secret-api-key-value")

トークンの検証

isValidTokenを使用して、API を呼び出す前にトークンが有効で有効期限が切れていないかどうかを確認します。

token = notebookutils.credentials.getToken('storage')
is_valid = notebookutils.credentials.isValidToken(token)

if is_valid:
    print("Token is valid")
else:
    print("Token is expired or invalid, requesting a new one")
    token = notebookutils.credentials.getToken('storage')

token <- notebookutils.credentials.getToken("storage")
is_valid <- notebookutils.credentials.isValidToken(token)

if (is_valid) print("Token is valid") else print("Token is expired or invalid")

Fabric用のNotebookUtils（旧MSSparkUtils）

フィードバック

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

Last updated on 2026-04-02