Подключение к Microsoft OneLake
Microsoft OneLake предоставляет открытый доступ ко всем элементам Fabric с помощью существующих API-интерфейсов Azure Data Lake Storage (ADLS) 2-го поколения и пакетов SDK. Вы можете получить доступ к данным в OneLake с помощью любого API, пакета SDK или средства, совместимого с ADLS 2-го поколения, только с помощью URI OneLake. Вы можете загрузить данные в lakehouse через Обозреватель хранилища Azure или прочитать таблицу Delta с помощью ярлыка из Azure Databricks.
Так как OneLake — это программное обеспечение как услуга (SaaS), некоторые операции, такие как управление разрешениями или обновление элементов, должны выполняться с помощью интерфейсов Fabric и не могут выполняться через API-интерфейсы ADLS 2-го поколения. Полный список изменений в API см. в разделе Эквивалентность API OneLake.
Синтаксис URI
Поскольку OneLake охватывает весь ваш клиентский экземпляр Microsoft Fabric, вы можете ссылаться на любой объект в вашем экземпляре, указывая его рабочую область, элемент и путь.
https://onelake.dfs.fabric.microsoft.com/<workspace>/<item>.<itemtype>/<path>/<fileName>
Примечание.
Так как можно повторно использовать имена элементов в нескольких типах элементов, необходимо указать тип элемента в расширении. Например, .lakehouse
для озера и .datawarehouse
для склада.
OneLake также поддерживает ссылки на рабочие области и элементы с глобальными уникальными идентификаторами (GUID). OneLake назначает идентификаторы GUID, которые не изменяются, даже если изменяется имя рабочей области или элемента. Вы можете найти GUID, связанный с вашей рабочей областью или элементом, в URL-адресе на портале Fabric. Идентификаторы GUID необходимо использовать как для рабочей области, так и для элемента, и не требуется тип элемента.
https://onelake.dfs.fabric.microsoft.com/<workspaceGUID>/<itemGUID>/<path>/<fileName>
При внедрении инструмента в OneLake вместо ADLS Gen2 (второго поколения), используйте следующее сопоставление:
- Имя учетной записи всегда
onelake
. - Имя контейнера — это имя рабочей области.
- Путь к данным начинается с элемента. Например:
/mylakehouse.lakehouse/Files/
.
OneLake также поддерживает драйвер файловой системы BLOB-объектов Azure (ABFS) для обеспечения большей совместимости с ADLS 2-го поколения и Хранилище BLOB-объектов Azure. Драйвер ABFS использует собственный идентификатор abfs
схемы и другой формат URI для обращения к файлам и каталогам в учетных записях ADLS 2-го поколения. Чтобы использовать этот формат URI в OneLake, замените рабочую область на файловую систему и добавьте элемент и его тип.
abfs[s]://<workspace>@onelake.dfs.fabric.microsoft.com/<item>.<itemtype>/<path>/<fileName>
URI драйвера abfs не разрешает специальные символы, например пробелы, в имени рабочей области. В этих случаях можно ссылаться на рабочие области и элементы с глобальными уникальными идентификаторами (GUID), как описано ранее в этом разделе.
Авторизация
Вы можете пройти проверку подлинности API OneLake с помощью идентификатора Microsoft Entra, передав заголовок авторизации. Если инструмент поддерживает вход в учетную запись Azure для передачи токена, вы можете выбрать любую подписку. OneLake требует только токен пользователя и не учитывает вашу подписку Azure.
При вызове OneLake напрямую через API-интерфейсы DFS, вы можете аутентифицироваться с помощью токена-носителя для своей учетной записи Microsoft Entra. Чтобы узнать больше о запросе и управлении токенами-носителями для вашей организации, ознакомьтесь с Библиотекой проверки подлинности Microsoft.
Для быстрого, разового тестирования OneLake с помощью вызовов API напрямую, вот простой пример использования PowerShell для входа в вашу учетную запись Azure, получения токена, ограниченного областью хранения, и его копирования в буфер обмена для удобного использования в других местах. Дополнительные сведения о получении маркеров доступа с помощью PowerShell см. в разделе Get-AzAccessToken.
Примечание.
OneLake поддерживает только токены в целевой группе Storage
. В следующем примере мы задали аудиторию с помощью ResourceTypeName
параметра.
Connect-AzAccount
$testToken = Get-AzAccessToken -AsSecureString -ResourceTypeName Storage
# Retrieved token is of string type which you can validate with the "$testToken.Token.GetTypeCode()" command.
$testToken.Token | Set-Clipboard
Место расположения данных
Если вы используете глобальную конечную точку ('https://onelake.dfs.fabric.microsoft.com'), чтобы совершать запросы данных в регионе, отличающемся от региона, в котором находится ваша рабочая область, существует вероятность того, что данные могут покинуть ваш регион во время процесса разрешения конечной точки. Если вас беспокоит место хранения данных, то использование правильной региональной конечной точки для вашей рабочей области гарантирует, что ваши данные останутся в текущем регионе и не будут пересекать региональные границы. Вы можете обнаружить правильную региональную конечную точку, проверив регион емкости, к которому подключена рабочая область.
Региональные конечные точки OneLake соответствуют одному и тому же формату: https://<region>-onelake.dfs.fabric.microsoft.com
Например, рабочая область, подключенная к емкости в регионе "Запад США", будет доступна через региональную конечную точку https://westus-onelake.dfs.fabric.microsoft.com
.
Распространенные проблемы
Если средство или пакет, совместимый с ADLS 2-го поколения, не работает над OneLake, наиболее распространенной проблемой является проверка URL-адресов. Так как OneLake использует другую конечную точку (dfs.fabric.microsoft.com
), чем ADLS 2-го поколения,dfs.core.windows.net
некоторые средства не распознают конечную точку OneLake и блокируют ее. Некоторые средства позволяют использовать пользовательские конечные точки (например, PowerShell). В противном случае часто достаточно просто добавить конечную точку OneLake как поддерживаемую конечную точку. Если вы обнаружите проблему проверки URL-адреса или у вас возникли другие проблемы, связанные с подключением к OneLake, сообщите нам об этом.
Ресурсы
OneLake доступен через те же API и пакеты SDK, что и ADLS 2-го поколения. Дополнительные сведения об использовании API ADLS 2-го поколения см. на следующих страницах:
- Справочник по API ADLS 2-го поколения
- Пакеты SDK файловой системы ADLS 2-го поколения
Примеры
Создать файл
Запросить |
ПОЛОЖИТЕ https://onelake.dfs.fabric.microsoft.com/{workspace}/{item}.{itemtype}/Files/sample?resource=file |
---|---|
Заголовки | Authorization: Bearer <userAADToken> |
Response |
ResponseCode:201 Created Заголовки: x-ms-version : 2021-06-08 x-ms-request-id : 272526c7-0995-4cc4-b04a-8ea3477bc67b x-ms-content-crc64 : OAJ6r0dQWP0= x-ms-request-server-encrypted : true ETag : 0x8DA58EE365 Тело: |