Σύνδεση εφαρμογών στο API Fabric για GraphQL

Η σύνδεση εφαρμογών στο API του Fabric για GraphQL επιτρέπει στις εφαρμογές web, κινητών συσκευών και παρασκηνίου να υποβάλλουν ερωτήματα σε προελεύσεις δεδομένων Fabric χρησιμοποιώντας ένα σύγχρονο, αποτελεσματικό API. Αυτή η ενοποίηση απαιτεί κατάλληλο έλεγχο ταυτότητας μέσω του Microsoft Entra ID και διαμόρφωση της εφαρμογής σας για ασφαλή κλήση του τελικού σημείου GraphQL.

Αυτό το άρθρο σας καθοδηγεί στη σύνδεση μιας εφαρμογής React στο Fabric GraphQL API ως εξής:

1. Δημιουργία και ρύθμιση παραμέτρων μιας εφαρμογής Microsoft Entra για έλεγχο ταυτότητας
2. Ρύθμιση δείγματος GraphQL API στο Fabric με δεδομένα για υποβολή ερωτήματος
3. Κλωνοποίηση και διαμόρφωση μιας ολοκληρωμένης εφαρμογής React από το GitHub
4. Δοκιμή της πιστοποιημένης σύνδεσης

Το σεμινάριο χρησιμοποιεί το React, αλλά οι έννοιες ελέγχου ταυτότητας ισχύουν για οποιαδήποτε γλώσσα. Για δείγματα σε C#, Python ή άλλες γλώσσες, ανατρέξτε στο αποθετήριο δεδομένων GitHub δειγμάτων Microsoft Fabric.

Ποιος χρειάζεται να συνδέσει εφαρμογές

Η ρύθμιση σύνδεσης εφαρμογών είναι απαραίτητη για:

• Προγραμματιστές ιστού και κινητών συσκευών που δημιουργούν εφαρμογές που καταναλώνουν δεδομένα από λίμνες και αποθήκες Fabric
• Προγραμματιστές ενοποίησης που συνδέουν δεδομένα Fabric σε προσαρμοσμένες εφαρμογές και αυτοματοποιημένες ροές εργασιών
• Προγραμματιστές Backend που δημιουργούν υπηρεσίες που ενσωματώνονται στην ενοποιημένη πλατφόρμα ανάλυσης του Fabric
• Μηχανικοί δεδομένων που ρυθμίζουν αυτοματοποιημένες ροές εργασιών επεξεργασίας δεδομένων που καταναλώνουν δεδομένα Fabric μέσω API

Χρησιμοποιήστε αυτόν τον οδηγό όταν χρειάζεται να ελέγξετε την ταυτότητα και να εξουσιοδοτήσετε εφαρμογές για πρόσβαση στα API του Fabric GraphQL.

Προαπαιτούμενα στοιχεία

• Εργαλεία ανάπτυξης: Χρειάζεστε Node.js (έκδοση LTS) και τον κώδικα του Visual Studio εγκατεστημένο στον υπολογιστή σας.

• Πριν συνδέσετε μια εφαρμογή, βεβαιωθείτε ότι έχετε ένα API για το GraphQL στο Fabric. Για περισσότερες πληροφορίες, ανατρέξτε στο θέμα Δημιουργία API για GraphQL στο Fabric και προσθήκη δεδομένων.

• Το API για το GraphQL απαιτεί από τις εφαρμογές να χρησιμοποιούν το Microsoft Entra για έλεγχο ταυτότητας. Καταχωρήστε και διαμορφώστε την εφαρμογή σας ώστε να εκτελεί κλήσεις API κατά του Fabric. Για περισσότερες πληροφορίες, ανατρέξτε στο θέμα Δημιουργία εφαρμογής Microsoft Entra στο Azure.

• Το διαπιστευτήριο με έλεγχο ταυτότητας (κύρια χρήστης, κύρια υπηρεσία ή διαχειριζόμενη ταυτότητα) που καλεί το API χρειάζεται δικαιώματα εκτέλεσης για το API GraphQL (επιλογή Εκτέλεση ερωτημάτων και μεταλλάξεων κατά την προσθήκη δικαιωμάτων άμεσης πρόσβασης). Εάν χρησιμοποιείτε καθολική σύνδεση (SSO) ως επιλογή συνδεσιμότητας στο API, βεβαιωθείτε ότι η πιστοποίηση έχει δικαιώματα ανάγνωσης ή εγγραφής στην επιλεγμένη προέλευση δεδομένων. Για περισσότερες πληροφορίες, ανατρέξτε στο θέμα Σύνδεση σε μια προέλευση δεδομένων και δημιουργία του σχήματος.

Σύνοψη ελέγχου ταυτότητας και δικαιωμάτων

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

Ο παρακάτω πίνακας συνοψίζει τα διάφορα υποστηριζόμενα σενάρια ελέγχου ταυτότητας και τα ελάχιστα απαιτούμενα δικαιώματα για πελάτες που έχουν πρόσβαση στο GraphQL API:

Κλήση API	Συνδεσιμότητα προέλευσης δεδομένων	Απαιτούμενα δικαιώματα API GraphQL	Απαιτούμενα δικαιώματα προέλευσης δεδομένων	Εμβέλεια εφαρμογής Microsoft Entra
Κύρια χρήστη (UPN)	Καθολική σύνδεση (SSO)	Εκτέλεση ερωτημάτων και μεταλλάξεων σε επίπεδο API	Κατάλληλα δικαιώματα ανάγνωσης/εγγραφής που εκχωρούνται στο UPN στην προέλευση δεδομένων	GraphQLApi.Execute.All
Κύρια υπηρεσία (SPN)	Καθολική σύνδεση (SSO)	Εκτέλεση ερωτημάτων και μεταλλάξεων σε επίπεδο API	Κατάλληλα δικαιώματα ανάγνωσης/εγγραφής που εκχωρούνται στο SPN στην προέλευση δεδομένων	Δεν ισχύει
Κύρια χρήστη (UPN)	Αποθηκευμένα διαπιστευτήρια	Εκτέλεση ερωτημάτων και μεταλλάξεων σε επίπεδο API	Κατάλληλα δικαιώματα ανάγνωσης/εγγραφής που εκχωρούνται στα αποθηκευμένα διαπιστευτήρια (σύνδεση) στην προέλευση δεδομένων	GraphQLApi.Execute.All
Κύρια υπηρεσία (SPN)	Αποθηκευμένα διαπιστευτήρια	Εκτέλεση ερωτημάτων και μεταλλάξεων σε επίπεδο API	Κατάλληλα δικαιώματα ανάγνωσης/εγγραφής που εκχωρούνται στο SPN στην προέλευση δεδομένων	Δεν ισχύει

Δημιουργία εφαρμογής Microsoft Entra

Για να μπορέσει η εφαρμογή σας να καλέσει το Fabric GraphQL API, πρέπει να το καταχωρήσετε στο Microsoft Entra ID. Αυτή η καταχώρηση δημιουργεί μια ταυτότητα για την εφαρμογή σας και καθορίζει τα δικαιώματα που χρειάζεται. Η διαδικασία εγγραφής δημιουργεί ένα αναγνωριστικό προγράμματος-πελάτη (αναγνωριστικό εφαρμογής) και καθορίζει τη ροή ελέγχου ταυτότητας που χρησιμοποιεί η εφαρμογή σας για τη λήψη διακριτικών πρόσβασης.

Για εφαρμογές React, διαμορφώνετε ρυθμίσεις εφαρμογής μίας σελίδας (SPA) που χρησιμοποιούν τη ροή PKCE—μια ασφαλή μέθοδο ελέγχου ταυτότητας που έχει σχεδιαστεί για εφαρμογές που βασίζονται σε πρόγραμμα περιήγησης όπου δεν είναι δυνατή η ασφαλής αποθήκευση μυστικών κωδικών προγράμματος-πελάτη.

1. Καταχωρήστε μια εφαρμογή χρησιμοποιώντας τα βήματα που περιγράφονται στο Γρήγορη εκκίνηση: Καταχώρηση μιας εφαρμογής στην πλατφόρμα ταυτότητας της Microsoft.

2. Οι τιμές Αναγνωριστικό εφαρμογής (υπολογιστής-πελάτης) της εφαρμογής Microsoft και Αναγνωριστικό καταλόγου (μισθωτής) εμφανίζονται στο πλαίσιο Σύνοψη. Καταγράψτε αυτές τις τιμές επειδή τις χρειάζεστε όταν ρυθμίζετε τις παραμέτρους της εφαρμογής React.

3. Διαμορφώστε τα δικαιώματα API, ώστε η εφαρμογή σας να έχει πρόσβαση στο Fabric GraphQL API. Στη λίστα Διαχείριση, επιλέξτε δικαιώματα APIκαι, στη συνέχεια, Προσθήκη δικαιώματος.

4. Προσθέστε την υπηρεσία PowerBI, επιλέξτε Δικαιώματα με ανάθεση και επιλέξτε GraphQLApi.Execute.Όλα τα δικαιώματα. Αυτό το δικαίωμα επιτρέπει στην εφαρμογή σας να εκτελεί ερωτήματα και μεταλλάξεις για λογαριασμό του συνδεδεμένου χρήστη. Επιβεβαιώστε ότι δεν απαιτείται συγκατάθεση διαχειριστή.

5. Επιστρέψτε στη λίστα Διαχείριση , επιλέξτε Έλεγχος ταυτότητας Προσθήκη>πλατφόρμας>Εφαρμογή μίας σελίδας.

6. Για σκοπούς τοπικής ανάπτυξης, προσθέστε http://localhost:3000 στην περιοχή URIs ανακατεύθυνσης και επιβεβαιώστε ότι η εφαρμογή έχει ενεργοποιηθεί για τη ροή του κωδικού εξουσιοδότησης με το κλειδί επαλήθευσης για Exchange κώδικα (PKCE). Επιλέξτε το κουμπί Ρύθμιση παραμέτρων για να αποθηκεύσετε τις αλλαγές σας. Εάν η εφαρμογή αντιμετωπίσει σφάλμα που σχετίζεται με αιτήματα μεταξύ προελεύσεων, προσθέστε την πλατφόρμα εφαρμογών για κινητές συσκευές και επιτραπέζιους υπολογιστές στο προηγούμενο βήμα με το ίδιο URI ανακατεύθυνσης.

7. Επιστρέψτε στοελέγχου ταυτότητας , κάντε κύλιση προς τα κάτω στην περιοχή Ρυθμίσεις για προχωρημένους και, στην περιοχή Να επιτρέπονται οι δημόσιες ροές προγράμματος-πελάτη, επιλέξτε Ναι για Ενεργοποιήστε τις παρακάτω ροές για κινητές συσκευές και υπολογιστές.

Ρύθμιση ενός δείγματος API GraphQL για πρόσβαση σε εφαρμογές

Με την εφαρμογή Microsoft Entra καταχωρημένη, χρειάζεστε ένα GraphQL API στο Fabric για να υποβάλετε ερώτημα. Αυτή η ενότητα σάς καθοδηγεί στη δημιουργία ενός δείγματος API χρησιμοποιώντας το σύνολο δεδομένων δημόσιων αργιών του Fabric. Αυτό σας δίνει ένα λειτουργικό API για να δοκιμάσετε τον έλεγχο ταυτότητας και την ανάκτηση δεδομένων χωρίς να χρειάζεται να διαμορφώσετε τις δικές σας προελεύσεις δεδομένων.

Το δείγμα API εκθέτει δεδομένα αργιών από έναν πίνακα Lakehouse, στον οποίο η εφαρμογή React υποβάλλει ερώτημα για να εμφανίσει τις επίσημες αργίες.

1. Από την αρχική σελίδα της πύλης Fabric, επιλέξτε Διαχείριση δεδομένων από τη λίστα φόρτων εργασίας.

2. Στην εμπειρία Μηχανική δεδομένων, επιλέξτε Χρήση δείγματος και, στην περιοχή Lakehouse, επιλέξτε Δημόσιες αργίες για να δημιουργήσετε αυτόματα ένα νέο Lakehouse με δεδομένα δημόσιων αργιών.

   

3. Ακολουθήστε τα βήματα από Δημιουργήστε ένα API για το GraphQL για να δημιουργήσετε ένα νέο API GraphQL και επιλέξτε το Lakehouse που δημιουργήσατε. Προσθέστε τον πίνακα αργιών, ώστε οι υπολογιστές-πελάτες να έχουν πρόσβαση σε αυτά τα δεδομένα.

   

4. Πριν δημιουργήσετε την εφαρμογή React, βεβαιωθείτε ότι το API σας λειτουργεί σωστά δοκιμάζοντάς το στο πρόγραμμα επεξεργασίας API. Χρησιμοποιήστε το ακόλουθο ερώτημα—αυτό είναι το ίδιο ερώτημα που εκτελεί αργότερα η εφαρμογή React:

    query {
    publicholidays (filter: {countryRegionCode: {eq:"US"}, date: {gte: "2024-01-01T00:00:00.000Z", lte: "2024-12-31T00:00:00.000Z"}}) {
        items {
          countryOrRegion
          holidayName
          date
        }
      }
    }
   

5. Επιλέξτε Αντιγραφή τελικού σημείου στη γραμμή εργαλείων του στοιχείου API.

   

6. Στην οθόνη Αντιγραφή σύνδεσης, επιλέξτε Αντιγραφή.

   

7. Καταγράψτε το αναγνωριστικό προγράμματος-πελάτη και το αναγνωριστικό μισθωτή από την εφαρμογή Microsoft Entra και το URI τελικού σημείου. Χρειάζεστε αυτές τις τιμές όταν διαμορφώνετε την εφαρμογή React.

Κλωνοποιήστε και διαμορφώστε την εφαρμογή React

Τώρα που έχετε ρυθμίσει την εφαρμογή Microsoft Entra και το GraphQL API, μπορείτε να διαμορφώσετε μια εφαρμογή React για να συνδεθείτε σε αυτά. Η εφαρμογή χρησιμοποιεί τη Βιβλιοθήκη ελέγχου ταυτότητας της Microsoft (MSAL) για να χειριστεί τον έλεγχο ταυτότητας και να κάνει αιτήματα GraphQL με διακριτικά Bearer.

1. Κλωνοποιήστε το αποθετήριο δειγμάτων από το GitHub:

   git clone https://github.com/microsoft/fabric-samples.git
   

2. Μεταβείτε στο φάκελο της εφαρμογής React:

   cd fabric-samples/docs-samples/data-engineering/GraphQL/React
   

   Ο φάκελος περιέχει μια πλήρη εφαρμογή React. Χρειάζεται μόνο να επεξεργαστείτε src/authConfig.js για να διαμορφώσετε το συγκεκριμένο τελικό σημείο και τα διαπιστευτήριά σας.

3. Ανοίξτε το έργο στον επεξεργαστή κώδικα:

   code .
   

4. Στο πρόγραμμα επεξεργασίας, μεταβείτε στο φάκελο και ανοίξτε authConfig.jsτο src .

5. Αντικαταστήστε τις ακόλουθες τιμές κράτησης θέσης με τα συγκεκριμένα στοιχεία σας:

   • Enter_the_GraphQL_Endpoint_Here - Αντικαταστήστε με το τελικό σημείο του GraphQL API από το Ρυθμίστε ένα δείγμα GraphQL API για πρόσβαση στην εφαρμογή
   • Enter_the_Application_Id_Here - Αντικαταστήστε με το αναγνωριστικό εφαρμογής (προγράμματος-πελάτη) από τη Δημιουργία εφαρμογής Microsoft Entra
   • Enter_the_Tenant_Info_Here - Αντικαταστήστε με το αναγνωριστικό καταλόγου (μισθωτή) από τη Δημιουργία εφαρμογής Microsoft Entra

   Σημαντικό

   Στο ίδιο αρχείο, η loginRequest σταθερά περιλαμβάνει το πεδίο εφαρμογής https://analysis.windows.net/powerbi/api/GraphQLApi.Execute.All. Αυτό ακριβώς το πεδίο εφαρμογής απαιτείται για την πρόσβαση σε API Fabric GraphQL. Μην αφαιρείτε ή τροποποιείτε αυτό το εύρος. Διαφορετικά, ο έλεγχος ταυτότητας αποτυγχάνει.

6. Αποθηκεύστε το αρχείο.

7. Στο τερματικό σας, μεταβείτε στον ριζικό φάκελο του έργου και εκτελέστε:

   npm install
   

   Αυτό εγκαθιστά όλες τις απαιτούμενες εξαρτήσεις.

Δοκιμάστε την εφαρμογή

Με τη ρύθμιση παραμέτρων της εφαρμογής, εκτελέστε την τοπικά για να επαληθεύσετε ότι όλα λειτουργούν σωστά:

1. Στο τερματικό σας, εκτελέστε:

   npm start
   

   Αυτή η εντολή ξεκινά τον διακομιστή ανάπτυξης και ανοίγει την εφαρμογή στο πρόγραμμα περιήγησής σας.

2. Ολοκληρώστε τη ροή ελέγχου ταυτότητας όταν η εφαρμογή φορτωθεί στις http://localhost:3000. Ακολουθήστε τα βήματα εισόδου που περιγράφονται στην ενότητα εκμάθησης Καλέστε το API από την εφαρμογή.

3. Αφού συνδεθείτε με επιτυχία, επιλέξτε το κουμπί Query Fabric API for GraphQL Data . Αυτό ενεργοποιεί τη ροή ελέγχου ταυτότητας, αποκτά ένα διακριτικό πρόσβασης και εκτελεί το ερώτημα GraphQL σε σχέση με το Fabric API σας.

   

4. Εάν όλα έχουν ρυθμιστεί σωστά, η εφαρμογή εμφανίζει τις επίσημες αργίες σε έναν πίνακα. Αυτό επιβεβαιώνει ότι:

   • Η εφαρμογή Microsoft Entra έχει τα σωστά δικαιώματα
   • Το διακριτικό πρόσβασης αποκτήθηκε με επιτυχία
   • Το GraphQL API έλεγξε την ταυτότητα του αιτήματος
   • Το ερώτημα που εκτελείται σε σχέση με τα δεδομένα Lakehouse

   

Άλλες εντολές npm

Πέρα npm start και npm install, μπορείτε να χρησιμοποιήσετε αυτές τις κοινές εντολές npm για διαφορετικά σενάρια ανάπτυξης:

• npm run dev - Εναλλακτικός τρόπος εκκίνησης του διακομιστή ανάπτυξης
• npm run build - Δημιουργήστε μια βελτιστοποιημένη έκδοση παραγωγής της εφαρμογής σας
• npm run preview - Δοκιμάστε την κατασκευή παραγωγής τοπικά πριν από την ανάπτυξη
• npm test - Εκτελέστε αυτοματοποιημένες δοκιμές για να επαληθεύσετε ότι ο κώδικάς σας λειτουργεί σωστά

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

Τώρα που έχετε μια λειτουργική εφαρμογή συνδεδεμένη στο Fabric GraphQL API, εξερευνήστε αυτούς τους πόρους για να δημιουργήσετε πιο εξελιγμένες λύσεις:

• Δημιουργήστε ένα API για το GraphQL στο Fabric και προσθέστε δεδομένα - Μάθετε πώς μπορείτε να εκθέσετε τις δικές σας προελεύσεις δεδομένων
• Υποβολή ερωτήματος σε πολλές προελεύσεις δεδομένων στο Fabric API για GraphQL - Συνδυασμός δεδομένων από διαφορετικές προελεύσεις σε ένα μόνο ερώτημα
• Fabric API για πρόγραμμα επεξεργασίας GraphQL - Δοκιμή και ανάπτυξη ερωτημάτων διαδραστικά
• Δημιουργία εφαρμογής Microsoft Entra στο Azure - Λεπτομερής οδηγός για την καταχώρηση της εφαρμογής παραγωγής
• Δείγματα Microsoft Fabric GraphQL - Αναζήτηση δειγμάτων σε πολλές γλώσσες