Доступ к таблицам Azure Databricks из клиентов Apache Iceberg

Это важно

API каталога Unity Apache Iceberg REST catalog находится в общедоступной предварительной версии в Databricks Runtime 16.4 LTS и выше. Эта конечная точка рекомендуется для чтения из таблиц и записи в таблицы клиентами Iceberg.

Каталог Unity также имеет конечную точку API каталога Iceberg REST только для чтения. Это устаревшая конечная точка. См. чтение таблиц Databricks с использованием клиентов Apache Iceberg (устаревшие).

Каталог REST Apache Iceberg позволяет поддерживаемым клиентам, таким как Apache Spark, Apache Flink и Trino, считывать и записывать в таблицы Iceberg, зарегистрированные в каталоге Unity, в Azure Databricks.

Полный список поддерживаемых интеграции см. в разделе "Интеграция каталога Unity".

Используйте оконечную точку Iceberg каталога Unity Catalog

Каталог Unity предоставляет реализацию спецификации API каталога REST Iceberg.

Настройте доступ с помощью конечной точки /api/2.1/unity-catalog/iceberg-rest. См. спецификацию Iceberg REST API для получения подробной информации об использовании данного REST API.

Заметка

Azure Databricks ввела предоставление учетных данных для некоторых клиентов, использующих Iceberg для чтения данных. Databricks рекомендует использовать выдачу учетных данных для управления доступом к расположениям облачного хранилища для поддерживаемых систем. См. учетные данные каталога Unity для доступа к внешним системам и доступ к таблицам Iceberg с использованием внешних систем.

Если обмен учетными данными не поддерживается для клиента, необходимо настроить доступ от клиента к расположению хранилища, содержащему файлы и метаданные для таблицы Delta или Iceberg. Дополнительные сведения о конфигурации см. в документации для клиента Iceberg.

Требования

Azure Databricks поддерживает доступ к каталогам Iceberg REST для таблиц в Unity Catalog. Для использования этих конечных точек необходимо включить каталог Unity в рабочей области. Следующие типы таблиц доступны с помощью каталога REST Iceberg:

Тема Читайте Напишите
Управляемый Айсберг Да Да
Чужеземный Айсберг Да нет
Управляемый Delta (с поддержкой операций чтения Iceberg) Да нет
Внешний Delta (с поддержкой операций чтения Iceberg) Да нет

Внешние таблицы Iceberg не обновляются автоматически при использовании API REST каталога Iceberg для их чтения. Для обновления необходимо запустить REFRESH FOREIGN TABLE, чтобы прочитать последний моментальный снимок. Поддержка выдачи учетных данных в таблицах Foreign Iceberg не предусмотрена.

Заметка

Необходимо настроить Delta tables для обеспечения доступа через API REST каталога Iceberg. См. как считывать таблицы Delta с помощью клиентов Iceberg.

Чтобы настроить доступ для чтения или записи в таблицы Azure Databricks из клиентов Айсберга с помощью каталога REST Iceberg, необходимо выполнить следующие действия.

Заметка

Спецификация Iceberg не позволяет дублировать файлы данных в одном снимке таблицы. Чтобы предотвратить это, при обнаружении Unity Catalog блокирует внешние обработчики от фиксации дублирующихся файлов данных в таблицу.

Использование таблиц Iceberg с Apache Spark

Ниже приведен пример настройки Apache Spark для доступа к таблицам Azure Databricks через Iceberg REST Catalog API с аутентификацией OAuth:

"spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions",

# Configuration for accessing tables in Unity Catalog
"spark.sql.catalog.<spark-catalog-name>": "org.apache.iceberg.spark.SparkCatalog",
"spark.sql.catalog.<spark-catalog-name>.type": "rest",
"spark.sql.catalog.<spark-catalog-name>.rest.auth.type": "oauth2",
"spark.sql.catalog.<spark-catalog-name>.uri": "<workspace-url>/api/2.1/unity-catalog/iceberg-rest",
"spark.sql.catalog.<spark-catalog-name>.oauth2-server-uri": "<workspace-url>/oidc/v1/token",
"spark.sql.catalog.<spark-catalog-name>.credential":"<oauth_client_id>:<oauth_client_secret>",
"spark.sql.catalog.<spark-catalog-name>.warehouse":"<uc-catalog-name>"
"spark.sql.catalog.<spark-catalog-name>.scope":"all-apis"

Замените следующие переменные:

  • <uc-catalog-name>: имя каталога в каталоге Unity, содержащего таблицы.
  • <spark-catalog-name>: имя, которое необходимо назначить этому каталогу в сеансе Spark.
  • <oauth_client_id>: идентификатор клиента OAuth для субъекта проверки подлинности.
  • <oauth_client_secret>: секрет клиента OAuth для аутентифицирующего субъекта.
  • <workspace-url>: URL-адрес рабочей области Azure Databricks. Например: adb-1234567890123456.12.azuredatabricks.net.

С помощью этих конфигураций можно запрашивать таблицы в каталоге Unity с помощью Apache Spark. Чтобы получить доступ к таблицам в нескольких каталогах, необходимо настроить каждый каталог отдельно.

При запросе таблиц в каталоге Unity с помощью конфигураций Spark помните следующее:

  • Вам потребуется "spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions" только в том случае, если вы запускаете хранимые процедуры, специфичные для Айсберга,.

  • Azure Databricks использует облачное хранилище объектов для всех таблиц. Необходимо добавить JAR-файл iceberg-spark-runtime в качестве пакета для Spark.

    • AWS: org.apache.iceberg:iceberg-aws-bundle:<iceberg-version>
    • Лазурный: org.apache.iceberg:iceberg-azure-bundle:<iceberg-version>
    • GCP: org.apache.iceberg:iceberg-gcp-bundle:<iceberg-version>

    Для получения дополнительной информации см. документацию по интеграции Iceberg AWS для Spark.

    Заметка

    Эти конфигурации не требуются при доступе к таблицам Iceberg из Azure Databricks. Загрузка JARs Iceberg на внешние кластеры Azure Databricks не поддерживается.

Доступ к таблицам Azure Databricks с помощью Snowflake

Snowflake предоставляет два варианта доступа к таблицам через каталог REST Iceberg: использование баз данных, связанных с каталогом Snowflake, или использование внешних таблиц.

Для обоих вариантов сначала настройте интеграцию каталога Snowflake. Azure Databricks поддерживает следующие методы проверки подлинности для интеграции с каталогом Snowflake:

  • Маркер носителя: использует личный маркер доступа Azure Databricks (PAT) или токен OAuth. Поддерживается на всех облачных платформах.
  • Сервисный принципал Entra OAuth (только Azure): использует сервисный принципал Microsoft Entra ID для непосредственной аутентификации с конечной точкой токена Entra.

Дополнительные сведения о параметрах проверки подлинности Snowflake для интеграции с каталогом REST см. в документации по Snowflake.

Snowflake с аутентификацией с помощью токена пользователя

В следующем примере настраивается интеграция каталога Snowflake с помощью маркера носителя. Вы можете использовать личный токен доступа Azure Databricks (PAT) или токен OAuth, сгенерированный из служебного принципала Azure Databricks. Дополнительные сведения о создании маркеров OAuth см. в статье "Авторизация доступа субъекта-службы к Azure Databricks с помощью OAuth".

CREATE OR REPLACE CATALOG INTEGRATION <catalog-integration-name>
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = '<uc-schema-name>'
  REST_CONFIG = (
    CATALOG_URI = '<workspace-url>/api/2.1/unity-catalog/iceberg-rest',
    WAREHOUSE = '<uc-catalog-name>'
  )
  REST_AUTHENTICATION = (
    TYPE = BEARER
    BEARER_TOKEN = '<token>'
  )
  ENABLED = TRUE;

Замените следующие переменные:

  • <catalog-integration-name>: имя, которое нужно назначить каталогу, зарегистрированным в Snowflake.
  • <uc-schema-name>: имя схемы в каталоге Unity, к которому требуется получить доступ.
  • <uc-catalog-name>: имя каталога в каталоге Unity, к которому требуется получить доступ.
  • <workspace-url>: URL-адрес рабочей области Azure Databricks. Например, https://cust-success.cloud.databricks.com или https://adb-1234567890123456.12.azuredatabricks.net.
  • <token>: личный маркер доступа (PAT) для субъекта, настраивающего интеграцию.

Snowflake с сервисным принципалом Entra OAuth

В Azure интеграции с каталогом Snowflake, использующие субъект-службу с поддержкой Entra, не могут использовать конечную точку токена OIDC Azure Databricks (<workspace-url>/oidc/v1/token). Вместо этого необходимо выполнить проверку подлинности непосредственно в конечной точке токена Microsoft Entra. Это отличается от подхода OAuth, используемого для других клиентов Iceberg (например, Apache Spark) в Azure.

Заметка

Документация Snowflake может указывать, что Entra ID не поддерживается. В конфигурации ниже используется Entra OAuth для области ресурсов Azure Databricks, и это поддерживаемый путь для доступа к каталогу Unity в Snowflake на Azure.

Перед началом работы убедитесь, что у вас есть следующие ресурсы:

Запустите следующий SQL в Snowflake:

CREATE OR REPLACE CATALOG INTEGRATION <catalog-integration-name>
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = '<uc-schema-name>'
  REST_CONFIG = (
    CATALOG_URI = 'https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest'
    WAREHOUSE = '<uc-catalog-name>'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_TOKEN_URI = 'https://login.microsoftonline.com/<azure-tenant-id>/oauth2/v2.0/token'
    OAUTH_CLIENT_ID = '<entra-client-id>'
    OAUTH_CLIENT_SECRET = '<entra-client-secret>'
    OAUTH_ALLOWED_SCOPES = ('2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default')
  )
  ENABLED = TRUE
  REFRESH_INTERVAL_SECONDS = 600;

Замените следующие переменные:

  • <catalog-integration-name>: имя, которое нужно назначить каталогу, зарегистрированным в Snowflake.
  • <uc-schema-name>: имя схемы в каталоге Unity, к который требуется получить доступ.
  • <uc-catalog-name>: имя каталога в каталоге Unity, к который требуется получить доступ.
  • <workspace-url>: URL-адрес рабочей области Azure Databricks. Например: adb-1234567890123456.12.azuredatabricks.net.
  • <azure-tenant-id>: идентификатор клиента Microsoft Entra.
  • <entra-client-id>: идентификатор приложения (клиента) субъекта-службы Entra.
  • <entra-client-secret>: секрет клиента для субъекта-службы Entra.

Это важно

Область 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default — это идентификатор приложения Azure Databricks, зарегистрированный в Entra. Это отличается от all-apis области, используемой с конечной точкой OIDC Azure Databricks. Использование неправильной области является распространенной причиной сбоев проверки подлинности при настройке этой интеграции.

После создания интеграции с каталогом следуйте документации Snowflake , чтобы создать связанную с каталогом базу данных для доступа к таблицам.

Дополнительные сведения о создании субъектов-служб Entra и управлении ими для Azure Databricks см. в статье Аутентификация с помощью субъектов-служб Microsoft Entra.

Заметка

Snowflake не поддерживает аутентификацию Entra для интеграций каталога, использующих приватную сеть Azure (Приватный канал Azure) для подключения к Azure Databricks. Подключение к конечной точке каталога REST Azure Databricks Iceberg должно выполняться через публичные сети при проверке подлинности с помощью principal службы Entra.

Базы данных, связанные с каталогом

Базы данных, связанные с каталогом Snowflake, автоматически синхронизируются с каталогом Unity для обнаружения схем и таблиц Iceberg. Это устраняет необходимость обновления метаданных вручную.

После настройки интеграции каталога Snowflake обратитесь к документации по Snowflake, чтобы создать базу данных с привязкой к каталогу для доступа к таблицам.

Это важно

Попытка записи из Snowflake в таблицы Azure Databricks только для чтения может привести к ошибкам. См. сведения о поддерживаемых операциях в документации по Snowflake.

Внешние таблицы

Кроме того, можно создать внешние таблицы после создания интеграции каталога Snowflake. Этот подход требует ручного обновления метаданных для просмотра обновлений.

CREATE OR REPLACE ICEBERG TABLE my_table
  CATALOG = '<catalog-integration-name>'
  CATALOG_TABLE_NAME = '<uc-table-name>';

Использование таблиц Azure Databricks с PyIceberg

Чтобы использовать PyIceberg для доступа к таблицам Azure Databricks, необходимо установить PyIceberg с необходимыми зависимостями. PyIceberg требуется pyarrow для операций таблицы, таких как чтение данных и проверка метаданных таблицы. Установите PyIceberg с дополнительным компонентом pyarrow.

pip install "pyiceberg[pyarrow]"

Заметка

Если вы не установите pyarrow, такие операции, как описание или чтение таблиц, приводят к сбою. Полный список необязательных зависимостей см. в документации PyIceberg.

Ниже приведен пример параметров конфигурации, позволяющих PyIceberg получить доступ к таблицам Azure Databricks, подключившись к каталогу REST Iceberg в каталоге Unity:

catalog:
  unity_catalog:
    uri: https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest
    warehouse: <uc-catalog-name>
    token: <token>

Замените следующие переменные:

  • <workspace-url>: URL-адрес рабочей области Azure Databricks. Например: adb-1234567890123456.12.azuredatabricks.net.
  • <uc-catalog-name>: имя каталога в каталоге Unity, к которому требуется получить доступ.
  • <token>: личный маркер доступа (PAT) для субъекта, настраивающего интеграцию.

См. документацию по конфигурации каталога REST PyIceberg.

Пример команды curl для REST API

В следующем curl примере загружается таблица с помощью REST API:

curl -X GET -H "Authorization: Bearer $OAUTH_TOKEN" -H "Accept: application/json" \
https://<workspace-instance>/api/2.1/unity-catalog/iceberg-rest/v1/catalogs/<uc_catalog_name>/namespaces/<uc_schema_name>/tables/<uc_table_name>

Ответ выглядит следующим образом:

{
  "metadata-location": "abfss://my-container@my-storage-account.dfs.core.windows.net/path/to/iceberg/table/metadata/file",
  "metadata": <iceberg-table-metadata-json>,
  "config": {
    "expires-at-ms": "<epoch-ts-in-millis>",
    "adls.sas-token.<storage-account-name>.dfs.core.windows.net": "<temporary-sas-token>"
  }
}

Заметка

Поле expires-at-ms указывает, когда истекает срок действия учетных данных. Срок действия по умолчанию составляет один час. Для повышения производительности клиент кэширует учетные данные до истечения срока действия, прежде чем запрашивать новые.

  • Last updated on