Criar uma API para o GraphQL no Fabric e adicionar dados

Comece a usar a API de malha para GraphQL criando uma API e, em seguida, vinculando uma fonte de dados para expor os dados escolhidos por meio da API. O Fabric cria o esquema GraphQL automaticamente com base em seus dados, e os aplicativos estão prontos para se conectar em minutos.

Quem deve criar APIs GraphQL

Criar APIs GraphQL no Fabric é concebido para:

• Engenheiros de dados a expor dados Fabric de lagos e armazéns através de APIs modernas para consumo de aplicações
• Colaboradores do Fabric Workspace que querem criar rapidamente APIs de acesso a dados sem escrever código backend
• Desenvolvedores de BI a construir aplicações de análise personalizadas que necessitam de acesso programático a dados Fabric
• Desenvolvedores de integração a criar camadas de acesso a dados para aplicações personalizadas e fluxos de trabalho automatizados
• Equipas de desenvolvimento que preferem a abordagem flexível e segura para tipos do GraphQL em vez de ligações diretas à base de dados

Use este guia quando precisar de criar uma nova API GraphQL que exponha os dados do seu lakehouse, data warehouse ou base de dados Fabric para aplicações.

Pré-requisitos

Para criar uma API para o GraphQL, precisa de:

As suas permissões:

• Sê membro do espaço de trabalho Fabric onde queres criar a API
• Ter pelo menos o papel de Colaborador nesse espaço de trabalho (ou superior: Administrador, Membro)

Configuração organizacional:

• Um administrador Fabric ou administrador de capacidade deve ativar a definição de tenant "Os utilizadores podem criar itens Fabric"

  

• O espaço de trabalho deve ser suportado por uma capacidade Fabric (Premium, Trial ou Fabric)

Acesso à fonte de dados (para passos posteriores):

• Permissões de leitura sobre as fontes de dados que planeia expor através da API GraphQL
• As permissões podem ser concedidas através da adesão ao espaço de trabalho ou permissões diretas de fontes de dados
• Neste guia, usamos um endpoint de análise SQL do AdventureWorks ligado a uma base de dados espelhada como fonte de dados de exemplo. Para obter os dados de exemplo do AdventureWorks, consulte Carregar dados de exemplo do AdventureWorks na sua base de dados SQL.

Criando uma API para o GraphQL

Para criar uma API para o GraphQL:

1. Vai ao portal Fabric em https://fabric.microsoft.com e inicia sessão com a tua conta organizacional.

2. Selecione um espaço de trabalho onde queira criar a API e depois selecione Novo item. No painel que se abre, em Desenvolver dados, selecione API para GraphQL.

   

3. Introduza um Nome para a sua nova API para o item GraphQL e selecione Criar.

Agora tens um endpoint ativo da API GraphQL no Fabric. Neste ponto, pode copiar a URL do endpoint do portal Fabric, selecionar Gerar código para obter exemplos de código, e a API estará pronta para receber pedidos. Na secção seguinte, vamos ligar fontes de dados para construir o seu esquema, mas o próprio endpoint já está funcional.

Conectar-se a uma fonte de dados e criar seu esquema

Neste momento, o endpoint da API está pronto, mas ainda não está a expor quaisquer dados. APIs para GraphQL são definidas em um esquema organizado em termos de tipos e campos, em um sistema fortemente tipado. O Fabric gera automaticamente o esquema GraphQL necessário com base nos dados que você escolhe expor aos clientes GraphQL.

Para ligar uma fonte de dados e construir o seu esquema:

1. Certifique-se de que selecionou o novo item da API GraphQL no seu espaço de trabalho.

2. Em Adicionar dados à API para GraphQL selecione o painel Selecionar fonte de dados.

   

3. Em seguida, selecione a opção de conectividade para sua API:

   

   Aqui você pode definir como os clientes de API podem acessar a API para executar solicitações GraphQL com base em duas opções distintas:

   • Single log-on (SSO): Pode usar as credenciais do cliente para se ligar a fontes de dados. O utilizador autenticado da API deve ter acesso às tabelas subjacentes na fonte de dados.

     Por exemplo, se você estiver expondo dados do Lakehouse para seus clientes de API, o usuário autenticado precisará ter acesso à API e ao Lakehouse. Mais especificamente, permissões para Executar na API GraphQL (Executar Consultas e Mutações ao adicionar permissões de acesso direto) e permissões de leitura ou gravação necessárias na fonte de dados escolhida, conforme adequado. Alternativamente, o utilizador pode ser adicionado como membro do espaço de trabalho com um papel de contribuidor , onde tanto a API como os itens da fonte de dados estão localizados, o que proporciona o acesso necessário a ambos os itens a partir de uma única localização. Para obter mais informações, consulte Conceder aos usuários acesso a espaços de trabalho.

   • Credenciais guardadas: Pode usar as credenciais guardadas para se ligar a fontes de dados. O utilizador autenticado da API não precisa de acesso direto aos dados. Uma credencial salva é compartilhada para acessar os dados entre a API e as tabelas subjacentes na fonte de dados.

     Por exemplo, se estiver a expor dados do Lakehouse aos seus clientes API, o utilizador autenticado só precisa de ter acesso direto à API (opção Executar Consultas e Mutações ao adicionar permissões de acesso direto) e não ao Lakehouse. Uma credencial salva é usada para conectar a API à fonte de dados e é compartilhada por todos os usuários autenticados da API. Essa opção é necessária se você estiver expondo uma fonte de dados do Azure, como um banco de dados SQL do Azure por meio do GraphQL.

   Uma vez selecionadas, estas opções são aplicadas para todas as fontes de dados adicionadas posteriormente à API. Não é possível misturar logon único e credenciais salvas na mesma API. Pode usar Nomes Principais de Utilizador (UPNs) ou Nomes Principais de Serviço (SPNs) para se ligar à sua API, usando SSO ou credenciais guardadas, dependendo dos seus requisitos de segurança.

   Para uma divisão detalhada dos requisitos de permissões para diferentes cenários de autenticação, consulte Resumo de Autenticação e permissões.

   Nota

   A API para GraphQL requer que os aplicativos cliente usem o Microsoft Entra ID para autenticação. Seu aplicativo cliente deve ser registrado e configurado adequadamente para executar chamadas de API no Fabric. O aplicativo registrado no Microsoft Entra ID requer permissões de API GraphQLApi.Execute.All para o serviço do Power BI. Você pode encontrar um tutorial completo com instruções e código de exemplo para entidades de usuário e entidades de serviço em Connect Applications.

4. No catálogo OneLake, escolha a fonte de dados a que pretende ligar-se. Selecione Filtrar para ver apenas tipos específicos de fontes de dados do Fabric ou pesquise por uma palavra-chave específica. Quando estiver pronto, selecione Conectar.

   

   Neste exemplo, escolhemos um endpoint de análise SQL ligado a uma base de dados espelhada que contém os dados de exemplo do AdventureWorks.

5. Se selecionou Credenciais Guardadas anteriormente, e se não houver uma credencial guardada para a sua API GraphQL já implementada, será solicitado a criar uma nova credencial guardada.

6. Aparece a página Escolher dados , onde pode escolher quais os objetos que quer expor no seu esquema GraphQL.

7. Marque as caixas de seleção ao lado das tabelas, exibições ou procedimentos armazenados individuais que você deseja expor na API. Para selecionar todos os objetos em uma pasta, marque a caixa de seleção com o nome da fonte de dados na parte superior.

   

8. Selecione Carregar para iniciar o processo de geração do esquema GraphQL.

9. O esquema é gerado e você pode começar a prototipar consultas GraphQL (ler, listar) ou mutações (criar, atualizar, excluir) para interagir com seus dados.

   

   Sugestão

   Introduza Ctrl/Cmd + barra de espaço para obter sugestões enquanto escreves as tuas consultas no editor.

   Para mais informações sobre a utilização do editor de APIs, consulte Fabric API para o editor GraphQL.

Resumo

É isso! Criou com sucesso uma API GraphQL no Fabric, ligou a sua fonte de dados e gerou um esquema. A sua API está agora pronta para aceitar ligações e pedidos de aplicações clientes. Pode usar o editor de API para testar e prototipar consultas GraphQL, e usar o explorador de esquemas para verificar os tipos de dados e campos expostos na API.

Conteúdos relacionados

• API de malha para editor GraphQL
• API de malha para visualização de esquema GraphQL e explorador de esquema