安裝適用於 Python 的 Databricks Connect
注意
本文涵蓋 Databricks Runtime 13.3 LTS 和更新版本適用的 Databricks Connect。
本文說明如何安裝適用於 Python 的 Databricks Connect。 請參閱 什麼是 Databricks Connect?。 如需本文的 Scala 版本,請參閱 安裝適用於 Scala 的 Databricks Connect。
需求
若要安裝適用於 Python 的 Databricks Connect,必須符合下列需求:
您的開發計算機上必須安裝 Python 3,而安裝在開發電腦上的 Python 次要版本必須符合下表中的版本需求。
Databricks Connect 版本 計算類型 相容的 Python 版本 15.3 Cluster 3.11 15.2 Cluster 3.11 15.1 Cluster 3.11 15.1 無伺服器 3.10 13.3 LTS 至 14.3 LTS Cluster 3.10 如果您想要使用 PySpark UDF,您的開發電腦安裝的次要 Python 版本必須符合叢集或無伺服器計算上安裝之 Databricks Runtime 隨附的 Python 次要版本。 若要尋找叢集的次要 Python 版本,請參閱 適用於叢集或無伺服器計算之 Databricks Runtime 版本資訊的系統環境 一節。 請參閱 Databricks Runtime 版本資訊版本資訊,以及相容性 和 無伺服器計算版本資訊。
啟用 Python 虛擬環境
Databricks 強烈建議您已針對與 Databricks Connect 搭配使用的每個 Python 版本啟用 Python 虛擬環境 。 Python 虛擬環境可協助您確定您使用的是正確的 Python 版本和 Databricks Connect。 如需這些工具以及如何啟用這些工具的詳細資訊,請參閱 venv 或 詩歌。
安裝 Databricks Connect 用戶端
本節說明如何使用 venv 或 Poetry 安裝 Databricks Connect 用戶端。
注意
如果您已安裝適用於Visual Studio Code的 Databricks 擴充功能,就不需要遵循這些設定指示,因為適用於Visual Studio Code 的 Databricks 延伸模組已經內建支援 Databricks Connect for Databricks Runtime 13.3 LTS 和更新版本。 針對 Visual Studio Code 的 Databricks 延伸模組使用 Databricks Connect,跳至 偵錯程式代碼。
使用 venv 安裝 Databricks Connect 用戶端
啟用虛擬環境后,執行
uninstall
命令,以卸載已安裝 PySpark。 這是必要的,databricks-connect
因為套件與 PySpark 衝突。 如需詳細資訊,請參閱 衝突的 PySpark 安裝。 若要檢查是否已安裝 PySpark,請執行show
命令。# Is PySpark already installed? pip3 show pyspark # Uninstall PySpark pip3 uninstall pyspark
在虛擬環境仍啟用之後,請執行
install
命令來安裝 Databricks Connect 用戶端。--upgrade
使用 選項,將任何現有的用戶端安裝升級至指定的版本。pip3 install --upgrade "databricks-connect==14.3.*" # Or X.Y.* to match your cluster version.
注意
Databricks 建議您附加 「dot-asterisk」 表示法來指定
databricks-connect==X.Y.*
,而不是databricks-connect=X.Y
,以確保已安裝最新的套件。 雖然這不是必要條件,但它有助於確定您可以使用該叢集的最新支援功能。
直接跳到設定 連線屬性。
使用詩歌安裝 Databricks Connect 用戶端
啟用虛擬環境后,執行
remove
命令,以卸載已安裝 PySpark。 這是必要的,databricks-connect
因為套件與 PySpark 衝突。 如需詳細資訊,請參閱 衝突的 PySpark 安裝。 若要檢查是否已安裝 PySpark,請執行show
命令。# Is PySpark already installed? poetry show pyspark # Uninstall PySpark poetry remove pyspark
在虛擬環境仍啟用之後,請執行
add
命令來安裝 Databricks Connect 用戶端。poetry add databricks-connect@~14.3 # Or X.Y to match your cluster version.
注意
Databricks 建議您使用「波狀符號」表示法來指定
databricks-connect@~14.3
,而不是databricks-connect==14.3
,以確保已安裝最新的套件。 雖然這不是必要條件,但它有助於確定您可以使用該叢集的最新支援功能。
設定連線屬性
在本節中,您會設定屬性來建立 Databricks Connect 與 Azure Databricks 叢集 或 無伺服器計算之間的連線,其中包括下列內容:
- Azure Databricks 工作區實例名稱。 這是 您 ompute 的伺服器主機名 值。 請參閱 取得 Azure Databricks 計算資源的連線詳細數據。
- 您想要使用之 Databricks 驗證類型所需的任何其他屬性。
注意
適用於 Python 0.19.0 和更新版本之 Databricks SDK 支援 OAuth 使用者對電腦 (U2M) 驗證 。 您可能需要將程式代碼專案的已安裝 Databricks SDK 版本更新為 0.19.0 或更新版本,才能使用 OAuth U2M 驗證。 請參閱 開始使用適用於 Python 的 Databricks SDK。
針對 OAuth U2M 驗證,您必須先使用 Databricks CLI 進行驗證,才能執行 Python 程式代碼。 請參閱教學課程。
適用於 Python 0.18.0 和更新版本之 Databricks SDK 支援 OAuth 機器對機器 (M2M) 驗證 OAuth 機器對機器 (M2M) 驗證。 您可能需要將程式代碼專案的已安裝 Databricks SDK for Python 版本更新為 0.18.0 或更新版本,才能使用 OAuth M2M 驗證。 請參閱 開始使用適用於 Python 的 Databricks SDK。
適用於 Python 的 Databricks SDK 尚未實 作 Azure 受控識別驗證。
設定叢集的連線
若要設定叢集的連線,您需要叢集的標識符。 您可以從 URL 取得叢集識別碼。 請參閱 叢集 URL 和標識碼。
您可以使用下列其中一種方式來設定叢集的連線。 Databricks Connect 會依下列順序搜尋組態屬性,並使用它找到的第一個組態。 如需進階組態資訊,請參閱 適用於 Python 的 Databricks Connect 進階使用方式。
- DatabricksSession 類別的 remote() 方法。
- Databricks 組態配置檔
- DATABRICKS_CONFIG_PROFILE環境變數
- 每個組態屬性的環境變數
- 名為 DEFAULT 的 Databricks 組態配置檔
類別 DatabricksSession
的 remote()
方法
針對此選項,僅適用於 Azure Databricks 個人存取令牌驗證 、指定工作區實例名稱、Azure Databricks 個人存取令牌,以及叢集的標識符。
您可以透過數種方式初始化 DatabricksSession
類別,如下所示:
- 在中
DatabricksSession.builder.remote()
設定host
、token
和cluster_id
欄位。 - 使用 Databricks SDK 的
Config
類別。 - 指定 Databricks 組態配置檔以及
cluster_id
欄位。 - 在 中
DatabricksSession.builder.remote()
設定 Spark Connect 連接字串。
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()
Databricks 組態配置檔
針對此選項,請建立或識別包含字段cluster_id
的 Azure Databricks 組態配置檔,以及您想要使用之 Databricks 驗證類型所需的任何其他欄位。
每個驗證類型的必要組態設定檔欄位如下所示:
- 針對 Azure Databricks 個人存取權杖驗證:
host
和token
。 - 針對 OAuth 電腦對電腦 (M2M) 驗證 (其中支援):
host
、client_id
和client_secret
。 - 針對 OAuth 使用者對電腦 (U2M) 驗證 (其中支援):
host
。 - 針對Microsoft Entra ID(先前稱為 Azure Active Directory)服務主體驗證:
host
、azure_tenant_id
、、azure_client_id
azure_client_secret
和 可能azure_workspace_resource_id
。 - 針對 Azure CLI 驗證:
host
。 - 針對 Azure 受控識別驗證 (支援的位置):
host
、azure_use_msi
、azure_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()
DATABRICKS_CONFIG_PROFILE
環境變數
針對此選項,請建立或識別包含字段cluster_id
的 Azure Databricks 組態配置檔,以及您想要使用之 Databricks 驗證類型所需的任何其他欄位。
如果您已經使用叢集識別元來設定 DATABRICKS_CLUSTER_ID
環境變數,則不需要指定 cluster_id
。
每個驗證類型的必要組態設定檔欄位如下所示:
- 針對 Azure Databricks 個人存取權杖驗證:
host
和token
。 - 針對 OAuth 電腦對電腦 (M2M) 驗證 (其中支援):
host
、client_id
和client_secret
。 - 針對 OAuth 使用者對電腦 (U2M) 驗證 (其中支援):
host
。 - 針對Microsoft Entra ID(先前稱為 Azure Active Directory)服務主體驗證:
host
、azure_tenant_id
、、azure_client_id
azure_client_secret
和 可能azure_workspace_resource_id
。 - 針對 Azure CLI 驗證:
host
。 - 針對 Azure 受控識別驗證 (支援的位置):
host
、azure_use_msi
、azure_client_id
、 和 可能azure_workspace_resource_id
。
將 DATABRICKS_CONFIG_PROFILE
環境變數設定為此組態配置檔的名稱。 然後初始化 類別, DatabricksSession
如下所示:
from databricks.connect import DatabricksSession
spark = DatabricksSession.builder.getOrCreate()
每個組態屬性的環境變數
針對此選項,請設定DATABRICKS_CLUSTER_ID
環境變數,以及您想要使用之 Databricks 驗證類型所需的任何其他環境變數。
每個驗證類型的必要環境變數如下:
- 針對 Azure Databricks 個人存取權杖驗證:
DATABRICKS_HOST
和DATABRICKS_TOKEN
。 - 針對 OAuth 電腦對電腦 (M2M) 驗證 (其中支援):
DATABRICKS_HOST
、DATABRICKS_CLIENT_ID
和DATABRICKS_CLIENT_SECRET
。 - 針對 OAuth 使用者對電腦 (U2M) 驗證 (其中支援):
DATABRICKS_HOST
。 - 針對Microsoft Entra ID(先前稱為 Azure Active Directory)服務主體驗證:
DATABRICKS_HOST
、ARM_TENANT_ID
、、ARM_CLIENT_ID
ARM_CLIENT_SECRET
和 可能DATABRICKS_AZURE_RESOURCE_ID
。 - 針對 Azure CLI 驗證:
DATABRICKS_HOST
。 - 針對 Azure 受控識別驗證 (支援的位置):
DATABRICKS_HOST
、ARM_USE_MSI
、ARM_CLIENT_ID
、 和 可能DATABRICKS_AZURE_RESOURCE_ID
。
然後初始化 類別, DatabricksSession
如下所示:
from databricks.connect import DatabricksSession
spark = DatabricksSession.builder.getOrCreate()
名為的 Databricks 組態配置檔 DEFAULT
針對此選項,請建立或識別包含字段cluster_id
的 Azure Databricks 組態配置檔,以及您想要使用之 Databricks 驗證類型所需的任何其他欄位。
如果您已經使用叢集識別元來設定 DATABRICKS_CLUSTER_ID
環境變數,則不需要指定 cluster_id
。
每個驗證類型的必要組態設定檔欄位如下所示:
- 針對 Azure Databricks 個人存取權杖驗證:
host
和token
。 - 針對 OAuth 電腦對電腦 (M2M) 驗證 (其中支援):
host
、client_id
和client_secret
。 - 針對 OAuth 使用者對電腦 (U2M) 驗證 (其中支援):
host
。 - 針對Microsoft Entra ID(先前稱為 Azure Active Directory)服務主體驗證:
host
、azure_tenant_id
、、azure_client_id
azure_client_secret
和 可能azure_workspace_resource_id
。 - 針對 Azure CLI 驗證:
host
。 - 針對 Azure 受控識別驗證 (支援的位置):
host
、azure_use_msi
、azure_client_id
、 和 可能azure_workspace_resource_id
。
將此組態設定檔 DEFAULT
命名為 。
然後初始化 類別, DatabricksSession
如下所示:
from databricks.connect import DatabricksSession
spark = DatabricksSession.builder.getOrCreate()
設定與無伺服器計算的連線
重要
這項功能處於公開預覽狀態。
Databricks Connect 支援連線到無伺服器計算。 若要使用這項功能,必須符合連線到無伺服器的需求。 請參閱 需求。
重要
這項功能有下列限制:
- 適用於 Python 的所有 Databricks Connect 限制
- 所有無伺服器計算限制
- 只有包含在無伺服器計算環境的 Python 相依性,才能用於 UDF。 請參閱 系統環境。 無法安裝其他相依性。
- 不支援具有自定義模組的UDF。
您可以透過下列其中一種方式設定與無伺服器計算的連線:
將本機環境變數
DATABRICKS_SERVERLESS_COMPUTE_ID
設定為auto
。 如果設定此環境變數,Databricks Connect 會cluster_id
忽略 。在本機 Databricks 組態配置檔中,設定
serverless_compute_id = auto
,然後從您的 Databricks Connect Python 程式代碼參考該配置檔。[DEFAULT] host = https://my-workspace.cloud.databricks.com/ serverless_compute_id = auto token = dapi123...
或者,只要更新 Databricks Connect Python 程序代碼,如下所示:
from databricks.connect import DatabricksSession spark = DatabricksSession.builder.serverless(True).getOrCreate()
from databricks.connect import DatabricksSession spark = DatabricksSession.builder.remote(serverless=True).getOrCreate()
注意
無伺服器計算會話會在閑置 10 分鐘後逾時。 之後,必須在用戶端重新啟動 Python 程式,才能建立新的 Spark 工作階段,以連線到無伺服器計算。
驗證 Databricks 的連線
若要驗證您的環境、預設認證和計算連線已針對 Databricks Connect 正確設定,請執行 databricks-connect test
命令,此命令會在偵測到安裝程式中的任何不相容時,失敗並出現非零結束代碼和對應的錯誤訊息。
databricks-connect test
或者,您可以使用 pyspark
包含在 Databricks Connect for Python 中的殼層,並執行簡單的命令。 如需 PySpark 殼層的詳細資訊,請參閱 Pyspark 殼層。
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應