Trabalhar com dados do cliente no Fabric

O Microsoft Fabric OneLake é um data lake lógico unificado para toda a organização, projetado para ser o único local para todos os dados de análise. Ele vem automaticamente com cada cliente do Microsoft Fabric e é construído sobre o Azure Data Lake Storage (ADLS) Gen2. O OneLake oferece suporte a qualquer tipo de arquivo, estruturado ou não, e armazena todos os dados tabulares no formato Delta Parquet. Ele permite a colaboração em diferentes grupos de negócios fornecendo um único data lake que é regido por padrão com a propriedade distribuída para colaboração dentro dos limites de um locatário. Os espaços de trabalho em um locatário permitem que diferentes partes da organização distribuam políticas de propriedade e acesso, e todos os dados no OneLake são acessados por meio de itens de dados, como Lakehouses e Warehouses. Em termos de armazenamentos de dados, o OneLake serve como o local de armazenamento comum para ingestão, transformação, insights em tempo real e visualizações de Business Intelligence. Ele centraliza os diferentes serviços do Fabric e é o armazenamento para itens de dados consumidos por todas as cargas de trabalho no Fabric.

o Microsoft Fabric Eventhouse fornece uma solução escalonável para lidar e analisar grandes volumes de dados, especialmente em cenários de análise em tempo real. Os eventhouses gerenciam com eficiência fluxos de dados em tempo real, permitindo que as organizações ingeram, processem e analisem dados quase em tempo real. Eles são ideais para cenários que exigem insights oportunos e são o mecanismo preferencial para análise de texto semiestruturado e gratuito. Um Eventhouse é um workspace de bancos de dados que pode ser compartilhado entre projetos, otimizando o desempenho e o custo gerenciando vários bancos de dados ao mesmo tempo. Os eventhouses dão suporte a dados de várias fontes e formatos, indexando e particionando dados automaticamente com base no tempo de ingestão.

Como ler e gravar dados no Microsoft Fabric

O Microsoft Fabric é uma plataforma que permite o armazenamento e o gerenciamento de dados dos clientes. Para ler e gravar dados no Fabric, você precisa usar as APIs REST do Fabric e os métodos de autenticação apropriados.

Permissões da API

Alguns métodos de acesso aos dados do cliente exigem o uso de outros serviços fora do Fabric, como o Armazenamento do Azure ou o Banco de Dados SQL do Azure. Por exemplo, no exemplo do kit de desenvolvedor do Microsoft Fabric, a permissão de API user_impersonation do Armazenamento do Azure é usada em conjunto com a permissão Lakehouse.Read.All do serviço do Power BI para acessar dados de Lakehouses.

Você pode usar o Banco de Dados SQL do Azure para acessar dados de tabela de itens do Warehouse. Nesse caso, configure seu aplicativo com o Banco de Dados SQL do Azure user_impersonation para consultar o banco de dados em nome do usuário, e o serviço do Power BI Warehouse.Read.All para consultar o ponto de extremidade Get Warehouse da API REST do Fabric.

Certifique-se de configurar seu aplicativo do Microsoft Entra ID de acordo com suas necessidades de desenvolvimento.

Autenticação

Antes de começar a usar as APIs REST do Fabric ou outros serviços, como o Armazenamento do Azure e o Banco de Dados SQL do Azure, em nome do usuário, você precisa se autenticar usando um token. Esse token pode ser obtido através de um processo de troca de tokens.

O SDK do Kit de Desenvolvimento de Carga de Trabalho do Fabric fornece um método para adquirir um token de acesso no front-end da carga de trabalho. Por exemplo, veja Controlador de Carga de Trabalho de Exemplo.

Esse token de cliente deve ser passado para o back-end da carga de trabalho e trocado usando o fluxo On-Behalf-Of de um token com os escopos necessários para acessar o recurso desejado, como o OneLake. Por exemplo, para acessar e ler de um Lakehouse, um usuário deve autorizar o aplicativo a fazer chamadas de API em seu nome, usando a permissão user_impersonation do Armazenamento do Azure. Em seguida, no back-end, o token de acesso deve ser obtido com o escopo delegado https://storage.azure.com/user_impersonation para usar o Armazenamento do Microsoft Azure.

Se você decidir usar o SQL para acessar os dados do cliente, o token de acesso deverá ser obtido com o escopo https://database.windows.net//user_impersonation para usar o Banco de Dados SQL do Azure e o namespace Microsoft.Data.SqlClient. O token de acesso deve ser usado como escrito, com duas barras "/" antes de user_impersonation, para ser validado pela classe SQLConnection. Para obter mais exemplos de autenticação de token, confira o exemplo do kit de desenvolvedor do Microsoft Fabric.

Mais detalhes sobre como obter um token podem ser encontrados na documentação da API REST do Kit de desenvolvimento de carga de trabalho do Microsoft Fabric.

Ler metadados

As APIs REST do Fabric fornecem uma maneira de acessar as propriedades dos itens. Por exemplo, consultar a API Get Lakehouse fornece os metadados de um determinado Lakehouse, incluindo propriedades úteis, como os caminhos OneLake e a cadeia de conexão SQL. Outro ponto de extremidade útil é a API Get Warehouse, que retorna as seguintes informações:

    {
        Id: Guid
        Type: string
        DisplayName: string
        Description: string
        WorkspaceId: Guid
        Properties {
            ConnectionInfo: string
            CreatedDate: DateTime
            LastUpdatedTime: DateTime
        }
    }

Aqui, a propriedade "ConnectionInfo" é o nome de domínio totalmente qualificado (FQDN) do SQL Server do Warehouse. Com esse FQDN, você pode estabelecer uma conexão de SQL. Para obter mais informações: confira Conectividade com armazenamento de dados no Microsoft Fabric. Para obter exemplos de implementação, confira o Kit de desenvolvimento de carga de trabalho do Microsoft Fabric.

Lendo dados

Depois de autenticar, você pode se conectar ao OneLake usando as APIs REST do Armazenamento do Azure Data Lake para ler diferentes tipos de dados. Recomendamos utilizar o protocolo Delta Lake para ler tabelas.

Como alternativa, caso opte por utilizar o Banco de Dados SQL do Azure, você poderá implementar o procedimento a seguir para ler dados de um Warehouse.

Crie um contexto de autorização. Para obter um exemplo de criação de um contexto de autorização, confira o método AuthenticateDataPlaneCall.
Adquira um token com o escopo Warehouse.Read.All em nome do usuário usando o token de portador passado do front-end.
Use o token do Fabric para chamar a API Get Warehouse. É necessário acessar as informações de conexão e o nome de exibição do Warehouse, que é o catálogo inicial do servidor.
Adquira um token com escopos SQL em nome do usuário. Para estabelecer com êxito uma conexão de SQL, use o escopo https://database.windows.net//user_impersonation.

Use o token de SQL e as informações de conexão para abrir uma conexão de SQL:

private SqlConnection GetSqlConnection(string token, string databaseFqdn, string initialCatalog)
        {
            var builder = new SqlConnectionStringBuilder();
            builder.DataSource = databaseFqdn; // ConnectionInfo from Get Warehouse API
            builder.InitialCatalog = initialCatalog; //display name of the Warehouse
            builder.ConnectTimeout = 120;

            var connection = new SqlConnection();
            connection.AccessToken = token; // SQL token acquired with the Azure SQL Database user_impersonation scope
            connection.ConnectionString = builder.ConnectionString;
            connection.Open();
            return connection;
        }

Essa conexão agora pode ser consultada para acessar dados do Warehouse. Para obter mais informações sobre como utilizar o namespace Microsoft.Data.SqlClient, confira a documentação do namespace Microsoft.Data.SqlClient.

Eventhouse API

Depois de autenticar, você pode executar ações como criar o Eventhouse, excluir o Eventhouse, obter uma lista de Eventhouses etc. Uma maneira de fazer isso é usando o portal – visão geral do Eventhouse.

A outra maneira é usar a API REST do Eventhouse – Visão Geral da API REST do Eventhouse.

Autorizar.
Adquira um token com o escopo FabricEventhouse.Read.All em nome do usuário usando o token de portador passado do front-end.
Use o token do Fabric para chamar a API Get Eventhouse.
Agora, com uma lista dos Bancos de Dados do Eventhouse, você pode consultar o banco de dados específico desejado, conforme descrito na seção de dados de consulta abaixo.

Consultar dados

Para consultar dados de um Banco de Dados KQL do Eventhouse, siga estas etapas: primeiro, autentique-se usando o método apropriado. Em seguida, conecte-se ao Eventhouse para recuperar a lista de bancos de dados. Em seguida, consulte o banco de dados específico que você deseja acessar. É importante distinguir entre comandos de consulta, como .show tablese consultas de dados, como <TableName> | take 10. Para obter a documentação completa sobre a API REST do KQL, confira a documentação da API REST do KQL.

A outra maneira é usar a API REST do Eventhouse – Visão Geral da API REST do Eventhouse.

Autorizar.
Adquira um token com o escopo KQLDatabase.ReadWrite.All em nome do usuário usando o token de portador passado do front-end.
Use o token KQL para chamar a API Rest KQL.

Gravação de dados

Além de ler dados usando o token, você também pode usar APIs do ADLS para gravar dados em tabelas, conforme descrito pelo protocolo Delta Lake.

Você também pode usar as APIs para criar arquivos e diretórios.

Como alternativa, você pode usar outras cargas de trabalho do Fabric para gravar dados na plataforma. Por exemplo, você pode usar a API de carga de trabalho Lakehouse do Fabric para carregar com eficiência tipos de arquivos comuns em uma tabela Delta otimizada. Isso é feito enviando uma solicitação POST para o endpoint da API "Tables - Load Table".

A conexão de SQL também pode ser usada para executar comandos que inserem dados em tabelas.

Integração do OneLake

Você pode optar por usar a integração do OneLake em suas cargas de trabalho. Se você fizer isso, quando um novo item for criado para sua carga de trabalho, o Fabric criará automaticamente pastas para o novo item.

Para optar por isso, o XML do manifesto do item deve declarar essa configuração definindo o atributo CreateOneLakeFoldersOnArtifactCreation como true. Por exemplo:

<ItemManifestConfiguration xmlns:xsi= "http://www.w3.org/2001/XMLSchema-instance" SchemaVersion="1.101.0">  
  <Item TypeName="Org.WorkloadSample.SampleWorkloadItem" Category="Data" CreateOneLakeFoldersOnArtifactCreation="true">
    <Workload WorkloadName="Org.WorkloadSample" />
    ...
  </Item>
</ItemManifestConfiguration>

Observação

SchemaVersion deve ser definido como 1.101.0 (ou versões posteriores com suporte).

O mesmo SchemaVersion deve ser definido em WorkloadManifest.xml:

<WorkloadManifestConfiguration xmlns:xsi= "http://www.w3.org/2001/XMLSchema-instance" SchemaVersion="1.101.0">
  <Workload WorkloadName="Org.WorkloadSample" HostingType="Remote">
  ...
  </Workload>
</WorkloadManifestConfiguration>

Quando um novo item é criado, as seguintes pastas raiz são criadas no OneLake:

<WorkspaceID>/<ItemID>/Files

<WorkspaceID>/<ItemID>/Tables

Você pode criar pastas adicionais com elas e usá-las para armazenar dados em qualquer formato (em Files pasta) ou no formato parquet (em Tables pasta). Siga as instruções acima para ler/gravar do armazenamento do OneLake.

Kit de Desenvolvimento de Cargas de Trabalho do Microsoft Fabric

Comentários

Esta página foi útil?

Last updated on 2025-10-23