Utilitas kredensial NotebookUtils untuk Fabric

Anda dapat menggunakan utilitas kredensial untuk mendapatkan token akses dan mengelola rahasia di Azure Key Vault. Modul ini notebookutils.credentials terintegrasi dengan MICROSOFT Entra ID untuk akuisisi token dan Azure Key Vault untuk manajemen rahasia, sehingga Anda dapat terhubung ke sumber daya Azure dengan aman tanpa mengekspos kredensial dalam kode.

Utilitas kredensial tersedia di notebook Python, PySpark, Scala, dan R. Contoh di halaman ini menggunakan Python sebagai bahasa utama, dengan setara Scala dan R yang ditunjukkan di mana API publik mendukungnya.

Penting

Jangan pernah mengodekan rahasia atau kredensial secara langsung dalam kode buku catatan. Selalu gunakan Azure Key Vault untuk menyimpan nilai sensitif dan mengambilnya saat runtime dengan notebookutils.credentials.getSecret.

Batasan dan keamanan

Sebelum Anda menggunakan utilitas kredensial, waspadai batasan ini:

  • Kedaluwarsa token – Token kedaluwarsa setelah periode. Untuk operasi jangka panjang, terapkan logika refresh untuk meminta token baru sebelum kedaluwarsa.
  • Batasan cakupan prinsip layanan – Saat berjalan di bawah prinsip layanan, token untuk pbi audiens memiliki cakupan yang terbatas dibandingkan dengan identitas pengguna.
  • MSAL untuk cakupan penuh – Jika Anda memerlukan cakupan layanan Fabric lengkap di bawah perwakilan layanan, gunakan autentikasi MSAL alih-alih getToken.
  • Redaksi rahasia – Keluaran notebook secara otomatis meredaksi nilai rahasia untuk mencegah terekspos secara tidak sengaja.
  • Izin Key Vault – Anda harus memiliki izin yang sesuai (Dapatkan untuk membaca, Mengatur untuk menulis) di Azure Key Vault untuk mengakses atau menyimpan rahasia.
  • Perubahan audiens – Cakupan audiens token mungkin berkembang dari waktu ke waktu. Verifikasi cakupan saat ini dalam dokumentasi.

Jalankan perintah berikut untuk mendapatkan gambaran umum tentang metode yang tersedia:

notebookutils.credentials.help()

Tabel berikut ini mencantumkan metode kredensial yang tersedia:

Metode Signature Deskripsi
getToken getToken(audience: String): String Mengembalikan token Microsoft Entra untuk audiens yang ditentukan.
getSecret getSecret(akvName: String, secret: String): String Mengembalikan nilai rahasia dari Azure Key Vault yang ditentukan.
putSecret putSecret(akvName: String, secretName: String, secretValue: String): String Menyimpan rahasia di Azure Key Vault yang ditentukan. Metode ini tidak tersedia di API Scala publik.
isValidToken isValidToken(token: String): Boolean Memeriksa apakah token yang diberikan valid dan tidak kedaluwarsa. Metode ini tidak tersedia di API Scala publik.

Dapatkan token

getToken mengembalikan token Microsoft Entra untuk audiens tertentu. Tabel berikut ini memperlihatkan kunci audiens yang saat ini tersedia:

Kunci audiens Sumber Daya Skenario penggunaan
storage Azure Storage Mengakses ADLS Gen2 dan Blob Storage
pbi Power BI Memanggil REST API Power BI dan Fabric
keyvault Azure Key Vault Mengambil informasi rahasia dari Key Vault
kusto Synapse RTA KQL DB Menyambungkan ke Azure Data Explorer

Jalankan perintah berikut untuk mendapatkan token:

notebookutils.credentials.getToken('audience Key')

Contoh penggunaan token

Anda dapat menggunakan token yang dikembalikan untuk mengautentikasi terhadap berbagai layanan Azure.

Azure Storage

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

API REST Power BI dan Fabric

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')

Menggunakan token dengan Azure SDK

Notebook Fabric tidak mendukung DefaultAzureCredential secara langsung. Anda dapat menggunakan kelas kredensial kustom sebagai solusi untuk meneruskan token NotebookUtils ke klien 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}")

Tip

Token kedaluwarsa setelah jangka waktu tertentu. Jika komputer jinjing Anda menjalankan operasi yang panjang, terapkan logika penyegaran untuk meminta token baru sebelum yang saat ini kedaluwarsa.

Pertimbangan

  • Cakupan token dengan pbi sebagai audiens mungkin berubah dari waktu ke waktu.

  • Saat Anda memanggil notebookutils.credentials.getToken("pbi"), token yang dikembalikan memiliki cakupan terbatas jika notebook berjalan di bawah prinsipal layanan. Token tidak memiliki cakupan layanan Fabric lengkap. Jika notebook berjalan di bawah identitas pengguna, token masih memiliki cakupan layanan Fabric lengkap, tetapi ini mungkin berubah dengan peningkatan keamanan. Untuk memastikan bahwa token memiliki cakupan layanan Fabric lengkap, gunakan autentikasi MSAL alih-alih notebookutils.credentials.getToken API. Untuk informasi selengkapnya, lihat Mengautentikasi dengan MICROSOFT Entra ID.

  • Cakupan berikut tersedia saat Anda memanggil notebookutils.credentials.getToken dengan kunci audiens pbi dari entitas utama layanan:

    • Lakehouse.ReadWrite.All – Akses baca dan tulis ke item lakehouse
    • MLExperiment.ReadWrite.All – Akses membaca dan menulis ke item eksperimen
    • MLModel.ReadWrite.All – Akses baca dan tulis ke item model ML
    • Notebook.ReadWrite.All – Akses membaca dan menulis ke item buku catatan
    • SparkJobDefinition.ReadWrite.All – Akses baca dan tulis ke item definisi pekerjaan Spark
    • Workspace.ReadWrite.All – Akses baca dan tulis ke ruang kerja
    • Dataset.ReadWrite.All – Akses baca dan tulis ke item model semantik

Tip

Jika Anda memerlukan akses ke layanan Fabric tambahan atau izin yang lebih luas di bawah perwakilan layanan, gunakan MSAL untuk Python untuk mengautentikasi langsung dengan cakupan layanan Fabric lengkap alih-alih mengandalkan getToken("pbi").

Dapatkan rahasia

getSecret mengembalikan sekret Azure Key Vault untuk nama sekret dan titik akhir Azure Key Vault tertentu. Panggilan menggunakan kredensial pengguna Anda saat ini untuk mengautentikasi terhadap Key Vault.

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

Anda dapat mengambil beberapa rahasia untuk membangun string koneksi atau mengonfigurasi layanan:

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}"

Nota

Output dari notebook secara otomatis menyamarkan nilai-nilai rahasia demi keamanan. Jika Anda mencetak atau menampilkan rahasia yang diambil, output menunjukkan tempat penampung yang diredaksi alih-alih nilai aktual.

Gunakan URL Key Vault yang sepenuhnya memenuhi syarat dalam format https://<vault-name>.vault.azure.net/. Anda harus memiliki izin yang sesuai untuk mengakses Key Vault dan rahasia individual.

Praktik terbaik keamanan

Ikuti rekomendasi ini saat Anda bekerja dengan kredensial di notebook Fabric:

  • Simpan semua nilai sensitif di Azure Key Vault. Jangan pernah menyematkan kredensial, string koneksi, atau kunci API langsung dalam kode notebook.
  • Jangan mencatat nilai rahasia. Mengandalkan redaksi rahasia otomatis dalam output notebook. Hindari menulis rahasia ke file atau meneruskannya sebagai parameter notebook.
  • Gunakan kunci audiens yang benar. Cocokkan kunci audiens dengan sumber daya Azure target sehingga token hanya memiliki izin yang dibutuhkan.
  • Pahami konteks identitas. Ketahui apakah notebook Anda berjalan dengan identitas pengguna atau perwakilan layanan, karena cakupan token yang tersedia dapat berbeda. Uji autentikasi dalam konteks interaktif dan pipeline.
  • Menangani kedaluwarsa token. Token kedaluwarsa. Untuk operasi jangka panjang, terapkan logika refresh untuk meminta token baru sebelum yang saat ini kedaluwarsa.
  • Batasi akses Key Vault. Hanya berikan izin minimum yang diperlukan ke Key Vault Anda. Mengaudit akses rahasia melalui log diagnostik Azure Key Vault.
  • Gunakan identitas terkelola jika memungkinkan. Identitas terkelola mengurangi kebutuhan untuk mengelola kredensial secara manual dan menyediakan alur autentikasi yang lebih aman.

Tetapkan sebagai rahasia

putSecret menyimpan rahasia di Azure Key Vault yang telah ditentukan. Jika rahasia sudah ada, nilai diperbarui.

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

Anda harus memiliki izin yang sesuai (Atur izin) di Azure Key Vault untuk menulis rahasia.

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

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

Validasikan token

Gunakan isValidToken untuk memeriksa apakah token valid dan tidak kedaluwarsa sebelum Anda memanggil API dengannya.

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')

Konten terkait

  • Last updated on