Używanie programu SQLAlchemy z usługą Azure Databricks

Azure Databricks udostępnia dialekt SQLAlchemy (system, którego SQLAlchemy używa do komunikacji z różnymi typami implementacji API baz danych i bazami danych) dla Azure Databricks. SQLAlchemy to zestaw narzędzi języka Python SQL i maper relacyjny obiektów (ORM). SqlAlchemy udostępnia zestaw dobrze znanych biznesowych wzorców trwałości, zaprojektowanych pod kątem efektywnego i wysokowydajnego dostępu do bazy danych, dostosowanych do prostego, naturalnego dla języka Python języka domenowego. Zobacz Funkcje i filozofia.

Dialekt SQLAlchemy dla usługi Azure Databricks musi być zainstalowany, aby korzystać z funkcji SQLAlchemy w usłudze Azure Databricks. W tym artykule opisano dialekt SQLAlchemy dla usługi Azure Databricks w wersji 1.0 i 2.0, który będzie oparty na łączniku SQL Usługi Databricks dla języka Python w wersji 4.0.0 lub nowszej.

Wymagania

  • Maszyna deweloperna z uruchomionym językiem Python >=3.8 i <=3.11.
  • Usługa Databricks zaleca używanie środowisk wirtualnych języka Python, takich jak te udostępniane przez venv dołączone do języka Python. Środowiska wirtualne pomagają zapewnić, że używasz poprawnych wersji języka Python i łącznika SQL usługi Databricks dla języka Python. Konfigurowanie i używanie środowisk wirtualnych wykracza poza zakres tego artykułu. Aby uzyskać więcej informacji, zobacz Tworzenie środowisk wirtualnych.
  • Istniejący klaster lub magazyn SQL.

Wprowadzenie

  • Zainstaluj usługę databricks-sqlalchemy dla programu SQLAlchemy w wersji 1 przy użyciu pip install databricks-sqlalchemy~=1.0 lub sqlAlchemy w wersji 2 przy użyciu pip install databricks-sqlalchemy. Aby uzyskać informacje o wersji, zapoznaj się z historią wydań databricks-sqlalchemy.

  • Zbierz następujące informacje dotyczące klastra lub magazynu SQL, którego chcesz użyć:

    Klaster

    SQL Warehouse

    • Nazwa hosta serwera usługi SQL Warehouse. Możesz to uzyskać z wartości nazwy hosta serwera na karcie Szczegóły połączenia dla magazynu danych SQL.
    • Ścieżka HTTP magazynu SQL. Możesz to uzyskać z wartości ścieżki HTTP na karcie Szczegóły połączenia dla usługi SQL Warehouse.

Uwierzytelnianie

Dialekt SQLAlchemy dla Azure Databricks wykorzystuje Databricks SQL Connector dla Python do połączenia i przekazuje do konektora wartości z connect_args. Obsługuje następujące typy uwierzytelniania:

Uwierzytelnianie za pomocą osobistego tokena dostępu

Aby utworzyć osobisty token dostępu usługi Azure Databricks, wykonaj kroki opisane w artykule Tworzenie osobistych tokenów dostępu dla użytkowników obszaru roboczego.

Aby uwierzytelnić dialekt SQLAlchemy, użyj następującego fragmentu kodu. W tym fragmencie kodu założono, że ustawiono następujące zmienne środowiskowe:

  • DATABRICKS_TOKENustawiony na osobisty token dostępu usługi Azure Databricks.
  • DATABRICKS_SERVER_HOSTNAMEustawioną na wartość nazwy hosta serwera dla twojego klastra lub magazynu SQL.
  • DATABRICKS_HTTP_PATHustaw wartość ścieżki HTTP dla klastra lub magazynu SQL.
  • DATABRICKS_CATALOG, ustawiony w katalogu docelowym katalogu Unity.
  • DATABRICKS_SCHEMA, ustawiony na schemat docelowy (znany również jako baza danych) w katalogu Unity.

Aby ustawić zmienne środowiskowe, zapoznaj się z dokumentacją systemu operacyjnego.

import os
from sqlalchemy import create_engine

access_token    = os.getenv("DATABRICKS_TOKEN")
server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME")
http_path       = os.getenv("DATABRICKS_HTTP_PATH")
catalog         = os.getenv("DATABRICKS_CATALOG")
schema          = os.getenv("DATABRICKS_SCHEMA")

engine = create_engine(
  url = f"databricks://token:{access_token}@{server_hostname}?" +
        f"http_path={http_path}&catalog={catalog}&schema={schema}"
)

# ...

Poprzednia zmienna engine służy do łączenia się z określonym wykazem i schematem za pośrednictwem zasobu obliczeniowego usługi Azure Databricks.

Uwierzytelnianie OAuth typu użytkownik-maszyna (U2M)

Uwierzytelnianie OAuth U2M wykorzystuje logowanie użytkownika w czasie rzeczywistym i zgodę na uwierzytelnienie, aby uwierzytelnić docelowe konto użytkownika Azure Databricks. Aby dowiedzieć się, które wersje Databricks SQL Connector for Python są obsługiwane w każdej chmurze, zobacz uwierzytelnianie OAuth użytkownik-maszyna (U2M).

Aby uwierzytelnić dialekt SQLAlchemy za pomocą OAuth U2M, użyj poniższego fragmentu kodu. Ten fragment zakłada, że ustawiłeś DATABRICKS_SERVER_HOSTNAME, DATABRICKS_HTTP_PATH, DATABRICKS_CATALOG i DATABRICKS_SCHEMA zmienne środowiskowe, jak opisano w uwierzytelnianiu tokenem dostępu osobistego.

import os
from sqlalchemy import create_engine

server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME")
http_path       = os.getenv("DATABRICKS_HTTP_PATH")
catalog         = os.getenv("DATABRICKS_CATALOG")
schema          = os.getenv("DATABRICKS_SCHEMA")

engine = create_engine(
  url = f"databricks://{server_hostname}?" +
        f"http_path={http_path}&catalog={catalog}&schema={schema}",
  connect_args = {"auth_type": "databricks-oauth"}
)

# ...

Uwierzytelnianie komunikacji maszyna-maszyna OAuth (M2M)

OAuth M2M authentication uwierzytelnia jako jednostkę usługi Azure Databricks. Musisz także zainstalować Databricks SDK dla Python (na przykład uruchamiając pip install databricks-sdk). Aby dowiedzieć się o Databricks SQL Connector for Python oraz wersjach SDK, które obsługują go w każdej chmurze, zobacz uwierzytelnianie OAuth typu maszyna-maszyna (M2M).

Aby użyć uwierzytelniania OAuth M2M, wykonaj następujące czynności:

  1. Utwórz wchód główny usługi Azure Databricks w obszarze roboczym Azure Databricks i utwórz tajemnicę OAuth dla tego wchodu głównego. Zobacz Autoryzowanie dostępu jednostki usługi do usługi Azure Databricks przy użyciu protokołu OAuth.
  2. Daj tej jednostce usługi dostęp do swojego klastra lub magazynu SQL. Zobacz Uprawnienia obliczeniowe lub Zarządzanie usługą SQL Warehouse.

Aby uwierzytelnić dialekt SQLAlchemy za pomocą OAuth M2M, użyj poniższego fragmentu kodu. Oprócz zmiennych środowiskowych DATABRICKS_SERVER_HOSTNAME, DATABRICKS_HTTP_PATH, DATABRICKS_CATALOG oraz DATABRICKS_SCHEMA, ten fragment zakłada, że ustaliłeś następujące zmienne środowiskowe:

  • DATABRICKS_CLIENT_ID, przypisz do wartości UUID jednostki głównej usługi lub Identyfikator aplikacji.
  • DATABRICKS_CLIENT_SECRET, ustaw wartość tajnego klucza dla tajnego klucza OAuth głównego obiektu usługi.
import os
from databricks.sdk.core import Config, oauth_service_principal
from sqlalchemy import create_engine

server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME")
http_path       = os.getenv("DATABRICKS_HTTP_PATH")
catalog         = os.getenv("DATABRICKS_CATALOG")
schema          = os.getenv("DATABRICKS_SCHEMA")

def credential_provider():
  config = Config(
    host          = f"https://{server_hostname}",
    client_id     = os.getenv("DATABRICKS_CLIENT_ID"),
    client_secret = os.getenv("DATABRICKS_CLIENT_SECRET"))
  return oauth_service_principal(config)

engine = create_engine(
  url = f"databricks://{server_hostname}?" +
        f"http_path={http_path}&catalog={catalog}&schema={schema}",
  connect_args = {"credentials_provider": credential_provider}
)

# ...

SQLAlchemy, wersja 1

Przykłady połączeń można znaleźć w tym example.py

SQLAlchemy, wersja 2

Przykłady połączeń można znaleźć w poniższej sekcji i pliku sqlalchemy_example.py w usłudze GitHub.

Referencja DBAPI

Dodatkowe zasoby

  • Ostatnia aktualizacja o