Criar uma API para 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 do GraphQL

A criação de APIs do GraphQL no Fabric foi projetada para:

• Engenheiros de dados expondo dados do Fabric lakehouse e data warehouse por meio de APIs modernas para uso em aplicativos
• Colaboradores do workspace do Fabric que desejam criar rapidamente APIs de acesso a dados sem gravar código de back-end
• Desenvolvedores de BI criando aplicativos de análise personalizados que precisam de acesso programático aos dados do Fabric
• Desenvolvedores de integração criando camadas de acesso a dados para aplicativos personalizados e fluxos de trabalho automatizados
• Equipes de desenvolvimento que preferem a abordagem flexível e segura do GraphQL em vez de conexões diretas de banco de dados

Use este guia quando precisar criar uma nova API do GraphQL que exponha seus dados do Fabric Lakehouse, warehouse ou banco de dados para aplicativos.

Pré-requisitos

Para criar uma API para GraphQL, você precisa:

Suas permissões:

• Ser membro do workspace do Fabric em que você deseja criar a API
• Ter pelo menos a função de Colaborador nesse ambiente de trabalho (ou superior: Administrador, Membro)

Configuração organizacional:

• Um administrador do Fabric ou administrador de capacidade deve habilitar a configuração de locatário "Os usuários podem criar itens do Fabric"

  

• O workspace deve ser apoiado por uma capacidade do Fabric (capacidade Premium, Teste ou Fabric)

Acesso à fonte de dados (para etapas posteriores):

• Ler permissões nas fontes de dados que você planeja expor por meio da API do GraphQL
• As permissões podem ser concedidas por meio da associação ao espaço de trabalho ou de permissões diretas de fonte de dados.
• Neste guia, usamos um endpoint de análise SQL do AdventureWorks vinculado a um banco de dados espelhado como uma fonte de dados de exemplo. Para obter os dados de exemplo do AdventureWorks, consulte carregar dados de exemplo do AdventureWorks em seu banco de dados SQL.

Criando uma API para GraphQL

Para criar uma API para o GraphQL:

1. Acesse o portal https://fabric.microsoft.com do Fabric e entre com sua conta organizacional.

2. Selecione um workspace no qual você deseja criar a API e selecione Novo item. No painel aberto, em Desenvolver dados, selecione API para GraphQL.

   

3. Insira um nome para o novo item da API para GraphQL e selecione Criar.

Agora você tem um endpoint de API do GraphQL ativo no Fabric. Neste ponto, você pode copiar a URL do ponto de extremidade do portal do Fabric, selecionar Gerar código para obter exemplos de código e a API está pronta para receber solicitações. Na próxima seção, conectaremos fontes de dados para criar seu esquema, mas o ponto de extremidade em si já está funcional.

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

Neste ponto, o endpoint da API está pronto, mas ainda não expõe nenhum dado. 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 do GraphQL.

Para conectar uma fonte de dados e criar seu esquema:

1. Verifique se você selecionou o novo item da API do GraphQL em seu workspace.

2. Em Adicionar dados à API para GraphQL , selecione o bloco 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 do GraphQL com base em duas opções distintas:

   • Logon único (SSO): você pode usar as credenciais do cliente para se conectar a fontes de dados. O usuário de API autenticado deve ter acesso às tabelas subjacentes na fonte de dados.

     Por exemplo, se você estiver expondo dados do Lakehouse aos seus clientes de API, o usuário autenticado precisará ter acesso à API e ao Lakehouse. Mais especificamente, permissões de Execução para a API GraphQL (opção 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 necessário. Como alternativa, o usuário pode ser adicionado como membro do workspace com uma função de colaborador em que os itens da API e da fonte de dados estão localizados, o que fornece o acesso necessário a ambos os itens de um único local. Para obter mais informações, consulte Conceder aos usuários acesso a espaços de trabalho.

   • Credenciais salvas: você pode usar credenciais salvas para se conectar a fontes de dados. O usuário de API autenticado 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 você estiver expondo dados do Lakehouse aos clientes de API, o usuário autenticado precisará 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 de API autenticados. Essa opção será necessária se você estiver expondo uma fonte de dados do Azure, como um banco de dados SQL do Azure por meio do GraphQL.

   Depois de selecionadas, essas opções são impostas para todas as fontes de dados adicionadas posteriormente à API. Não é possível misturar credenciais de logon único e salvas na mesma API. Você pode usar UPNs (Nomes de Entidade de Usuário) ou SPNs (Nomes de Entidade de Serviço) para se conectar à API, usando SSO ou credenciais salvas, dependendo de seus requisitos de segurança.

   Para obter um detalhamento dos requisitos de permissão para diferentes cenários de autenticação, consulte o resumo de autenticação e permissões.

   Observação

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

4. No catálogo do OneLake, escolha a fonte de dados à qual você deseja se conectar. Selecione Filtro 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 vinculado a um banco de dados espelhado que contém os dados de exemplo do AdventureWorks.

5. Se você selecionou credenciais salvas anteriormente e, se não houver uma credencial salva para sua API do GraphQL já em vigor, será solicitado que você crie uma nova credencial salva.

6. A página Escolher dados é exibida, em que você pode escolher quais objetos você deseja expor em seu esquema GraphQL.

7. Selecione as caixas de seleção ao lado das tabelas individuais, exibições ou procedimentos armazenados 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 de esquema do GraphQL.

9. O esquema é gerado e você pode iniciar a criação de consultas GraphQL (leitura, lista) ou mutações (criar, atualizar, excluir) para interagir com seus dados.

   

   Dica

   Insira Ctrl/Cmd + barra de espaços para obter sugestões ao escrever suas consultas no editor.

   Para obter mais informações sobre como usar o editor de API, consulte o editor da API do Fabric para GraphQL.

Resumo

É isso! Você criou com êxito uma API do GraphQL no Fabric, conectou sua fonte de dados e gerou um esquema. Sua API agora está pronta para aceitar conexões e solicitações de aplicativos cliente. Você pode usar o editor de API para testar e protótipo de consultas GraphQL e usar o Gerenciador de Esquemas para verificar os tipos de dados e os campos expostos na API.

Conteúdo relacionado

• API do Fabric para editor GraphQL
• API do Fabric para GraphQL: visualização de esquema e explorador de esquemas