Partilhar via

Conecte aplicativos à API de malha para GraphQL

Para ligar uma aplicação a uma API para GraphQL, são necessários três detalhes essenciais: uma ID do cliente, a sua ID do inquilino e o seu endereço do ponto de extremidade GraphQL em Fabric. As seções a seguir explicam como criar e recuperar os detalhes necessários e acessar sua API usando um aplicativo React de exemplo.

Outras linguagens

Este tutorial explica como conectar um aplicativo de exemplo React à API de malha para GraphQL. Você encontra C#, Python e outros exemplos de linguagem no repositório GitHub de exemplos do Microsoft Fabric.

Pré-requisitos

  • Antes de conectar um aplicativo, verifique se você tem uma API para GraphQL no Fabric. Para obter mais informações, consulte Criar uma API para o GraphQL na malha e adicionar dados.

  • A API para GraphQL requer que os aplicativos usem o Microsoft Entra para autenticação. Registre e configure seu aplicativo para executar chamadas de API no Fabric. Para obter mais informações, consulte Criar um aplicativo Microsoft Entra no Azure.

  • A credencial autenticada (entidade de usuário, entidade de serviço ou identidade gerenciada) que chama a API precisa de permissões de execução para a API GraphQL (opção Executar consultas e mutações ao adicionar permissões de acesso direto). Se estiver usando o logon único (SSO) como a opção de conectividade na API, verifique se a credencial tem permissões de leitura ou gravação na fonte de dados escolhida. 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

As etapas a seguir explicam como configurar o suporte para um aplicativo ReactJS no Microsoft Entra.

  1. Registre um aplicativo usando as etapas descritas em Guia de início rápido: registrar um aplicativo com a plataforma de identidade da Microsoft.

  2. Os valores de ID do Aplicativo (cliente) e ID do Diretório (locatário) do aplicativo Microsoft Entra aparecem na caixa Resumo. Registre esses valores porque eles são necessários posteriormente.

  3. Na lista Gerenciar, selecione permissões de APIe, em seguida, Adicionar permissão.

  4. Adicione o Serviço PowerBI, selecione Permissões delegadas e selecione GraphQLApi.Execute.All permissões. Confirme se o consentimento do administrador não é necessário.

  5. Volte para a lista Gerenciar, selecione Autenticação>Adicionar um> plataforma.

  6. 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. Se o aplicativo encontrar 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.

  7. 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.

  1. Na página inicial do portal do Fabric, selecione Engenharia de dados na lista de cargas de trabalho.

  2. Na experiência de Engenharia de Dados, selecione Usar um exemplo e, em Lakehouse, selecione Feriados públicos para criar automaticamente um novo Lakehouse com dados de feriados.

    Captura de ecrã ao selecionar a opção de dados de exemplo Lakehouse.

  3. Siga as etapas de Criar uma API para GraphQL para criar uma nova API GraphQL e selecione o Lakehouse que você criou. Adicione a tabela de feriados para que os clientes possam acessar esses dados.

    Captura de tela da adição do exemplo Lakehouse como fonte de dados GraphQL.

  4. Teste a API GraphQL no editor de API usando a consulta de exemplo a seguir. É a mesma consulta usada no 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
     }
   }
 }

  5. Selecione Copiar ponto de extremidade na barra de ferramentas do item da API.

    Captura de tela das opções da barra de ferramentas para um item da API.

  6. Na tela Copiar link, selecione Copiar.

    Captura de tela da tela de diálogo Copiar link, mostrando onde selecionar Copiar.

  7. Use o ID do Cliente e o ID do Inquilino do aplicativo Microsoft Entra gravados anteriormente e copie o URI do ponto de extremidade porque é necessário posteriormente.

Configurar um aplicativo React para acessar a API de feriados

Observação

Se preferir ignorar as etapas manuais a seguir, você pode clonar o repositório GitHub com o aplicativo completo. Siga a etapa 3 para adicionar detalhes específicos sobre o seu ponto de extremidade GraphQL e os IDs recuperados do Microsoft Entra ao arquivo authConfig.js, instale as dependências com npm install e avance para a etapa 9 para continuar a testar a execução da aplicação.

  1. Use um aplicativo React existente como ponto de partida. Siga 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 configurada, incluindo os arquivos e pastas necessários adicionados à estrutura do projeto. Altere três arquivos para adaptar o aplicativo para o caso de uso do GraphQL.

  2. Na pasta src, abra o ficheiro authConfig.js e substitua o conteúdo do ficheiro 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: 
 * [OpenID Connect scopes](/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.

  3. Substitua os seguintes valores pelos valores do centro de administração do Microsoft Entra.

    • clientId - O identificador do aplicativo, também conhecido como cliente. Substitua Enter_the_Application_Id_Here pelo valor ID da aplicação (cliente) que foi anotado anteriormente a partir da página de visão geral da aplicação Microsoft Entra registada.

    • Autoridade - É composta 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 de diretório (locatário) que foi registrado anteriormente na página de visão geral do aplicativo registrado.

    • graphQLEndpoint - A API Fabric para o ponto de extremidade GraphQL. Substitua Enter_the_GraphQL_Endpoint_Here pelo ponto de extremidade da API GraphQL registrado anteriormente.

  4. Guarde o ficheiro.

  5. Na mesma src pasta, abra o App.js arquivo 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>
  );
}

  6. Guarde o ficheiro.

  7. Finalmente, na src/components pasta, abra o ProfileData.jsx arquivo 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>CountryOrRegion</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>
)};

  8. Salve todas as alterações do arquivo.

  9. Em seu aplicativo de terminal, vá para a pasta raiz do projeto React e execute o comando npm start para testar o aplicativo localmente.

  10. Assim que o aplicativo for carregado em seu navegador a partir do http://localhost:3000, siga as etapas na última parte do tutorial: Chamar a API do aplicativo.

  11. Depois de entrar, selecione no botão Query Fabric API for GraphQL Data.

    Captura de ecrã da aplicação de exemplo React após iniciar sessão.

  12. Uma solicitação autenticada bem-sucedida para a API GraphQL no Fabric retorna dados da consulta GraphQL para o Lakehouse no aplicativo cliente React:

    Captura de tela do aplicativo de exemplo React depois de receber a solicitação GraphQL.

Conteúdos relacionados

  • Last updated on