Menginstal Databricks Connect untuk Python
Catatan
Artikel ini membahas Databricks Connect untuk Databricks Runtime 13.3 LTS ke atas.
Artikel ini menjelaskan cara menginstal Databricks Connect untuk Python. Lihat Apa itu Databricks Connect?. Untuk versi Scala artikel ini, lihat Menginstal Databricks Connect untuk Scala.
Persyaratan
Untuk menginstal Databricks Connect untuk Python, persyaratan berikut harus dipenuhi:
Jika Anda tersambung ke komputasi tanpa server, ruang kerja Anda harus memenuhi persyaratan untuk komputasi tanpa server.
Jika Anda terhubung ke kluster, kluster target Anda harus memenuhi persyaratan konfigurasi kluster, yang mencakup persyaratan versi Databricks Runtime.
Anda harus menginstal Python 3 pada komputer pengembangan Anda, dan versi minor Python yang diinstal pada mesin pengembangan Anda harus memenuhi persyaratan versi dalam tabel di bawah ini.
Versi Databricks Connect Tipe komputasi Versi Python yang kompatibel 15,1 Kluster 3.11 15,1 Tanpa server 3.10 13.3 LTS hingga 14.3 LTS Kluster 3.10 Jika Anda ingin menggunakan PySpark UDF, Python versi minor yang diinstal mesin pengembangan Anda harus cocok dengan versi minor Python yang disertakan dengan Databricks Runtime yang diinstal pada kluster atau komputasi tanpa server. Untuk menemukan versi Python minor kluster Anda, lihat bagian Lingkungan sistem dari catatan rilis Databricks Runtime untuk kluster atau komputasi tanpa server Anda. Lihat Versi dan kompatibilitas catatan rilis Databricks Runtime serta Catatan rilis komputasi tanpa server.
Mengaktifkan lingkungan virtual Python
Databricks sangat menyarankan agar Anda mengaktifkan lingkungan virtual Python untuk setiap versi Python yang Anda gunakan dengan Databricks Connect. Lingkungan virtual Python membantu memastikan bahwa Anda menggunakan versi Python dan Databricks Connect yang benar bersama-sama. Untuk informasi selengkapnya tentang alat-alat ini dan cara mengaktifkannya, lihat venv atau Puisi.
Menginstal klien Databricks Connect
Bagian ini menjelaskan cara menginstal klien Databricks Connect dengan venv atau Poetry.
Catatan
Jika Anda sudah menginstal ekstensi Databricks untuk Visual Studio Code, Anda tidak perlu mengikuti instruksi penyiapan ini, karena ekstensi Databricks untuk Visual Studio Code sudah memiliki dukungan bawaan untuk Databricks Connect untuk Databricks Runtime 13.3 LTS ke atas. Lewati ke Kode debug dengan menggunakan Databricks Connect untuk ekstensi Databricks untuk Visual Studio Code.
Menginstal klien Databricks Connect dengan venv
Dengan mengaktifkan lingkungan virtual Anda, hapus instalan PySpark, jika sudah diinstal, dengan menjalankan
uninstall
perintah . Ini diperlukan karena paket bertentangandatabricks-connect
dengan PySpark. Untuk detailnya, lihat Penginstalan PySpark yang Saling Bertentangan. Untuk memeriksa apakah PySpark sudah diinstal, jalankanshow
perintah .# Is PySpark already installed? pip3 show pyspark # Uninstall PySpark pip3 uninstall pyspark
Dengan lingkungan virtual Anda masih diaktifkan, instal klien Databricks Connect dengan menjalankan
install
perintah .--upgrade
Gunakan opsi untuk meningkatkan penginstalan klien yang ada ke versi yang ditentukan.pip3 install --upgrade "databricks-connect==14.3.*" # Or X.Y.* to match your cluster version.
Catatan
Databricks merekomendasikan agar Anda menambahkan notasi "tanda bintang titik" untuk menentukan
databricks-connect==X.Y.*
alih-alihdatabricks-connect=X.Y
, untuk memastikan bahwa paket terbaru diinstal. Meskipun ini bukan persyaratan, ini membantu memastikan bahwa Anda dapat menggunakan fitur terbaru yang didukung untuk kluster tersebut.
Lewati ke depan untuk Mengonfigurasi properti koneksi.
Menginstal klien Databricks Connect dengan Puisi
Dengan mengaktifkan lingkungan virtual Anda, hapus instalan PySpark, jika sudah diinstal, dengan menjalankan
remove
perintah . Ini diperlukan karena paket bertentangandatabricks-connect
dengan PySpark. Untuk detailnya, lihat Penginstalan PySpark yang Saling Bertentangan. Untuk memeriksa apakah PySpark sudah diinstal, jalankanshow
perintah .# Is PySpark already installed? poetry show pyspark # Uninstall PySpark poetry remove pyspark
Dengan lingkungan virtual Anda masih diaktifkan, instal klien Databricks Connect dengan menjalankan
add
perintah .poetry add databricks-connect@~14.3 # Or X.Y to match your cluster version.
Catatan
Databricks merekomendasikan agar Anda menggunakan notasi "at-tilde" untuk menentukan
databricks-connect@~14.3
alih-alihdatabricks-connect==14.3
, untuk memastikan bahwa paket terbaru diinstal. Meskipun ini bukan persyaratan, ini membantu memastikan bahwa Anda dapat menggunakan fitur terbaru yang didukung untuk kluster tersebut.
Mengonfigurasi properti koneksi
Di bagian ini, Anda mengonfigurasi properti untuk membuat koneksi antara Databricks Connect dan kluster Azure Databricks atau komputasi tanpa server, yang mencakup hal berikut:
- Nama instans ruang kerja Azure Databricks. Ini adalah nilai Nama Host Server untuk komputasi Anda. Lihat Mendapatkan detail koneksi untuk sumber daya komputasi Azure Databricks.
- Properti lain yang diperlukan untuk jenis autentikasi Databricks yang ingin Anda gunakan.
Catatan
Autentikasi pengguna ke komputer (U2M) OAuth didukung pada Databricks SDK untuk Python 0.19.0 ke atas. Anda mungkin perlu memperbarui versi Databricks SDK untuk Python ke 0.19.0 atau yang lebih baru untuk menggunakan autentikasi OAuth U2M. Lihat Mulai menggunakan Databricks SDK untuk Python.
Untuk autentikasi OAuth U2M, Anda harus menggunakan Databricks CLI untuk mengautentikasi sebelum menjalankan kode Python Anda. Lihat Tutorial.
Autentikasi OAuth machine-to-machine (M2M) autentikasi OAuth machine-to-machine (M2M) didukung pada Databricks SDK untuk Python 0.18.0 ke atas. Anda mungkin perlu memperbarui versi Databricks SDK untuk Python ke 0.18.0 atau yang lebih baru untuk menggunakan autentikasi M2M OAuth. Lihat Mulai menggunakan Databricks SDK untuk Python.
Databricks SDK untuk Python belum menerapkan autentikasi identitas terkelola Azure.
Mengonfigurasi koneksi ke kluster
Untuk mengonfigurasi koneksi ke kluster, Anda akan memerlukan ID kluster Anda. Anda bisa mendapatkan ID kluster dari URL. Lihat URL dan ID kluster.
Anda dapat mengonfigurasi koneksi ke kluster Anda dengan salah satu cara berikut. Databricks Connect mencari properti konfigurasi dalam urutan berikut, dan menggunakan konfigurasi pertama yang ditemukannya. Untuk informasi konfigurasi tingkat lanjut, lihat Penggunaan tingkat lanjut Databricks Connect untuk Python.
- Metode remote() kelas DatabricksSession.
- Profil konfigurasi Databricks
- Variabel lingkungan DATABRICKS_CONFIG_PROFILE
- Variabel lingkungan untuk setiap properti konfigurasi
- Profil konfigurasi Databricks bernama DEFAULT
Metode DatabricksSession
kelas remote()
Untuk opsi ini, yang hanya berlaku untuk autentikasi token akses pribadi Azure Databricks, tentukan nama instans ruang kerja, token akses pribadi Azure Databricks, dan ID kluster.
Anda dapat menginisialisasi kelas dengan DatabricksSession
beberapa cara, sebagai berikut:
- Atur
host
bidang ,token
, dancluster_id
diDatabricksSession.builder.remote()
. - Gunakan kelas Databricks SDK
Config
. - Tentukan profil konfigurasi Databricks bersama dengan
cluster_id
bidang . - Atur string koneksi Spark Connect di
DatabricksSession.builder.remote()
.
Alih-alih menentukan properti koneksi ini dalam kode Anda, Databricks merekomendasikan untuk mengonfigurasi properti melalui variabel lingkungan atau file konfigurasi, seperti yang dijelaskan di seluruh bagian ini. Contoh kode berikut mengasumsikan bahwa Anda menyediakan beberapa implementasi fungsi yang diusulkan retrieve_*
untuk mendapatkan properti yang diperlukan dari pengguna atau dari beberapa penyimpanan konfigurasi lainnya, seperti Azure KeyVault.
Kode untuk masing-masing pendekatan ini adalah sebagai berikut:
# 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()
Profil konfigurasi Databricks
Untuk opsi ini, buat atau identifikasi profil konfigurasi Azure Databricks yang berisi bidang cluster_id
dan bidang lain yang diperlukan untuk jenis autentikasi Databricks yang ingin Anda gunakan.
Bidang profil konfigurasi yang diperlukan untuk setiap jenis autentikasi adalah sebagai berikut:
- Untuk autentikasi token akses pribadi Azure Databricks:
host
dantoken
. - Untuk autentikasi komputer-ke-mesin (M2M) OAuth (jika didukung):
host
, ,client_id
danclient_secret
. - Untuk autentikasi pengguna-ke-mesin (U2M) OAuth (jika didukung):
host
. - Untuk autentikasi
host
perwakilan layanan Microsoft Entra ID (sebelumnya Azure Active Directory): , ,azure_tenant_id
azure_client_id
,azure_client_secret
, dan mungkinazure_workspace_resource_id
. - Untuk autentikasi Azure CLI:
host
. - Untuk autentikasi identitas terkelola Azure (jika didukung):
host
, ,azure_use_msi
azure_client_id
, dan mungkinazure_workspace_resource_id
.
Kemudian atur nama profil konfigurasi ini melalui Config
kelas .
Anda dapat menentukan cluster_id
dengan beberapa cara, sebagai berikut:
- Sertakan
cluster_id
bidang di profil konfigurasi Anda, lalu cukup tentukan nama profil konfigurasi. - Tentukan nama profil konfigurasi bersama dengan
cluster_id
bidang .
Jika Anda telah mengatur DATABRICKS_CLUSTER_ID
variabel lingkungan dengan ID kluster, Anda tidak perlu menentukan cluster_id
.
Kode untuk masing-masing pendekatan ini adalah sebagai berikut:
# 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()
Variabel DATABRICKS_CONFIG_PROFILE
lingkungan
Untuk opsi ini, buat atau identifikasi profil konfigurasi Azure Databricks yang berisi bidang cluster_id
dan bidang lain yang diperlukan untuk jenis autentikasi Databricks yang ingin Anda gunakan.
Jika Anda telah mengatur DATABRICKS_CLUSTER_ID
variabel lingkungan dengan ID kluster, Anda tidak perlu menentukan cluster_id
.
Bidang profil konfigurasi yang diperlukan untuk setiap jenis autentikasi adalah sebagai berikut:
- Untuk autentikasi token akses pribadi Azure Databricks:
host
dantoken
. - Untuk autentikasi komputer-ke-mesin (M2M) OAuth (jika didukung):
host
, ,client_id
danclient_secret
. - Untuk autentikasi pengguna-ke-mesin (U2M) OAuth (jika didukung):
host
. - Untuk autentikasi
host
perwakilan layanan Microsoft Entra ID (sebelumnya Azure Active Directory): , ,azure_tenant_id
azure_client_id
,azure_client_secret
, dan mungkinazure_workspace_resource_id
. - Untuk autentikasi Azure CLI:
host
. - Untuk autentikasi identitas terkelola Azure (jika didukung):
host
, ,azure_use_msi
azure_client_id
, dan mungkinazure_workspace_resource_id
.
Atur DATABRICKS_CONFIG_PROFILE
variabel lingkungan ke nama profil konfigurasi ini. Kemudian inisialisasi DatabricksSession
kelas sebagai berikut:
from databricks.connect import DatabricksSession
spark = DatabricksSession.builder.getOrCreate()
Variabel lingkungan untuk setiap properti konfigurasi
Untuk opsi ini, atur DATABRICKS_CLUSTER_ID
variabel lingkungan dan variabel lingkungan lain yang diperlukan untuk jenis autentikasi Databricks yang ingin Anda gunakan.
Variabel lingkungan yang diperlukan untuk setiap jenis autentikasi adalah sebagai berikut:
- Untuk autentikasi token akses pribadi Azure Databricks:
DATABRICKS_HOST
danDATABRICKS_TOKEN
. - Untuk autentikasi komputer-ke-mesin (M2M) OAuth (jika didukung):
DATABRICKS_HOST
, ,DATABRICKS_CLIENT_ID
danDATABRICKS_CLIENT_SECRET
. - Untuk autentikasi pengguna-ke-mesin (U2M) OAuth (jika didukung):
DATABRICKS_HOST
. - Untuk autentikasi
DATABRICKS_HOST
perwakilan layanan Microsoft Entra ID (sebelumnya Azure Active Directory): , ,ARM_TENANT_ID
ARM_CLIENT_ID
,ARM_CLIENT_SECRET
, dan mungkinDATABRICKS_AZURE_RESOURCE_ID
. - Untuk autentikasi Azure CLI:
DATABRICKS_HOST
. - Untuk autentikasi identitas terkelola Azure (jika didukung):
DATABRICKS_HOST
, ,ARM_USE_MSI
ARM_CLIENT_ID
, dan mungkinDATABRICKS_AZURE_RESOURCE_ID
.
Kemudian inisialisasi DatabricksSession
kelas sebagai berikut:
from databricks.connect import DatabricksSession
spark = DatabricksSession.builder.getOrCreate()
Profil konfigurasi Databricks bernama DEFAULT
Untuk opsi ini, buat atau identifikasi profil konfigurasi Azure Databricks yang berisi bidang cluster_id
dan bidang lain yang diperlukan untuk jenis autentikasi Databricks yang ingin Anda gunakan.
Jika Anda telah mengatur DATABRICKS_CLUSTER_ID
variabel lingkungan dengan ID kluster, Anda tidak perlu menentukan cluster_id
.
Bidang profil konfigurasi yang diperlukan untuk setiap jenis autentikasi adalah sebagai berikut:
- Untuk autentikasi token akses pribadi Azure Databricks:
host
dantoken
. - Untuk autentikasi komputer-ke-mesin (M2M) OAuth (jika didukung):
host
, ,client_id
danclient_secret
. - Untuk autentikasi pengguna-ke-mesin (U2M) OAuth (jika didukung):
host
. - Untuk autentikasi
host
perwakilan layanan Microsoft Entra ID (sebelumnya Azure Active Directory): , ,azure_tenant_id
azure_client_id
,azure_client_secret
, dan mungkinazure_workspace_resource_id
. - Untuk autentikasi Azure CLI:
host
. - Untuk autentikasi identitas terkelola Azure (jika didukung):
host
, ,azure_use_msi
azure_client_id
, dan mungkinazure_workspace_resource_id
.
Beri nama profil DEFAULT
konfigurasi ini .
Kemudian inisialisasi DatabricksSession
kelas sebagai berikut:
from databricks.connect import DatabricksSession
spark = DatabricksSession.builder.getOrCreate()
Mengonfigurasi koneksi ke komputasi tanpa server
Penting
Fitur ini ada di Pratinjau Publik.
Databricks Connect mendukung penyambungan ke komputasi tanpa server. Untuk menggunakan fitur ini, persyaratan untuk menyambungkan ke tanpa server harus dipenuhi. Lihat Persyaratan.
Penting
Fitur ini memiliki batasan berikut ini:
- Semua batasan Databricks Connect untuk Python
- Semua batasan komputasi tanpa server
- Hanya dependensi Python yang disertakan sebagai bagian dari lingkungan komputasi tanpa server yang dapat digunakan untuk UDF. Lihat Lingkungan sistem. Dependensi tambahan tidak dapat diinstal.
- UDF dengan modul kustom tidak didukung.
Anda dapat mengonfigurasi koneksi ke komputasi tanpa server dengan salah satu cara berikut:
Atur variabel
DATABRICKS_SERVERLESS_COMPUTE_ID
lingkungan lokal keauto
. Jika variabel lingkungan ini diatur, Databricks Connect mengabaikancluster_id
.Di profil konfigurasi Databricks lokal, atur
serverless_compute_id = auto
, lalu referensikan profil tersebut dari kode Databricks Connect Python Anda.[DEFAULT] host = https://my-workspace.cloud.databricks.com/ serverless_compute_id = auto token = dapi123...
Atau, cukup perbarui kode Databricks Connect Python Anda sebagai berikut:
from databricks.connect import DatabricksSession as SparkSession spark = DatabricksSession.builder.serverless(True).getOrCreate()
from databricks.connect import DatabricksSession as SparkSession spark DatabricksSession.builder.remote(serverless=True).getOrCreate()
Catatan
Waktu sesi komputasi tanpa server habis setelah 10 menit tidak aktif. Setelah ini, proses Python perlu dimulai ulang di sisi klien untuk membuat sesi Spark baru untuk terhubung ke komputasi tanpa server.
Memvalidasi koneksi ke Databricks
Untuk memvalidasi lingkungan Anda, kredensial default, dan koneksi ke komputasi disiapkan dengan benar untuk Databricks Connect, jalankan databricks-connect test
perintah, yang gagal dengan kode keluar non-nol dan pesan kesalahan yang sesuai saat mendeteksi ketidaksesuaian dalam penyiapan.
databricks-connect test
Atau, Anda dapat menggunakan pyspark
shell yang disertakan sebagai bagian dari Databricks Connect for Python, dan menjalankan perintah sederhana. Untuk detail selengkapnya tentang shell PySpark, lihat shell Pyspark.