Databricks Connect voor Python installeren

Notitie

Dit artikel bevat informatie over Databricks Connect voor Databricks Runtime 13.3 LTS en hoger.

In dit artikel wordt beschreven hoe u Databricks Connect voor Python installeert. Zie Wat is Databricks Connect? Zie Databricks Connect installeren voor Scala voor de Scala-versie van dit artikel.

Vereisten

Als u Databricks Connect voor Python wilt installeren, moet aan de volgende vereisten worden voldaan:

• Als u verbinding maakt met serverloze berekeningen, moet uw werkruimte voldoen aan de vereisten voor serverloze berekeningen.

  Notitie

  Serverloze berekening wordt ondersteund in Databricks Connect versie 15.1 en hoger. Bovendien zijn databricks Connect-versies op of lager dan de Databricks Runtime-release op serverloos volledig compatibel. Zie opmerkingen bij de release. Zie De verbinding met Databricks Connect valideren om te controleren of de databricks-versie compatibel is met serverloze berekeningen.

• Als u verbinding maakt met een cluster, moet uw doelcluster voldoen aan de clusterconfiguratievereisten , waaronder versievereisten voor Databricks Runtime.

• Python 3 moet zijn geïnstalleerd op uw ontwikkelcomputer en de secundaire versie van Python die op uw ontwikkelcomputer is geïnstalleerd, moet voldoen aan de versievereisten in de onderstaande tabel.

  Rekentype	Databricks Connect-versie	Compatibele Python-versie
  Serverloos	15.1 en hoger	3.11
  Cluster	15.1 en hoger	3.11
  Cluster	13.3 LTS tot 14.3 LTS	3.10

• Als u PySpark UDF's wilt gebruiken, moet de geïnstalleerde secundaire versie van Python van uw ontwikkelcomputer overeenkomen met de secundaire versie van Python die is opgenomen in de Databricks Runtime die is geïnstalleerd op het cluster of serverloze compute. Als u de secundaire Python-versie van uw cluster wilt vinden, raadpleegt u de sectie Systeemomgeving van de releaseopmerkingen van Databricks Runtime voor uw cluster of serverloze compute. Zie de releaseversies van Databricks Runtime en de releaseopmerkingen voor serverloze berekeningen.

Een virtuele Python-omgeving activeren

Databricks raadt ten zeerste aan dat u een virtuele Python-omgeving hebt geactiveerd voor elke Python-versie die u gebruikt met Databricks Connect. Virtuele Python-omgevingen helpen ervoor te zorgen dat u de juiste versies van Python en Databricks Connect samen gebruikt. Zie venv of Poëzie voor meer informatie over deze hulpmiddelen en hoe u ze activeert.

De Databricks Connect-client installeren

In deze sectie wordt beschreven hoe u de Databricks Connect-client installeert met venv of Poetry.

Notitie

Als u de Databricks-extensie voor Visual Studio Code al hebt geïnstalleerd, hoeft u deze installatie-instructies niet te volgen, omdat de Databricks-extensie voor Visual Studio Code al ingebouwde ondersteuning heeft voor Databricks Connect voor Databricks Runtime 13.3 LTS en hoger. Ga verder met foutopsporingscode met databricks Connect voor de Databricks-extensie voor Visual Studio Code.

De Databricks Connect-client installeren met venv

1. Als uw virtuele omgeving is geactiveerd, verwijdert u PySpark, als deze al is geïnstalleerd, door de opdracht uit te uninstall voeren. Dit is vereist omdat het databricks-connect pakket conflicteert met PySpark. Zie Conflicterende PySpark-installaties voor meer informatie. Voer de show opdracht uit om te controleren of PySpark al is geïnstalleerd.

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

2. Als uw virtuele omgeving nog steeds is geactiveerd, installeert u de Databricks Connect-client door de opdracht uit te install voeren. Gebruik de --upgrade optie om een bestaande clientinstallatie bij te werken naar de opgegeven versie.

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

   Notitie

   Databricks raadt u aan de notatie 'dot-asterisk' toe te voegen om in plaats van databricks-connect=X.Y, op te geven databricks-connect==X.Y.* dat het meest recente pakket is geïnstalleerd. Hoewel dit geen vereiste is, kunt u ervoor zorgen dat u de nieuwste ondersteunde functies voor dat cluster kunt gebruiken.

Ga verder met verbindingseigenschappen configureren.

De Databricks Connect-client installeren met Poëzie

1. Als uw virtuele omgeving is geactiveerd, verwijdert u PySpark, als deze al is geïnstalleerd, door de opdracht uit te remove voeren. Dit is vereist omdat het databricks-connect pakket conflicteert met PySpark. Zie Conflicterende PySpark-installaties voor meer informatie. Voer de show opdracht uit om te controleren of PySpark al is geïnstalleerd.

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

2. Als uw virtuele omgeving nog steeds is geactiveerd, installeert u de Databricks Connect-client door de opdracht uit te add voeren.

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

   Notitie

   Databricks raadt u aan om de at-tilde-notatie te gebruiken om in plaats van databricks-connect==15.4, op te geven databricks-connect@~15.4 dat het meest recente pakket is geïnstalleerd. Hoewel dit geen vereiste is, kunt u ervoor zorgen dat u de nieuwste ondersteunde functies voor dat cluster kunt gebruiken.

Verbindingseigenschappen configureren

In deze sectie configureert u eigenschappen voor het tot stand brengen van een verbinding tussen Databricks Connect en uw Azure Databricks-cluster of serverloze compute, waaronder het volgende:

• De naam van het Azure Databricks-werkruimte-exemplaar. Dit is de serverhostnaamwaarde voor uw berekening. Zie Verbindingsgegevens ophalen voor een Azure Databricks-rekenresource.
• Alle andere eigenschappen die nodig zijn voor het Databricks-verificatietype dat u wilt gebruiken.

Notitie

• OAuth-gebruikers-naar-machine-verificatie (U2M) wordt ondersteund in Databricks SDK voor Python 0.19.0 en hoger. Mogelijk moet u de geïnstalleerde versie van de Databricks SDK van uw codeproject voor Python bijwerken naar 0.19.0 of hoger om OAuth U2M-verificatie te gebruiken. Zie Aan de slag met de Databricks SDK voor Python.

  Voor OAuth U2M-verificatie moet u de Databricks CLI gebruiken om te verifiëren voordat u uw Python-code uitvoert. Zie de zelfstudie.

• Verificatie van OAuth-machine-naar-machine (M2M) OAuth-verificatie van machine-naar-machine (M2M) wordt ondersteund in Databricks SDK voor Python 0.18.0 en hoger. Mogelijk moet u de geïnstalleerde versie van de Databricks SDK van uw codeproject voor Python bijwerken naar 0.18.0 of hoger om OAuth M2M-verificatie te gebruiken. Zie Aan de slag met de Databricks SDK voor Python.

• De Databricks SDK voor Python heeft nog geen verificatie van door Azure beheerde identiteiten geïmplementeerd.

Een verbinding met een cluster configureren

Als u een verbinding met een cluster wilt configureren, hebt u de id van uw cluster nodig. U kunt de cluster-id ophalen via de URL. Zie cluster-URL en -id.

U kunt de verbinding met uw cluster op een van de volgende manieren configureren. Databricks Connect zoekt in de volgende volgorde naar configuratie-eigenschappen en gebruikt de eerste configuratie die wordt gevonden. Zie Geavanceerd gebruik van Databricks Connect voor Python voor geavanceerde configuratie-informatie.

1. De methode remote() van de DatabricksSession-klasse.
2. Een Databricks-configuratieprofiel
3. De omgevingsvariabele DATABRICKS_CONFIG_PROFILE
4. Een omgevingsvariabele voor elke configuratie-eigenschap
5. Een Databricks-configuratieprofiel met de naam DEFAULT

De methode van remote() de DatabricksSession klasse

Voor deze optie, die alleen van toepassing is op persoonlijke toegangstokenverificatie van Azure Databricks, geeft u de naam van het werkruimte-exemplaar, het persoonlijke toegangstoken van Azure Databricks en de id van het cluster op.

U kunt de DatabricksSession klasse op verschillende manieren initialiseren:

• Stel de host, tokenen cluster_id de velden in DatabricksSession.builder.remote().
• Gebruik de klasse van Config de Databricks SDK.
• Geef een Databricks-configuratieprofiel op samen met het cluster_id veld.
• Stel de Spark Connect-verbindingsreeks inDatabricksSession.builder.remote().

In plaats van deze verbindingseigenschappen in uw code op te geven, raadt Databricks aan om eigenschappen te configureren via omgevingsvariabelen of configuratiebestanden, zoals beschreven in deze sectie. In de volgende codevoorbeelden wordt ervan uitgegaan dat u een implementatie van de voorgestelde retrieve_* functies opgeeft om de benodigde eigenschappen op te halen van de gebruiker of uit een ander configuratiearchief, zoals Azure KeyVault.

De code voor elk van deze benaderingen is als volgt:

# 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()

Een Databricks-configuratieprofiel

Voor deze optie maakt of identificeert u een Azure Databricks-configuratieprofiel met het veld cluster_id en eventuele andere velden die nodig zijn voor het Databricks-verificatietype dat u wilt gebruiken.

De vereiste configuratieprofielvelden voor elk verificatietype zijn als volgt:

• Voor persoonlijke toegangstokenverificatie van Azure Databricks: host en token.
• Voor OAuth M2M-verificatie (machine-naar-machine) (waar ondersteund): host, client_iden client_secret.
• Voor OAuth-gebruikers-naar-machine-verificatie (U2M) (waar ondersteund): host.
• Voor verificatie van de service-principal van Microsoft Entra ID (voorheen Azure Active Directory): host, azure_tenant_idazure_client_id, , azure_client_secreten mogelijk azure_workspace_resource_id.
• Voor Azure CLI-verificatie: host.
• Voor verificatie van door Azure beheerde identiteiten (waar ondersteund): host, azure_use_msi, azure_client_iden mogelijk azure_workspace_resource_id.

Stel vervolgens de naam van dit configuratieprofiel in via de Config klasse.

U kunt dit op een aantal manieren opgeven cluster_id :

• Neem het cluster_id veld op in uw configuratieprofiel en geef de naam van het configuratieprofiel op.
• Geef de naam van het configuratieprofiel op samen met het cluster_id veld.

Als u de DATABRICKS_CLUSTER_ID omgevingsvariabele al hebt ingesteld met de id van het cluster, hoeft u niet ook op te geven cluster_id.

De code voor elk van deze benaderingen is als volgt:

# 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()

De DATABRICKS_CONFIG_PROFILE omgevingsvariabele

Voor deze optie maakt of identificeert u een Azure Databricks-configuratieprofiel met het veld cluster_id en eventuele andere velden die nodig zijn voor het Databricks-verificatietype dat u wilt gebruiken.

Als u de DATABRICKS_CLUSTER_ID omgevingsvariabele al hebt ingesteld met de id van het cluster, hoeft u niet ook op te geven cluster_id.

De vereiste configuratieprofielvelden voor elk verificatietype zijn als volgt:

• Voor persoonlijke toegangstokenverificatie van Azure Databricks: host en token.
• Voor OAuth M2M-verificatie (machine-naar-machine) (waar ondersteund): host, client_iden client_secret.
• Voor OAuth-gebruikers-naar-machine-verificatie (U2M) (waar ondersteund): host.
• Voor verificatie van de service-principal van Microsoft Entra ID (voorheen Azure Active Directory): host, azure_tenant_idazure_client_id, , azure_client_secreten mogelijk azure_workspace_resource_id.
• Voor Azure CLI-verificatie: host.
• Voor verificatie van door Azure beheerde identiteiten (waar ondersteund): host, azure_use_msi, azure_client_iden mogelijk azure_workspace_resource_id.

Stel de DATABRICKS_CONFIG_PROFILE omgevingsvariabele in op de naam van dit configuratieprofiel. Initialiseer vervolgens de DatabricksSession klasse als volgt:

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

Een omgevingsvariabele voor elke configuratie-eigenschap

Stel voor deze optie de DATABRICKS_CLUSTER_ID omgevingsvariabele en eventuele andere omgevingsvariabelen in die nodig zijn voor het Databricks-verificatietype dat u wilt gebruiken.

De vereiste omgevingsvariabelen voor elk verificatietype zijn als volgt:

• Voor persoonlijke toegangstokenverificatie van Azure Databricks: DATABRICKS_HOST en DATABRICKS_TOKEN.
• Voor OAuth M2M-verificatie (machine-naar-machine) (waar ondersteund): DATABRICKS_HOST, DATABRICKS_CLIENT_IDen DATABRICKS_CLIENT_SECRET.
• Voor OAuth-gebruikers-naar-machine-verificatie (U2M) (waar ondersteund): DATABRICKS_HOST.
• Voor verificatie van de service-principal van Microsoft Entra ID (voorheen Azure Active Directory): DATABRICKS_HOST, ARM_TENANT_IDARM_CLIENT_ID, , ARM_CLIENT_SECRETen mogelijk DATABRICKS_AZURE_RESOURCE_ID.
• Voor Azure CLI-verificatie: DATABRICKS_HOST.
• Voor verificatie van door Azure beheerde identiteiten (waar ondersteund): DATABRICKS_HOST, ARM_USE_MSI, ARM_CLIENT_IDen mogelijk DATABRICKS_AZURE_RESOURCE_ID.

Initialiseer vervolgens de DatabricksSession klasse als volgt:

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

Een Databricks-configuratieprofiel met de naam DEFAULT

Voor deze optie maakt of identificeert u een Azure Databricks-configuratieprofiel met het veld cluster_id en eventuele andere velden die nodig zijn voor het Databricks-verificatietype dat u wilt gebruiken.

Als u de DATABRICKS_CLUSTER_ID omgevingsvariabele al hebt ingesteld met de id van het cluster, hoeft u niet ook op te geven cluster_id.

De vereiste configuratieprofielvelden voor elk verificatietype zijn als volgt:

• Voor persoonlijke toegangstokenverificatie van Azure Databricks: host en token.
• Voor OAuth M2M-verificatie (machine-naar-machine) (waar ondersteund): host, client_iden client_secret.
• Voor OAuth-gebruikers-naar-machine-verificatie (U2M) (waar ondersteund): host.
• Voor verificatie van de service-principal van Microsoft Entra ID (voorheen Azure Active Directory): host, azure_tenant_idazure_client_id, , azure_client_secreten mogelijk azure_workspace_resource_id.
• Voor Azure CLI-verificatie: host.
• Voor verificatie van door Azure beheerde identiteiten (waar ondersteund): host, azure_use_msi, azure_client_iden mogelijk azure_workspace_resource_id.

Geef dit configuratieprofiel DEFAULTeen naam.

Initialiseer vervolgens de DatabricksSession klasse als volgt:

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

Een verbinding met serverloze berekeningen configureren

Belangrijk

Deze functie is beschikbaar als openbare preview.

Databricks Connect biedt ondersteuning voor het maken van verbinding met serverloze berekeningen. Als u deze functie wilt gebruiken, moet aan de vereisten voor het maken van verbinding met serverloos worden voldaan. Zie Vereisten.

Belangrijk

Deze functie heeft de volgende beperkingen:

• Alle beperkingen van Databricks Connect voor Python
• Alle serverloze rekenbeperkingen
• Alleen Python-afhankelijkheden die zijn opgenomen als onderdeel van een serverloze rekenomgeving, kunnen worden gebruikt voor UDF's. Zie de systeemomgeving. Er kunnen geen extra afhankelijkheden worden geïnstalleerd.
• UDF's met aangepaste modules worden niet ondersteund.

U kunt een verbinding met serverloze berekeningen op een van de volgende manieren configureren:

• Stel de lokale omgevingsvariabele DATABRICKS_SERVERLESS_COMPUTE_ID in op auto. Als deze omgevingsvariabele is ingesteld, negeert Databricks Connect het cluster_id.

• Stel serverless_compute_id = autoin een lokaal Databricks-configuratieprofiel het profiel in en verwijs vervolgens naar dat profiel vanuit uw Databricks Connect Python-code.

  [DEFAULT]
  host = https://my-workspace.cloud.databricks.com/
  serverless_compute_id = auto
  token = dapi123...
  

• U kunt ook uw Databricks Connect Python-code als volgt bijwerken:

  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()
  

Notitie

Er treedt een time-out op voor de serverloze rekensessie na 10 minuten inactiviteit. Hierna moet er een nieuwe Spark-sessie worden gemaakt om verbinding te maken met serverloze compute. Dit kan met spark = DatabricksSession.builder.serverless(True).getOrCreate().

De verbinding met Databricks valideren

Als u uw omgeving, standaardreferenties en verbinding met berekeningen wilt valideren, moet u de databricks-connect test opdracht uitvoeren die mislukt met een afsluitcode zonder nul en een bijbehorend foutbericht wanneer er incompatibiliteit in de installatie wordt gedetecteerd.

databricks-connect test

U kunt uw omgeving ook valideren in uw Python-code met behulp van validateSession():

DatabricksSession.builder.validateSession(True).getOrCreate()