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 インストーラーをダウンロードします。

    Sonatype (またはhttps://repo1.maven.org/maven2/net/snowflake/snowflake-ingest-sdk)

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

注釈

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

Python SDK のインストール

Python SDK にはPython 3.6またはそれ以上が必要です。

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

pip install snowflake-ingest
Copy

または、 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;
Copy

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

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

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

注釈

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

キーペア認証の使用およびキーローテーション

Snowpipe REST エンドポイントには、キーペアの認証と JSON Webトークン(JWT)が必要です。JWTs では、RSA 暗号化を使用した公開/秘密キーペアを使用して署名されます。

このプロセスの一環として、次を実行する必要があります。

  1. 公開キーと秘密キーのペアを生成します。生成された秘密キーはファイル内にある必要があります(例: rsa_key.p8 という名前)。

  2. 公開キーをSnowflakeユーザーに割り当てます。ユーザーにキーを割り当てたら、 DESCRIBE USER コマンドを実行します。出力では、 RSA_PUBLIC_KEY_FP プロパティは、ユーザーに割り当てられた公開キーのフィンガープリントに設定する必要があります。

キーペアを生成してユーザーにキーを割り当てる方法については、 キーペア認証とキーペアローテーション をご参照ください。

フィンガープリントを作成して JWT トークンを生成する言語固有の例については、以下のセクションをご参照ください。

アクセス権限の付与

Snowpipe REST エンドポイントを呼び出すには、次の 最低限 の権限を持つロールが必要です。

オブジェクト

権限

メモ

名前付きパイプ

OPERATE (insertFiles エンドポイント)、 MONITOR (insertReportloadHistoryScan エンドポイント)

名前付きステージ

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

名前付きファイル形式

USAGE

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

ターゲットデータベース

USAGE

ターゲットスキーマ

USAGE

ターゲットテーブル

INSERT , SELECT

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

注釈

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

たとえば、 mypipe という名前のパイプを介してデータをロードできる、 snowpipe1 という名前のロールを作成します。パイプは外部ステージを参照します。

 -- Create a role for the Snowpipe privileges.
use role securityadmin;

create or replace role snowpipe1;

-- Grant the USAGE privilege on the database and schema that contain the pipe object.
grant usage on database mydb to role snowpipe1;
grant usage on schema mydb.myschema to role snowpipe1;

-- Grant the INSERT and SELECT privileges on the target table.
grant insert, select on mydb.myschema.mytable to role snowpipe1;

-- Grant the USAGE privilege on the external stage.
grant usage on stage mydb.myschema.mystage to role snowpipe1;

-- Grant the OPERATE and MONITOR privileges on the pipe object.
grant operate, monitor 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;
Copy

ステップ4: データファイルをステージする

Snowpipeを使用してファイルをロードするために作成した内部ステージまたは外部ステージにデータファイルをコピーします。

  • クラウドストレージサービスが提供するツールを使用して、ファイルを外部ステージにコピーします。

  • PUT コマンドを使用して、ファイルを内部ステージにコピーします。

    注釈

    SnowflakeアカウントがAmazon Web Servicesでホストされている場合は、常に PUT ... OVERWRITE = TRUE 構文を使用することをお勧めします。

    Amazon S3は、バケットで作成された新しいオブジェクトに書き込み後の読み取りの一貫性を提供します。ただし、オブジェクトが作成される前に HEAD または GET リクエストが行われた場合、S3はオブジェクトに 結果整合性 を提供します。これは、新しいオブジェクトが作成された直後のリクエストは file not found 例外が返される可能性があることを意味します。OVERWRITE = TRUE パラメータを設定すると、S3バケットにオブジェクトを作成する前に HEAD リクエストが開始されるのを回避できます。

    S3整合性モデルの詳細については、 S3のドキュメント をご参照ください。

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