Χρήση αρχών υπηρεσίας με το Fabric API για GraphQL

Οι αρχές υπηρεσίας επιτρέπουν τον μη αλληλεπιδραστικό, προγραμματικό έλεγχο ταυτότητας στο Fabric API για GraphQL. Σε αντίθεση με τους κύριους χρήστες που απαιτούν από κάποιον να συνδεθεί αλληλεπιδραστικά, οι κύριοι χρήστες χρησιμοποιούν διαπιστευτήρια εφαρμογής (αναγνωριστικό προγράμματος-πελάτη και μυστικό) για αυτόματο έλεγχο ταυτότητας. Αυτό τα καθιστά ιδανικά για υπηρεσίες υποστήριξης, αυτοματοποιημένες ροές εργασίας, αγωγούς CI/CD και οποιαδήποτε εφαρμογή εκτελείται χωρίς αλληλεπίδραση με τον χρήστη.

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

Φιλοδώρημα

Θέλετε να δείτε τις αρχές υπηρεσιών σε δράση; Αφού ολοκληρώσετε αυτήν τη ρύθμιση, δοκιμάστε το σεμινάριο Σύνδεση πρακτόρων AI στο Fabric API για GraphQL με έναν τοπικό διακομιστή Model Context Protocol (MCP). Δείχνει πώς μπορείτε να χρησιμοποιήσετε τον έλεγχο ταυτότητας κύριας υπηρεσίας για να επιτρέψετε σε πράκτορες AI, όπως το GitHub Copilot, να υποβάλλουν ερωτήματα στα δεδομένα σας Fabric χρησιμοποιώντας φυσική γλώσσα.

Ποιος χρησιμοποιεί τις κύριες υπηρεσίες

Ο έλεγχος ταυτότητας κύριας υπηρεσίας έχει σχεδιαστεί για:

Μηχανικοί δεδομένων που δημιουργούν αυτοματοποιημένες διαδικασίες ETL και προγραμματισμένες λειτουργίες δεδομένων που έχουν πρόσβαση σε λίμνες και αποθήκες Fabric
Προγραμματιστές παρασκηνίου που δημιουργούν εφαρμογές διακομιστή σε διακομιστή που καταναλώνουν δεδομένα Fabric μέσω προγραμματισμού
Διαχειριστές χώρου εργασίας Fabric που ρυθμίζουν υπηρεσίες χωρίς επιτήρηση και διεργασίες παρασκηνίου για πρόσβαση σε δεδομένα
Μηχανικοί DevOps που υλοποιούν διοχετεύσεις CI/CD που αλληλεπιδρούν με προελεύσεις δεδομένων Fabric
Προγραμματιστές ενοποίησης που δημιουργούν αυτοματοποιημένες ροές εργασιών που απαιτούν μη αλληλεπιδραστική πρόσβαση σε δεδομένα Fabric

Σημείωμα

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

Προαπαιτούμενα

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

Ένας χώρος εργασίας Microsoft Fabric με δικαιώματα διαχειριστή
Ένα υπάρχον API για το GraphQL στον χώρο εργασίας σας. Ανατρέξτε στο θέμα Δημιουργία API για το GraphQL στο Fabric και προσθήκη δεδομένων.
Δικαιώματα για τη δημιουργία εγγραφών εφαρμογών στο Microsoft Entra ID
Πρόσβαση διαχειριστή μισθωτή για να ενεργοποιήσετε τις ρυθμίσεις κύριας υπηρεσίας στο Fabric (ή ζητήστε από τον διαχειριστή σας να το ενεργοποιήσει)

Βήμα 1: Δημιουργήστε μια καταχώρηση εφαρμογής Microsoft Entra

Ακολουθήστε τον πλήρη οδηγό στο θέμα Καταχώρηση μιας εφαρμογής Microsoft Entra και δημιουργία κύριας υπηρεσίας για να δημιουργήσετε την καταχώρηση της εφαρμογής σας.

Βασικά σημεία για τους διευθυντές υπηρεσιών:

Παράλειψη URI ανακατεύθυνσης και πλατφορμών ελέγχου ταυτότητας (απαιτείται μόνο για διαδραστικές εφαρμογές)
Μετάβαση Δικαιώματα και εμβέλεια API (οι κύριες υπηρεσίες δεν χρησιμοποιούν δικαιώματα με ανάθεση)
Δημιουργήστε έναν μυστικό κωδικό πελάτη στην περιοχή Πιστοποιητικά και μυστικοί κωδικοί με κατάλληλη περίοδο λήξης

Important

Καταγράψτε αυτές τις τρεις τιμές κατά τη ρύθμιση:

Αναγνωριστικό μισθωτή: Βρίσκεται στο Microsoft Entra ID στην περιοχή Επισκόπηση>Αναγνωριστικό μισθωτή
Αναγνωριστικό προγράμματος-πελάτη: Βρίσκεται στην εγγραφή της εφαρμογής σας στην ενότητα Επισκόπηση>Αναγνωριστικό εφαρμογής (πελάτης)
Μυστικό πελάτη (Client Secret): Η μυστική τιμή που εμφανίζεται όταν δημιουργείτε ένα νέο μυστικό προγράμματος-πελάτη. Αντιγραφή αμέσως—εμφανίζεται μόνο μία φορά.

Βήμα 2: Ενεργοποίηση κύριων υπηρεσιών στις ρυθμίσεις μισθωτή Fabric

Ένας διαχειριστής μισθωτή Fabric πρέπει να ενεργοποιήσει τη χρήση της κύριας υπηρεσίας:

Στην πύλη Fabric, μεταβείτε στιςρυθμίσεις μισθωτήπύλης> διαχείρισης
Στην περιοχή Ρυθμίσεις προγραμματιστή, ενεργοποιήστε την επιλογή Οι κύριες υπηρεσίες μπορούν να χρησιμοποιούν API Fabric
Επιλέξτε Εφαρμογή

Αυτή η ρύθμιση κάνει την εγγραφή της εφαρμογής σας ορατή στο Fabric για εκχώρηση δικαιωμάτων. Για περισσότερες πληροφορίες, ανατρέξτε στο θέμα Υποστήριξη ταυτότητας.

Βήμα 3: Εκχώρηση δικαιωμάτων στο Fabric

Η κύρια υπηρεσία σας χρειάζεται δύο επίπεδα πρόσβασης:

Επιλογή Α: Μεμονωμένα δικαιώματα API (συνιστάται για παραγωγή)

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

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

Επιλογή Β: Ρόλος χώρου εργασίας (απλούστερος για ανάπτυξη/δοκιμή)

Προσθέστε την εγγραφή της εφαρμογής σας ως μέλος χώρου εργασίας με τον ρόλο Συμβάλλων . Αυτό παρέχει πρόσβαση τόσο στο GraphQL API όσο και σε όλες τις πηγές δεδομένων στον χώρο εργασίας.

Στην πύλη Fabric, ανοίξτε τον χώρο εργασίας σας
Επιλέξτε Διαχείριση πρόσβασης
Επιλέξτε Προσθήκη ατόμων ή ομάδων.
Αναζητήστε το όνομα εγγραφής της εφαρμογής σας
Επιλέξτε τον ρόλο Συμβάλλων
Επιλέξτε Προσθήκη

Σημείωμα

Δεν αναθέτετε ρόλους Azure στην καταχώρηση της εφαρμογής σας στο Microsoft Entra ID για αυτό το σενάριο. Η διαχείριση όλων των δικαιωμάτων γίνεται εντός του Fabric μέσω δικαιωμάτων API ή ρόλων χώρου εργασίας.

Ελέγξτε τον έλεγχο ταυτότητας της κύριας υπηρεσίας σας

Μόλις ρυθμιστεί, δοκιμάστε την κύρια υπηρεσία σας ανακτώντας ένα διακριτικό πρόσβασης και καλώντας το GraphQL API σας.

Αποκτήστε ένα διακριτικό πρόσβασης με Node.js

Εγκαταστήστε το @azure/identity πακέτο:

npm install @azure/identity

Δημιουργήστε ένα αρχείο για να ανακτήσετε το διακριτικό πρόσβασης:

const { ClientSecretCredential } = require('@azure/identity');

// Define your Microsoft Entra ID credentials
const tenantId = "<YOUR_TENANT_ID>";
const clientId = "<YOUR_CLIENT_ID>";
const clientSecret = "<YOUR_CLIENT_SECRET>"; // Service principal secret value

const scope = "https://api.fabric.microsoft.com/.default"; // The scope of the token to access Fabric

// Create a credential object with service principal details
const credential = new ClientSecretCredential(tenantId, clientId, clientSecret);

// Function to retrieve the token
async function getToken() {
    try {
        // Get the token for the specified scope
        const tokenResponse = await credential.getToken(scope);
        console.log("Access Token:", tokenResponse.token);
    } catch (err) {
        console.error("Error retrieving token:", err.message);
    }
}

Αποθηκεύστε το αρχείο και εκτελέστε το:

node getToken.js

Με αυτόν τον τρόπο ανακτάται ένα διακριτικό πρόσβασης από το Microsoft Entra ID.

Καλέστε το GraphQL API σας με το PowerShell

Χρησιμοποιήστε το διακριτικό για να ρωτήσετε το GraphQL API σας:

$headers = @{
    Authorization = "Bearer <YOUR_TOKEN>"
    'Content-Type' = 'application/json'
}

$body = @{
    query = @"
    <YOUR_GRAPHQL_QUERY>
"@
}

# Make the POST request to the GraphQL API
$response = Invoke-RestMethod -Uri "<YOUR_GRAPHQL_API_ENDPOINT>" -Method POST -Headers $headers -Body ($body | ConvertTo-Json)

# Output the response
$response | ConvertTo-Json -Depth 10

Καλέστε το GraphQL API σας με cURL

Χρησιμοποιήστε το cURL για να υποβάλετε ερώτημα στο API σας:

curl -X POST <YOUR_GRAPHQL_API_ENDPOINT> \
-H "Authorization: <YOUR_TOKEN>" \
-H "Content-Type: application/json" \
-d '{"query": "<YOUR_GRAPHQL_QUERY(in a single line)>"}'

Συμπληρώστε Node.js παράδειγμα (token + κλήση API)

Εγκατάσταση εξαρτήσεων:

npm install @azure/identity axios

Δημιουργήστε ένα πλήρες παράδειγμα που ανακτά ένα διακριτικό και καλεί το API σας:

const { ClientSecretCredential } = require('@azure/identity');
const axios = require('axios');

// Microsoft Entra ID credentials
const tenantId = "<YOUR_TENANT_ID>";
const clientId = "<YOUR_CLIENT_ID>";
const clientSecret = "<YOUR_CLIENT_SECRET>"; // Service principal secret value

// GraphQL API details
const graphqlApiUrl = "YOUR_GRAPHQL_API_ENDPOINT>";
const scope = "https://api.fabric.microsoft.com/.default"; // The scope to request the token for

// The GraphQL query
const graphqlQuery = {
  query: `
  <YOUR_GRAPHQL_QUERY>
  `
};

// Function to retrieve a token and call the GraphQL API
async function fetchGraphQLData() {
  try {
    // Step 1: Retrieve token using the ClientSecretCredential
    const credential = new ClientSecretCredential(tenantId, clientId, clientSecret);
    const tokenResponse = await credential.getToken(scope);
    const accessToken = tokenResponse.token;

    console.log("Access token retrieved!");

    // Step 2: Use the token to make a POST request to the GraphQL API
    const response = await axios.post(
      graphqlApiUrl,
      graphqlQuery,
      {
        headers: {
          'Authorization': `Bearer ${accessToken}`,
          'Content-Type': 'application/json'
        }
      }
    );

    // Step 3: Output the GraphQL response data
    console.log("GraphQL API response:", JSON.stringify(response.data));
    
  } catch (err) {
    console.error("Error:", err.message);
  }
}

// Execute the function
fetchGraphQLData();

Αποθήκευση και εκτέλεση:

node callGraphQL.js

Επίλυση προβλημάτων

Η εγγραφή εφαρμογής δεν είναι ορατή στο Fabric

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

Σφάλματα ελέγχου ταυτότητας

Επιβεβαιώστε ότι το αναγνωριστικό μισθωτή, το αναγνωριστικό προγράμματος-πελάτη και ο μυστικός κωδικός προγράμματος-πελάτη είναι σωστά
Βεβαιωθείτε ότι ο μυστικός κωδικός προγράμματος-πελάτη δεν έχει λήξει
Βεβαιωθείτε ότι χρησιμοποιείτε το πεδίο εφαρμογής https://api.fabric.microsoft.com/.default

Σφάλματα δικαιωμάτων

Ελέγξτε ότι η κύρια υπηρεσία έχει άδεια εκτέλεσης στο GraphQL API
Βεβαιωθείτε ότι η κύρια υπηρεσία έχει πρόσβαση ανάγνωσης/εγγραφής στην υποκείμενη προέλευση δεδομένων
Επιβεβαιώστε ότι ο ρόλος χώρου εργασίας είναι Συμβάλλων ή υψηλότερος, εάν χρησιμοποιείτε δικαιώματα σε επίπεδο χώρου εργασίας

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

Ανάδραση

Ήταν χρήσιμη αυτή η σελίδα;

Last updated on 2026-01-20