Service-principals gebruiken met Fabric-API voor GraphQL

Service-principals maken niet-interactieve, programmatische verificatie mogelijk voor Fabric-API voor GraphQL. In tegenstelling tot gebruikersprincipals waarvoor iemand zich interactief moet aanmelden, gebruiken service-principals toepassingsreferenties (client ID en geheime sleutel) om automatisch te verifiëren. Dit maakt ze ideaal voor back-endservices, geautomatiseerde werkstromen, CI/CD-pijplijnen en elke toepassing die wordt uitgevoerd zonder tussenkomst van de gebruiker.

Deze handleiding helpt u bij het maken van een Microsoft Entra-app-registratie, het configureren als een service-principal en het verlenen van toegang tot uw Fabric GraphQL-API's. U leert hoe u de referenties kunt verkrijgen die nodig zijn voor verificatie en het testen van uw installatie met voorbeeldcode.

Wie maakt gebruik van serviceprincipes

De verificatie van een service-principal is ontworpen voor:

• Data engineers bouwen geautomatiseerde ETL-processen en geplande gegevensbewerkingen met toegang tot Fabric lakehouses en data warehouses.
• Back-endontwikkelaars die server-tot-servertoepassingen maken die programmatisch Fabric-gegevens benutten
• Fabric-werkruimtebeheerders die onbeheerde services en achtergrondprocessen instellen voor gegevenstoegang
• DevOps-technici implementeren CI/CD-pijplijnen die communiceren met Fabric-gegevensbronnen
• Integratieontwikkelaars die geautomatiseerde werkstromen maken waarvoor niet-interactieve Fabric-gegevenstoegang is vereist

Vereiste voorwaarden

Voordat u de service-principalverificatie instelt, moet u ervoor zorgen dat u het volgende heeft:

• Een Microsoft Fabric-werkruimte met beheerdersmachtigingen
• Een bestaande API voor GraphQL in uw werkruimte. Zie Een API voor GraphQL maken in Fabric en gegevens toevoegen.
• Machtigingen voor het maken van app-registraties in Microsoft Entra-id
• Tenantbeheerderstoegang voor het inschakelen van service-principal-instellingen in Fabric (of vraag uw beheerder om dit in te schakelen)

Stap 1: Een Microsoft Entra-app-registratie maken

Volg de volledige gids over Een Microsoft Entra-app registreren en een service-principal maken om uw app-registratie te voltooien.

Belangrijke punten voor service-principals:

• Omleidings-URI's en verificatieplatforms overslaan (alleen nodig voor interactieve apps)
• Overslaan API-machtigingen en -bereiken (service-principals gebruiken geen gedelegeerde machtigingen)
• Maak een clientgeheim onder Certificaten en geheimen met een geschikte verloopperiode

Stap 2: Service-principals inschakelen in tenantinstellingen van Fabric

Een Fabric-tenantbeheerder moet het gebruik van de service-principal inschakelen:

1. Ga in de Fabric-portal naar de beheerportal> en tenantinstellingen
2. Schakel onder Instellingen voor ontwikkelaarsservice-principals in om Fabric-API's te gebruiken
3. Selecteer toepassen

Met deze instelling wordt uw app-registratie zichtbaar in Fabric voor machtigingentoewijzing. Zie Identiteitsondersteuning voor meer informatie.

Stap 3: Machtigingen verlenen in Fabric

Uw service-principal heeft twee toegangsniveaus nodig:

Optie A: Afzonderlijke API-machtigingen (aanbevolen voor productie)

1. Open in de Fabric-portal de werkruimte met uw GraphQL-API
2. Selecteer het beletselteken (...) naast uw API-item
3. Selecteer Machtigingen beheren
4. Selecteer Gebruiker toevoegen
5. Uw app-registratienaam zoeken en selecteren
6. Selecteer Voer query's en mutaties uit (verleent uitvoeringsrechten)
7. Toekenning selecteren

Zorg er bovendien voor dat de service-principal over de juiste lees-/schrijfmachtigingen beschikt voor de onderliggende gegevensbron (Lakehouse, Data Warehouse of SQL-database).

Optie B: Werkruimterol (eenvoudiger voor ontwikkeling/testen)

Voeg uw app-registratie toe als werkruimtelid met de rol Inzender . Hiermee verleent u toegang tot zowel de GraphQL-API als alle gegevensbronnen in de werkruimte.

1. Open uw werkruimte in de Fabric-portal
2. Selecteer Toegang beheren
3. Selecteer Personen of groepen toevoegen
4. Zoek naar de naam van uw app-registratie
5. De rol Inzender selecteren
6. Selecteer Toevoegen

De authenticatie van uw service principal testen

Nadat u de service-principal hebt geconfigureerd, test u uw service-principal door een toegangstoken op te halen en uw GraphQL-API aan te roepen.

Een toegangstoken ophalen met Node.js

Installeer het @azure/identity-pakket:

npm install @azure/identity

Maak een bestand om uw toegangstoken op te halen:

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

Sla het bestand op en voer het uit:

node getToken.js

Hiermee wordt een toegangstoken opgehaald uit Microsoft Entra ID.

Uw GraphQL-API aanroepen met PowerShell

Gebruik het token om een query uit te voeren op uw 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 

Uw GraphQL-API aanroepen met cURL

Gebruik cURL om een query uit te voeren op uw 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)>"}'

Volledig Node.js voorbeeld (token + API-aanroep)

Afhankelijkheden installeren:

npm install @azure/identity axios

Maak een volledig voorbeeld waarmee een token wordt opgehaald en uw API wordt aangeroepen:

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

Opslaan en uitvoeren:

node callGraphQL.js

Probleemoplossingsproces

App-registratie is niet zichtbaar in Fabric

• Controleer of service-principals de Fabric-API's kunnen gebruiken in de huurderinstellingen
• Wacht enkele minuten nadat u de instelling hebt ingeschakeld voordat wijzigingen worden doorgevoerd

Verificatiefouten

• Controleer of uw tenant-id, client-id en clientgeheim juist zijn
• Controleren of het clientgeheim niet is verlopen
• Zorg dat u de scope gebruikt https://api.fabric.microsoft.com/.default

Machtigingsfouten

• Controleer of de service-principal de machtiging Uitvoeren heeft voor de GraphQL-API
• Controleer of de service-principal lees-/schrijftoegang heeft tot de onderliggende gegevensbron
• Controleer of de werkruimterol Inzender of hoger is als u machtigingen op werkruimteniveau gebruikt

Verwante inhoud

• Een Microsoft Entra-app maken in Azure
• Meer informatie over het maken van een API voor GraphQL in Fabric en het toevoegen van gegevens.
• Ontdek hoe u query's uitvoert op meerdere gegevensbronnen in fabric-API voor GraphQL.