Compartilhar via

Conectar aplicativos à API do Fabric para GraphQL

Para conectar um aplicativo a uma API para GraphQL, você precisa de três detalhes principais: uma ID do cliente, sua ID de locatário e seu endereço de ponto de extremidade graphQL no 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.

Outros idiomas

Este tutorial explica como conectar um aplicativo de exemplo do React à API do Fabric para GraphQL. Você encontra exemplos de C#, Python e outros idiomas 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 GraphQL no Fabric 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, confira Criar um aplicativo do Microsoft Entra no Azure.

  • A credencial autenticada (entidade de segurança do usuário, entidade de serviço ou identidade gerenciada) que chama a API precisa executar permissões para a API do GraphQL (opção Executar Consultas e Mutações ao adicionar permissões de acesso direto). Se estiver usando o SSO (logon único) 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 Conectar-se a uma fonte de dados e criar seu esquema.

Criar um aplicativo 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 Início Rápido: Registrar um aplicativo com a plataforma de identidade da Microsoft.

  2. Os valores da ID e da 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 API e, em seguida, Adicionar permissão.

  4. Adicione o Serviço do PowerBI, selecione permissões delegadas e selecione as permissões GraphQLApi.Execute.All . 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 Proof Key for Code Exchange (PKCE). Selecione o botão Configurar para salvar as alterações. Se o aplicativo encontrar um erro relacionado a solicitações entre origens, adicione a plataforma de aplicativos móveis e de área de trabalho na etapa anterior com o mesmo URI de redirecionamento.

  7. De volta a Autenticação, role para baixo até Configurações Avançadas e, em Permitir fluxos de cliente públicos, selecione Sim para Habilitar os fluxos móveis e de área de trabalho a seguir.

Configurar uma API GraphQL de exemplo para acesso a aplicativos

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

  1. Na página inicial do portal 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 públicos.

    Captura de tela sobre como selecionar a opção de dados de exemplo Lakehouse.

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

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

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

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

  6. Na caixa de diálogo Copiar link, selecione Copiar.

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

  7. Use a ID do cliente e a ID do locatário do aplicativo Microsoft Entra gravado anteriormente e copie o URI do ponto de extremidade porque ele é necessário mais tarde.

Configurar um aplicativo React para acessar a API de feriados públicos

Observação

Se preferir ignorar as etapas manuais a seguir, você poderá clonar o repositório GitHub com o aplicativo completo. Siga a etapa 3 para adicionar detalhes específicos sobre o endpoint do GraphQL e as IDs recuperadas do Microsoft Entra ao arquivo authConfig.js, instale as dependências com npm install e pule para a etapa 9 para prosseguir com o teste da execução do aplicativo.

  1. Use um aplicativo React existente como ponto de partida. Siga as etapas no tutorial Criar um aplicativo de página única do React e prepare-o para autenticação para criar um projeto react com a autenticação do 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 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: 
 * [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 valores a seguir pelos valores obtidos do Centro de administração do Microsoft Entra.

    • clientId – o identificador do aplicativo, também conhecido como o cliente. Substitua Enter_the_Application_Id_Here pelo valor da ID do aplicativo(cliente) que foi registrado anteriormente na página de visão geral do aplicativo Microsoft Entra registrado.

    • autoridade - Isso é composto por duas partes:

      • A Instância é o ponto de extremidade do provedor de nuvem. Verifique com os diferentes pontos de extremidade disponíveis em Nuvens nacionais.

      • A ID do Locatário é o identificador do locatário em que o aplicativo está registrado. Substitua Enter_the_Tenant_Info_Here pelo valor da ID do Diretório (locatário) que foi registrado anteriormente na página de visão geral do aplicativo registrado.

    • graphQLEndpoint – O ponto de extremidade da API do Fabric para GraphQL. Substitua Enter_the_GraphQL_Endpoint_Here pelo ponto de extremidade da API GraphQL registrado anteriormente.

  4. Salve o arquivo.

  5. Na mesma src pasta, abra o App.js arquivo e substitua o conteúdo do arquivo pelo seguinte snippet 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. Salve o arquivo.

  7. Por fim, na src/components pasta, abra o ProfileData.jsx arquivo e substitua o conteúdo do arquivo pelo seguinte snippet 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. Depois que o aplicativo for carregado no navegador http://localhost:3000, siga as etapas na última parte do tutorial Chamar a API do aplicativo.

  11. Depois de entrar, selecione no botão API do Query Fabric para Dados do GraphQL.

    Captura de tela do aplicativo de exemplo React após a entrada.

  12. Uma solicitação autenticada bem-sucedida para a API do 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údo relacionado

  • Last updated on