Работа с данными клиентов в Fabric

Microsoft Fabric OneLake — это единое логическое озеро данных для всей организации, предназначенное для всех аналитических данных. Он поставляется автоматически с каждым клиентом Microsoft Fabric и построен на основе Azure Data Lake Storage (ADLS) 2-го поколения. OneLake поддерживает любой тип файла, структурированного или неструктурированного и сохраняет все табличные данные в формате Delta Parquet. Он обеспечивает сотрудничество между различными бизнес-группами, предоставляя единое озеро данных, управляемое по умолчанию с распределенным владением для совместной работы в пределах границ тенанта. OneLake также поддерживает совместное использование данных между клиентами, что позволяет управлять доступом к общим наборам данных через границы клиента Microsoft Entra. Рабочие области в клиенте позволяют различным частям организации распространять политики владения и доступа, а все данные в OneLake можно получить с помощью таких элементов данных, как Lakehouses и Warehouses. С точки зрения хранилищ данных OneLake служит общим местом хранения для приема, преобразования, аналитики в режиме реального времени и визуализаций бизнес-аналитики. Она объединяет различные службы Fabric и является хранилищем для элементов данных, используемых всеми рабочими процессами в Fabric.

Сочетания клавиш OneLake

Ярлыки OneLake — это встроенные ссылки, указывающие на данные во внешних системах хранения (например, Azure Data Lake Storage, Amazon S3 или Google Cloud Storage) или в других рабочих областях и тенантах Fabric. Ярлыки предоставляют доступ к данным без ETL или миграции данных, обеспечивая доступ с нулем копий и делая ссылочные данные частью локального пространства имен OneLake. Разработчики рабочих нагрузок могут считывать данные, на которые ссылается ярлык, с помощью одних и того же REST API ADLS 2-го поколения, используемых для собственных данных OneLake.

Microsoft Fabric Eventhouse предоставляет масштабируемое решение для обработки и анализа больших объемов данных, особенно в сценариях аналитики в режиме реального времени. Центры событий эффективно управляют потоками данных в режиме реального времени, позволяя организациям получать, обрабатывать и анализировать данные практически в режиме реального времени. Они идеально подходят для сценариев, требующих своевременной аналитики и являются предпочтительным механизмом для полуструктурированного и свободного анализа текста. Eventhouse — это рабочая область баз данных, которые можно совместно использовать в проектах, оптимизируя производительность и затраты, одновременно управляя несколькими базами данных. Центры событий поддерживают данные из нескольких источников и форматов, автоматически индексируя и секционируя данные на основе времени приема.

Чтение и запись данных в Microsoft Fabric

Microsoft Fabric — это платформа, которая позволяет хранить и управлять данными клиентов. Чтобы считывать и записывать данные в Fabric, необходимо использовать REST API Fabric и соответствующие методы проверки подлинности.

Разрешения API

Некоторые методы доступа к данным клиента требуют использования других служб за пределами Fabric, таких как служба хранилища Azure или База данных SQL Azure. Например, в примере пакета средств разработчика Microsoft Fabric разрешение API Azure user_impersonation используется вместе с разрешением Power BI Lakehouse.Read.All для доступа к данным из Lakehouses.

Базу данных SQL Azure можно использовать для доступа к данным таблицы из элементов хранилища. В этом случае настройте приложение с База данных SQL Azure user_impersonation, чтобы запросить базу данных от имени пользователя, и Warehouse.Read.All для запроса конечной точки REST API Get Warehouse.

Убедитесь, что вы настроите приложение Идентификатора Microsoft Entra в соответствии с вашими потребностями разработки.

Для сценариев совместного доступа к данным между клиентами приложение должно пройти проверку подлинности в идентификаторе Microsoft Entra исходного клиента. Убедитесь, что регистрация приложения включает соответствующие делегированные полномочия для исходного арендатора и что владелец данных предоставил разрешения OneLake внешней учетной записи.

Проверка подлинности

Прежде чем начать использовать REST API Fabric или другие службы, такие как служба хранилища Azure и База данных SQL Azure, от имени пользователя, необходимо сначала пройти проверку подлинности с помощью токена. Этот маркер можно получить с помощью процесса обмена токенами.

Пакет SDK для средств разработки Fabric предоставляет метод получения токена доступа во фронтенде рабочей нагрузки. Например, см. Пример контроллера рабочей нагрузки.

Этот клиентский токен должен передаваться в бекенд рабочей нагрузки и обмениваться с использованием потока делегирования от имени для получения токена с необходимыми разрешениями для доступа к нужным ресурсам, таким как OneLake. Например, для доступа и чтения из Lakehouse пользователь должен предоставить приложению авторизацию для выполнения API-вызовов от их имени с помощью разрешения службы хранилища user_impersonation Azure. Затем в серверной части нужно получить токен доступа с делегированными правами https://storage.azure.com/user_impersonation для использования хранилища Azure.

Если вы решите использовать SQL для доступа к данным клиентов, токен доступа должен быть получен с областью https://database.windows.net//user_impersonation для использования базы данных Azure SQL и пространства имен Microsoft.Data.SqlClient. Маркер доступа должен использоваться в указанном виде, с двумя косыми чертами перед user_impersonation, для проверки классом SQLConnection. Для получения дополнительных примеров аутентификации с помощью токенов, вы можете посмотреть пример в пакете средств разработчика Microsoft Fabric.

Для получения дополнительной информации о том, как получить токен, смотрите документацию Microsoft Fabric Workload Development REST API.

Чтение метаданных

Интерфейсы REST API Fabric предоставляют способ доступа к свойствам элементов. Например, запрос Get Lakehouse API предоставляет вам метаданные для определенного Lakehouse, включая полезные свойства, такие как пути OneLake и строка подключения SQL. Еще одна полезная конечная точка — API Get Warehouse, который возвращает следующие сведения:

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

Здесь свойство "ConnectionInfo" является полностью квалифицированным доменным именем (FQDN) SQL-сервера для хранилища данных. С помощью этого полного доменного имени можно установить подключение к SQL. Дополнительные сведения см. в статье Подключение к хранилищу данных в Microsoft Fabric. Примеры реализации см. в Microsoft Fabric Workload Development Kit.

Чтение данных

После проверки подлинности вы можете подключиться к OneLake с помощью REST API Azure Data Lake Storage для чтения различных типов данных. Для чтения таблиц рекомендуется использовать протокол Delta Lake. Вы также можете использовать те же API для чтения таблиц и файлов с помощью сочетаний клавиш OneLake; Вызовы API ведут себя так же, как чтение собственных данных OneLake, независимо от того, ссылается ли ярлык на внешнее хранилище или данные, к которым предоставлен общий доступ из другого клиента.

Кроме того, если вы решили использовать База данных SQL Azure, можно реализовать следующую процедуру для чтения данных из хранилища.

Создайте контекст авторизации. Пример создания контекста авторизации см. в методе AuthenticateDataPlaneCall.
Получите токен с областью Warehouse.Read.All от имени пользователя, используя токен носителя, переданный с клиентского интерфейса.
Используйте токен Fabric для вызова API Get Warehouse. Для доступа к сведениям о подключении и отображаемому имени хранилища требуется доступ к исходному каталогу сервера.
Получение маркера с областями действия SQL от имени пользователя. Чтобы успешно установить подключение к SQL, используйте область https://database.windows.net//user_impersonation.

Используйте маркер SQL и сведения о подключении, чтобы открыть подключение к 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;
        }

Теперь это подключение можно запросить для доступа к данным из хранилища. Дополнительные сведения об использовании пространства имен Microsoft.Data.SqlClient см. в документации пространства имен Microsoft.Data.SqlClient.

Eventhouse API

После проверки подлинности можно выполнять такие действия, как создание центра событий, удаление центра событий, получение списка центров событий и т. д. Одним из способов это сделать является использование портала — обзор центра событий .

Другой способ — использование REST API Eventhouse — обзор REST API eventhouse.

Авторизуйтесь.
Получите токен с областью FabricEventhouse.Read.All от имени пользователя, используя токен-переносчик, переданный из фронтенда.
Используйте токен Fabric для вызова API Get Eventhouse.
Теперь с списком баз данных в хранилище событий можно запросить нужную базу данных, как описано в разделе данных запроса ниже.

Запрос данных

Чтобы запросить данные из базы данных KQL Eventhouse, выполните следующие действия. Сначала выполните проверку подлинности с помощью соответствующего метода. Затем подключитесь к eventhouse, чтобы получить список баз данных. Затем запросите конкретную базу данных, к которой требуется получить доступ. Важно различать команды запросов, такие как .show tables, и запросы данных, например <TableName> | take 10. Полная документация по REST API KQL см. в документации по REST API KQL.

Другой способ — использование REST API Eventhouse — обзор REST API eventhouse.

Авторизуйтесь.
Получение маркера с помощью KQLDatabase.ReadWrite.All от имени пользователя с помощью маркера носителя, переданного с внешнего интерфейса.
Используйте маркер Kql для вызова KQL Rest API.

Запись данных

Кроме чтения данных с помощью маркера можно также использовать ADLS API для записи данных в таблицы, как это описано в протоколе Delta Lake.

Вы также можете использовать API для создания файлов и каталогов.

Кроме того, можно использовать другие рабочие нагрузки Fabric для записи данных на платформу. Например, можно использовать API рабочей нагрузки Fabric Lakehouse для эффективной загрузки распространенных типов файлов в оптимизированную таблицу Delta. Это делается путем отправки запроса POST в конечную точку API Tables - Load Table.

Подключение SQL также можно использовать для выполнения команд, которые вставляют данные в таблицы.

Интеграция OneLake

Вы можете выбрать использование интеграции OneLake в ваших рабочих нагрузках. Если вы это сделаете, то при создании нового элемента для рабочей нагрузки Fabric автоматически создаст папки для нового элемента.

Чтобы принять участие, XML манифеста элемента должен объявить это, установив для атрибута CreateOneLakeFoldersOnArtifactCreation значение true. Рассмотрим пример.

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

Примечание.

SchemaVersion должен иметь значение 1.101.0 (или более поздние поддерживаемые версии).

То же значение SchemaVersion должно быть задано в WorkloadManifest.xml:

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

При создании нового элемента в OneLake создаются следующие корневые папки:

<WorkspaceID>/<ItemID>/Files

<WorkspaceID>/<ItemID>/Tables

В этих папках можно создать дополнительные папки и использовать их для хранения данных в любом формате (в Files папке) или в формате parquet (в Tables папке). Следуйте приведенным выше инструкциям для чтения и записи из хранилища OneLake.