Partilhar via

Conecte aplicativos à API de malha para GraphQL

Ligar aplicações à API do Fabric para GraphQL permite que as suas aplicações web, móveis e backend consultem fontes de dados Fabric usando uma API moderna e eficiente. Esta integração requer autenticação adequada através do Microsoft Entra ID e a configuração da sua aplicação para chamar o endpoint GraphQL de forma segura.

Este artigo guia-o como ligar uma aplicação React à API Fabric GraphQL através de:

  1. Criação e configuração de uma aplicação Microsoft Entra para autenticação
  2. Configurar uma API GraphQL de exemplo no Fabric com dados a consultar
  3. Clonagem e configuração de uma aplicação React completa a partir do GitHub
  4. Testar a ligação autenticada

O tutorial usa React, mas os conceitos de autenticação aplicam-se a qualquer linguagem. Para exemplos em C#, Python ou outras linguagens, consulte o repositório Microsoft Fabric Samples GitHub.

Quem precisa de conectar aplicações

A configuração da ligação à aplicação é essencial para:

  • Desenvolvedores web e móveis que criam aplicações que consomem dados de lakehouses e data warehouses do Fabric
  • Desenvolvedores de integração que ligam dados do Fabric a aplicações personalizadas e fluxos de trabalho automatizados
  • Desenvolvedores de backend para criar serviços que se integram com a plataforma unificada de análise da Fabric
  • Engenheiros de dados a configurar fluxos de trabalho automatizados de processamento de dados que consomem dados Fabric através de APIs

Use este guia quando precisar de autenticar e autorizar aplicações para aceder às suas APIs Fabric GraphQL.

Pré-requisitos

  • Ferramentas de desenvolvimento: Precisa de Node.js (versão LTS) e Visual Studio Code instalados na sua máquina.

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

Resumo de autenticação e permissões

O acesso à API GraphQL requer autenticação e autorização adequadas tanto ao nível da API como ao nível da fonte de dados subjacente. Pode autenticar usando um user principal (representando um utilizador individual) ou um service principal (representando uma aplicação ou serviço). Para a conectividade da fonte de dados, pode usar single sign-on (SSO) onde a identidade do chamador é passada através para a fonte de dados, ou credenciais guardadas onde se utiliza uma ligação pré-configurada.

A tabela seguinte resume os diferentes cenários de autenticação suportados e as permissões mínimas necessárias para clientes que acedem à API GraphQL:

Chamador de API Conectividade da origem de dados Permissões necessárias da API do GraphQL Permissões de fonte de dados necessárias Âmbito da aplicação Microsoft Entra
Usuário Principal (UPN) Logon único (SSO) 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) Logon único (SSO) 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
Usuário Principal (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 uma aplicação do Microsoft Entra

Antes de a sua aplicação poder aceder à API Fabric GraphQL, deve registá-la no Microsoft Entra ID. Este registo cria uma identidade para a sua aplicação e define que permissões necessita. O processo de registo gera um ID de Cliente (identificador de aplicação) e estabelece o fluxo de autenticação que a sua aplicação utiliza para obter tokens de acesso.

Para aplicações React, configura-se as definições de aplicação de página única (SPA) que utilizam o fluxo PKCE — um método de autenticação seguro concebido para aplicações baseadas em navegador onde os segredos do cliente não podem ser armazenados em segurança.

  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. Regista estes valores porque precisas deles quando configuras a aplicação React.

  3. Configure as permissões da API para que a sua aplicação possa aceder à API Fabric GraphQL. 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. Esta permissão permite que a sua aplicação execute consultas e mutações em nome do utilizador com sessão iniciada. 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

Com a sua aplicação Microsoft Entra registada, precisa de uma API GraphQL no Fabric para fazer consultas. Esta secção guia-o na criação de uma API de exemplo usando o conjunto de dados de feriados públicos do Fabric. Isto dá-lhe uma API funcional para testar autenticação e recuperação de dados sem precisar de configurar as suas próprias fontes de dados.

A API de exemplo expõe dados de feriados de uma tabela Lakehouse, que a sua aplicação React consulta para mostrar feriados públicos.

  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. Antes de construir a aplicação React, verifique se a sua API funciona corretamente testando-a no editor de APIs. Use a seguinte consulta — esta é a mesma consulta que a sua aplicação 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 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. Regista o ID do Cliente e o ID do Tenant a partir da aplicação Microsoft Entra e do URI do endpoint. Precisas destes valores quando configuras a aplicação React.

Clone e configure a aplicação React

Agora que tens a aplicação Microsoft Entra e a API GraphQL configuradas, podes configurar uma aplicação React para se ligar a eles. A aplicação utiliza a Microsoft Authentication Library (MSAL) para gerir a autenticação e faz pedidos GraphQL com tokens Bearer.

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

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

  2. Navegue até à pasta da aplicação React:

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

    A pasta contém uma aplicação completa do React. Só precisas de editar src/authConfig.js para configurar o teu endpoint e credenciais específicos.

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

    code .

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

  5. Substitua os seguintes valores provisórios pelos seus dados específicos:

    Importante

    No mesmo ficheiro, a loginRequest constante inclui o âmbito https://analysis.windows.net/powerbi/api/GraphQLApi.Execute.All. Este âmbito exato é necessário para aceder às APIs Fabric GraphQL. Não remova nem modifique este escopo; de outro modo, a autenticação falha.

  6. Guarde o ficheiro.

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

    npm install

    Isto instala todas as dependências necessárias.

Testar a aplicação

Com a aplicação configurada, executa-a localmente para verificar se tudo funciona corretamente:

  1. No seu terminal, execute:

    npm start

    Este comando inicia o servidor de desenvolvimento e abre a aplicação no seu navegador.

  2. Complete o fluxo de autenticação quando a aplicação for carregada em http://localhost:3000. Siga os passos de início de sessão descritos na secção do tutorial Chame a API a partir da aplicação.

  3. Após iniciar sessão com sucesso, selecione o botão Query Fabric API para Dados de GraphQL. Isto desencadeia o fluxo de autenticação, adquire um token de acesso e executa a consulta GraphQL na sua API Fabric.

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

  4. Se tudo estiver configurado corretamente, a aplicação mostra os feriados públicos numa tabela. Isto confirma que:

    • A sua aplicação Microsoft Entra tem as permissões corretas
    • O token de acesso foi adquirido com sucesso
    • A API GraphQL autenticou o pedido
    • A consulta foi executada contra os dados de Lakehouse

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

Outros comandos npm

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

  • npm run dev - Forma alternativa de iniciar o servidor de desenvolvimento
  • npm run build - Criar uma build de produção otimizada da sua aplicação
  • npm run preview - Testar a versão de produção localmente antes de implementar
  • npm test - Executar testes automatizados para verificar se o seu código funciona corretamente

Conteúdos relacionados

Agora que tem uma aplicação funcional ligada à sua API Fabric GraphQL, explore estes recursos para construir soluções mais sofisticadas:

  • Last updated on