Conecte aplicativos à API de malha para GraphQL

2025-06-10

Para conectar um aplicativo a uma API para GraphQL, você precisa de três informações importantes: uma ID de cliente, sua ID de locatário e seu endereço de ponto de extremidade GraphQL na malha. Nas seções a seguir, mostramos como criar e recuperar todos os detalhes que você precisa e como acessar sua API usando um aplicativo de exemplo.

Pré-requisitos

Antes de conectar um aplicativo, você deve ter uma API para GraphQL na malha. Para obter mais informações, consulte Criar uma API para o GraphQL na malha e adicionar dados.
Atualmente, a API para GraphQL requer que os aplicativos usem o Microsoft Entra para autenticação. Seu aplicativo precisa ser registrado e configurado adequadamente para executar chamadas de API no Fabric. Para obter mais informações, consulte Criar um aplicativo Microsoft Entra no Azure.
A credencial autenticada (principal de utilizador, principal de serviço ou identidade gerida) que invoca a API requer permissões de Execução para a API GraphQL (Executar Consultas e Mutações ao adicionar permissões de acesso direto) e, caso utilize o logon único (SSO) como opção de conectividade na API, são necessárias permissões de leitura ou de escrita na fonte de dados escolhida, conforme apropriado. Para obter mais informações, consulte ligar-se a uma fonte de dados e construir o seu esquema.

Criar uma aplicação do Microsoft Entra

Nas etapas a seguir, mostramos como configurar o suporte para um aplicativo ReactJS no Microsoft Entra.

Registre um aplicativo usando as etapas descritas em Guia de início rápido: registrar um aplicativo com a plataforma de identidade da Microsoft.
Os valores de ID do aplicativo Microsoft Entra (cliente) e ID do diretório (locatário) são exibidos na caixa Resumo. Registre esses valores conforme forem necessários posteriormente.
Na lista Gerenciar, selecione permissões de APIe, em seguida, Adicionar permissão.
Adicione o Serviço PowerBI, selecione Permissões delegadas e selecione GraphQLApi.Execute.All permissões. Certifique-se de que o consentimento do administrador não é necessário.
De volta à lista Gerenciar , selecione Autenticação>Adicionar uma plataforma, >Aplicativo de página única.
Para fins de desenvolvimento local, adicione http://localhost:3000 em Redirecionar URIs e confirme se o aplicativo está habilitado para o fluxo de código de autorização com PKCE (Proof Key for Code Exchange). Selecione o botão Configurar para salvar as alterações. Caso o aplicativo receba um erro relacionado a solicitações de origem cruzada, adicione a plataforma de aplicativos móveis e de desktop na etapa anterior com o mesmo URI de redirecionamento.
Voltar à Autenticação, role para baixo até Definições Avançadas e, em Permitir fluxos de clientes públicos, selecione Sim para Ativar os seguintes fluxos móveis e de ambiente de trabalho.

Configurar uma API GraphQL de exemplo para acesso ao aplicativo

Neste exemplo, criamos uma API GraphQL para expor dados de exemplo do Lakehouse aos clientes.

Na página inicial do portal do Fabric, selecione Engenharia de dados na lista de cargas de trabalho.
Na experiência de Engenharia de Dados, selecione Usar uma amostra e, em Lakehouse, selecione Feriados públicos para criar automaticamente uma nova Lakehouse com dados de feriados.
Seguindo as etapas de Criar uma API para GraphQL, crie uma nova API GraphQL e selecione o Lakehouse que você criou. Adicione a tabela de feriados para permitir que os clientes acessem esses dados.

Teste a API GraphQL no editor de API usando a consulta de exemplo a seguir. É a mesma consulta que usamos em nosso aplicativo cliente React:

 query {
   publicholidays (filter: {countryRegionCode: {eq:"US"}, date: {gte: "2024-01-01T00:00:00.000Z", lte: "2024-12-31T00:00:00.000Z"}}) {
     items {
       countryOrRegion
       holidayName
       date
     }
   }
 }

Selecione Copiar ponto de extremidade na barra de ferramentas do item da API.
Na tela Copiar link, selecione Copiar.
Como a ID do Cliente e a ID do Locatário do aplicativo Microsoft Entra registradas anteriormente, copie o URI do ponto de extremidade conforme necessário posteriormente.

Configurar um aplicativo React para acessar a API de feriados

Observação

Se preferires pular as próximas etapas manuais, podes clonar o repositório GitHub com a aplicação completa, depois de seguires o passo 3 para adicionar detalhes específicos sobre o teu ponto de extremidade GraphQL e IDs do Microsoft Entra.

Usamos um aplicativo React existente como ponto de partida. Siga todas as etapas no tutorial Criar um aplicativo de página única React e prepare-o para autenticação para criar um projeto React com a autenticação Microsoft Entra já configurada, incluindo arquivos e pastas adicionais necessários para serem adicionados à estrutura do projeto. Só precisamos alterar três arquivos para adaptar o aplicativo para o nosso caso de uso do GraphQL.

Na pasta src, abra o arquivo authConfig.js e substitua o conteúdo do arquivo pelo seguinte trecho de código:

 /*
  * Copyright (c) Microsoft Corporation. All rights reserved.
  * Licensed under the MIT License.
  */

 import { LogLevel } from "@azure/msal-browser";

 /**
  * Configuration object to be passed to MSAL instance on creation. 
  * For a full list of MSAL.js configuration parameters, visit:
  * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/configuration.md 
  */

 export const graphqlConfig = {
     graphqlEndpoint: "`Enter_the_GraphQL_Endpoint_Here"
 };

 export const msalConfig = {
     auth: {
         clientId: "Enter_the_Application_Id_Here",
         authority: "https://login.microsoftonline.com/Enter_the_Tenant_Info_Here",
         redirectUri: "http://localhost:3000",
     },
     cache: {
         cacheLocation: "sessionStorage", // This configures where your cache will be stored
         storeAuthStateInCookie: false, // Set this to "true" if you are having issues on IE11 or Edge
     },
     system: {	
         loggerOptions: {	
             loggerCallback: (level, message, containsPii) => {	
                 if (containsPii) {		
                     return;		
                 }		
                 switch (level) {
                     case LogLevel.Error:
                         console.error(message);
                         return;
                     case LogLevel.Info:
                         console.info(message);
                         return;
                     case LogLevel.Verbose:
                         console.debug(message);
                         return;
                     case LogLevel.Warning:
                         console.warn(message);
                         return;
                     default:
                         return;
                 }	
             }	
         }	
     }
 };

 /**
  * Scopes you add here will be prompted for user consent during sign-in. 
  * By default, MSAL.js will add OIDC scopes (openid, profile, email) to any login request.
  * For more information about OIDC scopes, visit: 
  * https://docs.microsoft.com/azure/active-directory/develop/v2-permissions-and-consent#openid-connect-scopes
  */
 export const loginRequest = {
     scopes: ["https://analysis.windows.net/powerbi/api/GraphQLApi.Execute.All"]
 };

 /**
  * Add here the scopes to request when obtaining an access token for MS Graph API. For more information, see:
  * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/resources-and-scopes.md
  */
 export const graphConfig = {
     graphMeEndpoint: "https://graph.microsoft.com/v1.0/me",
 };

Como você pode ver no código acima, é importante usar o escopo correto para acessar o aplicativo. No nosso caso https://analysis.windows.net/powerbi/api/GraphQLApi.Execute.All.

Substitua os seguintes valores pelos valores do centro de administração do Microsoft Entra.
- clientId - O identificador da aplicação, também referido como o cliente. Substitua Enter_the_Application_Id_Here pelo valor de ID do aplicativo (cliente) que foi registrado anteriormente na página de visão geral do aplicativo Microsoft Entra registrado.
- authority - Este é composto por duas partes:
  - A instância é o ponto de extremidade do provedor de nuvem. Verifique com os diferentes pontos finais disponíveis em Nuvens nacionais.
  - O ID do Locatário é o identificador do locatário onde o aplicativo está registrado. Substitua Enter_the_Tenant_Info_Here pelo valor de ID do diretório (locatário) que foi registrado anteriormente na página de visão geral do aplicativo registrado.
- graphQLEndpoint - A API de malha para o endpoint GraphQL. Substitua Enter_the_GraphQL_Endpoint_Here pelo ponto de extremidade da API GraphQL registrado anteriormente.
Guarde o ficheiro.

Na mesma pasta src , abra o arquivo App.js e substitua o conteúdo do arquivo pelo seguinte trecho de código:

 import React, { useState } from 'react';
 import { PageLayout } from './components/PageLayout';
 import { loginRequest, graphqlConfig } from './authConfig';
 import { ProfileData } from './components/ProfileData';
 import { AuthenticatedTemplate, UnauthenticatedTemplate, useMsal } from '@azure/msal-react';
 import './App.css';
 import Button from 'react-bootstrap/Button';
 import Spinner from 'react-bootstrap/Spinner';

 /**
 * Renders information about the signed-in user or a button to retrieve data about the user
 */
 const ProfileContent = () => {
   const { instance, accounts } = useMsal();
   const [graphqlData, setGraphqlData] = useState(null);
   const [display, setDisplay] = useState(false);

   function RequestGraphQL() {
       // Silently acquires an access token which is then attached to a request for GraphQL data
       instance
           .acquireTokenSilent({
               ...loginRequest,
               account: accounts[0],
           })
           .then((response) => {
               callGraphQL(response.accessToken).then((response) => setGraphqlData(response));
           });
   }

 async function callGraphQL(accessToken) {
   setDisplay(true);
   const query = `query {
     publicholidays (filter: {countryRegionCode: {eq:"US"}, date: {gte: "2024-01-01T00:00:00.000Z", lte: "2024-12-31T00:00:00.000Z"}}) {
       items {
         countryOrRegion
         holidayName
         date
       }
     }
   }`;
   fetch(graphqlConfig.graphqlEndpoint, {
           method: 'POST',
           headers: {
               'Content-Type': 'application/json',
               'Authorization': `Bearer ${accessToken}`,
           },
           body: JSON.stringify({ 
               query: query
           })
       })
       .then((res) => res.json())
       .then((result) => setGraphqlData(result));
 }

   return (
       <>
           <h5 className="card-title">Welcome {accounts[0].name}</h5>
           <br/>
           {graphqlData ? (
               <ProfileData graphqlData={graphqlData} />
           ) : (
               <Button variant="primary" onClick={RequestGraphQL}>
                   Query Fabric API for GraphQL Data 
                   {display ? (
                         <Spinner
                             as="span"
                             animation="border"
                             size="sm"
                             role="status"
                             aria-hidden="true"
                         />
                     ) : null}
               </Button>
           )}
       </>
   );
 };

 /**
 * If a user is authenticated the ProfileContent component above is rendered. Otherwise a message indicating a user is not authenticated is rendered.
 */
 const MainContent = () => {
   return (
       <div className="App">
           <AuthenticatedTemplate>
               <ProfileContent />
           </AuthenticatedTemplate>

           <UnauthenticatedTemplate>
               <h5>
                   <center>
                       Please sign-in to see your profile information.
                   </center>
               </h5>
           </UnauthenticatedTemplate>
       </div>
   );
 };

 export default function App() {
   return (
       <PageLayout>
           <center>
               <MainContent />
           </center>
       </PageLayout>
   );
 }

Guarde o ficheiro.

Finalmente, na pasta src/components , abra o arquivo ProfileData.jsx e substitua o conteúdo do arquivo pelo seguinte trecho de código:

 import React from "react";
 import ListGroup from 'react-bootstrap/ListGroup'; 
 import Table from 'react-bootstrap/Table';
 /**
  * Renders information about the user obtained from MS Graph 
  * @param props
  */
 export const ProfileData = (props) => {
   const holidays = props.graphqlData.data.publicholidays.items;
   return (
     <Table striped bordered hover responsive>
     <thead>
       <tr>
         <th>Country</th>
         <th>Holiday</th>
         <th>Date</th>
       </tr>
     </thead>
     <tbody>
       {holidays.map((item,i) => (
       <tr key={i}>
         <td>{item.countryOrRegion}</td>
         <td>{item.holidayName}</td>
         <td>{item.date}</td>
       </tr>
       ))}
       </tbody>
     </Table>
 )};

Salve todas as alterações do arquivo.
No aplicativo de terminal de sua escolha, vá para a pasta raiz do projeto React e execute o comando npm start para testar o aplicativo localmente.
Depois que o aplicativo for carregado em seu navegador a partir do http://localhost:3000, siga as etapas na última parte do tutorial : Chame a API do aplicativo para autenticar.
Depois de entrar, clique no botão Query Fabric API for GraphQL Data.
Uma solicitação autenticada bem-sucedida para a API do GraphQL no Fabric retorna os dados da consulta do GraphQL para o Lakehouse em nosso aplicativo cliente React:

Outras linguagens

Encontre C#, Python e outros exemplos de linguagem para se conectar à API do GraphQL no repositório GitHub de exemplos do Microsoft Fabric.

Partilhar via

Conecte aplicativos à API de malha para GraphQL

Pré-requisitos

Criar uma aplicação do Microsoft Entra

Configurar uma API GraphQL de exemplo para acesso ao aplicativo

Configurar um aplicativo React para acessar a API de feriados

Outras linguagens

Conteúdos relacionados

Comentários

Recursos adicionais