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.

Kimlik bilgileri yardımcı programları Python, PySpark, Scala ve R not defterlerinde kullanılabilir. Bu sayfadaki örneklerde python birincil dil olarak kullanılır ve genel API'nin bunları desteklediği Scala ve R eşdeğerleri gösterilir.

Ö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 değerlerin maskelemesi – Notebook çıktıları, yanlışlıkla açığa çıkmayı önlemek için gizli değerleri otomatik olarak maskeler.
  • 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()

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 genel Scala API'sinde kullanılamaz.
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')

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 – Lakehouse öğelerine okuma ve yazma erişimi
    • MLExperiment.ReadWrite.All – Machine Learning Denemesi öğelerine okuma ve yazma erişimi
    • MLModel.ReadWrite.All – Machine Learning Modeli öğelerine okuma ve yazma erişimi
    • Notebook.ReadWrite.All – Not defteri öğelerine okuma ve yazma erişimi
    • SparkJobDefinition.ReadWrite.All – Spark İş Tanımı öğelerine okuma ve yazma erişimi
    • Workspace.ReadWrite.All – Çalışma alanı öğelerine okuma ve yazma erişimi
    • Dataset.ReadWrite.All – Veri kümesi öğ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')

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

Uyarı

Dizüstü bilgisayar çıktıları, güvenlik için gizli değerleri otomatik olarak sansürler. Alınan bir sır yazdırılırsa veya görüntülenirse, çıktıda gerçek değer yerine gizlenmiş bir yer tutucu gösterilir.

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 günlüğe kaydetmeyin. Not defteri çıktılarında otomatik gizlilik gizlemeyi kullanın. Dosyalara gizli dizi yazmaktan veya bunları not defteri parametresi olarak geçirmekten kaçının.
  • 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

putSecret belirtilen Azure Key Vault'ta bir gizli depolar. Gizli anahtar zaten varsa, değer güncellenir.

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

Azure Key Vault'ta gizlileri yazmak için uygun izin ayarlarına sahip olmanız gerekir.

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

İlgili içerik

  • Last updated on