Usar principais de serviço com a API Fabric para GraphQL

As entidades de serviço permitem autenticação programática não interativa com a API Fabric para GraphQL. Ao contrário dos princípios de utilizador, que exigem que alguém inicie sessão de forma interativa, os princípios de serviço usam credenciais de aplicação (ID do cliente e segredo) para se autenticarem automaticamente. Isto torna-as ideais para serviços de backend, fluxos de trabalho automatizados, pipelines CI/CD e qualquer aplicação que corra sem interação do utilizador.

Este guia guia-o como criar um registo de uma aplicação Microsoft Entra, configurá-lo como principal de serviço e conceder-lhe acesso às suas APIs Fabric GraphQL. Vai aprender a obter as credenciais necessárias para a autenticação e testar a sua configuração com código de exemplo.

Sugestão

Quer ver os principais de serviço em ação? Depois de concluir esta configuração, experimente o tutorial Connect AI Agents to Fabric API para GraphQL com um servidor local Model Context Protocol (MCP). Demonstra como usar autenticação por principal de serviço para permitir que agentes de IA como o GitHub Copilot consultem os seus dados Fabric usando linguagem natural.

Quem utiliza service principals

A autenticação do principal de serviço é concebida para:

Engenheiros de dados a construir processos ETL automatizados e operações de dados programadas que acedam a casas e armazéns Fabric
Desenvolvedores backend que criam aplicações servidor para servidor que consomem programaticamente dados Fabric
Administradores de espaço de trabalho do Fabric estão a configurar serviços sem supervisão e processos em segundo plano para acesso a dados
Engenheiros DevOps a implementar pipelines de CI/CD que interagem com fontes de dados Fabric
Desenvolvedores de integração que criam fluxos de trabalho automatizados que requerem acesso a dados Fabric não interativo

Observação

Para aplicações interativas que usam princípios de utilizador (como React ou aplicações web), veja Ligar aplicações à API Fabric para GraphQL . Este guia foca-se na autenticação de princípio de serviço (não interativa).

Pré-requisitos

Antes de configurar a autenticação do principal de serviço, certifique-se de que tem:

Um espaço de trabalho Microsoft Fabric com permissões de administrador
Uma API existente para GraphQL no seu espaço de trabalho. Veja Criar uma API para GraphQL no Fabric e adicionar dados.
Permissões para criar registos de aplicações no Microsoft Entra ID
Acesso de administrador do tenant para ativar as definições do principal de serviço no Fabric (ou peça ao seu administrador que o ative)

Passo 1: Criar um registo numa aplicação Microsoft Entra

Siga o guia completo em Registar uma aplicação Microsoft Entra e criar um principal de serviço para criar o registo da sua aplicação.

Pontos-chave para as entidades de serviço:

Saltar URIs de redirecionamento e plataformas de autenticação (apenas necessárias para aplicações interativas)
Skip Permissões e escopos da API (os principais de serviço não usam permissões delegadas)
Crie um segredo de cliente em Certificados & segredos com um período de expiração adequado

Importante

Capture estes três valores durante a configuração:

ID de Inquilino: Encontrado no ID Microsoft Entra em Visão Geral>ID de Inquilino
ID do Cliente: Encontrado no registo da sua aplicação em Visão Geral>ID da Aplicação (cliente)
Segredo do Cliente: O valor do segredo mostrado quando cria um novo segredo do cliente. Copiar imediatamente — só é exibido uma vez.

Passo 2: Ativar elementos principais de serviço nas definições de inquilino do Fabric

Um administrador de tenant Fabric deve ativar a utilização do principal de serviço:

No portal Fabric, vai ao Portal de Administração>definições de Tenant
Nas definições de Programador, ativar a opção para que os principais de serviço possam usar APIs do Fabric
Selecione Aplicar

Esta configuração torna o registo da sua aplicação visível no Fabric para atribuição de permissões. Para mais informações, consulte Suporte de Identidade.

Passo 3: Conceder permissões no Fabric

O seu principal de serviço precisa de dois níveis de acesso:

Opção A: Permissões individuais de API (recomendadas para produção)

No portal Fabric, abra o espaço de trabalho que contém a sua API GraphQL
Selecione o menu de opções (...) ao lado do seu item API
Selecionar permissões de gestão
Selecionar Adicionar utilizador
Procure e selecione o nome de registo da sua aplicação
Selecionar Executar Consultas e Mutações (concede permissão de execução)
Selecione Conceder

Além disso, certifique-se de que o principal do serviço tem as permissões adequadas de leitura/escrita para a fonte de dados subjacente (Lakehouse, Data Warehouse ou base de dados SQL).

Opção B: Função de Workspace (mais simples para desenvolvimento/testes)

Adicione o registo da sua aplicação como membro do espaço de trabalho com a função de Contribuidor . Isto concede acesso tanto à API GraphQL como a todas as fontes de dados no espaço de trabalho.

No portal Fabric, abra o seu espaço de trabalho
Selecione Gerir acesso
Selecionar Adicionar pessoas ou grupos
Procure o nome de registo da sua aplicação
Selecione o papel de Contribuinte
Selecione Adicionar

Observação

Para este cenário, não atribuis funções Azure ao registo da tua aplicação no Microsoft Entra ID. Todas as permissões são geridas no Fabric através de permissões da API ou funções de workspace.

Teste a autenticação da sua identidade de serviço

Depois de configurado, teste o seu principal de serviço recuperando um token de acesso e ligando à sua API GraphQL.

Obtenha um token de acesso com Node.js

Instale o pacote @azure/identity:

npm install @azure/identity

Crie um ficheiro para recuperar o seu token de acesso:

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

Guarda o ficheiro e executa-o:

node getToken.js

Isto recupera um token de acesso do Microsoft Entra ID.

Chame a sua API GraphQL com PowerShell

Utilize o token para consultar a sua 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

Chame a sua API GraphQL usando cURL

Use cURL para consultar a sua 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)>"}'

Exemplo Node.js completo (token + chamada API)

Instalar dependências:

npm install @azure/identity axios

Crie um exemplo completo que recupere um token e chame a sua 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();

Guardar e executar:

node callGraphQL.js

Solução de problemas

Registo de aplicações não visível no Fabric

Verificar se os principais de serviço podem usar APIs do Fabric está ativado nas definições do inquilino
Espere alguns minutos após ativar a definição para que as alterações se propaguem

Erros de autenticação

Confirme que o seu ID de Inquilino, ID do Cliente e Secret do Cliente estão corretos
Verifica se o segredo do cliente não expirou
Certifique-se de que está a usar o telescópio https://api.fabric.microsoft.com/.default

Erros de permissões

Verifique se o principal do serviço tem permissão de Execução na API GraphQL
Verifique se o principal do serviço tem acesso de leitura/escrita à fonte de dados subjacente
Confirme que a função no espaço de trabalho é de Contribuidor ou superior, caso esteja a usar permissões ao nível do espaço de trabalho

Criar um aplicativo Microsoft Entra no Azure
Saiba como criar uma API para o GraphQL no Fabric e adicionar dados.
Descubra como consultar várias fontes de dados na API de malha para GraphQL.

Feedback

Esta página foi útil?

Last updated on 2026-01-21