NotebookUtils kimlik bilgileri yardımcı programları, Fabric için

Azure Key Vault'ta erişim belirteçleri almak ve gizli dizileri yönetmek için kimlik bilgileri yardımcı programlarını kullanabilirsiniz. Modül, notebookutils.credentials belirteç alımı için Microsoft Entra Id ve gizli dizi yönetimi için Azure Key Vault ile tümleştirilerek kimlik bilgilerini kodda göstermeden Azure kaynaklarına güvenli bir şekilde bağlanabilirsiniz.

Python not defterleri ve Fabric Spark defterlerindeki kimlik bilgileri araçlarını kullanabilirsiniz. Fabric Spark dizüstü bilgisayarlarında PySpark, Scala veya R kullanabilirsiniz. Yöntem kullanılabilirliği, notebook çalışma zamanına ve API'ye göre farklılık gösterir. Örneğin, putSecret sadece Python çalışma zamanını kullanan Python defterlerinde çalışır. Spark defterleri bunu desteklemiyor, Python kodu PySpark ile çalıştırsalar bile. Scala veya R kullanan Spark dizüstü bilgisayarları da bunu desteklemiyor.

Aşağıdaki örneklerde ana dil olarak Python kullanılmaktadır. Scala ve R eşdeğerleri, not defteri çalışma zamanı ve herkese açık API bu yöntemi desteklediğinde yer alır.

Önemli

Gizli dizileri veya kimlik bilgilerini hiçbir zaman doğrudan not defteri kodunda sabit kodlamayın. Hassas değerleri depolamak ve çalışma zamanında notebookutils.credentials.getSecret ile almak için her zaman Azure Key Vault'u kullanın.

Kısıtlamalar ve güvenlik

Kimlik bilgileri yardımcı programlarını kullanmadan önce şu kısıtlamalara dikkat edin:

Belirteç süre sonu – Belirteçlerin süresi bir süre sonra dolar. Uzun süre çalışan işlemler için yenileme mantığını uygulayarak süre dolmadan önce yeni bir belirteç isteyin.
Hizmet sorumlusu kapsam sınırlamaları – Hizmet sorumlusu altında çalışırken, hedef kitleye pbi yönelik belirteçler kullanıcı kimliğiyle karşılaştırıldığında kapsamları kısıtlar.
Tam kapsam için MSAL – Hizmet sorumlusu altında tam Fabric hizmet kapsamına ihtiyacınız varsa, getToken yerine MSAL kimlik doğrulamasını kullanın.
Gizli redaksiyon – Defter çıktısı, kod doğrudan yazdırıldığında veya görüntülendiğinde orijinal gizli değeri sansürlemeye çalışır. Bu en iyi önlemler, ekran paylaşımı sırasında da dahil olmak üzere kazara yapılan açıklamaları azaltır. Bu bir güvenlik sınırı değil. Alındıktan sonra, yetkili not defteri kodu düz metni alır ve sırrı veya sırdan türetilen içeriği işleyebilir, dönüştürebilir ya da ifşa edebilir.
Key Vault izinleri – Gizli dizilere erişmek veya bunları depolamak için Azure Key Vault'ta uygun izinlere (Okuma için al, Yazma için ayarla) sahip olmanız gerekir.
hedef kitle değişiklikleri – Belirteç hedef kitlesi kapsamları zaman içinde gelişebilir. Belgelerde geçerli kapsamları doğrulayın.

Kullanılabilir yöntemlere genel bir bakış elde etmek için aşağıdaki komutu çalıştırın:

notebookutils.credentials.help()

notebookutils.credentials.help()

notebookutils.credentials.help()

Aşağıdaki tabloda kullanılabilir kimlik bilgileri yöntemleri listelemektedir:

Yöntem	Signature	Açıklama
`getToken`	`getToken(audience: String): String`	Belirtilen hedef kitle için bir Microsoft Entra jetonu döndürür.
`getSecret`	`getSecret(akvName: String, secret: String): String`	Belirtilen Azure Key Vault'tan bir gizli anahtar değerini getirir.
`putSecret`	`putSecret(akvName: String, secretName: String, secretValue: String): String`	Belirtilen Azure Key Vault'ta bir gizli bilgi depolar. Bu yöntem yalnızca Python çalışma zamanını kullanan dizüstü bilgisayarlarda çalışır. Spark defterleri bunu desteklemiyor, Python kodu PySpark ile çalıştırsalar bile. Scala veya R kullanan Spark defterleri de bunu desteklemiyor.
`isValidToken`	`isValidToken(token: String): Boolean`	Verilen belirtecin geçerli olup olmadığını ve süresinin dolmadığını denetler. Bu yöntem genel Scala API'sinde kullanılamaz.

Jeton almak

getToken belirli bir hedef kitle için bir Microsoft Entra belirteci döndürür. Aşağıdaki tabloda şu anda kullanılabilir olan hedef kitle anahtarları gösterilmektedir:

hedef kitle anahtarı	Kaynak	Kullanım örneği
`storage`	Azure Depolama	ADLS 2. Nesil ve Blob Depolama'ya erişme
`pbi`	Power BI	Power BI ve Fabric REST API'lerini çağırma
`keyvault`	Azure Key Vault	Key Vault sırlarını alma
`kusto`	Synapse RTA KQL Veritabanı	Azure Veri Gezgini'ne bağlanma

Belirteci almak için aşağıdaki komutu çalıştırın:

notebookutils.credentials.getToken('audience Key')

notebookutils.credentials.getToken("audience Key")

notebookutils.credentials.getToken("audience Key")

Token kullanım örnekleri

Döndürülen belirteci kullanarak çeşitli Azure hizmetlerinde kimlik doğrulaması yapabilirsiniz.

Azure Depolama

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

Power BI ve Fabric REST API'leri

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 Veri Gezgini (Kusto)

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

Azure Key Vault

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

Azure SDK ile belirteçleri kullanma

Doku not defterleri doğrudan desteklemez DefaultAzureCredential . NotebookUtils belirteçlerini Azure SDK istemcilerine geçirmek için geçici bir çözüm olarak özel bir kimlik bilgisi sınıfı kullanabilirsiniz.

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

Tavsiye

Jetonlar belirli bir süre sonra otomatik olarak süresini doldurur. Not defteriniz uzun işlemler çalıştırıyorsa, geçerli belirtecin süresi dolmadan önce yeni bir belirteç istemek için yenileme mantığını uygulayın.

Değerlendirmeler

pbi dinleyici kitlesi olarak belirtilmiş belirteç kapsamları zamanla değişebilir.
çağırdığınızda notebookutils.credentials.getToken("pbi"), not defteri bir hizmet sorumlusu altında çalışıyorsa döndürülen belirtecin kapsamı sınırlıdır. Belirteç tam Fabric hizmeti kapsamına sahip değil. Not defteri kullanıcı kimliği altında çalışıyorsa, belirteç hala tam Fabric hizmeti kapsamına sahiptir, ancak bu durum güvenlik iyileştirmeleriyle değişebilir. Belirtecin tam Fabric hizmeti kapsamına sahip olduğundan emin olmak için notebookutils.credentials.getToken API yerine MSAL kimlik doğrulamasını kullanın. Daha fazla bilgi için bkz. Microsoft Entra Id ile kimlik doğrulaması yapma.
Hizmet sorumlusu kimliği altında hedef kitle anahtarıyla notebookutils.credentials.getToken arama pbi yaptığınızda aşağıdaki kapsamlar kullanılabilir:
- Lakehouse.ReadWrite.All – Göl evi eşyalarına okuma ve yazma erişimi
- MLExperiment.ReadWrite.All – Deney öğelerine okuma ve yazma erişimi
- MLModel.ReadWrite.All – ML model öğelerine okuma ve yazma erişimi
- Notebook.ReadWrite.All – Defter öğelerine okuma ve yazma erişimi
- SparkJobDefinition.ReadWrite.All – Spark iş tanımı öğelerine okuma ve yazma erişimi
- Workspace.ReadWrite.All – Çalışma alanlarına okuma ve yazma erişimi
- Dataset.ReadWrite.All – Anlamsal model öğelerine okuma ve yazma erişimi

Tavsiye

Hizmet sorumlusu altında ek Doku hizmetlerine veya daha geniş izinlere erişmeniz gerekiyorsa, Python için MSAL kullanarak getToken("pbi") yerine doğrudan tam Doku hizmet kapsamıyla kimlik doğrulaması yapın.

Gizli al

getSecret belirli bir Azure Key Vault uç noktası ve sır adı için bir Azure Key Vault sırrı döndürür. Çağrı, Key Vault'ta kimlik doğrulaması yapmak için geçerli kullanıcı kimlik bilgilerinizi kullanır.

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

Bağlantı dizeleri oluşturmak veya hizmetleri yapılandırmak için birden fazla gizli anahtar elde edebilirsiniz.

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

Önemli

Başarıyla alındıktan sonra, yetkili not defteri kodu gizli değeri düz metin olarak alır. Not defteri çıktısı, kod bunu doğrudan yazdırdığında veya görüntülediğinde özgün gizli değeri gizlemeye çalışır.

Bu koruma önlemi, ekran paylaşımı sırasında bile not defteri çıktısındaki bilgilerin yanlışlıkla ifşa edilmesini azaltır. Bu bir güvenlik sınırı değildir ve gizli içeriklerin işlemesini, dönüştürülmesini veya açıklanmasını engellemez.

https://<vault-name>.vault.azure.net/ biçiminde tam nitelikli Key Vault URL'sini kullanın. Key Vault'a ve sırlar'a erişmek için uygun izinlere sahip olmanız gerekir.

En iyi güvenlik uygulamaları

Fabric defterlerinde kimlik bilgileriyle çalışırken aşağıdaki önerilere uymanız önemlidir:

Tüm hassas değerleri Azure Key Vault'ta depolayın. Kimlik bilgilerini, bağlantı dizelerini veya API anahtarlarını hiçbir zaman doğrudan not defteri koduna eklemeyin.
Gizli değerleri ifşa etmeyin. Sırları yazdırmayın veya kaydetmeyin, dosyalara yazmayın ya da defter parametreleri olarak aktarmayın. Çıktı sansürleme, doğrudan not defteri çıktısındaki orijinal değeri korumaya çalışır. Gizli kaynaklı içeriklerin açıklanmasını engellemez.
Doğru hedef kitle anahtarını kullanın. Hedef kitle anahtarını hedef Azure kaynağıyla eşleştirerek belirtecin yalnızca ihtiyaç duyduğu izinlere sahip olmasını sağlayın.
Kimlik bağlamını anlama. Kullanılabilir belirteç kapsamları farklılık gösterebileceğinden not defterinizin, kullanıcı kimliği altında mı yoksa hizmet ilkesiyle mi çalıştığını bilin. Kimlik doğrulamayı hem etkileşimli hem de işlem hattı bağlamında test edin.
Belirteç süre sonunu işleme. Jetonların süresi dolar. Uzun süre çalışan işlemler için yenileme mantığını uygulayarak geçerli belirtecin süresi dolmadan önce yeni bir belirteç isteyin.
Key Vault erişimini sınırlayın. Key Vault'unuza yalnızca gerekli en düşük izinleri verin. Azure Key Vault tanılama günlükleri aracılığıyla gizli bilgi erişimini denetle.
Mümkün olduğunda yönetilen kimlikleri kullanın. Yönetilen kimlikler, kimlik bilgilerini el ile yönetme gereksinimini azaltır ve daha güvenli bir kimlik doğrulama akışı sağlar.

Gizli koy

putSecretbelirtilen Azure Key Vault'ta bir sırrı saklar veya günceller. Sadece Python çalışma zamanını kullanan defterlerde çalışıyor.

Önemli

Spark notebookları, PySpark ile Python kodu çalıştırsalar bile , desteklemezputSecret. Scala veya R kullanan Spark defterleri de bunu desteklemiyor. Python çalışma zamanını kullanan bir Python notebook kullanın.

# Run only in a notebook that uses the Python runtime.
notebookutils.credentials.putSecret(
    'https://<name>.vault.azure.net/',
    'secret name',
    'secret value'
)

Sır yazmak için Azure Key Vault'ta uygun izinlere (Set permission) ihtiyacınız var. Aşağıdaki örneği yalnızca Python çalışma zamanını kullanan bir notebook'ta çalıştırın. Bir Fabric Spark defterinde çalıştırmayın.

# Python runtime only. Fabric Spark notebooks don't support putSecret.
vault_url = "https://myvault.vault.azure.net/"

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

Belirteci doğrula

Bir API'yi çağırmadan önce belirtecin geçerli olup olmadığını ve süresinin dolmadığını denetlemek için kullanın isValidToken .

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 için NotebookUtils (eski MSSparkUtils)

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Son güncelleştirme: 2026-09-23

NotebookUtils kimlik bilgileri yardımcı programları, Fabric için

Kısıtlamalar ve güvenlik

Jeton almak

Token kullanım örnekleri

Azure Depolama

Power BI ve Fabric REST API'leri

Azure Veri Gezgini (Kusto)

Azure Key Vault

Azure SDK ile belirteçleri kullanma

Değerlendirmeler

Gizli al

En iyi güvenlik uygulamaları

Gizli koy

Belirteci doğrula

İlgili içerik

Geri Bildirim

Ek kaynaklar