Διαχείριση και εκτέλεση σημειωματάριων στο Fabric με API

Το API REST του Microsoft Fabric παρέχει ένα τελικό σημείο υπηρεσίας για τις λειτουργίες δημιουργίας, ανάγνωσης, ενημέρωσης και διαγραφής (CRUD) ενός στοιχείου Fabric. Αυτό το άρθρο περιγράφει τα διαθέσιμα API REST σημειωματάριου και τη χρήση τους.

Με τα API σημειωματάριου, οι μηχανικοί δεδομένων και οι επιστήμονες δεδομένων μπορούν να αυτοματοποιήσουν τις δικές τους διοχετεύσεις και να δημιουργήσουν εύκολα και αποτελεσματικά CI/CD. Αυτά τα API διευκολύνουν επίσης τους χρήστες να διαχειρίζονται και να χειρίζονται στοιχεία σημειωματάριου Fabric και ενσωματώνουν σημειωματάρια με άλλα εργαλεία και συστήματα. Τα σημειωματάρια μπορούν να ενορχηστρωθούν από αγωγούς Fabric και εξωτερικούς προγραμματιστές μέσω αυτών των API, επιτρέποντας την απρόσκοπτη ενοποίηση με αυτοματοποιημένες ροές εργασίας.

Αυτές οι ενέργειες διαχείρισης στοιχείων είναι διαθέσιμες για σημειωματάρια:

Ενέργεια	Περιγραφή
Δημιουργία στοιχείου	Δημιουργεί ένα σημειωματάριο μέσα σε έναν χώρο εργασίας.
Ενημέρωση στοιχείου	Ενημερώνει τα μετα-δεδομένα ενός σημειωματάριου.
Ενημέρωση ορισμού στοιχείου	Ενημερώνει το περιεχόμενο ενός σημειωματάριου.
Διαγραφή στοιχείου	Διαγράφει ένα σημειωματάριο.
Λήψη στοιχείου	Λαμβάνει τα μετα-δεδομένα ενός σημειωματάριου.
Λήψη ορισμού στοιχείου	Λαμβάνει το περιεχόμενο ενός σημειωματάριου.
Στοιχείο λίστας	Παράθεση όλων των στοιχείων σε έναν χώρο εργασίας.

Για περισσότερες πληροφορίες, ανατρέξτε στο θέμα Στοιχεία - API REST.

Οι ακόλουθες ενέργειες χρονοδιαγράμματος εργασίας είναι διαθέσιμες για σημειωματάρια:

Ενέργεια	Περιγραφή
Εκτέλεση εργασίας στοιχείου κατ' απαίτηση	Εκτελέστε ένα σημειωματάριο κατ' απαίτηση με υποστήριξη για παραμετροποίηση, ρύθμιση παραμέτρων περιόδου λειτουργίας (όπως ρυθμίσεις Spark/compute), επιλογή περιβάλλοντος και χρόνου εκτέλεσης και επιλογή προορισμού Fabric Lakehouse.
Ακύρωση παρουσίας εργασίας στοιχείου	Ακύρωση εκτέλεσης εργασίας σημειωματαρίου.
Λήψη παρουσίας εργασίας στοιχείου	Λάβετε την κατάσταση εκτέλεσης σημειωματάριου και ανακτήστε την τιμή εξόδου που επιστρέφεται από την εκτέλεση.

Για περισσότερες πληροφορίες, ανατρέξτε στο θέμα Χρονοδιάγραμμα εργασίας.

Σημείωμα

Ο έλεγχος ταυτότητας κύριας υπηρεσίας υποστηρίζεται τόσο για το Items REST API (λειτουργίες CRUD σημειωματάριου) όσο και για το Job Scheduler API (εκτέλεση, παρακολούθηση και ακύρωση). Αυτό επιτρέπει ασφαλή αυτοματισμό χωρίς επίβλεψη και σενάρια CI/CD. Προσθέστε την κύρια υπηρεσία στον χώρο εργασίας με έναν κατάλληλο ρόλο (Διαχειριστής, Μέλος ή Συμβάλλων) για τη διαχείριση και την εκτέλεση σημειωματαρίων.

Έξοδος τιμών από εκτελέσεις σημειωματαρίου

Οι εκτελέσεις σημειωματαρίου που εκτελούνται μέσω του Job Scheduler API μπορούν να επιστρέψουν μια τιμή εξόδου που μπορείτε να χρησιμοποιήσετε για ενορχήστρωση υπό όρους. Η τιμή εξόδου εμφανίζεται στο exitValue πεδίο του ωφέλιμου φορτίου απόκρισης «Λήψη παρουσίας εργασίας στοιχείου ».

Ένα σημειωματάριο μπορεί να ορίσει την τιμή εξόδου του καλώντας mssparkutils.notebook.exit("your-value") πριν ολοκληρωθεί η εκτέλεση. Η τιμή εξόδου είναι μια συμβολοσειρά και μπορεί να κωδικοποιήσει οποιοδήποτε σήμα αποτελέσματος—για παράδειγμα, "success", , "no_rows_processed"ή ένα αποτέλεσμα σειριοποιημένο με JSON.

Οι εξωτερικοί ενορχηστρωτές, οι διοχετεύσεις Fabric και άλλα εργαλεία αυτοματισμού μπορούν να καλέσουν τη Λήψη παρουσίας εργασίας στοιχείου μετά την ολοκλήρωση της εκτέλεσης για να διαβάσουν την τιμή εξόδου και τη διακλάδωση στα αποτελέσματα. Για παράδειγμα:

1. Υποβάλετε μια εργασία στοιχείου εκτέλεσης κατ' απαίτηση με παραμέτρους και ρυθμίσεις εκτέλεσης.
2. Poll Get Item Job Instance until status is ( Completed ή Failed).
3. Διαβάστε exitValue από την απάντηση για να προσδιορίσετε το επόμενο βήμα στη ροή εργασίας σας.

Αυτό το μοτίβο επιτρέπει την ενορχήστρωση υπό όρους και τη σηματοδότηση κατάντη με βάση τα αποτελέσματα εκτέλεσης του σημειωματάριου.

Αναλυτικό παράδειγμα

Το παρακάτω παράδειγμα δείχνει πώς μπορείτε να υποβάλετε μια εκτέλεση σημειωματαρίου και να ανακτήσετε την κατάσταση και την τιμή εξόδου της. Για το πλήρες σχήμα σώματος αίτησης, συμπεριλαμβανομένων των παραμέτρων, των ρυθμίσεων περιόδου λειτουργίας και των πεδίων επιλογής Lakehouse, ανατρέξτε στην αναφορά API Job Scheduler - Run on demand Item Job .

Βήμα 1: Υποβολή εκτέλεσης

Χρησιμοποιήστε το τελικό σημείο Εκτέλεση κατ' απαίτηση Εργασία στοιχείου για να ξεκινήσετε την εκτέλεση ενός σημειωματαρίου:

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{notebookId}/jobs/instances?jobType=RunNotebook

Η απόκριση επιστρέφει 202 Accepted με μια Location κεφαλίδα που περιέχει τη διεύθυνση URL της παρουσίας εργασίας που χρησιμοποιείτε για την παρακολούθηση της εκτέλεσης.

Βήμα 2: Ανάκτηση κατάστασης εκτέλεσης και τιμής εξόδου

Χρησιμοποιήστε τη διεύθυνση URL από την Location κεφαλίδα για να ελέγξετε την κατάσταση και να διαβάσετε την τιμή εξόδου μετά την ολοκλήρωση της εκτέλεσης:

GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items/{notebookId}/jobs/instances/{jobInstanceId}

Παράδειγμα απάντησης (συντομογραφία):

{
  "id": "<jobInstanceId>",
  "itemId": "<notebookId>",
  "jobType": "RunNotebook",
  "invokeType": "OnDemand",
  "status": "Completed",
  "startTimeUtc": "2026-03-01T10:00:00Z",
  "endTimeUtc": "2026-03-01T10:05:00Z",
  "failureReason": null,
  "exitValue": "success"
}

Διαβάστε exitValue για να προσδιορίσετε το αποτέλεσμα και διακλαδώστε τη λογική αυτοματισμού σας ανάλογα.