Usare i principali del servizio con l'API Fabric per GraphQL

I principali di servizio abilitano l'autenticazione non interattiva programmata all'API Fabric per GraphQL. A differenza delle entità utente che richiedono che un utente esegua l'accesso in modo interattivo, le entità servizio usano le credenziali dell'applicazione (ID client e segreto) per l'autenticazione automatica. Ciò li rende ideali per i servizi back-end, i flussi di lavoro automatizzati, le pipeline CI/CD e qualsiasi applicazione eseguita senza interazione dell'utente.

Questa guida illustra come creare una registrazione dell'app Microsoft Entra, configurarla come entità servizio e concedergli l'accesso alle API GraphQL di Fabric. Si apprenderà come ottenere le credenziali necessarie per l'autenticazione e testare la configurazione con il codice di esempio.

Suggerimento

Vuoi vedere i principali di servizio in azione? Dopo aver completato questa configurazione, provare l'esercitazione Connettere gli agenti di intelligenza artificiale all'API infrastruttura per GraphQL con un server MCP (Model Context Protocol) locale. Illustra come usare l'autenticazione dell'entità servizio per abilitare agenti di intelligenza artificiale come GitHub Copilot per eseguire query sui dati di Fabric usando il linguaggio naturale.

Chi utilizza i principali del servizio

L'autenticazione dell'entità servizio è progettata per:

Ingegneri dei dati che creano processi ETL automatizzati e operazioni di dati pianificate che accedono ai lakehouse e warehouse di Fabric
Sviluppatori back-end che creano applicazioni da server a server che utilizzano a livello di codice i dati di Fabric
Amministratori dell'area di lavoro infrastruttura che configurano servizi e processi in background automatici per l'accesso ai dati
Tecnici DevOps che implementano pipeline CI/CD che interagiscono con le origini dati di Fabric
Sviluppatori di integrazione che creano flussi di lavoro automatizzati che richiedono l'accesso ai dati di Fabric non interattivo

Annotazioni

Per le applicazioni interattive che usano entità utente (ad esempio React o app Web), vedere invece Connettere le applicazioni all'API Fabric per GraphQL. Questa guida è incentrata sull'autenticazione dell'entità servizio (non interattiva).

Prerequisiti

Prima di configurare l'autenticazione del principale del servizio, assicurati di avere:

Un'area di lavoro di Microsoft Fabric con autorizzazioni di amministratore
Un'API esistente per GraphQL nell'area di lavoro. Vedere Creare un'API per GraphQL in Fabric e aggiungere dati.
Autorizzazioni per creare registrazioni di app in Microsoft Entra ID
Accesso amministratore tenant per abilitare le impostazioni dell'entità servizio in Fabric (o chiedere all'amministratore di abilitare questa impostazione)

Passaggio 1: Creare una registrazione dell'app Microsoft Entra

Seguire la guida completa in Registrare un'app Microsoft Entra e creare un service principal per registrare l'app.

Punti chiave per i principali del servizio:

Ignorare gli URI di reindirizzamento e le piattaforme di autenticazione (necessari solo per le app interattive)
Saltare Autorizzazioni API e ambiti (le entità servizio non usano autorizzazioni delegate)
Crea un segreto del client in Certificati e segreti con un periodo di scadenza appropriato

Importante

Acquisire questi tre valori durante l'installazione:

ID tenant: trovato in MICROSOFT Entra ID in Panoramica>ID tenant
ID client: trovato nella registrazione dell'app in PANORAMICA>ID applicazione (client)
Segreto client: valore del segreto visualizzato quando si crea un nuovo segreto client. Copia immediatamente: viene visualizzato una sola volta.

Passaggio 2: Abilitare le entità servizio nelle impostazioni del tenant di Fabric

Un amministratore del tenant di Fabric deve attivare l'uso del principale del servizio.

Nel portale Fabric, vai a portale di amministrazione>Impostazioni tenant
In Impostazioni sviluppatore, abilitare le entità servizio possono usare le API di Fabric
Selezionare Applica.

Questa impostazione rende visibile la registrazione dell'app in Fabric per l'assegnazione dei permessi. Per altre informazioni, vedere Supporto delle identità.

Passaggio 3: Concedere le autorizzazioni in Fabric

L'entità principale del servizio necessita di due livelli di accesso:

Opzione A: Autorizzazioni API singole (consigliate per l'ambiente di produzione)

Nel portale di Fabric aprire l'area di lavoro contenente l'API GraphQL
Seleziona i puntini di sospensione (...) accanto all'elemento dell'API
Selezionare Gestisci autorizzazioni
Selezionare Aggiungi utente
Cercare e selezionare il nome di registrazione dell'app
Selezionare Esegui query e mutazioni (concede il permesso di esecuzione)
Selezionare Concedi

Assicurarsi inoltre che l'entità servizio disponga delle autorizzazioni di lettura/scrittura appropriate per l'origine dati sottostante (Lakehouse, Data Warehouse o database SQL).

Opzione B: Ruolo area di lavoro (più semplice per lo sviluppo/test)

Aggiungere la registrazione dell'app come membro dell'area di lavoro con il ruolo Collaboratore . In questo modo si concede l'accesso all'API GraphQL e a tutte le origini dati nell'area di lavoro.

Nel portale Fabric, apri l'area di lavoro
Selezionare Gestisci accesso
Selezionare Aggiungi persone o gruppi
Cerca il nome della registrazione dell'app
Selezionare il ruolo Collaboratore
Seleziona Aggiungi

Annotazioni

Non si assegnano ruoli di Azure alla registrazione dell'app in Microsoft Entra ID per questo scenario. Tutte le autorizzazioni vengono gestite all'interno di Fabric tramite autorizzazioni API o ruoli dell'area di lavoro.

Testare l'autenticazione dell'entità servizio

Dopo aver effettuato la configurazione, testare il principale del servizio ottenendo un token di accesso e chiamando l'API GraphQL.

Ottenere un token di accesso con Node.js

Installare il pacchetto @azure/identity:

npm install @azure/identity

Creare un file per recuperare il token di accesso:

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);
    }
}

Salvare il file ed eseguirlo:

node getToken.js

In questo modo viene recuperato un token di accesso dall'ID Microsoft Entra.

Chiamare l'API GraphQL con PowerShell

Usare il token per eseguire query sull'API GraphQL:

$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

Chiamare l'API GraphQL con cURL

Usare cURL per eseguire query nell'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)>"}'

Esempio completo Node.js (token e chiamata API)

Installare le dipendenze:

npm install @azure/identity axios

Creare un esempio completo che recupera un token e chiama l'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();

Salvare ed eseguire:

node callGraphQL.js

Risoluzione dei problemi

Registrazione dell'app non visibile in Fabric

Verificare che le entità servizio possano usare le API di Fabric siano abilitate nelle impostazioni del tenant
Attendere alcuni minuti dopo aver abilitato l'impostazione per la propagazione delle modifiche

Errori di autenticazione

Verificare che l'ID Tenant, l'ID Client e il Client Secret siano corretti
Verificare che il segreto client non sia scaduto
Assicurarsi di usare l'ambito https://api.fabric.microsoft.com/.default

Errori di autorizzazione

Verificare che l'entità servizio disponga dell'autorizzazione Execute per l'API GraphQL
Verificare che il principale del servizio abbia accesso in lettura/scrittura alla sorgente di dati sottostante
Verificare che il ruolo dell'area di lavoro sia Collaboratore o superiore se si usano autorizzazioni a livello di area di lavoro

Creare un'app Microsoft Entra in Azure
Informazioni su come creare un'API per GraphQL in Fabric e aggiungere dati.
Informazioni su come eseguire query su più origini dati nell'API fabric per GraphQL.

Valutazione

Questa pagina ti è stata utile?

Last updated on 2026-01-20