Compartilhar via

Conectar aplicativos à API do Fabric para GraphQL

Conectar aplicativos à API do Fabric para GraphQL permite que seus aplicativos Web, móveis e back-end consultem fontes de dados do Fabric usando uma API moderna e eficiente. Essa integração requer autenticação adequada por meio da Microsoft Entra ID e da configuração do aplicativo para chamar o endpoint do GraphQL com segurança.

Este artigo explica como conectar um aplicativo React à API do Fabric GraphQL:

  1. Criando e configurando um aplicativo do Microsoft Entra para autenticação
  2. Configurando uma API graphQL de exemplo no Fabric com dados para consultar
  3. Clonagem e configuração de um aplicativo React completo do GitHub
  4. Testando a conexão autenticada

O tutorial usa React, mas os conceitos de autenticação se aplicam a qualquer idioma. Para obter exemplos em C#, Python ou outros idiomas, consulte o repositório GitHub de exemplos do Microsoft Fabric.

Quem precisa conectar aplicativos

A configuração da conexão de aplicativo é essencial para:

  • Desenvolvedores web e móveis criando aplicativos que consomem dados de lakehouses e armazéns do Fabric
  • Desenvolvedores de integração conectando dados do Fabric a aplicativos personalizados e fluxos de trabalho automatizados
  • Desenvolvedores de back-end criando serviços que se integram à plataforma de análise unificada do Fabric
  • Engenheiros de dados configurando fluxos de trabalho automatizados de processamento de dados que consomem dados do Fabric por meio de APIs

Use este guia quando precisar autenticar e autorizar aplicativos a acessar suas APIs do GraphQL do Fabric.

Pré-requisitos

  • Ferramentas de desenvolvimento: você precisa deNode.js (versão LTS) e do Visual Studio Code instalados em seu computador.

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

Resumo de autenticação e permissões

O acesso à API do GraphQL requer autenticação e autorização adequadas no nível da API e no nível da fonte de dados subjacente. Você pode autenticar-se usando um principal de usuário (representando um usuário individual) ou um principal de serviço (representando um aplicativo ou serviço). Para conectividade de fonte de dados, você pode usar o SSO (logon único) em que a identidade do chamador é passada para a fonte de dados ou credenciais salvas em que uma conexão pré-configurada é usada.

A tabela a seguir resume os diferentes cenários de autenticação com suporte e as permissões mínimas necessárias para clientes que acessam a API do GraphQL:

Chamador de API Conectividade da fonte de dados Permissões de API do GraphQL necessárias Permissões de fonte de dados necessárias Escopo do aplicativo Microsoft Entra
Entidade de Segurança do Usuário (UPN) SSO (logon único) Executar consultas e mutações no nível da API Permissões apropriadas de leitura/gravação concedidas ao UPN na fonte de dados GraphQLApi.Execute.All
Entidade de Serviço (SPN) SSO (logon único) Executar consultas e mutações no nível da API Permissões apropriadas de leitura/gravação concedidas ao SPN na fonte de dados Não aplicável
Entidade de Segurança do Usuário (UPN) Credenciais salvas Executar consultas e mutações no nível da API Permissões apropriadas de leitura/gravação concedidas à credencial salva (conexão) na fonte de dados GraphQLApi.Execute.All
Entidade de Serviço (SPN) Credenciais salvas Executar consultas e mutações no nível da API Permissões apropriadas de leitura/gravação concedidas ao SPN na fonte de dados Não aplicável

Criar um aplicativo do Microsoft Entra

Antes que seu aplicativo possa chamar a API do GraphQL do Fabric, você deve registrá-la na ID do Microsoft Entra. Esse registro cria uma identidade para seu aplicativo e define quais permissões ele precisa. O processo de registro gera uma ID do cliente (identificador de aplicativo) e estabelece o fluxo de autenticação que seu aplicativo usa para obter tokens de acesso.

Para aplicativos React, você define configurações de SPA (aplicativo de página única) que usam o fluxo PKCE — um método de autenticação seguro projetado para aplicativos baseados em navegador em que os segredos do cliente não podem ser armazenados com segurança.

  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 você precisa deles ao configurar o aplicativo React.

  3. Configure permissões de API para que seu aplicativo possa acessar a API do GraphQL do Fabric. 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 . Essa permissão permite que seu aplicativo execute consultas e mutações em nome do usuário conectado. 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

Com o aplicativo Microsoft Entra registrado, você precisa de uma API do GraphQL no Fabric para consultar. Esta seção orienta você na criação de uma API de exemplo usando o conjunto de dados de feriados públicos do Fabric. Isso fornece uma API funcional para testar a autenticação e a recuperação de dados sem a necessidade de configurar suas próprias fontes de dados.

A API de exemplo expõe dados de feriados de uma tabela do Lakehouse, que seu aplicativo React consulta para exibir feriados públicos.

  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. Antes de criar o aplicativo React, verifique se sua API funciona corretamente testando-a no editor de API. Use a consulta a seguir: essa é a mesma consulta que o aplicativo React executa mais tarde:

     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. Registre o ID do Cliente, o ID do Locatário do aplicativo Microsoft Entra e o URI do ponto de extremidade. Você precisa desses valores ao configurar o aplicativo React.

Clonar e configurar o aplicativo React

Agora que você tem o aplicativo Microsoft Entra e a API do GraphQL configurados, você pode configurar um aplicativo React para se conectar a eles. O aplicativo usa a MSAL (Biblioteca de Autenticação da Microsoft) para lidar com a autenticação e faz solicitações do GraphQL com tokens de portador.

  1. Clone o repositório de exemplos do GitHub:

    git clone https://github.com/microsoft/fabric-samples.git

  2. Navegue até a pasta do aplicativo React:

    cd fabric-samples/docs-samples/data-engineering/GraphQL/React

    A pasta contém um aplicativo React completo. Você só precisa editar src/authConfig.js para configurar seu endpoint e credenciais específicos.

  3. Abra o projeto no editor de código:

    code .

  4. No editor, navegue até a src pasta e abra authConfig.js.

  5. Substitua os seguintes valores de espaço reservado pelos detalhes específicos:

    Importante

    No mesmo arquivo, a loginRequest constante inclui o escopo https://analysis.windows.net/powerbi/api/GraphQLApi.Execute.All. Esse escopo exato é necessário para acessar APIs do Fabric GraphQL. Não remova ou modifique esse escopo; caso contrário, a autenticação falhará.

  6. Salve o arquivo.

  7. No terminal, navegue até a pasta raiz do projeto e execute:

    npm install

    Isso instala todas as dependências necessárias.

Testar o aplicativo

Com o aplicativo configurado, execute-o localmente para verificar se tudo funciona corretamente:

  1. No terminal, digite:

    npm start

    Esse comando inicia o servidor de desenvolvimento e abre o aplicativo no navegador.

  2. Conclua o fluxo de autenticação quando o aplicativo for carregado em http://localhost:3000. Siga as etapas de entrada descritas na seção tutorial Chamar a API do aplicativo.

  3. Depois de entrar com êxito, selecione o botão API do Query Fabric para Dados do GraphQL . Isso dispara o fluxo de autenticação, adquire um token de acesso e executa a consulta GraphQL em sua API do Fabric.

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

  4. Se tudo estiver configurado corretamente, o aplicativo exibirá feriados públicos em uma tabela. Confirme que o está

    • Seu aplicativo Microsoft Entra tem as permissões corretas
    • O token de acesso foi adquirido com êxito
    • A API do GraphQL autenticou a solicitação
    • A consulta executada nos dados do Lakehouse

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

Outros comandos npm

Além npm start e npm install, você pode usar estes comandos npm comuns para diferentes cenários de desenvolvimento:

  • npm run dev – Maneira alternativa de iniciar o servidor de desenvolvimento
  • npm run build – Criar um build de produção otimizado do seu aplicativo
  • npm run preview – Testar o build de produção localmente antes de implantar
  • npm test – Executar testes automatizados para verificar se o código funciona corretamente

Conteúdo relacionado

Agora que você tem um aplicativo de trabalho conectado à API do GraphQL do Fabric, explore esses recursos para criar soluções mais sofisticadas:

  • Last updated on