Snowflake を利用する場合のチュートリアル ####################################### このチュートリアルでは、2事業者分のSnowflake Native Appを使用してDataCleanRoomを実行する手順を説明します。 事前要件 *********************** - 以下の2つの名前でNative Appをインストールしておくこと - AUTOPRIVACY_NATIVE_APP1 - AUTOPRIVACY_NATIVE_APP2 .. note:: Native Appのインストール方法については、:doc:`../user-guide/cloud-execution/snowflake/snowflake-installation` を参照してください。 - Snowflakeアカウントへのアクセス権限があること - Snowsightへのアクセス権限があること 概要 *********************** このチュートリアルでは、以下の手順でDataCleanRoomを実行します： 1. チュートリアルに使用するロールの作成 2. functionをuploadする 3. チュートリアルで使用するdatabase、schema、table、stageを作成する 4. Native Appを起動する 5. 権限の付与、外部アクセス統合の作成をする 6. ComputepoolとWarehouseを作成する 7. プロファイルを作成する 8. encrypted_fileを作成する 9. 暗号化ファイルのアップロード 10. cleanroomの設定を行い、実行する 各ステップの詳細 *********************** 1. チュートリアルに使用するロールの作成 ======================================================================= .. note:: 本ステップはACCOUNTADMIN権限を持つユーザが実行してください。 1. Snowflakeのコンソールを開き、SQLワークシートを開きます。 2. 以下のSQLを実行し、チュートリアルに使用するロールを作成します。 .. code-block:: sql CREATE ROLE autoprivacy_tutorial_role; 3. 以下のSQLを実行し、チュートリアルロールをユーザに付与します。 ``USER_NAME`` には、チュートリアルに使用するユーザの名前を指定してください。 .. code-block:: sql GRANT ROLE autoprivacy_tutorial_role TO USER ; 4. 以下のSQLを実行し、作成したロールに権限を付与します。 .. code-block:: sql GRANT CREATE DATABASE ON ACCOUNT TO ROLE autoprivacy_tutorial_role; GRANT CREATE INTEGRATION ON ACCOUNT TO ROLE autoprivacy_tutorial_role; GRANT CREATE WAREHOUSE ON ACCOUNT TO ROLE autoprivacy_tutorial_role WITH GRANT OPTION; GRANT CREATE COMPUTE POOL ON ACCOUNT TO ROLE autoprivacy_tutorial_role WITH GRANT OPTION; .. note:: 以降のステップは、``autoprivacy_tutorial_role`` ロールを使用して実行してください。 1. SQLワークシートで ``autoprivacy_tutorial_role`` ロールを使用する場合 以下のSQLを実行することで、SQLワークシートで ``autoprivacy_tutorial_role`` ロールを使用できます。 .. code-block:: sql USE ROLE autoprivacy_tutorial_role; 2. Snowflake Consoleで ``autoprivacy_tutorial_role`` ロールを使用する場合 左下のアイコンマークをクリックし、Switch Roleから ``autoprivacy_tutorial_role`` を選択することで、ロールを切り替えることができます。 ``Set as default`` をクリックすることで、ロールをデフォルトロールに設定することができます。 .. image:: ./images/switch_role.png :alt: ロール切り替え画面 :width: 100% :align: center 2. functionをuploadする ======================================================================= function をアップロードしてfunction_idを取得します。 本チュートリアルでは、以下のfunctionを用います。 https://github.com/acompany-develop/dcr-docs-examples/tree/main/functions/join .. note:: :doc:`../../apc-cli/notebooks/tutorial/basic_apc_cli_tutorial` のチュートリアルを行うなどしてすでにfunction_idを取得している場合は、本ステップをスキップしてください。 以下に、大まかな手順を示します。 APC-CLIの各コマンドの具体的な実行方法については、:doc:`../../apc-cli/notebooks/tutorial/basic_apc_cli_tutorial` のチュートリアルを参照してください。 1. APC-CLIのセットアップ 1. APC-CLIをインストール インストール方法については、:doc:`../../apc-cli/getting-started/installation` を参照ください。 2. プロファイルの作成 configureコマンドを用いてプロファイルを作成します。 configureコマンドの詳細については、:doc:`../../apc-cli/commands/configure` を参照ください。 3. 作成したプロファイルを用いて認証 auth-loginコマンドを用いて認証を行います。 auth-loginコマンドの詳細については、:doc:`../../apc-cli/commands/auth-login` を参照ください。 4. プロジェクト設定 set-projectコマンドを用いてプロジェクトを設定します。 set-projectコマンドの詳細については、:doc:`../../apc-cli/commands/set-project` を参照ください。 2. join functionのアップロード準備 以下のコマンドを実行し、join functionをダウンロードし、必要なライブラリをインストールします。 .. code-block:: bash git clone https://github.com/acompany-develop/dcr-docs-examples.git pip install --platform manylinux2014_x86_64 \ --only-binary=:all: \ --python-version 3.10 \ --target=dcr-docs-examples/functions/join/function/packages \ -r dcr-docs-examples/functions/join/requirements.txt 3. functionをアップロード function-storage uploadコマンドを用いて ``dcr-docs-examples/functions/join/function`` ディレクトリをアップロードします。 function-storage uploadコマンドの詳細については、:doc:`../../apc-cli/commands/function-storage` を参照ください。 3. チュートリアルで使用するdatabase、schema、table、stageを作成する ======================================================================= チュートリアルで使用するリソースを作成します。 また、これらのリソースへの権限をNative Appに付与します。 1. Snowflakeのコンソールを開き、SQLワークシートを開きます。 2. 以下のSQLを実行します。 .. code-block:: sql -- Databaseの作成 CREATE DATABASE IF NOT EXISTS AUTOPRIVACY_TUTORIAL_DB1; CREATE DATABASE IF NOT EXISTS AUTOPRIVACY_TUTORIAL_DB2; -- Schemaの作成 CREATE SCHEMA IF NOT EXISTS AUTOPRIVACY_TUTORIAL_DB1.TUTORIAL_SCHEMA1; CREATE SCHEMA IF NOT EXISTS AUTOPRIVACY_TUTORIAL_DB2.TUTORIAL_SCHEMA2; -- サンプルテーブルが存在していたら削除 DROP TABLE IF EXISTS AUTOPRIVACY_TUTORIAL_DB1.TUTORIAL_SCHEMA1.INPUT_TABLE1; DROP TABLE IF EXISTS AUTOPRIVACY_TUTORIAL_DB2.TUTORIAL_SCHEMA2.INPUT_TABLE2; -- サンプルテーブルの作成 CREATE TABLE IF NOT EXISTS AUTOPRIVACY_TUTORIAL_DB1.TUTORIAL_SCHEMA1.INPUT_TABLE1 ( id INTEGER, name STRING, age INTEGER, income INTEGER ); CREATE TABLE IF NOT EXISTS AUTOPRIVACY_TUTORIAL_DB2.TUTORIAL_SCHEMA2.INPUT_TABLE2 ( id INTEGER, occupation STRING, education STRING ); -- サンプルデータの挿入 INSERT INTO AUTOPRIVACY_TUTORIAL_DB1.TUTORIAL_SCHEMA1.INPUT_TABLE1 VALUES (1,'Alice',25,50000), (2,'Bob',30,75000), (3,'Charlie',35,100000), (4,'Dave',40,120000), (5,'Eve',45,150000), (6,'Frank',50,180000), (7,'Grace',55,200000), (8,'Heidi',60,250000), (9,'Ivan',65,300000), (10,'Jane',70,350000); INSERT INTO AUTOPRIVACY_TUTORIAL_DB2.TUTORIAL_SCHEMA2.INPUT_TABLE2 VALUES (1,'Engineer','Bachelor'), (2,'Doctor','Master'), (3,'Lawyer','Doctorate'), (4,'Teacher','Bachelor'), (5,'Artist','Master'), (6,'Manager','Master'), (7,'Consultant','Doctorate'), (8,'Designer','Bachelor'), (9,'Architect','Master'), (10,'Professor','Doctorate'); -- Stageの作成 CREATE STAGE IF NOT EXISTS AUTOPRIVACY_TUTORIAL_DB1.TUTORIAL_SCHEMA1.TUTORIAL_STAGE1 DIRECTORY = (ENABLE = TRUE); CREATE STAGE IF NOT EXISTS AUTOPRIVACY_TUTORIAL_DB2.TUTORIAL_SCHEMA2.TUTORIAL_STAGE2 DIRECTORY = (ENABLE = TRUE); -- 権限の付与 GRANT USAGE ON DATABASE AUTOPRIVACY_TUTORIAL_DB1 TO APPLICATION AUTOPRIVACY_NATIVE_APP1; GRANT USAGE ON SCHEMA AUTOPRIVACY_TUTORIAL_DB1.TUTORIAL_SCHEMA1 TO APPLICATION AUTOPRIVACY_NATIVE_APP1; GRANT SELECT ON TABLE AUTOPRIVACY_TUTORIAL_DB1.TUTORIAL_SCHEMA1.INPUT_TABLE1 TO APPLICATION AUTOPRIVACY_NATIVE_APP1; GRANT READ, WRITE ON STAGE AUTOPRIVACY_TUTORIAL_DB1.TUTORIAL_SCHEMA1.TUTORIAL_STAGE1 TO APPLICATION AUTOPRIVACY_NATIVE_APP1; GRANT USAGE ON DATABASE AUTOPRIVACY_TUTORIAL_DB2 TO APPLICATION AUTOPRIVACY_NATIVE_APP2; GRANT USAGE ON SCHEMA AUTOPRIVACY_TUTORIAL_DB2.TUTORIAL_SCHEMA2 TO APPLICATION AUTOPRIVACY_NATIVE_APP2; GRANT SELECT ON TABLE AUTOPRIVACY_TUTORIAL_DB2.TUTORIAL_SCHEMA2.INPUT_TABLE2 TO APPLICATION AUTOPRIVACY_NATIVE_APP2; GRANT READ, WRITE ON STAGE AUTOPRIVACY_TUTORIAL_DB2.TUTORIAL_SCHEMA2.TUTORIAL_STAGE2 TO APPLICATION AUTOPRIVACY_NATIVE_APP2; .. note:: 以降のステップでは、ブラウザを複数開いて同時に行うことを推奨します。 4. Native Appを起動する ======================================================================= SnowsightでData Productを選択し、Appsをクリックします。 Installed Appsの中から ``AUTOPRIVACY_NATIVE_APP1`` と ``AUTOPRIVACY_NATIVE_APP2`` をクリックして、それぞれのNative Appを起動します。 .. image:: ./images/native_app_lists.png :alt: アプリケーション一覧画面 :width: 100% :align: center 5. 権限の付与、外部アクセス統合の作成をする ======================================================================= Native Appを起動すると初回に以下のような権限付与画面が表示されます。 **Grant** をクリックして権限を付与します。 .. image:: ./images/native_app_grant_permission.png :alt: 権限付与画面 :width: 100% :align: center 権限を付与すると以下の画面が表示されるため、**Activate** をクリックしてNative Appを有効化します。 .. image:: ./images/native_app_granted_permission.png :alt: 権限付与完了画面 :width: 100% :align: center Native Appの有効化が完了すると、Native Appのコンソール画面が表示されるため、**Launch App** をクリックしてStreamlitを起動します。 Streamlitを起動すると、左上に外部アクセス統合を作成する案内が表示されます。 **Connect** をクリックして外部アクセス統合を作成します。 .. note:: **外部アクセス統合** とは、SnowflakeからSnowflake外のサーバにリクエストを行うための機能です。この機能を使用することで、SnowflakeからDCRサーバにリクエストを行うことができます。 .. image:: ./images/external_access_integration_connect.png :alt: アプリケーション起動画面 :width: 100% :align: center 6. ComputepoolとWarehouseを作成する ======================================================================= Streamlitの初期設定ページで、APC-CLIを実行するためのリソースを作成します。 .. image:: ./images/initialize_create_resource.png :alt: 初期設定画面 :width: 100% :align: center - **Compute Poolの作成** 1. pool_sizeを選択します（推奨: ``CPU_X64_XS``） 2. **Compute Pool作成** をクリックします - **Warehouseの作成** 1. warehouse_sizeを選択します（推奨: ``XSMALL``） 2. **Warehouse作成** をクリックします 7. プロファイルを作成する ======================================================================= プロファイル設定ページで、APC-CLIのプロファイルを作成します。 .. image:: ./images/profile_create.png :alt: プロファイル設定画面 :width: 100% :align: center 1. **New profile_name** に新たに作成するプロファイラの名前を入力します。 - AUTOPRIVACY_NATIVE_APP1の場合: ``profile1`` - AUTOPRIVACY_NATIVE_APP2の場合: ``profile2`` .. note:: チュートリアルのため、profile_nameを固定していますが、実際の利用時には任意の名前を指定できます。 2. サービス提供者から提供されるTOMLファイルをアップロードします。 - AUTOPRIVACY_NATIVE_APP1の場合: ``config1.toml`` - AUTOPRIVACY_NATIVE_APP2の場合: ``config2.toml`` 3. プレビュー画面を確認し、問題なければ **プロファイルの作成開始** をクリックします。 .. image:: ./images/profile_start.png :alt: プロファイルプレビュー画面 :width: 100% :align: center .. note:: **プロファイル作成中...** と表示されているトグルをクリックすることで、ジョブのステータスとログを確認できます。 .. image:: ./images/profile_running.png :alt: プロファイル作成中画面 :width: 100% :align: center 4. **プロファイル作成完了** と表示されたら、ログに表示されるUSER IDをメモしておきます。USER IDは後続のステップで使用します。 .. image:: ./images/profile_complete.png :alt: プロファイル作成完了画面 :width: 100% :align: center 8. 暗号化ファイルの作成 ======================================================================= DataCleanRoomで使用する暗号化ファイルを作成します。詳細は、:doc:`../user-guide/user-files/definition-files` から参照できます。 任意のエディタを用いて以下のファイルをencrypted_file.yamlとして作成します。 ただし、```` と ```` をステップ5で出力されたprofile1とprofile2のUser IDに置き換えてください。 .. code-block:: yaml inputs: input_1: &user_a_id input_2: &user_b_id outputs: output_1: *user_a_id output_2: *user_b_id 9. cleanroomの設定を行い、実行する ======================================================================= DataCleanRoom実行ページで、パラメータを設定して実行します。 1. CleanRoomの設定を行います： .. image:: ./images/cleanroom_config.png :alt: CleanRoom設定画面 :width: 100% :align: center - profile_name: ステップ5で作成したプロファイル名を選択 - AUTOPRIVACY_NATIVE_APP1の場合: ``profile1`` - AUTOPRIVACY_NATIVE_APP2の場合: ``profile2`` - project_id: サービス提供者から提供されるproject_idを入力 - cleanroom_name: ``join_app`` - function_id: 分析に使用するfunction_idを入力 - runtime: ``python3.10`` - handler: ``handler.run`` - memory: ``2`` 2. encrypted_filesをアップロードします。 ステップ8で作成したencrypted_file.yamlをアップロードします。 .. image:: ./images/cleanroom_data_encrypted_files.png :alt: encrypted_filesのアップロード :width: 100% :align: center 3. チュートリアルで使用するデータの入出力を設定します。 .. image:: ./images/cleanroom_data_inout.png :alt: DataCleanRoom実行画面 :width: 100% :align: center - input_pathの **TABLEから選択** をクリックし、input_pathを選択します。 .. image:: ./images/cleanroom_data_input.png :alt: データ入力設定 :width: 100% :align: center - AUTOPRIVACY_NATIVE_APP1の場合: - database: ``AUTOPRIVACY_TUTORIAL_DB1`` - schema: ``TUTORIAL_SCHEMA1`` - table: ``INPUT_TABLE1`` - csv_name: ``input_1.csv`` - AUTOPRIVACY_NATIVE_APP2の場合: - database: ``AUTOPRIVACY_TUTORIAL_DB2`` - schema: ``TUTORIAL_SCHEMA2`` - table: ``INPUT_TABLE2`` - csv_name: ``input_2.csv`` .. note:: 選択したTABLEのデータは、`csv_name` で指定したcsvファイル名でDCRサーバに送信されます。 - output_pathの **ディレクトリを選択** をクリックし、output_pathを選択します。 .. image:: ./images/cleanroom_data_output.png :alt: データ出力設定 :width: 100% :align: center - AUTOPRIVACY_NATIVE_APP1の場合: - database: ``AUTOPRIVACY_TUTORIAL_DB1`` - schema: ``TUTORIAL_SCHEMA1`` - stage: ``TUTORIAL_STAGE1`` - file_path: ``output`` - AUTOPRIVACY_NATIVE_APP2の場合: - database: ``AUTOPRIVACY_TUTORIAL_DB2`` - schema: ``TUTORIAL_SCHEMA2`` - stage: ``TUTORIAL_STAGE2`` - file_path: ``output`` 4. **CleanRoom実行開始** をクリックして実行を開始します .. image:: ./images/cleanroom_start.png :alt: CleanRoom実行開始画面 :width: 100% :align: center .. note:: **Cleanroom実行中...** と表示されているトグルをクリックすることで、ジョブのステータスとログを確認できます。 .. image:: ./images/cleanroom_running.png :alt: CleanRoom実行中画面 :width: 100% :align: center 5. **CleanRoom実行完了** と表示されたらチュートリアルは完了です。 .. image:: ./images/cleanroom_complete.png :alt: CleanRoom実行完了画面 :width: 100% :align: center 実行結果の確認 *********************** 出力結果に出力されたリンクをクリックすることで実行結果を確認いただけます。 ファイルの確認方法についてはSnowflake公式ドキュメント `ステージングされたファイルの表示 `_ を参照してください。