Udostępnij za pośrednictwem

Uzyskiwanie dostępu do tabel usługi Azure Databricks z klientów platformy Apache Iceberg

Ważne

Interfejs API katalogu REST Unity Catalog Apache Iceberg jest w wersji Public Preview w wersjach Databricks Runtime 16.4 LTS i nowszych. Ten punkt końcowy jest zalecany do odczytu i zapisu do/z tabel przez klientów Iceberg.

Unity Catalog ma również punkt końcowy API REST tylko do odczytu Iceberg. Jest to starszy punkt końcowy. Zobacz Odczytywanie tabel usługi Databricks z klientów platformy Apache Iceberg (starsza wersja).

Katalog REST platformy Apache Iceberg umożliwia klientom obsługiwanym, takim jak Apache Spark, Apache Flink i Trino, odczytywanie i zapisywanie w tabelach zarejestrowanych w wykazie platformy Iceberg platformy Unity w usłudze Azure Databricks.

Aby uzyskać pełną listę obsługiwanych integracji, zobacz Integracje Unity Catalog.

Użyj punktu końcowego katalogu Iceberg Unity Catalog

Unity Catalog zapewnia implementację specyfikacji API katalogu REST Iceberg.

Skonfiguruj dostęp przy użyciu punktu końcowego /api/2.1/unity-catalog/iceberg-rest. Aby uzyskać szczegółowe informacje na temat korzystania z tego interfejsu API REST, zobacz specyfikację interfejsu API REST Iceberg.

Ważne

Adres URL obszaru roboczego używany dla punktu końcowego katalogu REST usługi Iceberg musi zawierać identyfikator obszaru roboczego. Bez identyfikatora obszaru roboczego żądania API mogą skutkować przekierowaniem 303 do strony logowania zamiast oczekiwanej odpowiedzi.

Aby znaleźć adres URL obszaru roboczego i identyfikator obszaru roboczego, zobacz Nazwy wystąpień obszaru roboczego, adresy URL i identyfikatory.

Notatka

Azure Databricks wprowadziło dystrybucję poświadczeń dla niektórych klientów Iceberg. Databricks zaleca używanie zarządzania poświadczeniami w celu kontrolowania dostępu do lokalizacji przechowywania w chmurze w obsługiwanych systemach. Zobacz Unity Catalog: poświadczenia dla dostępu do systemów zewnętrznych i Dostęp do tabel Iceberg przy użyciu systemów zewnętrznych.

Jeśli obsługa poświadczeń jest nieobsługiwana dla klienta, musisz skonfigurować dostęp z klienta do lokalizacji przechowywania zawierającej pliki i metadane dla tabeli Delta lub Iceberg. Aby uzyskać szczegółowe informacje o konfiguracji, zapoznaj się z dokumentacją klienta platformy Iceberg.

Wymagania

Usługa Azure Databricks obsługuje dostęp do katalogu Iceberg przez REST do tabel w ramach Unity Catalog. Aby korzystać z tych punktów końcowych, musisz mieć włączony Unity Catalog w swoim obszarze roboczym. Następujące typy tabel są dostępne przy użyciu katalogu REST Iceberg:

Temat Przeczytaj Napisz
Zarządzana góra lodowa Tak Tak
Zagraniczna góra lodowa Tak Nie.
Zarządzana Delta (z włączonym odczytem Iceberg) Tak Nie.
Delta zewnętrzna (z włączonymi odczytami przy użyciu Iceberg) Tak Nie.

Zewnętrzne tabele Iceberg nie są automatycznie odświeżane podczas odczytywania tabel przy użyciu interfejsu API katalogu REST Iceberg. Aby odświeżyć, należy uruchomić polecenie REFRESH FOREIGN TABLE , aby odczytać najnowszą migawkę. Dystrybucja poświadczeń na zagranicznych stołach Iceberg nie jest obsługiwana.

Notatka

Tabele Delta należy skonfigurować tak, aby były dostępne przy użyciu REST API katalogu Iceberg. Zobacz Odczytywanie tabel Delta za pomocą klientów Iceberg.

Aby skonfigurować dostęp do odczytu lub zapisu w tabelach usługi Azure Databricks z klientów Iceberg przy użyciu katalogu Iceberg REST, należy wykonać następujące kroki konfiguracyjne:

Notatka

Specyfikacja Iceberg nie zezwala na zduplikowane pliki danych w jednym zrzucie tabeli. Aby temu zapobiec, po wykryciu Katalog Unity blokuje zatwierdzanie zduplikowanych plików danych w tabeli przez silniki zewnętrzne.

Używanie tabel Iceberg z Apache Spark

Poniżej przedstawiono przykład konfigurowania platformy Apache Spark w celu uzyskiwania dostępu do tabel usługi Azure Databricks za pośrednictwem interfejsu API wykazu REST platformy Iceberg przy użyciu uwierzytelniania 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"

Zastąp następujące zmienne:

  • <uc-catalog-name>: Nazwa katalogu w Unity Catalog, który zawiera twoje tabele.
  • <spark-catalog-name>: nazwa, którą chcesz przypisać do katalogu w sesji platformy Spark.
  • <oauth_client_id>: identyfikator klienta OAuth dla głównego uwierzytelnianego podmiotu.
  • <oauth_client_secret>: hasło tajne klienta OAuth dla podmiotu uwierzytelniającego.
  • <workspace-url>: adres URL obszaru roboczego usługi Azure Databricks, w tym identyfikator obszaru roboczego. Na przykład adb-1234567890123456.12.azuredatabricks.net.

Te konfiguracje umożliwiają wykonywanie zapytań w tabelach w katalogu Unity przy użyciu Apache Spark. Aby uzyskać dostęp do tabel w wielu katalogach, należy skonfigurować każdy wykaz oddzielnie.

Podczas wykonywania zapytań w tabelach w Katalogu Unity przy użyciu konfiguracji Spark warto pamiętać o następujących kwestiach:

  • Potrzebujesz "spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions" tylko w przypadku, gdy uruchamiasz procedury składowane specyficzne dla Iceberg .

  • Usługa Azure Databricks używa magazynu obiektów w chmurze dla wszystkich tabel. Musisz dodać JAR iceberg-spark-runtime jako pakiety programu Spark.

    • AWS: org.apache.iceberg:iceberg-aws-bundle:<iceberg-version>
    • Azure: org.apache.iceberg:iceberg-azure-bundle:<iceberg-version>
    • GCP: org.apache.iceberg:iceberg-gcp-bundle:<iceberg-version>

    Aby uzyskać szczegółowe informacje, zobacz dokumentację dotyczącą integracji Iceberg AWS z Apache Spark.

    Notatka

    Te konfiguracje nie są wymagane podczas uzyskiwania dostępu do tabel Iceberg z usługi Azure Databricks. Ładowanie zewnętrznych plików JAR Iceberg do klastrów Azure Databricks nie jest obsługiwane.

Uzyskiwanie dostępu do tabel usługi Azure Databricks za pomocą rozwiązania Snowflake

Snowflake oferuje dwie opcje uzyskiwania dostępu do tabel za pośrednictwem katalogu REST Iceberg: przy użyciu baz danych połączonych z katalogiem Snowflake lub tabel zewnętrznych.

W przypadku obu opcji najpierw skonfiguruj integrację wykazu Snowflake. Usługa Azure Databricks obsługuje następujące metody uwierzytelniania dla integracji z katalogiem Snowflake.

  • Token elementu nośnego: używa osobistego tokenu dostępu usługi Azure Databricks (PAT) lub tokenu OAuth. Obsługiwane we wszystkich chmurach.
  • Entra service principal OAuth (tylko platforma Azure): używa głównego elementu usługi Microsoft Entra ID do uwierzytelniania bezpośrednio do punktu końcowego tokenu Microsoft Entra.

Aby uzyskać więcej informacji na temat opcji uwierzytelniania usługi Snowflake dla integracji katalogu REST, zobacz dokumentację usługi Snowflake.

Snowflake z uwierzytelnianiem za pomocą tokenu typu bearer

Poniższy przykład konfiguracji integruje katalog Snowflake przy użyciu tokenu typu bearer. Możesz użyć osobistego tokenu dostępu (PAT) usługi Azure Databricks lub tokenu OAuth wygenerowanego przez jednostkę usługi Azure Databricks. Aby uzyskać szczegółowe informacje na temat generowania tokenów OAuth, zobacz Autoryzowanie dostępu jednostki usługi do usługi Azure Databricks przy użyciu protokołu 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;

Zastąp następujące zmienne:

  • <catalog-integration-name>: nazwa, która ma zostać przypisana do katalogu zarejestrowanego w usłudze Snowflake.
  • <uc-schema-name>: nazwa schematu w katalogu Unity, do którego potrzebujesz dostępu.
  • <uc-catalog-name>: nazwa katalogu w Unity Catalog, do którego potrzebujesz uzyskać dostęp.
  • <workspace-url>: adres URL obszaru roboczego usługi Azure Databricks, w tym identyfikator obszaru roboczego. Na przykład: https://cust-success.cloud.databricks.com/?o=6280049833385130 lub https://adb-1234567890123456.12.azuredatabricks.net.
  • <token>: osobisty token dostępu (PAT) dla głównej jednostki konfigurującej integrację.

Snowflake z główną jednostką usługi Entra OAuth

Na platformie Azure integracje katalogu snowflake korzystające z jednostki usługi opartej na usłudze Entra nie mogą używać punktu końcowego tokenu OIDC usługi Azure Databricks (<workspace-url>/oidc/v1/token). Zamiast tego należy uwierzytelnić się bezpośrednio w punkcie końcowym tokenu Microsoft Entra. To różni się od podejścia OAuth używanego dla innych klientów Iceberg (takich jak Apache Spark) w Azure.

Notatka

Dokumentacja rozwiązania Snowflake może wskazywać, że identyfikator Entra nie jest obsługiwany. Poniższa konfiguracja używa Entra OAuth, docelowo przeznaczonego dla zakresu zasobów Azure Databricks, i jest obsługiwaną metodą czytania Unity Catalog z Snowflake na platformie Azure.

Przed rozpoczęciem upewnij się, że masz następujące elementy:

Uruchom następujący kod SQL w rozwiązaniu 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;

Zastąp następujące zmienne:

  • <catalog-integration-name>: nazwa, która ma zostać przypisana do katalogu zarejestrowanego w usłudze Snowflake.
  • <uc-schema-name>: nazwa schematu w Unity Catalog, do którego chcesz uzyskać dostęp.
  • <uc-catalog-name>: nazwa katalogu w Unity Catalog, do którego musisz uzyskać dostęp.
  • <workspace-url>: adres URL obszaru roboczego usługi Azure Databricks, w tym identyfikator obszaru roboczego. Na przykład adb-1234567890123456.12.azuredatabricks.net.
  • <azure-tenant-id>: Twój identyfikator dzierżawy Microsoft Entra.
  • <entra-client-id>: identyfikator aplikacji (klienta) jednostki usługi Entra.
  • <entra-client-secret>: tajemnica klienta dla głównej usługi Entra.

Ważne

Zakres 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default to identyfikator aplikacji Azure Databricks zarejestrowany w Entra. Różni się to od all-apis obszaru używanego z punktem końcowym OIDC usługi Azure Databricks. Użycie nieprawidłowego zakresu jest częstą przyczyną błędów uwierzytelniania podczas konfigurowania tej integracji.

Po utworzeniu integracji katalogu postępuj zgodnie z dokumentacją Snowflake, aby utworzyć bazę danych połączoną z katalogiem do uzyskania dostępu do tabel.

Aby uzyskać więcej informacji na temat tworzenia jednostek usługi Entra dla usługi Azure Databricks i zarządzania nimi, zobacz Uwierzytelnianie za pomocą jednostek usługi Microsoft Entra.

Notatka

Snowflake nie obsługuje uwierzytelniania Entra dla integracji katalogu, które korzystają z sieci prywatnej (Azure Private Link) do połączenia z Azure Databricks. Połączenie z punktem końcowym katalogu REST usługi Azure Databricks Iceberg musi używać sieci publicznej podczas uwierzytelniania za pomocą jednostki usługi Entra.

Bazy danych powiązane z katalogiem

Bazy danych powiązane z katalogiem Snowflake automatycznie synchronizują się z Unity Catalog, aby wykrywać schematy i tabele Iceberg. Eliminuje to konieczność ręcznego odświeżania metadanych.

Po skonfigurowaniu integracji wykazu Snowflake zapoznaj się z dokumentacją usługi Snowflake, aby utworzyć bazę danych połączoną z wykazem w celu uzyskania dostępu do tabel.

Ważne

Próba zapisu z usługi Snowflake do tabel usługi Azure Databricks tylko do odczytu może spowodować błędy. Zapoznaj się z dokumentacją usługi Snowflake , aby zapoznać się z obsługiwanymi operacjami.

Tabele zewnętrzne

Alternatywnie można utworzyć tabele zewnętrzne po utworzeniu integracji katalogu Snowflake. Takie podejście wymaga ręcznego odświeżania metadanych w celu wyświetlenia aktualizacji.

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

Używanie tabel usługi Azure Databricks z rozwiązaniem PyIceberg

Aby uzyskać dostęp do tabel usługi Azure Databricks przy użyciu platformy PyIceberg, należy zainstalować bibliotekę PyIceberg z wymaganymi zależnościami. PyIceberg wymaga pyarrow do operacji na tabelach, takich jak odczytywanie danych i przeglądanie metadanych tabeli. Zainstaluj aplikację PyIceberg z dodatkowymi pyarrow elementami:

pip install "pyiceberg[pyarrow]"

Notatka

Jeśli nie zainstalujesz pyarrowprogramu , operacje, takie jak opisywanie lub odczytywanie tabel, kończą się niepowodzeniem. Pełną listę zależności opcjonalnych można znaleźć w dokumentacji PyIceberg.

Poniżej przedstawiono przykład ustawień konfiguracji umożliwiających narzędziu PyIceberg uzyskanie dostępu do tabel platformy Azure Databricks przez nawiązanie połączenia z Katalogiem REST Iceberg w katalogu Unity:

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

Zastąp następujące zmienne:

  • <workspace-url>: adres URL obszaru roboczego usługi Azure Databricks, w tym identyfikator obszaru roboczego. Na przykład adb-1234567890123456.12.azuredatabricks.net.
  • <uc-catalog-name>: nazwa katalogu w Unity Catalog, do którego potrzebujesz uzyskać dostęp.
  • <token>: osobisty token dostępu (PAT) dla głównej jednostki konfigurującej integrację.

Zapoznaj się z dokumentacją konfiguracji katalogu REST PyIceberg.

Przykład użycia curl w API REST

curl Poniższy przykład ładuje tabelę przy użyciu interfejsu API REST:

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>

Odpowiedź wygląda następująco:

{
  "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>"
  }
}

Notatka

Pole expires-at-ms wskazuje, kiedy wygasają poświadczenia. Domyślny czas wygaśnięcia to jedna godzina. Aby uzyskać lepszą wydajność, poproś klienta o buforowanie poświadczeń do momentu ich wygaśnięcia przed zażądaniem nowych.

  • Last updated on