PythonコネクタによるSnowflakeへの接続¶

SnowCD を使用したSnowflakeへのネットワーク接続の確認¶

ドライバーを設定したら、 SnowCD を使用して、Snowflakeへのネットワーク接続を評価およびトラブルシューティングできます。

初期構成プロセス中に SnowCD を使用して、オンデマンドでSnowflakeへのネットワーク接続を評価およびトラブルシューティングできます。

snowflake.connector モジュールのインポート¶

snowflake.connector モジュールをインポートするには、次のコマンドを実行します。

import snowflake.connector

環境変数、コマンドライン、構成ファイル、または別の適切なソースからログイン情報を取得できます。例:

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

ACCOUNT パラメーターには、使用する アカウント識別子 を使用します。アカウント識別子には snowflakecomputing.com サフィックスが含まれて いない ことに注意してください。

詳細と例については、 account パラメーターの使用上の注意（connect メソッドの場合） をご参照ください。

自分のAmazon S3バケットからデータをコピーする場合は、 AWS_ACCESS_KEY_ID と 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')

接続情報を読み取った後、デフォルトの認証方式またはフェデレーション認証（有効な場合）を使用して接続します。

セッションパラメーターの設定¶

Pythonコネクタを使用する場合は、 QUERY_TAG のようなセッションパラメーターを複数の方法で設定できます。

• 次のように、オプションの session_parameters という名前の接続パラメーターを渡すと、Snowflakeに接続するときにセッションレベルのパラメーターを設定できます。

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

  Copy

  snowflake.connector.connect メソッドに渡される session_parameters ディクショナリには、1つ以上のセッションレベルのパラメーターを含めることができます。

  注釈

  Python接続内で SEARCH_PATH パラメーターを設定することはできません。検索パスを設定する前にセッションを確立する必要があります。

• 接続後に ALTER SESSION SET SQL ステートメントを実行して、セッションパラメーターを設定することもできます。

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

  Copy

セッションパラメータの詳細については、一般的な パラメーター ページの個々のパラメーターの説明をご参照ください。

デフォルト認証方式を使用した接続¶

ログインパラメーターを使用してSnowflakeに接続します。

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

snowflake.connector.connect メソッドで利用可能な他の情報を使用してこれを拡張する必要がある場合があります。

connections.toml ファイルを使用した接続¶

Pythonコネクタにより、 connections.toml 構成ファイルに接続定義を追加できます。接続定義とは、接続に関連するパラメーターのコレクションのことです。 Snowflake Pythonライブラリは現在、 TOML バージョン1.0.0をサポートしています。

toml ファイルフォーマットの詳細については、 TOML (Tom's Obvious Minimal Language) をご参照ください。

Pythonコネクタは、 connections.toml ファイルを以下の場所で順に探します。

• ~/.snowflake ディレクトリがマシンに存在する場合、Python コネクターは ~/.snowflake/connections.toml ファイルを使用します。SNOWFLAKE_HOME 環境変数に場所を設定すると、デフォルトの ~/.snowflake ディレクトリを上書きすることができます。

• そうでない場合、Python Connectorは、オペレーティングシステムに基づいて、次のいずれかの場所にある connections.toml ファイルを使用します。

  • Linux: ~/.config/snowflake/connections.toml、ただし、 XDG 変数で更新可

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

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

接続構成ファイルに認証情報を追加するには、

1. テキストエディターで connections.toml ファイルを開いて編集します。たとえば、Linuxの vi エディターでファイルを開く場合:

   $ vi connections.toml
   

   Copy

2. 新しいSnowflake接続定義を追加します。

   TOML の構成ファイルの基本設定は、 Snowsight で生成できます。詳細については、 Snowflakeに接続するためのクライアント、ドライバー、ライブラリ、またはサードパーティアプリケーションの構成 をご参照ください。

   たとえば、アカウント myaccount、ユーザー johndoe、パスワード認証情報とデータベース情報を持つ myconnection というSnowflake接続を追加するには、構成ファイルに以下の行を追加します。

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

   Copy

   接続定義は、 snowflake.connector.connect メソッドで利用可能なものと同じ構成オプションをサポートします。

3. オプション: 以下のように、さらに接続を追加します。

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

   Copy

4. ファイルへの変更を保存します。

5. Pythonコードでは、 snowflake.connector.connect に以下と類似した接続名を指定します。

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

   Copy

   以下のように、 connections.toml ファイルで接続に定義された値を上書きすることもできます。

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

   Copy

デフォルト接続の設定¶

接続をデフォルトとして設定できるため、Snowflakeに接続するたびに snowflake.connector.connect() を呼び出して接続を指定する必要がありません。デフォルト接続を定義するには、優先順位の昇順に以下の方法があります。

• default という名前の接続定義を作成します。

  1. connections.toml ファイルで接続定義を作成し、 default という名前を付けます。

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

     Copy

  2. ファイルを保存します。

• connections.toml ファイルと同じディレクトリにあるSnowflake config.toml ファイルで、名前付き接続をデフォルト接続として指定します。

  1. 編集のために config.toml ファイルを開きます。そして、

  2. default_connection_name パラメーターを以下のように設定します。

     default_connection_name = "myaccount"
     

     Copy

  3. ファイルを保存します。

• SNOWFLAKE_DEFAULT_CONNECTION_NAME 環境変数を設定します。

  テスト接続の試行など、通常のデフォルト接続を変更することなく、一時的にデフォルト接続を上書きすることが必要になる場合があります。以下のように、 SNOWFLAKE_DEFAULT_CONNECTION_NAME 環境変数を設定すると、 connections.toml と config.toml ファイルで指定されたデフォルトの接続を上書きできます。

  SNOWFLAKE_DEFAULT_CONNECTION_NAME = myconnection_test
  

  Copy

デフォルト接続を使用するには、以下のようなPythonコードを実行します。

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

Copy

認証でのシングルサインオン（SSO）の使用¶

シングルサインオン（SSO）を使用するようにSnowflakeを構成 している場合、認証に SSO を使用するようにクライアントアプリケーションを構成できます。詳細については Snowflakeに接続するクライアントアプリケーションでの SSO の使用 をご参照ください。

多要素認証（MFA）の使用¶

Snowflakeは、 MFA トークンキャッシングと SSO の組み合わせを含む、 MFA トークンのキャッシングをサポートしています。

詳細については、 MFA トークンキャッシングを使用して認証中のプロンプトの数を最小限に抑える --- オプション をご参照ください。

キーペア認証とキーペアローテーションの使用¶

Pythonコネクタは、キーペア認証とキーローテーションをサポートしています。

キーペア認証とキーローテーションを構成する方法の詳細については、 キーペア認証とキーペアローテーション をご参照ください。

1. キーペア認証の構成が完了したら、 connect 関数の private_key_file パラメーターを秘密キーファイルへのパスに設定します。また、 private_key_file_pwd パラメーターに秘密キーファイルのパスフレーズを設定します。

2. 以下のサンプルコードを変更して実行します。

• セキュリティパラメーターを更新します。

  • path: 作成した秘密キーファイルへのローカルパスを指定します。

• 接続パラメーターを更新します。

  • user:Snowflakeログイン名を指定します。

  • account_identifier: 使用する アカウント識別子 を指定します。

    詳細については、 account パラメーターの使用上の注意（connect メソッドの場合） をご参照ください。

サンプルコード

import os
import snowflake.connector as sc

private_key_file = '<path>'
private_key_file_pwd = '<password>'

conn_params = {
    'account': '<account_identifier>',
    'user': '<user>',
    'authenticator': 'SNOWFLAKE_JWT',
    'private_key_file': private_key_file,
    'private_key_file_pwd':private_key_file_pwd,
    'warehouse': '<warehouse>',
    'database': '<database>',
    'schema': '<schema>'
}

ctx = sc.connect(**conn_params)
cs = ctx.cursor()

Copy

プロキシサーバーの使用¶

プロキシサーバーを使用するには、次の環境変数を構成します。

• HTTP_PROXY

• HTTPS_PROXY

• NO_PROXY

例:

Linuxまたは macOS:

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

Copy

Windows:

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

Copy

OAuth との接続¶

OAuthを使用して接続するには、接続文字列に oauth に設定された authenticator パラメーターと oauth_access_token に設定された token パラメーターを含める必要があります。詳細については、 クライアント、ドライバー、およびコネクタ をご参照ください。

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

ワークロードIDフェデレーション（WIF）による認証¶

ワークロードIDフェデレーション は、Snowflakeのサービス間の認証方法を提供します。この方法により、アプリケーション、サービス、コンテナは、 AWSIAM、Microsoft Entra IDまたはGoogle CloudサービスアカウントのようなクラウドプロバイダーのネイティブIDシステムを活用して、Snowflakeで認証することができます。このアプローチでは、長期間有効な認証情報を管理する必要がなくなり、外部 OAuth のような他の方法と比較して、認証情報の取得が簡素化されます。Snowflakeコネクタは、プラットフォームのIDプロバイダーから有効期間が短い認証情報を自動的に取得するように設計されています。

ワークロードIDフェデレーション認証コードを有効にするには、以下を実行します。

1. authenticator connection parameter to WORKLOAD_IDENTITY を設定します。

2. プラットフォームに応じて、workload_identity_provider connection parameter to AWS、 AZURE、 :codenowrap:`GCP`または:codenowrap:`OIDC`を設定します。

3. OpenID 接続（OIDC）の場合、token 接続パラメーターを指定します。

プログラムアクセストークンによる認証コード (PAT)¶

プログラムアクセストークン（PAT）は、Snowflake固有の認証方法です。この機能は使用前にアカウントで有効にする必要があります（詳細は 前提条件 を参照してください）。PAT での認証には、人とのやりとりは一切ありません。

PATs の詳細については、 認証のためのプログラム アクセス トークンの使用 をご参照ください。

接続タイムアウトの管理¶

snowflake.connector.connect を呼び出すと、ログインリクエストが送信されます。ログインリクエストが失敗した場合、コネクタで接続リクエストを再送することができます。以下のパラメーターは、コネクタがリクエストの再試行を停止するまでの制限時間を設定します。

• login_timeout: 接続リクエストを再送し続ける時間を秒単位で指定します。その時間内で接続が失敗した場合、コネクタはログインリクエストを再試行し続けるのではなく、現在の試行を完了した後にタイムアウトエラーで失敗します。タイムアウトを過ぎると、それ以上の再試行はできなくなります。しかし、現在進行中の試行は自然に終了します。

• network_timeout: cursor.execute からのクエリリクエストなど、他のリクエストに対してネットワークの問題が解決するまでの待ち時間を指定します。現在の試行が失敗して network_timeout 秒が経過し、タイムアウトが発生して当該リクエストが再試行されない場合。 network_timeout 秒経過後、現在の試行が終了する（自然に失敗する）ことは引き続き許可され、その後にタイムアウトが発生します。

• socket_timeout: ソケットレベルでの接続とリクエストのタイムアウトを指定します。

次の例では、 SNOWFLAKE_JWT 認証コードの socket_timeout を上書きしています。

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

次の例は、 socket_timeout を大きな値に設定した場合の効果を示しています。

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

次の例は、 SNOWFLAKE_JWT 認証コードのソケットタイムアウトを上書きする方法を示しています。

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

MAX_CON_RETRY_ATTEMPTS 環境変数は、ログインリクエストの最大再試行回数を制限することに注意してください。リクエストがタイムアウトしていないが、最大再試行回数に達している場合、リクエストは即座に失敗します。デフォルト値は1で、コネクタは1回だけ再試行を行います。

再試行のための接続バックオフポリシーの管理¶

状況によっては、コネクタがタイムアウトによる失敗したリクエストを再試行する割合や頻度を変えたい場合があります。たとえば、非常に多くの試行が同時に発生することに気づいたら、再試行のバックオフポリ シーを定義することで、それらのリクエストを分散させることができます。バックオフポリシーでは、再試行までの待ち時間を指定します。

Python用Snowflakeコネクタは、Pythonジェネレーター関数を指定する backoff_policy 接続パラメーターでバックオフポリシーを実装します。ジェネレーター関数では、次の再試行リクエストを送信するまでの待ち時間（バックオフ）を指定できます。

Snowflakeには、希望するパラメーターを持つ定義済みジェネレーター関数を作成するため、次のヘルパーが用意されています。自分で作成したくない場合は、以下を使用することができます。

• linear_backoff、これは各反復ごとにバックオフ時間を一定に増加させます。

• exponential_backoff、これは各反復ごとにバックオフ時間を定数倍します。

• mixed_backoff、これはバックオフ時間を exponential_backoff で増分するか、そのままにするかを各反復でランダムに選択します。

これらの定義済みジェネレーター関数は、次のパラメーターを使用して動作を指定します。

• base: 秒単位の初期バックオフ時間（デフォルト = 1）。

• factor: バックオフ時間を増分する係数。効果は実装によって異なります（デフォルト = 2）。linear_backup は値を加算し、 exponential_backup は値を乗算します。

• cap: 秒単位の最大バックオフ時間（デフォルト = 16）。

• enable_jitter: 計算された持続時間のジッターを有効化するかどうか（デフォルト = True）。

  指数関数的バックオフにおけるジッターの詳細については、 AWS 指数関数的バックオフとジッター の記事をご参照ください。

たとえば、次のように、 exponential_backoff ポリシーをデフォルト値またはカスタム値で使用できます。

from snowflake.connector.backoff_policies import exponential_backoff

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

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

また、 my_backoff_policy ジェネレーター関数を定義する次の例のように、独自のバックオフポリシージェネレーター関数を作成することもできます。

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

次に、 backoff_policy 接続パラメーターにジェネレーター関数の名前を次のように設定します。

snowflake.connector.connect(
  backoff_policy=constant_backoff
)

OCSP¶

ドライバーが接続すると、Snowflakeは証明書を送信して、Snowflakeを偽装しているホストではなく、Snowflakeへの接続であることを確認します。ドライバーはその証明書を OCSP （オンライン証明書状態プロトコル）サーバーに送信し、証明書が失効していないことを確認します。

ドライバーが証明書を確認するために OCSP サーバーに到達できない場合、ドライバーは "fail open" or "fail closed" できます。

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

接続性テストと診断の実行¶

接続性の問題が発生した場合は、コネクター内で直接診断を実行できます。Snowflake Supportは、接続性の問題を解決するために、この情報を要求することもあります。

診断コレクションは、以下の 接続 パラメーターを使用します。

• enable_connection_diag: 診断レポートを作成するかどうか。

• connection_diag_log_path: 生成されたレポートの絶対パス。

• connection_diag_allowlist_path: SYSTEM$ALLOWLIST() または SYSTEM$ALLOWLIST_PRIVATELINK() の出力を含む JSON ファイルへの絶対パス。接続で定義されたユーザーがシステム許可リスト関数を実行する権限を持っていない場合、またはアカウント URL への接続に失敗した場合にのみ必要です。

診断を生成する接続を設定するには

1. 接続パラメーターを構成します。

   • Snowflakeアカウントの認証情報パラメーターを設定します。

   • connect パラメーターに enable_connection_diag=True を設定します。

   • 必要であれば、 connection_diag_log_path パラメーターを設定して、生成されたレポートの場所を変更します。

   例:

   from snowflake import connector
   
   ctx = connector.connect(
           user=<user>,
           password=<password>,
           account=<account>,
           enable_connection_diag=True,
           connection_diag_log_path="<HOME>/diag-tests",
           )
   print('connected')
   

   Copy

2. コード・スニペットを実行します。

3. 指定されたログ・パスにある、生成された SnowflakeConnectionTestReport.txt ファイルの診断テスト出力を確認します。

接続性に問題がないかレポートを確認し、ネットワーク・チームと話し合うことができます。また、Snowflakeサポートにレポートを提出し、追加サポートを受けることもできます。