Snowpipe REST APIを使用したデータロードの準備

このトピックでは、 REST APIを呼び出すときにSnowpipeを開始する方法について説明します。必要なクライアント SDKのインストール、ステージ(必要な場合)とパイプの作成、Snowpipeユーザーごとの1回限りのセキュリティ設定などの手順を説明します。

このトピックの内容:

注釈

このセクションの手順は、Snowflakeデータベースにデータがロードされるターゲットテーブルが既にあることを前提としています。

クライアント要件(JavaまたはPython SDK)

Snowpipeサービスには、Java SDKまたはPython SDK の いずれか が必要です。これらの SDKs は、便宜上Snowflakeによって提供されます。

重要

バイナリは、Snowflakeとのマスターサービス契約(MSA)の条件に基づいてクライアントソフトウェアとして提供されます。

Java SDKのインストール

  1. Maven Central RepositoryからJava SDK インストーラーをダウンロードします。

    http://search.maven.org/ (または、 https://repo1.maven.org/maven2/net/snowflake/snowflake-ingest-sdk

  2. JAR ファイルを既存のプロジェクトに統合します。

注釈

開発者ノートは、ソースコード GitHub _にホストされています。

Python SDKのインストール

Python SDK にはPython 3.5以上が必要です。

SDKをインストールするには、次のコマンドを実行します。

pip install snowflake-ingest

または、 PyPI からホイールファイルをダウンロードし、既存のプロジェクトに統合します。

注釈

開発者ノートは、ソースコード GitHub _にホストされています。

ステップ1:ステージを作成する(必要な場合)

Snowpipeは、次のステージタイプからのロードをサポートしています。

  • 名前付き内部(Snowflake)または外部(つまり、Amazon S3、Google Cloud Storage、またはMicrosoft Azure)ステージ

  • テーブルステージ

CREATE STAGE コマンドを使用して名前付きステージを作成するか、既存のステージを使用することを選択できます。Snowpipeがターゲットテーブルにファイルをロードする前に、ファイルを一時的にステージングします。

ステップ2:パイプを作成する

インジェスションキューからテーブルにデータをロードするためにSnowpipeが使用する COPYINTO <テーブル> ステートメントを定義するために、システムに新しいパイプを作成します。詳細については、 CREATE PIPE をご参照ください。

注釈

パイプを作成するには、 CREATE PIPE アクセス制御権限、およびデータベース、スキーマ、ステージに対する USAGE 権限が必要です。

たとえば、 mystage ステージにステージングされたファイルから mytable テーブルにすべてのデータをロードする mydb.myschema スキーマにパイプを作成します。

create pipe mydb.myschema.mypipe if not exists as copy into mydb.myschema.mytable from @mydb.myschema.mystage;

ステップ3:セキュリティを構成する(ユーザーごと)

Snowpipeを使用して継続的なデータロードを実行するユーザーごとに、Snowpipe REST エンドポイントを呼び出すための公開/秘密キーペアを生成します。さらに、データロードのオブジェクト(つまり、ターゲットデータベース、スキーマ、およびテーブル)、ステージオブジェクト、およびパイプに十分な権限を付与します。

Snowpipeのデータロードを1人のユーザーに制限する場合は、そのユーザーのキーペア認証を1回構成するだけで済みます。その後は、各データのロードに使用されるデータベースオブジェクトに対するアクセス制御権限のみを付与する必要があります。

注釈

最小権限の一般原則に従うために、パイプを使用してファイルをインジェストする際に使用する、別個のユーザーとロールを作成することをお勧めします。ユーザーは、このロールを既定のロールとして作成する必要があります。

キーペア認証の使用

Snowflakeは一般的なユーザー名/パスワード認証ではなく、キーペア認証の使用をサポートしています。この認証方法には、2048ビット(最小)の RSA キーペアが必要です。OpenSSLを使用して PEM (Privacy Enhanced Mail)公開/秘密キーペアを生成します。公開キーは、Snowpipeサービスを使用するSnowflakeユーザーに割り当てられます。

公開/秘密キーペアを構成するには、

  1. ターミナルウィンドウのコマンドラインから、秘密キーを生成します。

    秘密キーは、暗号化バージョンまたは非暗号化バージョンのいずれかを生成できます。

    非暗号化バージョンを生成するには、次のコマンドを使用します。

    $ openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt
    

    暗号化バージョンを生成するには、次の(「-nocrypt」を省略する)コマンドを使用します。

    $ openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8
    

    通常は、暗号化されたバージョンを生成する方が安全です。

    2番目のコマンドを使用して秘密キーを暗号化する場合、 OpenSSL は秘密キーファイルの暗号化に使用されるパスフレーズの入力を求めます。強力なパスフレーズを使用して秘密キーを保護することをお勧めします。このパスフレーズを安全な場所に記録します。Snowflakeに接続するときに入力します。パスフレーズは秘密キーの保護にのみ使用され、Snowflakeには送信されないことに注意してください。

    サンプル PEM 秘密キー

    -----BEGIN ENCRYPTED PRIVATE KEY-----
    MIIE6TAbBgkqhkiG9w0BBQMwDgQILYPyCppzOwECAggABIIEyLiGSpeeGSe3xHP1
    wHLjfCYycUPennlX2bd8yX8xOxGSGfvB+99+PmSlex0FmY9ov1J8H1H9Y3lMWXbL
    ...
    -----END ENCRYPTED PRIVATE KEY-----
    
  2. コマンドラインから、秘密キーを参照して公開キーを生成します:

    秘密キーが暗号化され、「rsa_key.p8」という名前のファイルに含まれていると仮定して、次のコマンドを使用します:

    $ openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub
    

    サンプル PEM 公開キー

    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAy+Fw2qv4Roud3l6tjPH4
    zxybHjmZ5rhtCz9jppCV8UTWvEXxa88IGRIHbJ/PwKW/mR8LXdfI7l/9vCMXX4mk
    ...
    -----END PUBLIC KEY-----
    
  3. 公開キーファイルと秘密キーファイルを保存用のローカルディレクトリにコピーします。ファイルへのパスを記録します。秘密キーは PKCS#8(公開キー暗号化標準)形式を使用して格納され、前の手順で指定したパスフレーズを使用して暗号化されることに注意してください。ただし、オペレーティングシステムが提供するファイル許可メカニズムを使用して、ファイルを不正アクセスから保護する必要があります。ファイルが使用されていない場合、ファイルを保護するのはユーザーの責任です。

  4. ALTER USER を使用して、Snowflakeユーザーに公開キーを割り当てます。例:

    ALTER USER jsmith SET RSA_PUBLIC_KEY='MIIBIjANBgkqh...';
    

    注釈

    • ユーザーを変更できるのは、セキュリティ管理者(つまり、 SECURITYADMIN ロールのユーザー)以上のみです。

    • SQL ステートメントで公開キーのヘッダーとフッターを除外します。

    DESCRIBE USER を使用してユーザーの公開キーの指紋を検証します:

    DESC USER jsmith;
    +-------------------------------+-----------------------------------------------------+---------+-------------------------------------------------------------------------------+
    | property                      | value                                               | default | description                                                                   |
    |-------------------------------+-----------------------------------------------------+---------+-------------------------------------------------------------------------------|
    | NAME                          | JSMITH                                              | null    | Name                                                                          |
    ...
    ...
    | RSA_PUBLIC_KEY_FP             | SHA256:nvnONUsfiuycCLMXIEWG4eTp4FjhVUZQUQbNpbSHXiA= | null    | Fingerprint of user's RSA public key.                                         |
    | RSA_PUBLIC_KEY_2_FP           | null                                                | null    | Fingerprint of user's second RSA public key.                                  |
    +-------------------------------+-----------------------------------------------------+---------+-------------------------------------------------------------------------------+
    

    注釈

    RSA_PUBLIC_KEY_2_FP プロパティについては、このトピックの キーローテーション で説明しています。

キーローテーション

Snowflakeは、複数のアクティブキーをサポートして、連続したローテーションを可能にします。内部的に従う有効期限のスケジュールに基づいて、公開キーと秘密キーをローテーションして交換します。

現在、 ALTER USERRSA_PUBLIC_KEY および RSA_PUBLIC_KEY_2 パラメーターを使用して、最大2個の公開キーを1人のユーザーに関連付けることができます。

キーをローテーションするには:

  1. キーペア認証の使用 の手順を完了して:

    • 新しい秘密キーと公開キーのセットを生成します。

    • ユーザーに公開キーを割り当てます。公開キーの値を RSA_PUBLIC_KEY または RSA_PUBLIC_KEY_2 (現在使用されていないキーの値)に設定します。例:

      alter user jsmith set rsa_public_key_2='JERUEHtcve...';
      
  2. Snowflakeに接続するようにコードを更新します。新しい秘密キーを指定します。

    Snowflakeは、接続情報とともに送信された秘密キーに基づいて、認証用の正しいアクティブな公開キーを検証します。

  3. ユーザープロファイルから古い公開キーを削除します。例:

    alter user jsmith unset rsa_public_key;
    

アクセス権限の付与

Snowpipeを使用するには、次の権限を持つロールが必要です。

オブジェクト

権限

注意

名前付きパイプ

OWNERSHIP

名前付きステージ

USAGE (外部ステージ)、 READ (内部ステージ)

名前付きファイル形式

USAGE

オプション。ステージ(ステップ1:ステージを作成する(必要な場合) を参照)またはパイプ(ステップ2:パイプを作成する を参照)の いずれか が、名前付きファイル形式を参照する場合にのみ必要です。

ターゲットデータベース

USAGE

ターゲットスキーマ

USAGE

ターゲットテーブル

INSERT , SELECT

GRANT <権限> ... TO ROLE コマンドを使用して、これらの権限をロールに付与します。

注釈

ロールを作成して権限を付与できるのは、セキュリティ管理者(つまり、 SECURITYADMIN ロールを持つユーザー)以上、またはアカウントの CREATE ROLE 権限とグローバル MANAGE GRANTS 権限の両方を持つ別のロールのみです。

たとえば、 mydb.myschema データベースオブジェクトのセットと mypipe という名前のパイプにアクセスできる、 snowpipe1 という名前のロールを作成します。ユーザーにロールを付与します。

 -- Create a role to contain the Snowpipe privileges
use role securityadmin;

create or replace role snowpipe1;

-- Grant the required privileges on the database objects
grant usage on database mydb to role snowpipe1;

grant usage on schema mydb.myschema to role snowpipe1;

grant insert, select on mydb.myschema.mytable to role snowpipe1;

grant usage, read on stage mydb.myschema.mystage to role snowpipe1;

-- Grant the OWNERSHIP privilege on the pipe object
grant ownership on pipe mydb.myschema.mypipe to role snowpipe1;

-- Grant the role to a user
grant role snowpipe1 to user jsmith;

-- Set the role as the default role for the user
alter user jsmith set default_role = snowpipe1;

次: Snowpipe REST エンドポイントの呼び出しによるデータのロード で、パブリック REST エンドポイントを呼び出してデータをロードし、ロード履歴レポートを取得する方法を学びます。