Βοηθητικά προγράμματα διαπιστευτηρίων NotebookUtils για το Fabric

Μπορείτε να χρησιμοποιήσετε τα βοηθητικά προγράμματα διαπιστευτηρίων για να αποκτήσετε διακριτικά πρόσβασης και να διαχειριστείτε μυστικά στο Azure Key Vault. Η λειτουργική μονάδα ενσωματώνεται με το Microsoft Entra ID για απόκτηση διακριτικών και το notebookutils.credentials Azure Key Vault για μυστική διαχείριση, ώστε να μπορείτε να συνδέεστε με πόρους Azure με ασφάλεια χωρίς να εκθέτετε διαπιστευτήρια σε κώδικα.

Τα βοηθητικά προγράμματα διαπιστευτηρίων είναι διαθέσιμα σε φορητούς υπολογιστές Python, PySpark, Scala και R. Τα παραδείγματα σε αυτήν τη σελίδα χρησιμοποιούν την Python ως κύρια γλώσσα, με τα ισοδύναμα Scala και R να εμφανίζονται όπου τα υποστηρίζει το δημόσιο API.

Σημαντικό

Ποτέ μην κωδικοποιείτε μυστικά ή διαπιστευτήρια απευθείας στον κώδικα σημειωματάριου. Χρησιμοποιείτε πάντα το Azure Key Vault για να αποθηκεύετε ευαίσθητες τιμές και να τις ανακτάτε κατά το χρόνο εκτέλεσης με notebookutils.credentials.getSecret.

Περιορισμοί και ασφάλεια

Πριν χρησιμοποιήσετε βοηθητικά προγράμματα διαπιστευτηρίων, λάβετε υπόψη αυτούς τους περιορισμούς:

  • Λήξη διακριτικού – Τα διακριτικά λήγουν μετά από μια περίοδο. Για λειτουργίες μεγάλης διάρκειας, εφαρμόστε λογική ανανέωσης για να ζητήσετε ένα νέο διακριτικό πριν από τη λήξη.
  • Περιορισμοί εμβέλειας κύριας υπηρεσίας – Όταν εκτελούνται υπό μια κύρια υπηρεσία, τα διακριτικά για το κοινό έχουν περιορισμένα εύρη σε σύγκριση με την pbi ταυτότητα χρήστη.
  • MSAL για πλήρες πεδίο εφαρμογής – Εάν χρειάζεστε το πλήρες πεδίο εφαρμογής της υπηρεσίας Fabric σε μια κύρια υπηρεσία, χρησιμοποιήστε τον έλεγχο ταυτότητας MSAL αντί για getToken.
  • Μυστική απόκρυψη – Οι έξοδοι του Notebook αποκρύπτουν αυτόματα τις μυστικές τιμές για την αποφυγή τυχαίας έκθεσης.
  • Δικαιώματα Key Vault – Πρέπει να έχετε τα κατάλληλα δικαιώματα (Λήψη για ανάγνωση, Ορισμός για εγγραφή) στο Azure Key Vault για πρόσβαση ή αποθήκευση μυστικών κωδικών.
  • Αλλαγές κοινού – Τα εύρη κοινού διακριτικού ενδέχεται να εξελιχθούν με την πάροδο του χρόνου. Επαληθεύστε τα τρέχοντα πεδία στην τεκμηρίωση.

Εκτελέστε την ακόλουθη εντολή για να δείτε μια επισκόπηση των διαθέσιμων μεθόδων:

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. Αυτή η μέθοδος δεν είναι διαθέσιμη στο δημόσιο API Scala.
isValidToken isValidToken(token: String): Boolean Ελέγχει εάν το συγκεκριμένο διακριτικό είναι έγκυρο και δεν έχει λήξει. Αυτή η μέθοδος δεν είναι διαθέσιμη στο δημόσιο API Scala.

Λήψη διακριτικού

getToken επιστρέφει ένα διακριτικό Microsoft Entra για ένα δεδομένο κοινό. Ο παρακάτω πίνακας δείχνει τα τρέχοντα διαθέσιμα κλειδιά κοινού:

Κλειδί κοινού Πόρο Υπόθεση χρήσης
storage Υπηρεσία αποθήκευσης Azure Πρόσβαση στο ADLS Gen2 και στο Blob Storage
pbi Power BI Καλέστε τα Power BI και Fabric REST API
keyvault Azure Key Vault Ανάκτηση μυστικών του Key Vault
kusto Σύναψη RTA KQL DB Σύνδεση στην Εξερεύνηση δεδομένων Azure

Εκτελέστε την ακόλουθη εντολή για να λάβετε το διακριτικό:

notebookutils.credentials.getToken('audience Key')

Παραδείγματα χρήσης διακριτικού

Μπορείτε να χρησιμοποιήσετε το επιστρεφόμενο διακριτικό για έλεγχο ταυτότητας σε διάφορες υπηρεσίες Azure.

Υπηρεσία αποθήκευσης Azure

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. Εάν το σημειωματάριο εκτελείται με την ταυτότητα χρήστη, το διακριτικό εξακολουθεί να έχει το πλήρες πεδίο εφαρμογής της υπηρεσίας Fabric, αλλά αυτό μπορεί να αλλάξει με βελτιώσεις ασφαλείας. Για να εξασφαλίσετε ότι το διακριτικό έχει το πλήρες πεδίο εφαρμογής της υπηρεσίας Fabric, χρησιμοποιήστε τον έλεγχο ταυτότητας MSAL αντί για το notebookutils.credentials.getToken API. Για περισσότερες πληροφορίες, ανατρέξτε στο θέμα Έλεγχος ταυτότητας με Microsoft Entra ID.

  • Τα ακόλουθα πεδία είναι διαθέσιμα όταν καλείτε notebookutils.credentials.getToken με το κλειδί pbi κοινού με την ταυτότητα κύριας υπηρεσίας:

    • Lakehouse.ReadWrite.All – Πρόσβαση ανάγνωσης και εγγραφής σε στοιχεία Lakehouse
    • MLExperiment.ReadWrite.All – Πρόσβαση ανάγνωσης και εγγραφής σε στοιχεία πειράματος μηχανικής μάθησης
    • MLModel.ReadWrite.All – Πρόσβαση ανάγνωσης και εγγραφής σε στοιχεία μοντέλου μηχανικής εκμάθησης
    • Notebook.ReadWrite.All – Πρόσβαση ανάγνωσης και εγγραφής σε στοιχεία Σημειωματάριου
    • SparkJobDefinition.ReadWrite.All – Πρόσβαση ανάγνωσης και εγγραφής σε στοιχεία ορισμού εργασίας Spark
    • Workspace.ReadWrite.All – Πρόσβαση ανάγνωσης και εγγραφής σε στοιχεία χώρου εργασίας
    • Dataset.ReadWrite.All – Πρόσβαση ανάγνωσης και εγγραφής σε στοιχεία συνόλου δεδομένων

Συμβουλή

Εάν χρειάζεστε πρόσβαση σε πρόσθετες υπηρεσίες Fabric ή ευρύτερα δικαιώματα στο πλαίσιο μιας κύριας υπηρεσίας, χρησιμοποιήστε το MSAL για Python για έλεγχο ταυτότητας απευθείας με το πλήρες πεδίο της υπηρεσίας Fabric αντί να βασίζεστε στο getToken("pbi").

Αποκτήστε μυστικό

getSecret επιστρέφει έναν μυστικό κωδικό Azure Key Vault για ένα δεδομένο τελικό σημείο Azure Key Vault και μυστικό όνομα. Η κλήση χρησιμοποιεί τα τρέχοντα διαπιστευτήρια χρήστη για τον έλεγχο ταυτότητας στο Key Vault.

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

Σημείωμα

Οι έξοδοι του Notebook αποκρύπτουν αυτόματα τις μυστικές τιμές για ασφάλεια. Εάν εκτυπώσετε ή εμφανίσετε ένα μυστικό που έχει ανακτηθεί, το αποτέλεσμα εμφανίζει ένα σύμβολο κράτησης θέσης με απόκρυψη αντί για την πραγματική τιμή.

Χρησιμοποιήστε την πλήρως προσδιορισμένη διεύθυνση URL του Key Vault στη μορφή https://<vault-name>.vault.azure.net/. Πρέπει να έχετε τα κατάλληλα δικαιώματα για να αποκτήσετε πρόσβαση στο Key Vault και στα μεμονωμένα μυστικά.

Βέλτιστες πρακτικές ασφάλειας

Ακολουθήστε αυτές τις συστάσεις όταν εργάζεστε με διαπιστευτήρια σε σημειωματάρια Fabric:

  • Αποθηκεύστε όλες τις ευαίσθητες τιμές στο Azure Key Vault. Ποτέ μην ενσωματώνετε διαπιστευτήρια, συμβολοσειρές σύνδεσης ή κλειδιά API απευθείας στον κώδικα σημειωματαρίου.
  • Μην καταγράφετε μυστικές τιμές. Βασιστείτε στην αυτόματη μυστική απόκρυψη στις εξόδους του φορητού υπολογιστή. Αποφύγετε να γράφετε μυστικά σε αρχεία ή να τα περνάτε ως παραμέτρους σημειωματάριου.
  • Χρησιμοποιήστε το σωστό κλειδί κοινού. Αντιστοιχίστε το κλειδί κοινού με τον πόρο Azure προορισμού, ώστε το διακριτικό να έχει μόνο τα δικαιώματα που χρειάζεται.
  • Κατανοήστε το πλαίσιο ταυτότητας. Μάθετε εάν το σημειωματάριό σας εκτελείται με ταυτότητα χρήστη ή με κύρια υπηρεσία, επειδή τα διαθέσιμα πεδία διακριτικών μπορεί να διαφέρουν. Δοκιμάστε τον έλεγχο ταυτότητας τόσο σε αλληλεπιδραστικό περιβάλλον όσο και σε περιβάλλον διοχέτευσης.
  • Χειριστείτε τη λήξη του διακριτικού. Τα διακριτικά λήγουν. Για λειτουργίες μεγάλης διάρκειας, εφαρμόστε τη λογική ανανέωσης για να ζητήσετε ένα νέο διακριτικό πριν από τη λήξη του τρέχοντος.
  • Περιορίστε την πρόσβαση στο Key Vault. Εκχωρήστε μόνο τα ελάχιστα απαιτούμενα δικαιώματα στο Key Vault σας. Ελέγξτε την πρόσβαση μυστικού κωδικού μέσω των αρχείων καταγραφής διαγνωστικών του Azure Key Vault.
  • Χρησιμοποιήστε διαχειριζόμενες ταυτότητες όταν είναι δυνατόν. Οι διαχειριζόμενες ταυτότητες μειώνουν την ανάγκη μη αυτόματης διαχείρισης διαπιστευτηρίων και παρέχουν μια πιο ασφαλή ροή ελέγχου ταυτότητας.

Βάλτε μυστικό

putSecret αποθηκεύει έναν μυστικό κωδικό στο καθορισμένο Azure Key Vault. Εάν το μυστικό υπάρχει ήδη, η τιμή ενημερώνεται.

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

Σχετικό περιεχόμενο

  • Last updated on