Установка Databricks Подключение для Python

Примечание.

В этой статье рассматриваются Подключение Databricks runtime 13.0 и более поздних версий.

В этой статье описывается установка Databricks Подключение для Python. См. раздел "Что такое Databricks Подключение?". Сведения о версии Scala этой статьи см. в разделе Install Databricks Подключение для Scala.

Требования

• Целевая рабочая область Azure Databricks и кластер должны соответствовать требованиям к конфигурации кластера для Databricks Подключение.

• Необходимо установить Python 3 на компьютере разработки, а дополнительная версия клиентской установки Python должна совпадать с дополнительной версией Python кластера Azure Databricks. Чтобы найти дополнительную версию Python кластера, ознакомьтесь с разделом "Системная среда" заметок о выпуске Databricks Runtime для кластера. См . заметки о выпуске Databricks Runtime и версии совместимости.

  Примечание.

  Если вы хотите использовать определяемые пользователем функции PySpark, важно, чтобы на компьютере разработки была установлена дополнительная версия Python, соответствующая дополнительной версии Python, которая входит в состав Databricks Runtime, установленной в кластере.

• Версия основного и дополнительного пакета Databricks Подключение должна соответствовать версии databricks Runtime. Рекомендуется всегда использовать последнюю версию пакета Databricks Connect, соответствующую версии Databricks Runtime. Например, при использовании кластера Databricks Runtime 14.0 также следует использовать 14.0 версию databricks-connect пакета.

  Примечание.

  Список доступных выпусков Databricks Connect и обновлений обслуживания см. в разделе Заметки о выпуске Databricks Connect.

  Использование самого последнего пакета Databricks Подключение, соответствующего версии среды выполнения Databricks, не является обязательным требованием. Для Databricks Runtime 13.3 LTS и более поздних версий можно использовать пакет Databricks Подключение для всех версий Databricks Runtime в версии пакета Databricks Подключение. Однако если вы хотите использовать функции, доступные в более поздних версиях среды выполнения Databricks, необходимо соответствующим образом обновить пакет Databricks Подключение.

• Databricks настоятельно рекомендует активировать виртуальную среду Python для каждой версии Python, которая используется с Databricks Подключение. Виртуальные среды Python помогают убедиться, что вы используете правильные версии Python и Databricks Подключение вместе. Это может помочь сократить или сократить устранение связанных технических проблем. Узнайте, как активировать виртуальную среду Python для venv или поэзию в следующих разделах. Дополнительные сведения об этих инструментах см . в venv или поэзии.

Активация виртуальной среды Python с помощью venv

Если вы используете venv на компьютере разработки, а кластер работает под управлением Python 3.10, необходимо создать venv среду с этой версией. В следующем примере команды создаются скрипты для активации venv среды с помощью Python 3.10, а затем эта команда помещает эти скрипты в скрытую папку с именем .venv в текущем рабочем каталоге:

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

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

Сведения об использовании этих скриптов для активации этой venv среды см. в статье о работе venvs.

Перейдите вперед, чтобы настроить клиент.

Активация виртуальной среды Python с помощью поэзии

1. Установите поэзию, если вы еще этого не сделали.

2. Если вы используете поэзию на компьютере разработки и кластер работает под управлением Python 3.10, необходимо создать виртуальную среду поэзии с этой версией. В корневом каталоге существующего проекта кода Python необходимо poetry инициализировать проект кода Python для поэзии, выполнив следующую команду:

   poetry init
   

3. Поэзия отображает несколько подсказок для завершения. Ни один из этих запросов не зависит от Подключение Databricks. Сведения об этих запросах см . в разделе "Инициализация".

4. После выполнения запросов поэзия добавляет pyproject.toml файл в проект Python. Сведения о pyproject.toml файле см. в файле pyproject.toml.

5. В корневом каталоге проекта кода Python вы можете poetry считывать pyproject.toml файл, разрешать зависимости и устанавливать их, создавать poetry.lock файл для блокировки зависимостей и, наконец, создавать виртуальную среду. Для этого выполните следующую команду:

   poetry install
   

6. В корневом каталоге проекта кода Python необходимо poetry активировать виртуальную среду и ввести оболочку. Для этого выполните следующую команду:

   poetry shell
   

Вы будете знать, что виртуальная среда активируется, и оболочка вводится, когда имя виртуальной среды отображается в скобках непосредственно перед запросом терминала, например (my-project-py3.10).

Чтобы отключить виртуальную среду и выйти из оболочки в любое время, выполните команду exit.

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

Дополнительные сведения о создании виртуальных сред поэзии и управлении ими см. в статье "Управление средами".

Настройка клиента

Совет

Если у вас уже установлено расширение Databricks для Visual Studio Code, вам не нужно следовать этим инструкциям по настройке.

Расширение Databricks для Visual Studio Code уже имеет встроенную поддержку Databricks Подключение для Databricks Runtime 13.0 и более поздних версий. Перейдите к коду отладки с помощью Databricks Подключение расширения Databricks для Visual Studio Code.

После выполнения требований к Подключение Databricks выполните следующие действия, чтобы настроить клиент Databricks Подключение.

Шаг 1. Установка клиента Databricks Подключение

В этом разделе описывается установка клиента Databricks Подключение с помощью venv или Поэзии.

Установка клиента Databricks Подключение с помощью venv

1. После активации виртуальной среды удалите PySpark, если оно уже установлено, выполнив uninstall команду. Это необходимо, так как пакет databricks-connect конфликтует с PySpark. Дополнительные сведения см. в разделе Конфликтующие установки PySpark. Чтобы проверка, установлен ли PySpark, выполните show команду.

   # Is PySpark already installed?
   pip3 show pyspark
   
   # Uninstall PySpark
   pip3 uninstall pyspark
   

2. При активации виртуальной среды установите клиент Databricks Подключение, выполнив install команду. --upgrade Используйте параметр для обновления любой существующей установки клиента до указанной версии.

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

   Примечание.

   Databricks рекомендует добавить нотацию dot-asterisk, чтобы указать databricks-connect==X.Y.* вместо нее databricks-connect=X.Y, чтобы убедиться, что установлен последний пакет. Хотя это не является обязательным требованием, он помогает убедиться, что вы можете использовать последние поддерживаемые функции для этого кластера.

Перейдите к шагу 2. Настройка свойств подключения.

Установка клиента Databricks Подключение с помощью поэзии

1. После активации виртуальной среды удалите PySpark, если оно уже установлено, выполнив remove команду. Это необходимо, так как пакет databricks-connect конфликтует с PySpark. Дополнительные сведения см. в разделе Конфликтующие установки PySpark. Чтобы проверка, установлен ли PySpark, выполните show команду.

   # Is PySpark already installed?
   poetry show pyspark
   
   # Uninstall PySpark
   poetry remove pyspark
   

2. При активации виртуальной среды установите клиент Databricks Подключение, выполнив add команду.

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

   Примечание.

   Databricks рекомендует использовать нотацию at-tilde, чтобы указать databricks-connect@~14.0 вместо нее databricks-connect==14.0, чтобы убедиться, что последний пакет установлен. Хотя это не является обязательным требованием, он помогает убедиться, что вы можете использовать последние поддерживаемые функции для этого кластера.

Шаг 2. Настройка свойств подключения

В этом разделе описана настройка свойств для установления соединения между Databricks Подключение и удаленным кластером Azure Databricks. Эти свойства включают параметры для проверки подлинности Databricks Подключение в кластере.

Для Databricks Подключение для Databricks Runtime 13.1 и более поздних версий Databricks Подключение включает пакет SDK Databricks для Python. Этот пакет SDK реализует стандарт унифицированной проверки подлинности клиента Databricks, консолидированный и согласованный архитектурный и программный подход к проверке подлинности. Этот подход делает настройку и автоматизацию проверки подлинности с помощью Azure Databricks более централизованным и предсказуемым. Он позволяет настроить проверку подлинности Azure Databricks один раз, а затем использовать эту конфигурацию в нескольких средствах и пакетах SDK Azure Databricks без дальнейших изменений конфигурации проверки подлинности.

Примечание.

• Проверка подлинности OAuth на компьютере (U2M) поддерживается в пакете SDK Databricks для Python 0.19.0 и более поздних версий. Возможно, потребуется обновить установленную версию проекта кода пакета SDK Databricks для Python до 0.19.0 или более поздней, чтобы использовать проверку подлинности OAuth U2M. Ознакомьтесь с пакетом SDK Databricks для Python.

  Для проверки подлинности OAuth U2M необходимо использовать интерфейс командной строки Databricks для проверки подлинности перед запуском кода Python. См. руководство.

• Проверка подлинности OAuth на компьютере (M2M) OAuth на компьютере (M2M) поддерживается в пакете SDK Databricks для Python 0.18.0 и более поздних версий. Возможно, потребуется обновить установленную версию проекта кода пакета SDK Databricks для Python до 0.18.0 или более поздней, чтобы использовать проверку подлинности OAuth M2M. Ознакомьтесь с пакетом SDK Databricks для Python.

• Пакет SDK Databricks для Python еще не реализовал проверку подлинности управляемых удостоверений Azure.

• Databricks Подключение для Databricks Runtime 13.0 поддерживает проверку подлинности только личного маркера доступа Azure Databricks.

1. Соберите следующие свойства конфигурации.

   • Имя экземпляра рабочей области Azure Databricks. Это совпадает со значением имени узла сервера для кластера. Дополнительные сведения о подключении для вычислительного ресурса Azure Databricks см. в статье .
   • Идентификатор кластера. Идентификатор кластера можно получить по URL-адресу. См . URL-адрес кластера и идентификатор.
   • Любые другие свойства, необходимые для поддерживаемого типа проверки подлинности Databricks, который требуется использовать. Эти свойства описаны в этом разделе.

2. Настройте подключение в коде. Databricks Подключение ищет свойства конфигурации в следующем порядке, пока не найдет их. Когда он находит их, он перестает выполнять поиск по оставшимся параметрам. Сведения о каждом параметре отображаются после следующей таблицы:

   Параметр свойств конфигурации	Применяется к
   1. DatabricksSession Метод класса remote()	Проверка подлинности маркера личного доступа Azure Databricks
   2. Профиль конфигурации Azure Databricks	Все типы проверки подлинности Azure Databricks
   3. Переменная SPARK_REMOTE среды	Проверка подлинности маркера личного доступа Azure Databricks
   4. Переменная DATABRICKS_CONFIG_PROFILE среды	Все типы проверки подлинности Azure Databricks
   5. Переменная среды для каждого свойства конфигурации	Все типы проверки подлинности Azure Databricks
   6. Профиль конфигурации Azure Databricks с именем DEFAULT	Все типы проверки подлинности Azure Databricks

   1. DatabricksSession Метод класса remote()

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

      Класс можно инициализировать DatabricksSession несколькими способами следующим образом:

      • hostЗадайте в поле , tokenа также cluster_id поля DatabricksSession.builder.remote().
      • Используйте класс пакета SDK Config Databricks.
      • Укажите профиль конфигурации Databricks вместе с полем cluster_id .
      • Задайте Подключение строка подключения Spark в DatabricksSession.builder.remote().

      Databricks не рекомендует напрямую указывать эти свойства подключения в коде. Вместо этого Databricks рекомендует настраивать свойства с помощью переменных среды или файлов конфигурации, как описано в этом разделе. В следующих примерах кода предполагается, что вы предоставляете некоторые реализации предлагаемых retrieve_* функций самостоятельно, чтобы получить необходимые свойства от пользователя или из другого хранилища конфигурации, например Azure KeyVault.

      Код для каждого из этих подходов выглядит следующим образом:

      # 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

      Для этого параметра создайте или определите профиль конфигурации Azure Databricks, содержащий поле cluster_id и любые другие поля, необходимые для типа проверки подлинности Databricks, который требуется использовать.

      Обязательные поля профиля конфигурации для каждого типа проверки подлинности приведены следующим образом:

      • Для проверки подлинности маркера личного доступа Azure Databricks: host и token.
      • Для проверки подлинности на компьютере (M2M) OAuth (где поддерживается): hostclient_idи client_secret.
      • Для проверки подлинности OAuth между компьютерами (U2M) (где поддерживается): host
      • Для проверки подлинностиhost субъекта-службы Microsoft Entra ID (ранее — Azure Active Directory): , azure_tenant_id, azure_client_idazure_client_secretи, возможноazure_workspace_resource_id, .
      • Для проверки подлинности Azure CLI: host
      • Для проверки подлинности управляемых удостоверений Azure (где поддерживается): host, azure_use_msiazure_client_idи, возможноazure_workspace_resource_id, .

      Затем задайте имя этого профиля конфигурации через Config класс.

      Можно указать cluster_id несколько способов, как показано ниже.

      • cluster_id Включите поле в профиль конфигурации, а затем просто укажите имя профиля конфигурации.
      • Укажите имя профиля конфигурации вместе с полем cluster_id .

      Если вы уже установили DATABRICKS_CLUSTER_ID переменную среды с идентификатором кластера, вам также не нужно указывать cluster_id.

      Код для каждого из этих подходов выглядит следующим образом:

      # 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. Переменная SPARK_REMOTE среды

      Для этого параметра, который применяется только к проверке подлинности маркера личного доступа Azure Databricks, задайте SPARK_REMOTE переменную среды в следующую строку, заменив заполнители соответствующими значениями.

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

      Затем инициализировать DatabricksSession класс следующим образом:

      from databricks.connect import DatabricksSession
      
      spark = DatabricksSession.builder.getOrCreate()
      

      Чтобы задать переменные среды, ознакомьтесь с документацией операционной системы.

   4. Переменная DATABRICKS_CONFIG_PROFILE среды

      Для этого параметра создайте или определите профиль конфигурации Azure Databricks, содержащий поле cluster_id и любые другие поля, необходимые для типа проверки подлинности Databricks, который требуется использовать.

      Если вы уже установили DATABRICKS_CLUSTER_ID переменную среды с идентификатором кластера, вам также не нужно указывать cluster_id.

      Обязательные поля профиля конфигурации для каждого типа проверки подлинности приведены следующим образом:

      • Для проверки подлинности маркера личного доступа Azure Databricks: host и token.
      • Для проверки подлинности на компьютере (M2M) OAuth (где поддерживается): hostclient_idи client_secret.
      • Для проверки подлинности OAuth между компьютерами (U2M) (где поддерживается): host
      • Для проверки подлинностиhost субъекта-службы Microsoft Entra ID (ранее — Azure Active Directory): , azure_tenant_id, azure_client_idazure_client_secretи, возможноazure_workspace_resource_id, .
      • Для проверки подлинности Azure CLI: host
      • Для проверки подлинности управляемых удостоверений Azure (где поддерживается): host, azure_use_msiazure_client_idи, возможноazure_workspace_resource_id, .

      Задайте для переменной DATABRICKS_CONFIG_PROFILE среды имя этого профиля конфигурации. Затем инициализировать DatabricksSession класс следующим образом:

      from databricks.connect import DatabricksSession
      
      spark = DatabricksSession.builder.getOrCreate()
      

      Чтобы задать переменные среды, ознакомьтесь с документацией операционной системы.

   5. Переменная среды для каждого свойства конфигурации

      Для этого параметра задайте DATABRICKS_CLUSTER_ID переменную среды и любые другие переменные среды, необходимые для типа проверки подлинности Databricks, который требуется использовать.

      Необходимые переменные среды для каждого типа проверки подлинности приведены следующим образом:

      • Для проверки подлинности маркера личного доступа Azure Databricks: DATABRICKS_HOST и DATABRICKS_TOKEN.
      • Для проверки подлинности на компьютере (M2M) OAuth (где поддерживается): DATABRICKS_HOSTDATABRICKS_CLIENT_IDи DATABRICKS_CLIENT_SECRET.
      • Для проверки подлинности OAuth между компьютерами (U2M) (где поддерживается): DATABRICKS_HOST
      • Для проверки подлинностиDATABRICKS_HOST субъекта-службы Microsoft Entra ID (ранее — Azure Active Directory): , ARM_TENANT_ID, ARM_CLIENT_IDARM_CLIENT_SECRETи, возможноDATABRICKS_AZURE_RESOURCE_ID, .
      • Для проверки подлинности Azure CLI: DATABRICKS_HOST
      • Для проверки подлинности управляемых удостоверений Azure (где поддерживается): DATABRICKS_HOST, ARM_USE_MSIARM_CLIENT_IDи, возможноDATABRICKS_AZURE_RESOURCE_ID, .

      Затем инициализировать DatabricksSession класс следующим образом:

      from databricks.connect import DatabricksSession
      
      spark = DatabricksSession.builder.getOrCreate()
      

      Чтобы задать переменные среды, ознакомьтесь с документацией операционной системы.

   6. Профиль конфигурации Azure Databricks с именем DEFAULT

      Для этого параметра создайте или определите профиль конфигурации Azure Databricks, содержащий поле cluster_id и любые другие поля, необходимые для типа проверки подлинности Databricks, который требуется использовать.

      Если вы уже установили DATABRICKS_CLUSTER_ID переменную среды с идентификатором кластера, вам также не нужно указывать cluster_id.

      Обязательные поля профиля конфигурации для каждого типа проверки подлинности приведены следующим образом:

      • Для проверки подлинности маркера личного доступа Azure Databricks: host и token.
      • Для проверки подлинности на компьютере (M2M) OAuth (где поддерживается): hostclient_idи client_secret.
      • Для проверки подлинности OAuth между компьютерами (U2M) (где поддерживается): host
      • Для проверки подлинностиhost субъекта-службы Microsoft Entra ID (ранее — Azure Active Directory): , azure_tenant_id, azure_client_idazure_client_secretи, возможноazure_workspace_resource_id, .
      • Для проверки подлинности Azure CLI: host
      • Для проверки подлинности управляемых удостоверений Azure (где поддерживается): host, azure_use_msiazure_client_idи, возможноazure_workspace_resource_id, .

      Присвойте этому профилю DEFAULTконфигурации имя.

      Затем инициализировать DatabricksSession класс следующим образом:

      from databricks.connect import DatabricksSession
      
      spark = DatabricksSession.builder.getOrCreate()
      

3. Проверка среды и подключение к кластеру Databricks

   • Следующая команда убедитесь, что среда, учетные данные по умолчанию и подключение к кластеру настроены правильно для Databricks Подключение.

     databricks-connect test
     

     Эта команда выбирает учетные данные по умолчанию, настроенные в среде (например DEFAULT , профиль конфигурации или переменные среды).

     Команда завершается ошибкой с кодом выхода без нуля и соответствующим сообщением об ошибке при обнаружении несоответствия в настройке.

   • Кроме того, можно также использовать оболочкуpyspark, которая входит в состав Databricks Подключение для Python. Запустите оболочку, выполнив следующую команду:

     pyspark
     

     Появится оболочка Spark, например:

     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'.
     >>>
     

     В командной строке >>> выполните простую команду PySpark, например spark.range(1,10).show(). Если ошибки отсутствуют, вы успешно подключились.

     Если вы успешно подключились, остановите оболочку Spark, нажмите Ctrl + d или Ctrl + zвыполните команду или выполните командуquit().exit()

     Дополнительные сведения о двоичном databricks-connect файле см. в статье "Расширенное использование Databricks Подключение для Python"