Python için Databricks Bağlan yükleme

  • Makale

Not

Bu makalede Databricks Runtime 13.0 ve üzeri için Databricks Bağlan yer alır.

Bu makalede Python için Databricks Bağlan'nin nasıl yükleneceği açıklanmaktadır. Bkz. Databricks Bağlan nedir?. Bu makalenin Scala sürümü için bkz. Scala için Databricks Bağlan yükleme.

Gereksinimler

  • Hedef Azure Databricks çalışma alanınız ve kümeniz Databricks Bağlan için Küme yapılandırması gereksinimlerini karşılamalıdır.

  • Geliştirme makinenize Python 3 yüklemeniz gerekir ve istemci Python yüklemenizin ikincil sürümü Azure Databricks kümenizin ikincil Python sürümüyle aynı olmalıdır. Kümenizin ikincil Python sürümünü bulmak için kümenizin Databricks Runtime sürüm notlarının "Sistem ortamı" bölümüne bakın. Bkz . Databricks Runtime sürüm notları sürümleri ve uyumluluğu.

    Not

    PySpark UDF'lerini kullanmak istiyorsanız, geliştirme makinenizin yüklü Python ikincil sürümünün, kümede yüklü Databricks Runtime'da bulunan Python'ın ikincil sürümüyle eşleşmesi önemlidir.

  • Databricks Bağlan birincil ve ikincil paket sürümü Databricks Runtime sürümünüzle eşleşmelidir. Databricks her zaman Databricks Runtime sürümünüzle eşleşen en son Databricks Bağlan paketini kullanmanızı önerir. Örneğin, Databricks Runtime 14.0 kümesi kullandığınızda, paketin 14.0databricks-connect sürümünü de kullanmanız gerekir.

    Not

    Kullanılabilir Databricks Bağlan sürümleri ve bakım güncelleştirmelerinin listesi için Databricks Bağlan sürüm notlarına bakın.

    Databricks Runtime sürümünüzle eşleşen en son Databricks Bağlan paketini kullanmak bir gereksinim değildir. Databricks Runtime 13.3 LTS ve üzeri için Databricks Bağlan paketini Databricks Bağlan paketinin sürümünde veya üzerinde Databricks Runtime'ın tüm sürümlerine karşı kullanabilirsiniz. Ancak, Databricks Runtime'ın sonraki sürümlerinde kullanılabilen özellikleri kullanmak istiyorsanız Databricks Bağlan paketini uygun şekilde yükseltmeniz gerekir.

  • Databricks, Databricks Bağlan ile kullandığınız her Python sürümü için etkinleştirilmiş bir Python sanal ortamına sahip olduğunuzu kesinlikle önerir. Python sanal ortamları, Python ve Databricks'in doğru sürümlerini Bağlan birlikte kullandığınızdan emin olmanıza yardımcı olur. Bu, ilgili teknik sorunları azaltmaya veya kısaltmaya yardımcı olabilir. Aşağıdaki bölümlerde veya Şiir için venv Python sanal ortamını etkinleştirmeyi öğrenin. Bu araçlar hakkında daha fazla bilgi için bkz . venv veya Şiir.

venv ile Python sanal ortamını etkinleştirme

Geliştirme makinenizde kullanıyorsanız venv ve kümeniz Python 3.10 çalıştırıyorsa, bu sürüme sahip bir venv ortam oluşturmanız gerekir. Aşağıdaki örnek komut, Python 3.10 ile bir venv ortamı etkinleştirmek için betikleri oluşturur ve bu komut bu betikleri geçerli çalışma dizininde adlı .venv gizli bir klasöre yerleştirir:

# Linux and macOS
python3.10 -m venv ./.venv

# Windows
python3.10 -m venv .\.venv

Bu betikleri kullanarak bu venv ortamı etkinleştirmek için bkz . Venv'ler nasıl çalışır?

İstemciyi ayarlamaya atlayın.

Şiir ile Python sanal ortamını etkinleştirme

  1. Henüz yapmadıysanız Şiir yükleyin.

  2. Geliştirme makinenizde Şiir kullanıyorsanız ve kümeniz Python 3.10 çalıştırıyorsa, bu sürümle bir Şiir sanal ortamı oluşturmanız gerekir. Mevcut Python kod projenizin kök dizininden, poetry aşağıdaki komutu çalıştırarak Şiir için Python kod projenizi başlatmanızı isteyin:

    poetry init

  3. Şiir, tamamlamanız için birkaç istem gösterir. Bu istemlerin hiçbiri Databricks Bağlan'a özgü değil. Bu istemler hakkında bilgi için bkz . init.

  4. İstemleri tamamladıktan sonra, Şiir Python projenize bir pyproject.toml dosya ekler. Dosya hakkında pyproject.toml bilgi için bkz . pyproject.toml dosyası.

  5. Python kod projenizin kök dizininden dosyayı okumanızıpyproject.toml, poetry bağımlılıkları çözmenizi ve yüklemenizi, bağımlılıkları kilitlemek için bir poetry.lock dosya oluşturmanızı ve son olarak bir sanal ortam oluşturmanızı isteyin. Bunu yapmak için aşağıdaki komutu çalıştırın:

    poetry install

  6. Python kod projenizin kök dizininden sanal ortamı etkinleştirmenizi ve kabuğu girmenizi isteyin poetry . Bunu yapmak için aşağıdaki komutu çalıştırın:

    poetry shell

Sanal ortamınızın etkinleştirildiğini ve sanal ortamın adı terminal isteminizden hemen önce parantez içinde görüntülendiğinde kabuğun girildiğini bilirsiniz. Örneğin (my-project-py3.10).

Sanal ortamı devre dışı bırakmak ve kabukta istediğiniz zaman çıkmak için komutunu exitçalıştırın.

Sanal ortamın adı artık terminal isteminizden hemen önce parantez içinde görüntülenmediğinde kabukta çıktığınızı öğreneceksiniz.

Şiir sanal ortamları oluşturma ve yönetme hakkında daha fazla bilgi için bkz . Ortamları yönetme.

İstemciyi ayarlama

İpucu

Visual Studio Code için Databricks uzantısı zaten yüklüyse, bu kurulum yönergelerini izlemeniz gerekmez.

Visual Studio Code için Databricks uzantısı, Databricks Runtime 13.0 ve üzeri için Databricks Bağlan için yerleşik desteğe zaten sahiptir. Visual Studio Code için Databricks uzantısı için Databricks Bağlan kullanarak kodda hata ayıklamaya geçin.

Databricks Bağlan gereksinimlerini karşıladıktan sonra, Databricks Bağlan istemcisini ayarlamak için aşağıdaki adımları tamamlayın.

1. Adım: Databricks Bağlan istemcisini yükleme

Bu bölümlerde Venv veya Poetry ile Databricks Bağlan istemcisinin nasıl yükleneceği açıklanmaktadır.

Venv ile Databricks Bağlan istemcisini yükleme

  1. Sanal ortamınız etkinleştirildiğinde, pyspark zaten yüklüyse komutunu çalıştırarak uninstall kaldırın. Paketin PySpark ile çakışması databricks-connect nedeniyle bu gereklidir. Ayrıntılar için bkz . Çakışan PySpark yüklemeleri. PySpark'ın zaten yüklü olup olmadığını denetlemek için komutunu çalıştırın show .

    # Is PySpark already installed?
pip3 show pyspark

# Uninstall PySpark
pip3 uninstall pyspark

  2. Sanal ortamınız hala etkinken komutunu çalıştırarak Databricks Bağlan istemcisini install yükleyin. --upgrade Mevcut istemci yüklemelerini belirtilen sürüme yükseltmek için seçeneğini kullanın.

    pip3 install --upgrade "databricks-connect==14.0.*"  # Or X.Y.* to match your cluster version.

    Not

    Databricks, en son paketin yüklendiğinden emin olmak için yerine databricks-connect=X.Ybelirtmek databricks-connect==X.Y.* üzere "nokta-yıldız işareti" gösterimini eklemenizi önerir. Bu bir gereksinim olmasa da, bu küme için desteklenen en son özellikleri kullanabilmenize yardımcı olur.

2. Adım: Bağlantı özelliklerini yapılandırma'ya geçin.

Şiir ile Databricks Bağlan istemcisini yükleme

  1. Sanal ortamınız etkinleştirildiğinde, pyspark zaten yüklüyse komutunu çalıştırarak remove kaldırın. Paketin PySpark ile çakışması databricks-connect nedeniyle bu gereklidir. Ayrıntılar için bkz . Çakışan PySpark yüklemeleri. PySpark'ın zaten yüklü olup olmadığını denetlemek için komutunu çalıştırın show .

    # Is PySpark already installed?
poetry show pyspark

# Uninstall PySpark
poetry remove pyspark

  2. Sanal ortamınız hala etkinken komutunu çalıştırarak Databricks Bağlan istemcisini add yükleyin.

    poetry add databricks-connect@~14.0  # Or X.Y to match your cluster version.

    Not

    Databricks, en son paketin yüklendiğinden emin olmak için yerine databricks-connect==14.0belirtmek databricks-connect@~14.0 üzere "at-tilde" gösterimini kullanmanızı önerir. Bu bir gereksinim olmasa da, bu küme için desteklenen en son özellikleri kullanabilmenize yardımcı olur.

2. Adım: Bağlantı özelliklerini yapılandırma

Bu bölümde, Databricks Bağlan ile uzak Azure Databricks kümeniz arasında bağlantı kurmak için özellikleri yapılandıracaksınız. Bu özellikler databricks Bağlan kümenizle kimlik doğrulamasına yönelik ayarları içerir.

Databricks Runtime 13.1 ve üzeri için Databricks Bağlan için Databricks Bağlan, Python için Databricks SDK'sını içerir. Bu SDK, kimlik doğrulamasına yönelik birleştirilmiş ve tutarlı bir mimari ve programlı yaklaşım olan Databricks istemci birleşik kimlik doğrulama standardını uygular. Bu yaklaşım, Azure Databricks ile kimlik doğrulamasını ayarlamayı ve otomatikleştirmeyi daha merkezi ve öngörülebilir hale getirir. Azure Databricks kimlik doğrulamasını bir kez yapılandırmanıza ve daha fazla kimlik doğrulaması yapılandırma değişikliği yapmadan bu yapılandırmayı birden çok Azure Databricks aracında ve SDK'da kullanmanıza olanak tanır.

Not

  • OAuth kullanıcıdan makineye (U2M) kimlik doğrulaması , Python 0.19.0 ve üzeri için Databricks SDK'sı üzerinde desteklenir. OAuth U2M kimlik doğrulamasını kullanmak için kod projenizin Python için Databricks SDK'sının yüklü sürümünü 0.19.0 veya üzeri bir sürüme güncelleştirmeniz gerekebilir. Bkz . Python için Databricks SDK'sını kullanmaya başlama.

    OAuth U2M kimlik doğrulaması için, Python kodunuzu çalıştırmadan önce kimlik doğrulaması yapmak için Databricks CLI'yi kullanmanız gerekir. Öğretici'ye bakın.

  • OAuth makineden makineye (M2M) kimlik doğrulaması OAuth makineden makineye (M2M) kimlik doğrulaması, Python 0.18.0 ve üzeri için Databricks SDK'sı üzerinde desteklenir. OAuth M2M kimlik doğrulamasını kullanmak için kod projenizin Python için Databricks SDK'sının yüklü sürümünü 0.18.0 veya üzeri bir sürüme güncelleştirmeniz gerekebilir. Bkz . Python için Databricks SDK'sını kullanmaya başlama.

  • Python için Databricks SDK'sı henüz Azure yönetilen kimlikleri kimlik doğrulamasını uygulamadı.

  • Databricks Runtime 13.0 için Databricks Bağlan, kimlik doğrulaması için yalnızca Azure Databricks kişisel erişim belirteci kimlik doğrulamasını destekler.

  1. Aşağıdaki yapılandırma özelliklerini toplayın.

  2. Kodunuzun içindeki bağlantıyı yapılandırın. Databricks Bağlan, yapılandırma özelliklerini bulana kadar aşağıdaki sırayla arar. Bunları bulduklarında, kalan seçeneklerde aramayı durdurur. Her seçeneğin ayrıntıları aşağıdaki tablodan sonra görünür:

    Yapılandırma özellikleri seçeneği Şunlara uygulanır
    1. Sınıfın DatabricksSessionremote() yöntemi Yalnızca Azure Databricks kişisel erişim belirteci kimlik doğrulaması
    2. Azure Databricks yapılandırma profili Tüm Azure Databricks kimlik doğrulama türleri
    3. Ortam SPARK_REMOTE değişkeni Yalnızca Azure Databricks kişisel erişim belirteci kimlik doğrulaması
    4. Ortam DATABRICKS_CONFIG_PROFILE değişkeni Tüm Azure Databricks kimlik doğrulama türleri
    5. Her yapılandırma özelliği için bir ortam değişkeni Tüm Azure Databricks kimlik doğrulama türleri
    6. Adlı bir Azure Databricks yapılandırma profili DEFAULT Tüm Azure Databricks kimlik doğrulama türleri

    1. Sınıfın DatabricksSessionremote() yöntemi

      Yalnızca Azure Databricks kişisel erişim belirteci kimlik doğrulaması için geçerli olan bu seçenek için çalışma alanı örneği adını, Azure Databricks kişisel erişim belirtecini ve kümenin kimliğini belirtin.

      Sınıfı aşağıdaki gibi çeşitli yollarla başlatabilirsiniz DatabricksSession :

      • hostiçindeki DatabricksSession.builder.remote(), tokenve cluster_id alanlarını ayarlayın.
      • Databricks SDK'sının sınıfını Config kullanın.
      • Alanıyla cluster_id birlikte bir Databricks yapılandırma profili belirtin.
      • içinde Spark Bağlan bağlantı dizesi DatabricksSession.builder.remote()ayarlayın.

      Databricks, kodunuzda bu bağlantı özelliklerini doğrudan belirtmenizi önermez. Bunun yerine Databricks, bu bölümde açıklandığı gibi ortam değişkenleri veya yapılandırma dosyaları aracılığıyla özellikleri yapılandırmanızı önerir. Aşağıdaki kod örneklerde, kullanıcıdan veya Azure KeyVault gibi başka bir yapılandırma deposundan gerekli özellikleri almak için önerilen retrieve_* işlevlerin bazı uygulamalarını sağladığınız varsayılır.

      Bu yaklaşımların her birinin kodu aşağıdaki gibidir:

      # Set the host, token, and cluster_id fields in DatabricksSession.builder.remote.
# If you have already set the DATABRICKS_CLUSTER_ID environment variable with the
# cluster's ID, you do not also need to set the cluster_id field here.
from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.remote(
  host       = f"https://{retrieve_workspace_instance_name()}",
  token      = retrieve_token(),
  cluster_id = retrieve_cluster_id()
).getOrCreate()

# Use the Databricks SDK's Config class.
# If you have already set the DATABRICKS_CLUSTER_ID environment variable with the
# cluster's ID, you do not also need to set the cluster_id field here.
from databricks.connect import DatabricksSession
from databricks.sdk.core import Config

config = Config(
  host       = f"https://{retrieve_workspace_instance_name()}",
  token      = retrieve_token(),
  cluster_id = retrieve_cluster_id()
)

spark = DatabricksSession.builder.sdkConfig(config).getOrCreate()

# Specify a Databricks configuration profile along with the `cluster_id` field.
# If you have already set the DATABRICKS_CLUSTER_ID environment variable with the
# cluster's ID, you do not also need to set the cluster_id field here.
from databricks.connect import DatabricksSession
from databricks.sdk.core import Config

config = Config(
  profile    = "<profile-name>",
  cluster_id = retrieve_cluster_id()
)

spark = DatabricksSession.builder.sdkConfig(config).getOrCreate()

# Set the Spark Connect connection string in DatabricksSession.builder.remote.
from databricks.connect import DatabricksSession

workspace_instance_name = retrieve_workspace_instance_name()
token                   = retrieve_token()
cluster_id              = retrieve_cluster_id()

spark = DatabricksSession.builder.remote(
  f"sc://{workspace_instance_name}:443/;token={token};x-databricks-cluster-id={cluster_id}"
).getOrCreate()

    2. Azure Databricks yapılandırma profili

      Bu seçenek için, kullanmak istediğiniz Databricks kimlik doğrulama türü için gerekli olan alanı cluster_id ve diğer alanları içeren bir Azure Databricks yapılandırma profili oluşturun veya tanımlayın.

      Her kimlik doğrulama türü için gerekli yapılandırma profili alanları aşağıdaki gibidir:

      Ardından sınıfı aracılığıyla bu yapılandırma profilinin Config adını ayarlayın.

      Aşağıdaki gibi birkaç şekilde belirtebilirsiniz cluster_id :

      • cluster_id Alanı yapılandırma profilinize ekleyin ve yapılandırma profilinin adını belirtmeniz yeter.
      • Alanıyla cluster_id birlikte yapılandırma profili adını belirtin.

      Ortam değişkenini kümenin DATABRICKS_CLUSTER_ID kimliğiyle önceden ayarladıysanız, belirtmeniz de gerekmez cluster_id.

      Bu yaklaşımların her birinin kodu aşağıdaki gibidir:

      # Include the cluster_id field in your configuration profile, and then
# just specify the configuration profile's name:
from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.profile("<profile-name>").getOrCreate()

# Specify the configuration profile name along with the cluster_id field.
# In this example, retrieve_cluster_id() assumes some custom implementation that
# you provide to get the cluster ID from the user or from some other
# configuration store:
from databricks.connect import DatabricksSession
from databricks.sdk.core import Config

config = Config(
  profile    = "<profile-name>",
  cluster_id = retrieve_cluster_id()
)

spark = DatabricksSession.builder.sdkConfig(config).getOrCreate()

    3. Ortam SPARK_REMOTE değişkeni

      Yalnızca Azure Databricks kişisel erişim belirteci kimlik doğrulaması için geçerli olan bu seçenek için ortam değişkenini aşağıdaki dizeye ayarlayarak SPARK_REMOTE yer tutucuları uygun değerlerle değiştirin.

      sc://<workspace-instance-name>:443/;token=<access-token-value>;x-databricks-cluster-id=<cluster-id>

      Ardından sınıfını DatabricksSession aşağıdaki gibi başlatın:

      from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

      Ortam değişkenlerini ayarlamak için işletim sisteminizin belgelerine bakın.

    4. Ortam DATABRICKS_CONFIG_PROFILE değişkeni

      Bu seçenek için, kullanmak istediğiniz Databricks kimlik doğrulama türü için gerekli olan alanı cluster_id ve diğer alanları içeren bir Azure Databricks yapılandırma profili oluşturun veya tanımlayın.

      Ortam değişkenini kümenin DATABRICKS_CLUSTER_ID kimliğiyle önceden ayarladıysanız, belirtmeniz de gerekmez cluster_id.

      Her kimlik doğrulama türü için gerekli yapılandırma profili alanları aşağıdaki gibidir:

      Ortam değişkenini DATABRICKS_CONFIG_PROFILE bu yapılandırma profilinin adına ayarlayın. Ardından sınıfını DatabricksSession aşağıdaki gibi başlatın:

      from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

      Ortam değişkenlerini ayarlamak için işletim sisteminizin belgelerine bakın.

    5. Her yapılandırma özelliği için bir ortam değişkeni

      Bu seçenek için, kullanmak istediğiniz Databricks kimlik doğrulama türü için gereken ortam değişkenini ve diğer ortam değişkenlerini ayarlayınDATABRICKS_CLUSTER_ID.

      Her kimlik doğrulama türü için gerekli ortam değişkenleri aşağıdaki gibidir:

      Ardından sınıfını DatabricksSession aşağıdaki gibi başlatın:

      from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

      Ortam değişkenlerini ayarlamak için işletim sisteminizin belgelerine bakın.

    6. adlı bir Azure Databricks yapılandırma profili DEFAULT

      Bu seçenek için, kullanmak istediğiniz Databricks kimlik doğrulama türü için gerekli olan alanı cluster_id ve diğer alanları içeren bir Azure Databricks yapılandırma profili oluşturun veya tanımlayın.

      Ortam değişkenini kümenin DATABRICKS_CLUSTER_ID kimliğiyle önceden ayarladıysanız, belirtmeniz de gerekmez cluster_id.

      Her kimlik doğrulama türü için gerekli yapılandırma profili alanları aşağıdaki gibidir:

      Bu yapılandırma profilini olarak DEFAULTadlandır.

      Ardından sınıfını DatabricksSession aşağıdaki gibi başlatın:

      from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

  3. Ortamınızı ve Databricks kümesi bağlantısını doğrulama

    • Aşağıdaki komut ortamınızın, varsayılan kimlik bilgilerinizin ve küme bağlantısının Databricks Bağlan için doğru şekilde ayarlandığını doğrular.

      databricks-connect test

      Bu komut, ortamda (yapılandırma profili veya ortam değişkenleri gibi DEFAULT ) yapılandırılan varsayılan kimlik bilgilerini alır.

      Komut sıfır olmayan bir çıkış kodu ve kurulumda herhangi bir uyumsuzluk algıladığında buna karşılık gelen bir hata iletisiyle başarısız olur.

    • Ayrıca, Python için Databricks Bağlan kapsamındaki kabuğu da kullanabilirsinizpyspark. Aşağıdakileri çalıştırarak kabuğu başlatın:

      pyspark

      Spark kabuğu görüntülenir, örneğin:

      Python 3.10 ...
[Clang ...] on darwin
Type "help", "copyright", "credits" or "license" for more information.
Welcome to
      ____              __
     / __/__  ___ _____/ /__
    _\ \/ _ \/ _ `/ __/  '_/
   /__ / .__/\_,_/_/ /_/\_\   version 13.0
      /_/

Using Python version 3.10 ...
Client connected to the Spark Connect server at sc://...:.../;token=...;x-databricks-cluster-id=...
SparkSession available as 'spark'.
>>>

      >>> İstemde gibi spark.range(1,10).show()basit bir PySpark komutu çalıştırın. Hata yoksa başarıyla bağlandınız.

      Başarıyla bağlandıysanız Spark kabuğunu durdurmak için veya tuşuna basın Ctrl + d ya da komutunu quit() veya exit()komutunu çalıştırın.Ctrl + z

      İkili dosya hakkında databricks-connect daha fazla bilgi için bkz. Python için Databricks Bağlan gelişmiş kullanımı