Βελτιωμένη ανανέωση με το Power BI REST API

Μπορείτε να χρησιμοποιήσετε οποιαδήποτε γλώσσα προγραμματισμού που υποστηρίζει κλήσεις REST για να εκτελέσετε λειτουργίες ανανέωσης σημασιολογικών μοντέλων χρησιμοποιώντας το REST API ανανέωσης δεδομένων του Power BI.

Η βελτιστοποιημένη ανανέωση για μεγάλα και σύνθετα διαμεριζόμενα μοντέλα καλείται κατά παράδοση με μεθόδους προγραμματισμού που χρησιμοποιούν TOM (Μοντέλο αντικειμένου σε μορφή πίνακα), cmdlet του PowerShell ή TMSL (Γλώσσα δέσμης ενεργειών μοντέλου σε μορφή πίνακα). Ωστόσο, αυτές οι μέθοδοι απαιτούν συνδέσεις HTTP μεγάλης διάρκειας που μπορεί να είναι αναξιόπιστες.

Το API REST συνόλου δεδομένων ανανέωσης του Power BI μπορεί να εκτελεί λειτουργίες ανανέωσης μοντέλου ασύγχρονα, επομένως δεν απαιτούνται συνδέσεις HTTP μακράς διάρκειας από εφαρμογές προγράμματος-πελάτη. Σε σύγκριση με τις τυπικές λειτουργίες ανανέωσης, η βελτιωμένη ανανέωση με το REST API παρέχει περισσότερες επιλογές προσαρμογής και τις παρακάτω δυνατότητες που είναι χρήσιμες για μεγάλα μοντέλα:

• Δέσμες δεσμεύσεων
• Ανανέωση σε επίπεδο πίνακα και διαμερίσματος
• Εφαρμογή πολιτικών επαυξητικής ανανέωσης
• GET λεπτομέρειες ανανέωσης
• Ακύρωση ανανέωσης

Σημείωμα

• Στο παρελθόν, η βελτιωμένη ανανέωση ονομαζόταν ασύγχρονη ανανέωση με το REST API. Ωστόσο, μια τυπική ανανέωση που χρησιμοποιεί το API REST συνόλου δεδομένων ανανέωσης εκτελείται επίσης ασύγχρονα από την εγγενή φύση του.
• Οι βελτιωμένες λειτουργίες ανανέωσης του REST API του Power BI δεν ανανεώνουν αυτόματα τα cache πλακιδίων. Οι προσωρινές αποθηκεύσεις πλακιδίων ανανεώνονται μόνο όταν ένας χρήστης αποκτά πρόσβαση σε μια αναφορά.

Διεύθυνση URL βάσης

Η διεύθυνση URL βάσης έχει την ακόλουθη μορφή:

https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets/{datasetId}/refreshes 

Μπορείτε να προσαρτήσετε πόρους και λειτουργίες στη διεύθυνση URL βάσης με βάση τις παραμέτρους. Στο παρακάτω διάγραμμα, οι ομάδες, τα σύνολα δεδομένων και οι ανανεώσεις είναι συλλογές. Η Ομάδα, το Σύνολο δεδομένων και η Ανανέωση είναι αντικείμενα.

Απαιτήσεις

Χρειάζεστε τις ακόλουθες απαιτήσεις για να χρησιμοποιήσετε το REST API:

• Ένα σημασιολογικό μοντέλο στο Power BI Premium, το Premium ανά χρήστη ή το Power BI Embedded.
• Ένα αναγνωριστικό ομάδας και ένα αναγνωριστικό συνόλου δεδομένων για χρήση στη διεύθυνση URL αίτησης.
• Dataset.ReadWrite.All scope δικαιωμάτων.

Ο αριθμός των ανανεώσεων περιορίζεται σύμφωνα με τους γενικούς περιορισμούς για ανανεώσεις που βασίζονται σε API για μοντέλα Pro και Premium.

Έλεγχος ταυτότητας

Όλες οι κλήσεις πρέπει να πραγματοποιούν έλεγχο ταυτότητας με έγκυρο αναγνωριστικό Microsoft Entra OAuth 2 στην κεφαλίδα εξουσιοδότησης. Το διακριτικό πρέπει να ικανοποιεί τις ακόλουθες απαιτήσεις:

• Να είναι είτε διακριτικό χρήστη, είτε κύρια υπηρεσία εφαρμογής.
• Ζητήστε από το κοινό να ορίσει σωστά την https://api.powerbi.comτιμή .
• Να χρησιμοποιείται από έναν χρήστη ή μια εφαρμογή που διαθέτει επαρκή δικαιώματα στο μοντέλο.

Σημείωμα

Οι τροποποιήσεις του REST API δεν αλλάζουν τα δικαιώματα που έχουν οριστεί τη συγκεκριμένη στιγμή για ανανεώσεις μοντέλου.

POST /ανανεώσεις

Για να κάνετε μια ανανέωση, χρησιμοποιήστε το ρήμα POST στη συλλογή /refreshes για να προσθέσετε ένα νέο αντικείμενο ανανέωσης στη συλλογή. Η κεφαλίδα Location στην απόκριση περιλαμβάνει το requestId. Επειδή η λειτουργία είναι ασύγχρονη, μια εφαρμογή προγράμματος-πελάτη μπορεί να αποσυνδεθεί και να requestId τη χρησιμοποιήσει για να ελέγξει την κατάσταση αργότερα, εάν είναι απαραίτητο.

Ο παρακάτω κώδικας εμφανίζει ένα δείγμα αίτησης:

POST https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes

Το σώμα αίτησης μπορεί να μοιάζει με το παρακάτω παράδειγμα:

{
    "type": "Full",
    "commitMode": "transactional",
    "maxParallelism": 2,
    "retryCount": 2,
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer"
        },
        {
            "table": "DimDate"
        }
    ]
}

Σημείωμα

Η υπηρεσία αποδέχεται μόνο μία λειτουργία ανανέωσης τη φορά για ένα μοντέλο. Εάν υπάρχει μια τρέχουσα ανανέωση που εκτελείται και υποβληθεί μια άλλη αίτηση, επιστρέφει ένας 400 Bad Request κωδικός κατάστασης HTTP.

Παράμετροι

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

Ονομασία	Τύπος	Προεπιλεγμένος	Περιγραφή
type	Απαρίθμηση	automatic	Ο τύπος της επεξεργασίας που θα εκτελεστεί. Οι τύποι ευθυγραμμίζονται με τους τύπους εντολών ανανέωσης TMSL: full, , clearValuescalculate, dataOnly, automaticκαι defragment. Ο add τύπος δεν υποστηρίζεται.
commitMode	Απαρίθμηση	transactional	Καθορίζει εάν θα γίνει δέσμευση αντικειμένων σε δέσμες ή μόνο όταν ολοκληρωθούν. Οι λειτουργίες είναι transactional και partialBatch. Όταν χρησιμοποιείτε partialBatch τη λειτουργία ανανέωσης δεν πραγματοποιείται εντός μίας συναλλαγής. Κάθε εντολή δεσμεύεται μεμονωμένα. Εάν υπάρχει αποτυχία, το μοντέλο μπορεί να είναι κενό ή να περιλαμβάνει μόνο ένα υποσύνολο των δεδομένων. Για να διασφαλίσετε την αποτυχία και να διατηρήσετε τα δεδομένα που βρίσκονταν στο μοντέλο πριν από την έναρξη της λειτουργίας, εκτελέστε τη λειτουργία με commitMode = transactional.
maxParallelism	Int	10	Καθορίζει τον μέγιστο αριθμό νημάτων που μπορούν να εκτελέσουν τις εντολές επεξεργασίας παράλληλα. Αυτή η τιμή ευθυγραμμίζεται με την MaxParallelism ιδιότητα που μπορεί να οριστεί στην εντολή TMSL Sequence ή χρησιμοποιώντας άλλες μεθόδους.
retryCount	Int	0	Πόσες φορές επαναληφύεται η λειτουργία προτού αποτύχει.
objects	Πίνακας	Ολόκληρο το μοντέλο	Ένας πίνακας αντικειμένων προς επεξεργασία. Κάθε αντικείμενο περιλαμβάνει table κατά την επεξεργασία ενός ολόκληρου πίνακα ή table και partition κατά την επεξεργασία ενός διαμερίσματος. Εάν δεν έχουν καθοριστεί αντικείμενα, ανανεώνεται ολόκληρο το μοντέλο.
applyRefreshPolicy	Boolean	true	Εάν έχει οριστεί πολιτική επαυξητικής ανανέωσης, καθορίζει εάν θα εφαρμοστεί η πολιτική. Οι λειτουργίες είναι true ή false. Εάν η πολιτική δεν εφαρμοστεί, η πλήρης διαδικασία αφήνει ορισμούς διαμερίσματος αμετάβλητους και ανανεώνει πλήρως όλα τα διαμερίσματα στον πίνακα. Εάν commitMode το είναι transactional, applyRefreshPolicy μπορεί να είναι true ή false. Εάν commitMode το είναι partialBatch, trueapplyRefreshPolicy το δεν υποστηρίζεται και applyRefreshPolicy πρέπει να οριστεί σε false.
effectiveDate	Date	Τρέχουσα ημερομηνία	Εάν εφαρμόζεται μια πολιτική επαυξητικής ανανέωσης, η effectiveDate παράμετρος παρακάμπτει την τρέχουσα ημερομηνία. Εάν δεν καθοριστεί, χρησιμοποιείται η τιμή UTC για τον προσδιορισμό της τρέχουσας ημέρας.

Response

202 Accepted

Η απόκριση περιλαμβάνει επίσης ένα Location πεδίο κεφαλίδας απόκρισης για να παραπέμπει τον καλούντα στη λειτουργία ανανέωσης που δημιουργήθηκε και έγινε αποδεκτή. Το Location είναι η θέση του νέου πόρου που δημιούργησε η αίτηση, η οποία περιλαμβάνει το requestId που απαιτούν ορισμένες βελτιωμένες λειτουργίες ανανέωσης. Για παράδειγμα, στην ακόλουθη απόκριση, requestId το είναι το τελευταίο αναγνωριστικό στην απόκριση 87f31ef7-1e3a-4006-9b0b-191693e79e9e.

x-ms-request-id: 87f31ef7-1e3a-4006-9b0b-191693e79e9e
Location: https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes/87f31ef7-1e3a-4006-9b0b-191693e79e9e

GET /ανανεώσεις

Χρησιμοποιήστε το ρήμα GET στη συλλογή /refreshes για να αναφέρετε το ιστορικό, τις τρέχουσες και τις εκκρεμείς λειτουργίες ανανέωσης.

Το σώμα της απόκρισης μπορεί να μοιάζει με το παρακάτω παράδειγμα:

[
    {
        "requestId": "1344a272-7893-4afa-a4b3-3fb87222fdac",
        "refreshType": "ViaEnhancedApi",
        "startTime": "2020-12-07T02:06:57.1838734Z",
        "endTime": "2020-12-07T02:07:00.4929675Z",
        "status": "Completed",
        "extendedStatus": "Completed"
    },
    {
        "requestId": "474fc5a0-3d69-4c5d-adb4-8a846fa5580b",
        "startTime": "2020-12-07T01:05:54.157324Z",
        "refreshType": "ViaEnhancedApi",
        "endTime": "2020-12-07T01:05:57.353371Z",
        "status": "Unknown"
    }
    {
        "requestId": "85a82498-2209-428c-b273-f87b3a1eb905",
        "refreshType": "ViaEnhancedApi",
        "startTime": "2020-12-07T01:05:54.157324Z",
        "endTime": "2020-12-07T01:05:57.353371Z",
        "status": "Unknown",
        "extendedStatus": "NotStarted"
    }
]

Σημείωμα

Το Power BI ενδέχεται να αποσύρει αιτήσεις εάν υπάρχουν πάρα πολλές αιτήσεις σε σύντομο χρονικό διάστημα. Το Power BI κάνει ανανέωση, ουρές στην επόμενη αίτηση και απορρίπτει όλες τις άλλες. Βάσει σχεδίασης, δεν μπορείτε να υποβάλετε ερωτήματα για την κατάσταση των αιτήσεων που απορρίφθηκαν.

Ιδιότητες απόκρισης

Ονομασία	Τύπος	Description
requestId	Guid	Το αναγνωριστικό της αίτησης ανανέωσης. Πρέπει requestId να υποβάλετε ερώτημα για την κατάσταση της μεμονωμένης λειτουργίας ανανέωσης ή να ακυρώσετε μια λειτουργία ανανέωσης σε εξέλιξη.
refreshType	Συμβολοσειρά	OnDemand υποδεικνύει ότι η ανανέωση ενεργοποιήθηκε αλληλεπιδραστικά μέσω της πύλης Power BI. Scheduled υποδεικνύει ότι ένα χρονοδιάγραμμα ανανέωσης μοντέλου ενεργοποίησε την ανανέωση. ViaApi υποδεικνύει ότι μια κλήση API ενεργοποίησε την ανανέωση. ViaEnhancedApi υποδεικνύει ότι μια κλήση API ενεργοποίησε μια βελτιωμένη ανανέωση.
startTime	Συμβολοσειρά	Ημερομηνία και ώρα έναρξης της ανανέωσης.
endTime	Συμβολοσειρά	Ημερομηνία και ώρα λήξης ανανέωσης.
status	Συμβολοσειρά	Completed υποδεικνύει ότι η λειτουργία ανανέωσης ολοκληρώθηκε με επιτυχία. Failed υποδεικνύει ότι η λειτουργία ανανέωσης απέτυχε. Unknown υποδεικνύει ότι η κατάσταση ολοκλήρωσης δεν μπορεί να προσδιοριστεί. Με αυτήν την κατάσταση, endTime το είναι κενό. Disabled υποδεικνύει ότι η ανανέωση απενεργοποιήθηκε με επιλεκτική ανανέωση. Cancelled υποδεικνύει ότι η ανανέωση ακυρώθηκε με επιτυχία.
extendedStatus	Συμβολοσειρά	Αυξάνει την status ιδιότητα για να παρέχει περισσότερες πληροφορίες.

Σημείωμα

Σε Υπηρεσίες Ανάλυσης του Azure, το τελικό status αποτέλεσμα είναι succeeded. Εάν μετεγκαταστήσετε μια λύση Υπηρεσίες Ανάλυσης του Azure στο Power BI, ίσως χρειαστεί να τροποποιήσετε τις λύσεις σας.

Περιορισμός του αριθμού των λειτουργιών ανανέωσης που επιστρέφονται

Το Power BI REST API υποστηρίζει τον περιορισμό του αριθμού καταχωρήσεων που ζητήθηκαν στο ιστορικό ανανέωσης, χρησιμοποιώντας την προαιρετική $top παράμετρο. Εάν δεν καθορίζεται, η προεπιλογή είναι όλες οι διαθέσιμες καταχωρήσεις.

GET https://api.powerbi.com/v1.0/myorg/groups/{groupId}/datasets/{datasetId}/refreshes?$top={$top}      

GET /refreshes/<requestId>

Για να ελέγξετε την κατάσταση μιας λειτουργίας ανανέωσης, χρησιμοποιήστε το ρήμα GET στο αντικείμενο ανανέωσης καθορίζοντας το requestId. Εάν η λειτουργία είναι σε εξέλιξη, status επιστρέφει InProgress, όπως στο παρακάτω παράδειγμα σώματος απόκρισης:

{
    "startTime": "2020-12-07T02:06:57.1838734Z",
    "endTime": "2020-12-07T02:07:00.4929675Z",
    "type": "Full",
    "status": "InProgress",
    "currentRefreshType": "Full",
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer",
            "status": "InProgress"
        },
        {
            "table": "DimDate",
            "partition": "DimDate",
            "status": "InProgress"
        }
    ]
}

DELETE /refreshes/<requestId>

Για να ακυρώσετε μια λειτουργία ανανέωσης σε εξέλιξη, χρησιμοποιήστε το ρήμα DELETE στο αντικείμενο ανανέωσης καθορίζοντας το requestId.

Για παράδειγμα,

DELETE https://api.powerbi.com/v1.0/myorg/groups/f089354e-8366-4e18-aea3-4cb4a3a50b48/datasets/cfafbeb1-8037-4d0c-896e-a46fb27ff229/refreshes/1344a272-7893-4afa-a4b3-3fb87222fdac

Ζητήματα προς εξέταση και περιορισμοί

Η λειτουργία ανανέωσης έχει τα ακόλουθα ζητήματα και περιορισμούς:

Τυπικές λειτουργίες ανανέωσης

• Δεν μπορείτε να ακυρώσετε προγραμματισμένες ή κατ ́απαίτηση μη αυτόματες ανανεώσεις μοντέλου χρησιμοποιώντας τη συνάρτηση DELETE /refreshes/<requestId>.
• Οι προγραμματισμένες και κατ ́απαίτηση μη αυτόματες ανανεώσεις μοντέλου δεν υποστηρίζουν λεπτομέρειες λειτουργίας ανανέωσης χρησιμοποιώντας το GET /refreshes/<requestId>.
• Οι λειτουργίες "Λήψη λεπτομερειών" και "Άκυρο" είναι νέες λειτουργίες μόνο για βελτιωμένη ανανέωση. Η τυπική ανανέωση δεν υποστηρίζει αυτές τις λειτουργίες.

Power BI Embedded

Εάν το σύνολο εκχωρημένων πόρων διακοπεί με μη αυτόματο τρόπο στην πύλη Power BI ή χρησιμοποιώντας το PowerShell ή προκύψει διακοπή του συστήματος, η κατάσταση οποιασδήποτε τρέχουσας βελτιωμένης λειτουργίας ανανέωσης παραμένει InProgress για μέγιστο διάστημα έξι ωρών. Εάν το σύνολο εκχωρημένων πόρων συνεχιστεί εντός έξι ωρών, η λειτουργία ανανέωσης συνεχίζεται αυτόματα. Εάν οι εκχωρημένοι πόροι συνεχιστούν μετά από περισσότερες από έξι ώρες, η λειτουργία ανανέωσης μπορεί να επιστρέψει ένα σφάλμα χρονικού ορίου. Στη συνέχεια, πρέπει να επανεκκινήσετε τη λειτουργία ανανέωσης.

Κατάργηση μοντέλου σημασιολογίας

Το Power BI χρησιμοποιεί δυναμική διαχείριση μνήμης για τη βελτιστοποίηση της μνήμης των εκχωρημένων πόρων. Εάν το μοντέλο εκκαθαριστεί από τη μνήμη κατά τη διάρκεια μιας λειτουργίας ανανέωσης, ενδέχεται να επιστραφεί το ακόλουθο σφάλμα:

{
    "messages": [
        {
            "code": "0xC11C0020",
            "message": "Session cancelled because it is connected to a database that has been evicted to free up memory for other operations",
            "type": "Error"
        }
    ]
}

Η λύση είναι να επαναλάβετε τη λειτουργία ανανέωσης. Για να μάθετε περισσότερα σχετικά με τη δυναμική διαχείριση μνήμης και την εκκαθάριση μοντέλου, ανατρέξτε στο θέμα Κατάργηση μοντέλου.

Χρονικά όρια ανανέωσης λειτουργίας

Ο μέγιστος χρόνος για μια μεμονωμένη λειτουργία ανανέωσης είναι πέντε ώρες. Εάν η λειτουργία ανανέωσης δεν ολοκληρωθεί με επιτυχία εντός του ορίου των πέντε ωρών και retryCount δεν έχει καθοριστεί ή έχει καθοριστεί ως 0 (η προεπιλογή) στο σώμα αίτησης, επιστρέφει σφάλμα χρονικού ορίου.

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

Όταν σχεδιάζετε τη λύση βελτιωμένης ανανέωσης μοντέλου με το REST API ανανέωσης συνόλου δεδομένων, είναι σημαντικό να λάβετε υπόψη αυτά τα χρονικά όρια και την retryCount παράμετρο. Μια επιτυχημένη ολοκλήρωση ανανέωσης μπορεί να υπερβεί τις πέντε ώρες εάν αποτύχει μια αρχική λειτουργία ανανέωσης και retryCount καθοριστεί 1 ή περισσότερο.

Για παράδειγμα, εάν ζητήσετε μια λειτουργία ανανέωσης με "retryCount": 1και η αρχική λειτουργία επανάληψης αποτύχει τέσσερις ώρες από την ώρα έναρξης, ξεκινά μια δεύτερη λειτουργία ανανέωσης για αυτή την αίτηση. Εάν η δεύτερη λειτουργία ανανέωσης επιτύχει σε τρεις ώρες, ο συνολικός χρόνος για την επιτυχή εκτέλεση της αίτησης ανανέωσης είναι επτά ώρες.

Εάν οι λειτουργίες ανανέωσης αποτυγχάνουν τακτικά, υπερβείτε το χρονικό όριο των πέντε ωρών ή υπερβείτε τον επιθυμητό χρόνο επιτυχούς λειτουργίας ανανέωσης, εξετάστε το ενδεχόμενο να μειώσετε την ποσότητα των δεδομένων που ανανεώνονται από την προέλευση δεδομένων. Μπορείτε να διαιρέσετε την ανανέωση σε πολλές αιτήσεις, για παράδειγμα, μια αίτηση για κάθε πίνακα. Μπορείτε επίσης να καθορίσετε partialBatch στην commitMode παράμετρο.

Δείγμα κώδικα

Για ένα δείγμα κώδικα C# για να ξεκινήσετε, ανατρέξτε στο θέμα RestApiSample στο GitHub.

Για να χρησιμοποιήσετε το δείγμα κώδικα:

1. Κλωνοποιήστε ή κάντε λήψη του αποθετηρίου.
2. Ανοίξτε τη λύση RestApiSample.
3. Βρείτε τη γραμμή client.BaseAddress = … και καταχωρήστε τη βασική διεύθυνση URL.

Το δείγμα κώδικα χρησιμοποιεί έλεγχο ταυτότητας κύριας υπηρεσίας.

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

• API REST συνόλου δεδομένων ανανέωσης του Power BI
• Χρήση των Power BI REST API