Verbinden mit Snowflake mit dem Python-Konnektor¶

Überprüfen der Netzwerkverbindung zu Snowflake mit SnowCD¶

Nach der Konfiguration des Treibers können Sie die Netzwerkkonnektivität zu Snowflake mit SnowCD testen und Probleme beheben.

Sie können während der Erstkonfiguration und bei Bedarf SnowCD verwenden, um Ihre Netzwerkverbindung zu Snowflake zu testen und Probleme zu beheben.

Importieren des snowflake.connector-Moduls¶

Um das Modul snowflake.connector zu importieren, führen Sie den folgenden Befehl aus:

import snowflake.connector

Copy

Die Anmeldeinformationen können Sie aus Umgebungsvariablen, über die Befehlszeile, aus einer Konfigurationsdatei oder einer anderen geeigneten Quelle ermitteln. Beispiel:

PASSWORD = os.getenv('SNOWSQL_PWD')
WAREHOUSE = os.getenv('WAREHOUSE')
...

Verwenden Sie für den Parameter ACCOUNT Ihren Kontobezeichner. Beachten Sie, dass der Kontobezeichner nicht das Suffix snowflakecomputing.com enthält.

Weitere Details und Beispiele dazu finden Sie unter Nutzungshinweise für die Verwendung des account-Parameters (für die connect-Methode).

Wenn Sie Daten aus Ihrem eigenen Amazon S3-Bucket kopieren möchten, benötigen Sie die AWS_ACCESS_KEY_ID und AWS_SECRET_ACCESS_KEY.

import os

AWS_ACCESS_KEY_ID = os.getenv('AWS_ACCESS_KEY_ID')
AWS_SECRET_ACCESS_KEY = os.getenv('AWS_SECRET_ACCESS_KEY')

Copy

Bemerkung

Wenn Ihre Daten in einem Microsoft Azure-Container gespeichert sind, geben Sie die Anmeldeinformationen direkt in der COPY-Anweisung an.

Stellen Sie nach dem Lesen der Verbindungsinformationen eine Verbindung mit dem Standardauthentifikator oder der Verbundauthentifizierung her (falls aktiviert).

Einstellen der Sitzungsparameter¶

Bei der Verwendung des Python-Konnektors können Sie Sitzungsparameter, wie QUERY_TAG, auf verschiedene Weise festlegen:

• Sie können Parameter auf Sitzungsebene festlegen, wenn Sie eine Verbindung zu Snowflake herstellen, indem Sie den optionalen Verbindungsparameter mit dem Namen session_parameters wie folgt übergeben:

  con = snowflake.connector.connect(
      user='XXXX',
      password='XXXX',
      account='XXXX',
      session_parameters={
          'QUERY_TAG': 'EndOfMonthFinancials',
      }
  )
  

  Copy

  Das an die session_parameters-Methode übergebene connect()-Wörterbuch kann einen oder mehrere Parameter auf Sitzungsebene enthalten.

• Sie können Sitzungsparameter auch festlegen, indem Sie nach dem Herstellen der Verbindung die Anweisung ALTER SESSION SET SQL ausführen:

  con.cursor().execute("ALTER SESSION SET QUERY_TAG = 'EndOfMonthFinancials'")
  

  Copy

Weitere Informationen zu Sitzungsparametern finden Sie in den Beschreibungen der einzelnen Parameter auf der allgemeinen Seite Parameter.

Verbinden mit dem Standardauthentifikator¶

Stellen Sie eine Verbindung zu Snowflake unter Verwendung der erforderlichen Anmeldeparameter her:

conn = snowflake.connector.connect(
    user=USER,
    password=PASSWORD,
    account=ACCOUNT,
    warehouse=WAREHOUSE,
    database=DATABASE,
    schema=SCHEMA
    )

Copy

Möglicherweise müssen Sie dies mit anderen Informationen erweitern.

Verbinden mit der Datei connections.toml¶

Der Python-Konnektor bietet die Möglichkeit, Verbindungsdefinitionen zu einer connections.toml-Konfigurationsdatei hinzuzufügen. Eine Verbindungsdefinition bezieht sich auf eine Sammlung von verbindungsbezogenen Parametern. Weitere Informationen zu toml-Dateiformaten finden Sie unter TOML (Tom’s Obvious Minimal Language). Die Snowflake-Python-Bibliotheken unterstützen derzeit TOML, Version 1.0.0.

Der Python-Konnektor sucht die Datei connections.toml an den folgenden Speicherorten, in dieser Reihenfolge:

• Wenn auf Ihrem Computer ein Verzeichnis ~/.snowflake existiert, verwendet die Snowflake-CLI die Datei ~/.snowflake/connections.toml. Sie können das Standardverzeichnis ~/.snowflake überschreiben, indem Sie den Speicherort in der Umgebungsvariablen SNOWFLAKE_HOME festlegen.

• Andernfalls verwendet die Snowflake-CLI die Datei connections.toml an einem der folgenden Speicherorte, abhängig von Ihrem Betriebssystem:

  • Linux: ~/.config/snowflake/connections.toml, aber Sie können es mit XDG-Variablen aktualisieren

  • Windows: %USERPROFILE%\AppData\Local\snowflake\connections.toml

  • Mac: ~/Library/Application Support/snowflake/connections.toml

So fügen Sie Anmeldeinformationen in eine Verbindungskonfigurationsdatei ein:

1. Öffnen Sie die Datei connections.toml in einem Texteditor, um sie zu bearbeiten. Öffnen Sie beispielsweise die Datei mit dem Linux-Editor vi wie folgt:

   $ vi connections.toml
   

   Copy

2. Fügen Sie eine neue Snowflake-Verbindungsdefinition hinzu.

   Um beispielsweise eine Snowflake-Verbindung namens myconnection mit dem Konto myaccount, dem Benutzer johndoe und Anmeldeinformationen sowie Kennwort-Datenbankinformationen hinzuzufügen, fügen Sie die folgenden Zeilen in die Konfigurationsdatei ein:

   [myconnection]
   account = "myaccount"
   user = "jdoe"
   password = "******"
   warehouse = "my-wh"
   database = "my_db"
   schema = "my_schema"
   

   Copy

   Verbindungsdefinitionen unterstützen die gleichen Konfigurationsoptionen, die auch im Snowflake Python-Konnektor verfügbar sind.

3. Optional: Fügen Sie weitere Verbindungen wie folgt hinzu:

   [myconnection_test]
   account = "myaccount"
   user = "jdoe-test"
   password = "******"
   warehouse = "my-test_wh"
   database = "my_test_db"
   schema = "my_schema"
   

   Copy

4. Speichern Sie die Änderungen in der Datei.

5. Geben Sie in Ihrem Python-Code den Verbindungsnamen snowflake.connector.connect an, ähnlich wie im Folgenden:

   with snowflake.connector.connect(
         connection_name="myconnection",
   ) as conn:
   

   Copy

   Sie können auch die für die Verbindung in der Datei connections.toml definierten Werte wie folgt überschreiben:

   with snowflake.connector.connect(
         connection_name="myconnection",
         warehouse="test_xl_wh",
         database="testdb_2"
   ) as conn:
   

   Copy

Einstellen einer Standardverbindung¶

Sie können eine Verbindung als Standard festlegen, sodass Sie nicht jedes Mal eine Verbindung angeben müssen, wenn Sie snowflake.connector.connect() aufrufen, um sich mit Snowflake zu verbinden. Sie können eine Standardverbindung auf eine der folgenden Arten definieren, die in aufsteigender Reihenfolge ihrer Priorität aufgelistet sind:

• Erstellen Sie eine Verbindungsdefinition mit dem Namen default.

  1. Erstellen Sie in der Datei connections.toml die Verbindungsdefinition, und geben Sie ihr den Namen default, wie folgt:

     [default]
     account = "myaccount"
     user = "jdoe-test"
     password = "******"
     warehouse = "my-test_wh"
     database = "my_test_db"
     schema = "my_schema"
     

     Copy

  2. Speichern Sie die Datei.

• Geben Sie eine benannte Verbindung als Standardverbindung in der Snowflake-Datei config.toml an, die sich im selben Verzeichnis wie die Datei connections.toml befindet.

  1. Öffnen Sie die Datei config.toml zur Bearbeitung, und führen Sie Folgendes aus:

  2. Stellen Sie den Parameter default_connection_name wie folgt ein:

     default_connection_name = "myaccount"
     

     Copy

  3. Speichern Sie die Datei.

• Legen Sie die Umgebungsvariable SNOWFLAKE_DEFAULT_CONNECTION_NAME fest.

  Manchmal möchten Sie die Standardverbindung vielleicht vorübergehend überschreiben, z. B. um eine Testverbindung zu testen, ohne die normale Standardverbindung ändern zu müssen. Sie können die in den Dateien connections.toml und config.toml angegebene Standardverbindung überschreiben, indem Sie die Umgebungsvariable SNOWFLAKE_DEFAULT_CONNECTION_NAME wie folgt festlegen:

  SNOWFLAKE_DEFAULT_CONNECTION_NAME = myconnection_test
  

  Copy

Um die Standardverbindung zu verwenden, führen Sie Python-Code ähnlich wie den folgenden aus:

with snowflake.connector.connect() as conn:
    with conn.cursor() as cur:
        print(cur.execute("SELECT 1;").fetchall())

Copy

Verwenden von Single Sign-On (SSO) zur Authentifizierung¶

Wenn Sie Snowflake für die Verwendung von Single Sign-On (SSO) konfiguriert haben, können Sie Ihre Clientanwendung so konfigurieren, dass SSO für die Authentifizierung verwendet wird. Weitere Informationen dazu finden Sie unter Verwenden von SSO bei Clientanwendungen, die sich mit Snowflake verbinden.

Verwenden der mehrstufige Authentifizierung (MFA)¶

Snowflake unterstützt das Caching von MFA-Token, einschließlich der Kombination der von MFA-Token-Caching mit SSO.

Weitere Informationen dazu finden Sie unter Verwenden von MFA-Tokencaching zur Minimierung der Anzahl von Eingabeaufforderungen bei der Authentifizierung – Optional.

Verwenden von Schlüsselpaar-Authentifizierung und Schlüsselpaar-Rotation¶

Der Python-Konnektor unterstützt Schlüsselpaar-Authentifizierung und Schlüsselrotation.

Weitere Informationen zur Konfiguration der Schlüsselpaar-Authentifizierung und der Schlüsselrotation finden Sie unter Schlüsselpaar-Authentifizierung und Schlüsselpaar-Rotation.

1. Nachdem Sie die Konfiguration der Schlüsselpaar-Authentifizierung abgeschlossen haben, setzen Sie den Parameter private_key in der Funktion connect auf den Pfad zur Datei des privaten Schlüssels.

2. Ändern Sie den unten stehenden Beispielcode, und führen Sie ihn aus. Der Code entschlüsselt die Datei, die den privaten Schlüssel enthält, und übergibt sie an den Snowflake-Treiber, um eine Verbindung herzustellen:

• Aktualisieren Sie die Sicherheitsparameter:

  • path: Gibt den lokalen Pfad zu der von Ihnen erstellten Datei mit dem privaten Schlüssel an.

• Aktualisieren Sie die Verbindungsparameter:

  • user: Gibt Ihren Snowflake-Anmeldenamen an.

  • account_identifier: Gibt Ihren Kontobezeichner an.

    Weitere Details dazu finden Sie unter Nutzungshinweise für die Verwendung des account-Parameters (für die connect-Methode).

Beispielcode

import snowflake.connector
import os
from cryptography.hazmat.backends import default_backend
from cryptography.hazmat.primitives.asymmetric import rsa
from cryptography.hazmat.primitives.asymmetric import dsa
from cryptography.hazmat.primitives import serialization
with open("<path>/rsa_key.p8", "rb") as key:
    p_key= serialization.load_pem_private_key(
        key.read(),
        password=os.environ['PRIVATE_KEY_PASSPHRASE'].encode(),
        backend=default_backend()
    )

pkb = p_key.private_bytes(
    encoding=serialization.Encoding.DER,
    format=serialization.PrivateFormat.PKCS8,
    encryption_algorithm=serialization.NoEncryption())

ctx = snowflake.connector.connect(
    user='<user>',
    account='<account_identifier>',
    private_key=pkb,
    warehouse=WAREHOUSE,
    database=DATABASE,
    schema=SCHEMA
    )

cs = ctx.cursor()

Copy

Verwenden eines Proxyservers¶

Um einen Proxyserver zu verwenden, konfigurieren Sie die folgenden Umgebungsvariablen:

• HTTP_PROXY

• HTTPS_PROXY

• NO_PROXY

Beispiel:

Linux oder macOS:

export HTTP_PROXY='http://username:password@proxyserver.company.com:80'
export HTTPS_PROXY='http://username:password@proxyserver.company.com:80'

Copy

Windows:

set HTTP_PROXY=http://username:password@proxyserver.company.com:80
set HTTPS_PROXY=http://username:password@proxyserver.company.com:80

Copy

Verbinden mit OAuth¶

Um eine Verbindung mit OAuth herzustellen, muss die Verbindungszeichenfolge den Parameter authenticator mit dem Wert oauth und den Parameter token mit dem Wert oauth_access_token enthalten. Weitere Informationen dazu finden Sie unter Clients, Treiber und Konnektoren.

ctx = snowflake.connector.connect(
    user="<username>",
    host="<hostname>",
    account="<account_identifier>",
    authenticator="oauth",
    token="<oauth_access_token>",
    warehouse="test_warehouse",
    database="test_db",
    schema="test_schema"
)

Verwalten von Verbindungstimeouts¶

Durch den Aufruf von snowflake.connector.connect wird eine Anmeldeanforderung gesendet. Wenn eine Anmeldeanforderung fehlschlägt, kann der Konnektor die Verbindungsanforderung erneut senden. Mit den folgenden Parametern werden Zeitlimits festgelegt, nach denen der Konnektor keine weiteren Wiederholungen von Anforderungen ausführt:

• login_timeout: Gibt an, wie lange (in Sekunden) die Verbindungsanforderung erneut gesendet werden soll. Wenn die Verbindung innerhalb dieser Zeit nicht erfolgreich hergestellt wurde, bricht der Konnektor nach Beendigung des aktuellen Versuchs mit einem Timeout-Fehler ab, anstatt die Anmeldeanforderung erneut zu senden. Nach Ablauf des Timeouts werden weitere Wiederholungsversuche verhindert. Der aktuelle Versuch wird jedoch auf natürliche Weise beendet.

• network_timeout: Gibt an, wie lange auf die Behebung von Netzwerkproblemen für andere Anforderungen, z. B. Abfrageanforderungen von cursor.execute, gewartet werden soll. Wenn nach Ablauf der in network_timeout angegebenen Sekunden der aktuelle Versuch fehlschlägt, wird ein Timeout ausgelöst und die betreffende Anforderung wird nicht erneut versucht. Nach Ablauf der network_timeout-Sekunden darf der aktuelle Versuch noch zu Ende ausgeführt werden (er scheitert von selbst), danach tritt das Timeout ein.

• socket_timeout: Gibt die Verbindungs- und Anforderungs-Timeouts auf Socket-Ebene an.

Im folgenden Beispiel wird socket_timeout für den SNOWFLAKE_JWT-Authentifikator überschrieben:

# this request itself stops retrying after 60 seconds as it is a login request
conn = snowflake.connector.connect(
login_timeout=60,
network_timeout=30,
socket_timeout=10
)

# this request stops retrying after 30 seconds
conn.cursor.execute("SELECT * FROM table")

Das folgende Beispiel zeigt, welche Auswirkung ein großer socket_timeout-Wert hat:

# even though login_timeout is 1, connect will take up to n*300 seconds before failing
# (n depends on possible socket addresses)
# this issue arises because socket operations cannot be cancelled once started
conn = snowflake.connector.connect(
login_timeout=1,
socket_timeout=300
)

Das folgende Beispiel zeigt, wie das Socket-Timeout für den SNOWFLAKE_JWT-Authentifikator überschrieben werden kann:

# socket timeout for login request overriden by env variable JWT_CNXN_WAIT_TIME
conn = snowflake.connector.connect(
authenticator="SNOWFLAKE_JWT",
socket_timeout=300
)

# socket timeout for this request is still 300 seconds
conn.cursor.execute("SELECT * FROM table")

Beachten Sie, dass die Umgebungsvariable MAX_CON_RETRY_ATTEMPTS die maximale Anzahl der Wiederholungsversuche für Anmeldeanforderungen begrenzt. Wenn eine Anforderung das Timeout noch nicht erreicht hat, aber die maximale Anzahl der Wiederholungsversuche, schlägt die Anfrage sofort fehl. Der Standardwert ist 1, was bedeutet, dass der Konnektor nur einen Wiederholungsversuch ausführt.

Verwalten von Verbindungs-Backoff-Richtlinien für Wiederholungsversuche¶

In manchen Situationen kann es sinnvoll sein, die Rate oder Häufigkeit zu variieren, mit der der Konnektor fehlgeschlagene Anforderungen aufgrund von Timeouts wiederholt. Wenn Sie z. B. feststellen, dass sehr viele Versuche gleichzeitig stattfinden, können Sie diese Anforderungen verteilen, indem Sie eine Backoff-Richtlinie für Wiederholungsversuche festlegen. Eine Backoff-Richtlinie legt die Zeit fest, die zwischen den Wiederholungsversuchen gewartet wird.

Der Snowflake-Konnektor für Python implementiert Backoff-Richtlinien mit dem Verbindungsparameter backoff_policy, der eine Python-Generatorfunktion angibt. Mit der Generatorfunktion können Sie angeben, wie lange gewartet werden soll (Backoff), bevor die nächste Wiederholungsanforderung gesendet wird.

Snowflake bietet die folgenden Hilfsmittel, um vordefinierte Generatorfunktionen mit den gewünschten Parametern zu erstellen. Sie können diese verwenden, wenn Sie nicht selbst welche erstellen möchten:

• linear_backoff erhöht die Backoff-Dauer bei jeder Iteration um eine Konstante.

• exponential_backoff multipliziert bei jeder Iteration die Backoff-Dauer mit einer Konstante.

• mixed_backoff entscheidet bei jeder Iteration zufällig, ob die Backoff-Dauer um exponential_backoff erhöht oder die Backoff-Dauer beibehalten wird.

Diese vordefinierten Generatorfunktionen verwenden die folgenden Parameter, um deren Verhalten zu spezifizieren:

• base: Erstmalige Backoff-Zeit in Sekunden (Standard = 1).

• factor: Koeffizient zum Erhöhen der Backoff-Zeit. Die Wirkung hängt von der Implementierung ab (Standard = 2); linear_backup addiert den Wert, während exponential_backup den Wert multipliziert.

• cap: Maximale Backoff-Zeit in Sekunden (Standard = 16).

• enable_jitter: Ob für eine berechnete Dauer Jitter aktiviert werden soll (Standard = True). Weitere Informationen zu Jitter bei exponentiellem Backoff finden Sie im Artikel Exponentieller Backoff und Jitter in AWS.

Sie können z. B. die Richtlinie exponential_backoff mit Standardwerten oder mit kundenspezifischen Werten verwenden:

from snowflake.connector.backoff_policies import exponential_backoff

# correct, no required arguments
snowflake.connector.connect(
backoff_policy=exponential_backoff()
)

# correct, parameters are customizeable
snowflake.connector.connect(
backoff_policy=exponential_backoff(
    factor=5,
    base=10,
    cap=60,
    enable_jitter=False
  )
)

Sie können auch Ihre eigenen Generatorfunktionen für Backoff-Richtlinien erstellen, ähnlich wie die folgende, mit der die Generatorfunktion my_backoff_policy definiert wird:

def my_backoff_policy() -> int:
  while True:
    # yield the desired backoff duration

Sie können den Verbindungsparameter backoff_policy wie folgt auf den Namen Ihrer Generatorfunktion setzen:

snowflake.connector.connect(
  backoff_policy=constant_backoff
)

OCSP¶

Wenn der Treiber eine Verbindung herstellt, sendet Snowflake ein Zertifikat, um zu bestätigen, dass die Verbindung zu Snowflake und nicht zu einem Host besteht, der sich als Snowflake ausgibt. Der Treiber sendet dieses Zertifikat an einen OCSP (Online Certificate Status Protocol)-Server, um zu überprüfen, ob das Zertifikat widerrufen wurde.

Wenn der Treiber den OCSP-Server nicht erreichen kann, um das Zertifikat zu überprüfen, kann beim Treiber „Fail-open“ oder „Fail-close“ auftreten.

con = snowflake.connector.connect(
    account=<account_identifier>,
    user=<user>,
    ...,
    ocsp_fail_open=False,
    ...);