Snowflake接続の管理¶

代替構成ファイル¶

Snowflake CLI は、 connections.toml 構成ファイルもサポートしています。このファイルは、 config.toml ファイルと同じディレクトリに配置し、接続のみを含める必要があります。 connections.toml の構成には、 connections のない別のセクション名が必要です。例えば、 [connections.myconnection] は、単に [myconnection] となります。

接続を追加します。¶

新しい接続を作成し、 構成ファイル に追加するには、以下のようにします。

1. snow connection add コマンドを実行します。

   snow connection add
   

   Copy

2. プロンプトが表示されたら、必要な接続、アカウント、ユーザー名のパラメーターと、その他必要なオプションのパラメーターを入力します。

   Enter connection name: <connection_name>
   Enter account: <account>
   Enter user: <user-name>
   Enter password: <password>
   Enter role: <role-name>
   Enter warehouse: <warehouse-name>
   Enter database: <database-name>
   Enter schema: <schema-name>
   Enter host: <host-name>
   Enter port: <port-number>
   Enter region: <region-name>
   Enter authenticator: <authentication-method>
   Enter private key file: <path-to-private-key-file>
   Enter token file path: <path-to-mfa-token>
   Do you want to configure key pair authentication? [y/N]: y
   Key length [2048]: <key-length>
   Output path [~/.ssh]: <path-to-output-file>
   Private key passphrase: <key-description>
   Wrote new connection <connection-name> to config.toml
   

また、図のようにコマンドラインで特定のパラメーターの値を追加することもできます。

snow --config-file config.toml connection add -n myconnection2 --account myaccount2 --user jdoe2

デフォルトでは、 snow connection add コマンドは、オプションのパラメーターがコマンドラインで指定されていない場合、プロンプトを表示します。 account のようなオプションパラメーターを指定せずに接続を追加し、対話式プロンプトをスキップしたい場合は、示されているように --no-interactive オプションを使用することができます。。

snow connection add -n myconnection2 --user jdoe2 --no-interactive

接続を追加した後、 接続をテストする ことができます。接続が正しく動作することを確認します。

定義された接続を一覧表示する¶

利用可能な接続を一覧表示するには、次のように snow connection list コマンドを入力します。

snow connection list

+-------------------------------------------------------------------------------------------------+
| connection_name | parameters                                                       | is_default |
|-----------------+------------------------------------------------------------------+------------|
| myconnection    | {'account': 'myaccount', 'user': 'jondoe', 'password': '****',   | False      |
|                 | 'database': 'my_db', 'schema': 'my_schema', 'warehouse':         |            |
|                 | 'my-wh'}                                                         |            |
| myconnection2   | {'account': 'myaccount2', 'user': 'jdoe2'}                       | False      |
+-------------------------------------------------------------------------------------------------+

接続のテストと診断¶

接続がSnowflakeに正常に接続できるかどうかをテストするには、次のような snow connection test コマンドを入力します。

snow connection test -c myconnection2

+--------------------------------------------------+
| key             | value                          |
|-----------------+--------------------------------|
| Connection name | myconnection2                  |
| Status          | OK                             |
| Host            | example.snowflakecomputing.com |
| Account         | myaccount2                     |
| User            | jdoe2                          |
| Role            | ACCOUNTADMIN                   |
| Database        | not set                        |
| Warehouse       | not set                        |
+--------------------------------------------------+

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

診断コレクションは、以下の snow connection test コマンドオプションを使用します。

• --enable-diag で診断レポートを生成します。

• --diag-log-path で、生成されるレポートの絶対パスを指定します。

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

次の例は、 myconnection2 接続の診断レポートを生成し、 ~/report/SnowflakeConnectionTestReport.txt ファイルに保存します。

snow connection test -c myconnection2 --enable-diag --diag-log-path $(HOME)/report

+----------------------------------------------------------------------------+
| key                  | value                                               |
|----------------------+-----------------------------------------------------|
| Connection name      | myconnection2                                       |
| Status               | OK                                                  |
| Host                 | example.snowflakecomputing.com                      |
| Account              | myaccount2                                          |
| User                 | jdoe2                                               |
| Role                 | ACCOUNTADMIN                                        |
| Database             | not set                                             |
| Warehouse            | not set                                             |
| Diag Report Location | /Users/<username>/SnowflakeConnectionTestReport.txt |
+----------------------------------------------------------------------------+

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

デフォルト接続の設定¶

default_connection_name 構成ファイルと SNOWFLAKE_DEFAULT_CONNECTION_NAME 変数が設定されている場合は、それを上書きして、デフォルトとして使用する構成 Snowflake CLI を指定するために、 snow connection set-default コマンドを使用できます。

次の例では、デフォルトの接続を myconnection2 に設定しています。

snow connection set-default myconnection2

Default connection set to: myconnection2

Snowflake認証情報に環境変数を使用する¶

構成ファイルではなく、システム環境変数でSnowflake認証情報を指定することもできます。次の汎用環境変数は、接続パラメーターを置き換えるためにのみ使用できます。

• SNOWFLAKE_ACCOUNT

• SNOWFLAKE_USER

• SNOWFLAKE_PASSWORD

• SNOWFLAKE_DATABASE

• SNOWFLAKE_SCHEMA

• SNOWFLAKE_ROLE

• SNOWFLAKE_WAREHOUSE

• SNOWFLAKE_AUTHENTICATOR

• SNOWFLAKE_PRIVATE_KEY_PATH

• SNOWFLAKE_PRIVATE_KEY_RAW

• SNOWFLAKE_SESSION_TOKEN

• SNOWFLAKE_MASTER_TOKEN

• SNOWFLAKE_TOKEN_FILE_PATH

• SNOWFLAKE_OAUTH_CLIENT_ID

• SNOWFLAKE_OAUTH_CLIENT_SECRET

• SNOWFLAKE_OAUTH_AUTHORIZATION_URL

• SNOWFLAKE_OAUTH_TOKEN_REQUEST_URL

• SNOWFLAKE_OAUTH_REDIRECT_URI

• SNOWFLAKE_OAUTH_SCOPE

• SNOWFLAKE_OAUTH_DISABLE_PKCE

• SNOWFLAKE_OAUTH_ENABLE_REFRESH_TOKENS

• SNOWFLAKE_OAUTH_ENABLE_SINGLE_USE_REFRESH_TOKENS

• SNOWFLAKE_CLIENT_STORE_TEMPORARY_CREDENTIAL

snow コマンドに接続パラメーターを渡します。¶

snow コマンド、接続を必要とするすべてのコマンドで、接続パラメーターを直接渡すことができます。接続構成パラメーターの完全なリストについては、 snow sql --help コマンドを実行します。出力は、接続構成オプションのあるセクションのみを示していることに注意してください。

snow sql --help

╭─ Connection configuration ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --connection,--environment             -c      TEXT     Name of the connection, as defined in your config.toml. Default: default.
│ --host                                         TEXT     Host address for the connection. Overrides the value specified for the connection.
│ --port                                         INTEGER  Port for the connection. Overrides the value specified for the connection.
│ --account,--accountname                        TEXT     Name assigned to your Snowflake account. Overrides the value specified for the connection.
│ --user,--username                              TEXT     Username to connect to Snowflake. Overrides the value specified for the connection.
│ --password                                     TEXT     Snowflake password. Overrides the value specified for the connection.
│ --authenticator                                TEXT     Snowflake authenticator. Overrides the value specified for the connection.
│ --private-key-file,--private-key-path          TEXT     Snowflake private key file path. Overrides the value specified for the connection.
│ --token-file-path                              TEXT     Path to file with an OAuth token that should be used when connecting to Snowflake.
│ --database,--dbname                            TEXT     Database to use. Overrides the value specified for the connection.
│ --schema,--schemaname                          TEXT     Database schema to use. Overrides the value specified for the connection.
│ --role,--rolename                              TEXT     Role to use. Overrides the value specified for the connection.
│ --warehouse                                    TEXT     Warehouse to use. Overrides the value specified for the connection.
│ --temporary-connection                 -x               Uses connection defined with command line parameters, instead of one defined in config.
│ --mfa-passcode                                 TEXT     Token to use for multi-factor authentication (MFA).
│ --oauth-client-id                              TEXT     Value of the client ID provided by the identity provider for Snowflake integration.
│ --oauth-client-secret                          TEXT     Value of the client secret provided by the identity provider for Snowflake integration.
│ --oauth-authorization-url                      TEXT     Identity provider endpoint supplying the authorization code to the driver.
│ --oauth-token-request-url                      TEXT     Identity provider endpoint supplying the access tokens to the driver.
│ --oauth-redirect-uri                           TEXT     URI to use for the authorization code.
│ --oauth-scope                                  TEXT     Scope requested in the identity provider authorization request.
│ --oauth-disable-pkce                                    Disables Proof Key for Code Exchange (PKCE). Default: False.
│ --oauth-enable-refresh-tokens                           Enables a silent re-authentication when the actual access token becomes outdated. Default: False.
│ --oauth-enable-single-use-refresh-tokens                Whether to opt in to single-use refresh token semantics. Default: False.
│ --client-store-temporary-credential                     Store the temporary credential.
│ --enable-diag                                           Run the python connector diagnostic test.
│ --diag-log-path                                TEXT     Diagnostic report path.
│ --diag-allowlist-path                          TEXT     Diagnostic report path to optional allowlist.
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

認証にプライベートキーファイルを使用する¶

認証にプライベートキーファイルを使用するには、接続構成で 認証コード パラメーターを SNOWFLAKE_JWT に設定し、次のようにプライベートキーを含むファイルへのパスを指定する必要があります。

• snow connection add コマンドで、 --private_key-file オプションを図のように指定します。

  snow connection add \
     --connection-name jwt \
     --authenticator SNOWFLAKE_JWT \
     --private-key-file ~/.ssh/sf_private_key.p8
  

  Copy

• 構成ファイルを使用する。

  [connections.jwt]
  account = "my_account"
  user = "jdoe"
  authenticator = "SNOWFLAKE_JWT"
  private_key_file = "~/sf_private_key.p8"
  

  Copy

キーペア認証の設定の詳細については、 キーペア認証とキーペアローテーション をご参照ください。

Snowflake CLI は、以下の順序で接続パラメーターからプライベートキーを探します。

1. private_key_file が指定された場合、 Snowflake CLI は指定されたファイルパスからキーを読み込みます。

2. private_key_path が指定された場合、 Snowflake CLI は指定されたファイルパスからキーを読み込みます。

3. private_key_file または private_key_path が指定されていない場合、 Snowflake CLI は private_key_raw パラメーターから直接キーを読み込みます。

認証に OAuth を使用する¶

OAuth を使って接続するには、以下のどちらかを行います。

• snow connection add コマンドで、 --token-file-path オプションを図のように指定します。

  snow connection add --token-file-path "my-token.txt"
  

  Copy

• config.toml ファイルで、 authenticator = "oauth" を設定し、図のように接続定義に token_file_path パラメーターを追加します。

  [connections.oauth]
  account = "my_account"
  user = "jdoe"
  authenticator = "oauth"
  token_file_path = "my-token.txt"
  

  Copy

OAuth 2.0認証コードフローを使用する¶

OAuth 2.0認証コードフローは、ユーザーの認証情報を公開することなく、クライアントアプリケーションがユーザーに代わって認証サーバーからアクセストークンを取得するための安全な方法です。このフローとパラメーターの詳細については、Python用Snowflake Connectorドキュメントの OAuth 2.0 認証コードフローを有効にします。 を参照してください。

OAuth 2.0認証コードフローを使用するには、以下のような接続定義を config.toml ファイルに追加します。

[connections.oauth]
authenticator = "OAUTH_AUTHORIZATION_CODE"
user = "user"
account = "account"
oauth_client_id = "client_id"
oauth_client_secret = "client_secret"
oauth_redirect_uri = "http://localhost:8001/snowflake/oauth-redirect"
oauth_scope = "session:role:PUBLIC"

OAuth 2.0クライアント認証情報フローを使用する¶

OAuth 2.0クライアント認証情報フローは、Python用Snowflake Connectorがバックエンドサービスに接続するような、マシン間（M2M）認証のためのセキュアな方法を提供します。OAuth 2.0認証コードフローとは異なり、このメソッドはユーザー固有のデータに依存しません。このフローとパラメーターの詳細については、Python用Snowflake Connectorドキュメントの OAuth 2.0 クライアント認証フローを有効にします。 を参照してください。

OAuth 2.0クライアント認証情報フローを使用するには、以下のような接続定義を config.toml ファイルに追加します。

[connections.oauth]
authenticator = "OAUTH_CLIENT_CREDENTIALS"
user = "user"
account = "account"
oauth_client_id = "client_id"
oauth_client_secret = "client_secret"
oauth_token_request_url = "http://identity.provider.com/token"
oauth_scope = "session:role:PUBLIC"

多要素認証（MFA）を使用する¶

MFA を使用するには、

1. Snowflakeで 多要素認証 を設定し、 authenticator パラメーターを snowflake （デフォルト値）に設定します。

2. プッシュの代わりにDuoが生成したパスコードを使用する場合は、 --mfa-passcode <passcode> オプションを使用するか、 config.toml ファイルに passcode_in_password = true を設定し、 Pythonと MFA の併用 で説明されているようにパスコードをパスワードに含めます。

   注釈

   認証コードにパスコードを使用したい場合、最初の snow コマンドを実行した後は、トークンが有効である限りパスコードを入力することはできなくなります。以下のことを行ってください：

   • パスワードからパスコードを削除します。

   • config.toml ファイルの passcode_in_password = true を削除またはコメントします。

MFA キャッシュの使用¶

MFA キャッシュは、ログイン時に多要素認証（MFA）のプロンプトが表示される頻度を減らすセキュリティ機能です。MFA プロンプトが頻繁に表示されると、ワークフローが中断され、生産性が低下します。MFA キャッシュは、 MFA セッション情報を指定期間安全に保存することで、この問題に対処します。MFA キャッシュを使用すると、キャッシュされたセッションの時間枠内であれば、 MFA コードを繰り返し入力することなく認証できます。

MFA キャッシュを有効にします。

1. ご使用のアカウントに、 ALLOW_CLIENT_MFA_CACHING = true を設定します。

2. ファイル config.toml で、接続に authenticator = "username_password_mfa" を追加します。

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

SSO （シングルサインオン）を使用する¶

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

外部ブラウザーの使用¶

ブラウザーを使用して、OktaやActive Directory Federation Servicesなどの SAML 2.0準拠のアイデンティティプロバイダー（IdP）で Snowflake CLI 接続を認証できます。

外部ブラウザー認証を使用するには、以下のいずれかの方法を使用します。

• snow connection add --authenticator コマンドオプションを使用します。

  snow connection add --authenticator externalbrowser
  

  Copy

• config.toml ファイルの authenticator を externalbrowser にセットします。

  [connections.externalbrowser]
  account = "my_account"
  user = "jdoe"
  authenticator = "externalbrowser"
  

  Copy

PAT （プログラムアクセストークン）の使用¶

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

接続で PAT を使用するには、次のように、 authenticator を PROGRAMMATIC_ACCESS_TOKEN に設定し、 token_file_path をトークンのあるファイルをポイントするようにセットします。

[connections.externalbrowser]
account = "my_account"
user = "jdoe"
authenticator = "PROGRAMMATIC_ACCESS_TOKEN"
token_file_path = "path-to-pat-token"

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