Brug tjenesteprincipaler med Fabric API til GraphQL

Service principals muliggør ikke-interaktiv, programmatisk autentificering til Fabric API for GraphQL. I modsætning til brugerprincipper, der kræver, at nogen logger ind interaktivt, bruger serviceprincipper applikationsoplysninger (klient-ID og hemmelig) til automatisk autentificering. Dette gør dem ideelle til backend-tjenester, automatiserede workflows, CI/CD-pipelines og enhver applikation, der kører uden brugerinteraktion.

Denne guide guider dig gennem oprettelsen af en Microsoft Entra-app-registrering, konfiguration af den som serviceprincipal og tilladelse til adgang til dine Fabric GraphQL API'er. Du lærer, hvordan du får de nødvendige legitimationsoplysninger til autentificering og tester dit setup med eksempelkode.

Hvem bruger serviceprincipper.

Service principal-autentificering er designet til:

• Dataingeniører , der bygger automatiserede ETL-processer og planlagte dataoperationer, der får adgang til Fabric-søhuse og lagre
• Backend-udviklere , der skaber server-til-server-applikationer, som programmæssigt forbruger Fabric-data
• Fabric workspace-administratorer, der opsætter uovervågede tjenester og baggrundsprocesser til dataadgang
• DevOps-ingeniører , der implementerer CI/CD-pipelines, som interagerer med Fabric-datakilder
• Integrationsudviklere , der skaber automatiserede arbejdsgange, som kræver ikke-interaktiv Fabric-dataadgang

Forudsætninger

Før du opsætter service principal-autentificering, skal du sikre dig, at du har:

• Et Microsoft Fabric-arbejdsområde med administratorrettigheder
• Et eksisterende API til GraphQL i dit arbejdsområde. Se Opret et API for GraphQL i Fabric og tilføj data.
• Tilladelser til at oprette app-registreringer i Microsoft Entra ID
• Lejeradministrator-adgang til at aktivere service principal-indstillinger i Fabric (eller bed din administrator om at aktivere dette)

Trin 1: Opret en Microsoft Entra-app-registrering

Følg den komplette guide på Registrer en Microsoft Entra-app og opret en servicechef til at oprette din app-registrering.

Nøglepunkter for tjenesteledere:

• Spring omdirigerings-URI'er og autentificeringsplatforme over (kun nødvendige for interaktive apps)
• Spring over API-tilladelser og -scopes (service principals bruger ikke delegerede tilladelser)
• Opret en klienthemmelighed under Certifikater og hemmeligheder med en passende udløbsperiode

Trin 2: Aktivér service principals i Fabric-lejerindstillinger

En Fabric-lejeradministrator skal aktivere brug af tjenesteprincipalen:

1. I Fabric-portalen går du til Admin-portalens>lejerindstillinger
2. Under udviklerindstillinger kan Service principals aktivere og bruge Fabric API'er
3. Vælg Anvend

Denne indstilling gør din app-registrering synlig i Fabric for tilladelsestildeling. For mere information, se Identitetsstøtte.

Trin 3: Giv tilladelser i Fabric

Din serviceleder har brug for to adgangsniveauer:

Mulighed A: Individuelle API-tilladelser (anbefalet til produktion)

1. I Fabric-portalen åbner du arbejdsområdet, der indeholder dit GraphQL API
2. Vælg ellipsen (...) ved siden af dit API-element
3. Vælg Administrer tilladelser
4. Vælg Tilføj bruger
5. Søg efter og vælg registreringsnavnet på din app
6. Vælg Kør forespørgsler og mutationer (giver eksekveringstilladelse)
7. Vælg bevilling

Derudover skal du sikre, at servicehovedpersonen har passende læse-/skriverettigheder til den underliggende datakilde (Lakehouse, Data Warehouse eller SQL-database).

Mulighed B: Workspace-rolle (enklere til udvikling/test)

Tilføj din app-registrering som workspace-medlem med bidragyder-rollen . Dette giver adgang til både GraphQL API'en og alle datakilder i arbejdsområdet.

1. I Fabric-portalen åbner du dit arbejdsområde
2. Vælg Administrer adgang
3. Vælg Tilføj personer eller grupper
4. Søg efter din app-registreringsnavn
5. Vælg bidragyderrollen
6. Vælg Tilføj.

Test din service principal-autentificering

Når det er konfigureret, test din serviceprincipal ved at hente en adgangstoken og kalde dit GraphQL API.

Få et adgangstoken med Node.js

Installer @azure/identity pakken:

npm install @azure/identity

Opret en fil for at hente din adgangstok:

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

Gem filen og kør den:

node getToken.js

Dette henter en adgangstoken fra Microsoft Entra ID.

Kald dit GraphQL API med PowerShell

Brug tokenet til at forespørge din 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 

Kald dit GraphQL API med cURL

Brug cURL til at forespørge din 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)>"}'

Komplet Node.js eksempel (token + API-kald)

Installér afhængigheder:

npm install @azure/identity axios

Lav et komplet eksempel, der henter et token og kalder dit 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();

Gem og kør:

node callGraphQL.js

Fejlfinding

App-registrering ikke synlig i Fabric

• Kontroller, at Service Principals kan bruge Fabric API'er , er aktiveret i lejerindstillingerne
• Vent et par minutter efter at have aktiveret indstillingen, før ændringerne kan udbrede sig

Godkendelsesfejl

• Bekræft at dit lejer-ID, klient-ID og klienthemmelighed er korrekte
• Bekræfte, at klienthemmeligheden ikke er udløbet
• Sørg for, at du bruger teleskopet https://api.fabric.microsoft.com/.default

Tilladelsesfejl

• Tjek at serviceprincipalen har Execute-tilladelse på GraphQL API'en
• Verificér, at servicehovedpersonen har læse-/skriveadgang til den underliggende datakilde
• Bekræft at arbejdsområdet er Bidragyder eller bedre, hvis du bruger arbejdsområde-niveau tilladelser

Relateret indhold

• Opret en Microsoft Entra-app i Azure
• Få mere at vide om, hvordan du opretter en API til GraphQL i Fabric og tilføjer data.
• Find ud af, hvordan du forespørger på flere datakilder i Fabric API til GraphQL.