チュートリアル: Snowpark Container Servicesを使用してSnowflake Native Appを作成する¶

学習内容¶

このチュートリアルでは、次の方法を学習します。

• Snowflake Native App with Snowpark Container Services プロジェクトを初期化するには、 Snowflake CLI を使用します。

• アプリのDockerイメージを構築します。

• Snowflake Native App with Snowpark Container Services のアプリケーションパッケージと必要なアプリケーションファイルを作成します。

• コンテナ内でサービス関数を呼び出して、 Snowflake Native App with Snowpark Container Services をテストします。

前提条件¶

このチュートリアルを実行するには、次の前提条件を満たしている必要があります。

• Snowpark Container ServiceをサポートするSnowflakeアカウントへのアクセス。

• このチュートリアルで使用するロールを作成し、そのロールに必要な権限を付与するには、 ACCOUNTADMIN ロールを使用できる必要があります。

• ローカルマシンに Snowflake CLI バージョン 3.0.0 以上がインストールされている必要があります。

• ローカルマシンにDocker Desktopがインストールされている必要があります。

Snowflake CLI 接続を設定する¶

このチュートリアルで実行するコマンドは、アプリを開発しているアカウントにデフォルトで接続するように Snowflake CLI が構成されていることを前提としています。このアカウントがデフォルトで設定されていない場合は、 -c コマンドライン引数を使用して、別の名前付き接続を指定できます。次に例を示します。

snow sql -q "SELECT 1" -c connection_name

Copy

ウェアハウスとイメージリポジトリを作成する¶

必要なオブジェクトを作成するには、 Snowsight または Snowflake CLI のいずれかを使用して、次を実行します。

1. Snowsight の現在のコンテキストを tutorial_role ロールを使用するように設定するには、次のコマンドを実行します。

   USE ROLE tutorial_role;
   

   Copy

   Snowflake CLI を使用している場合は、代わりに --role tutorial_role を使用できます。

2. Snowflake Native App with Snowpark Container Services のウェアハウスを作成するには、次のコマンドを実行します。

   CREATE OR REPLACE WAREHOUSE tutorial_warehouse WITH
     WAREHOUSE_SIZE = 'X-SMALL'
     AUTO_SUSPEND = 180
     AUTO_RESUME = true
     INITIALLY_SUSPENDED = false;
   

   Copy

   Snowflake Native App では、 SQL コマンドとストアドプロシージャを実行するためにウェアハウスが必要です。

3. コンテナを保存するために使用するイメージリポジトリを作成するには、次のコマンドを実行します。

   CREATE DATABASE tutorial_image_database;
   CREATE SCHEMA tutorial_image_schema;
   CREATE IMAGE REPOSITORY tutorial_image_repo;
   

   Copy

このセクションでは、作成するアプリのクエリを実行するために使用されるウェアハウスと、コンテナイメージをホストするためのイメージリポジトリを作成しました。

次のセクションでは、コンテナのイメージを作成し、上で作成したイメージリポジトリにアップロードします。

プロジェクトディレクトリを作成する¶

アプリのソースコードはローカルファイルシステムに存在し、必要に応じてバージョン管理にチェックインできます。まず、 Snowflake CLI を使用してNative Appsプロジェクトをブートストラップします。次に、コンテナサービスのイメージをサブフォルダーに構築します。

1. ローカルファイルシステムで次のコマンドを実行して、 na-spcs-tutorial という名前のフォルダーを作成します。

   snow init --template app_basic na-spcs-tutorial
   

   Copy

   注釈

   後のサブセクションでは、このフォルダーに追加のファイルとサブフォルダーを追加し、このコマンドによって作成されたファイルを編集します。

   注釈

   snow init --help を実行して、 Snowflake Native App 開発環境をセットアップするための他のテンプレートを確認します。

2. na-spcs-tutorial フォルダー内に service というフォルダーを作成します。このフォルダーには、これから構築してSnowflakeに公開するコンテナベースのサービスのソースコードが含まれています。

3. チュートリアルに必要なDockerファイルを取得するには、 zipファイル をローカルファイルシステムにダウンロードします。

4. 内容を na-spcs-tutorial/service フォルダーに解凍します。このフォルダーには次のファイルが含まれている必要があります。

   • echo_service.py

   • Dockerfile

   • templates/basic_ui.html

   • echo_spec.yaml

5. ターミナルウィンドウを開き、このディレクトリに移動します。

Dockerイメージを構築し、コンテナにアップロードします。¶

Dockerイメージを構築してイメージリポジトリにアップロードするには、次を実行します。

1. 次のDocker CLI コマンドを実行します。コマンドには現在の作業ディレクトリ（.）を指定する必要があることに注意してください。

   docker build --rm --platform linux/amd64 -t my_echo_service_image:tutorial .
   

   Copy

   このコマンドは次を実行します。

   • ダウンロードしたzipファイルに含まれるDockerファイルを使用して、Dockerイメージを構築する

   • イメージの名前 my_echo_service_image

   • イメージに tutorial タグを適用します。

2. 前のセクションで作成したイメージリポジトリの URL を確認するには、次のコマンドを実行します。

   REPO_URL=$(snow spcs image-repository url tutorial_image_database.tutorial_image_schema.tutorial_image_repo --role tutorial_role)
   echo $REPO_URL
   

   Copy

   イメージリポジトリの URL が $REPO_URL 変数に取り込まれ、コンソールに表示されます。この値は次のステップで使用します。

3. イメージ URL を含むイメージのタグを作成するには、次のDocker CLI コマンドを実行します。

   docker tag <image_name> <image_url>/<image_name>
   

   Copy

   このコマンドには2つのパラメーターが必要です。

   • <image_name> イメージとタグの名前を指定します。

   • <image_url>/<image_name> イメージをアップロードするイメージリポジトリの URL と、リモートリポジトリに保存するイメージ名とタグを指定します。

   このチュートリアルでは、 $REPO_URL および my_echo_service_image:tutorial を使用します。

   docker tag my_echo_service_image:tutorial $REPO_URL/my_echo_service_image:tutorial
   

   Copy

4. Snowflakeレジストリで認証するには、次のSnowflake CLI コマンドを実行します。

   snow spcs image-registry login [-c connection_name]
   

   Copy

   このコマンドは、Snowflakeアカウント内のイメージリポジトリを使用するためにDocker CLI に必要な認証情報をロードします。デフォルトを使用しない場合は、接続名を指定する必要があります。

   すべてが成功した場合、 Login Succeeded というメッセージが表示されます。

5. Dockerイメージをイメージリポジトリにアップロードするには、次の docker push コマンドを実行します。

   docker push $REPO_URL/<image_name>
   

   Copy

   前のステップの <image_name> と同じ値を使用すると、このコマンドは次のようになります。

   docker push $REPO_URL/my_echo_service_image:tutorial
   

   Copy

6. 次のコマンドを実行して、イメージが正常にアップロードされたことを確認します。

   snow spcs image-repository list-images tutorial_image_database.tutorial_image_schema.tutorial_image_repo --role tutorial_role
   

   Copy

このセクションでは、echoサービスを含むDockerイメージを作成し、チュートリアルの前半で作成した tutorial_repository イメージリポジトリにプッシュしました。

次のセクションでは、このイメージを使用するアプリケーションパッケージを作成します。

アプリケーションパッケージのマニフェストファイルを作成する¶

アプリケーションパッケージに必要なマニフェストファイルを作成するには、次を実行します。

1. na-spcs-tutorial/app/manifest.yml を次のように変更します。

   manifest_version: 1
   
   artifacts:
      setup_script: setup_script.sql
      readme: README.md
      container_services:
         images:
         - /tutorial_image_database/tutorial_image_schema/tutorial_image_repo/my_echo_service_image:tutorial
   
   privileges:
   - BIND SERVICE ENDPOINT:
        description: "A service that can respond to requests from public endpoints."
   - CREATE COMPUTE POOL:
        description: "Permission to create compute pools for running services"
   

   Copy

   この例には、次が含まれています。

   • artifacts プロパティは、前のステップで作成したDockerイメージの場所や、 Snowsight に表示されるプロジェクト README など、コンテナ付きアプリに必要なリソースの場所を指定します。

   • privileges プロパティを使用すると、サービスはパブリックリクエストに応答できるだけでなく、独自のコンピューティングプールを作成することもできます。これらのプロパティは、チュートリアルの次のステップでサービスをインスタンス化するために必要です。

アプリケーションパッケージのセットアップスクリプトを作成する¶

アプリケーションパッケージに必要なセットアップスクリプトを作成するには、次を実行します。

1. na-spcs-tutorial/app/setup_script.sql ファイルを次のように変更します。

   CREATE APPLICATION ROLE IF NOT EXISTS app_user;
   
   CREATE SCHEMA IF NOT EXISTS core;
   GRANT USAGE ON SCHEMA core TO APPLICATION ROLE app_user;
   
   CREATE OR ALTER VERSIONED SCHEMA app_public;
   GRANT USAGE ON SCHEMA app_public TO APPLICATION ROLE app_user;
   
   CREATE OR REPLACE PROCEDURE app_public.start_app()
      RETURNS string
      LANGUAGE sql
      AS
   $$
   BEGIN
      -- account-level compute pool object prefixed with app name to prevent clashes
      LET pool_name := (SELECT CURRENT_DATABASE()) || '_compute_pool';
   
      CREATE COMPUTE POOL IF NOT EXISTS IDENTIFIER(:pool_name)
         MIN_NODES = 1
         MAX_NODES = 1
         INSTANCE_FAMILY = CPU_X64_XS
         AUTO_RESUME = true;
   
      CREATE SERVICE IF NOT EXISTS core.echo_service
         IN COMPUTE POOL identifier(:pool_name)
         FROM spec='service/echo_spec.yaml';
   
      CREATE OR REPLACE FUNCTION core.my_echo_udf (TEXT VARCHAR)
         RETURNS varchar
         SERVICE=core.echo_service
         ENDPOINT=echoendpoint
         AS '/echo';
   
      GRANT USAGE ON FUNCTION core.my_echo_udf (varchar) TO APPLICATION ROLE app_user;
   
      RETURN 'Service successfully created';
   END;
   $$;
   
   GRANT USAGE ON PROCEDURE app_public.start_app() TO APPLICATION ROLE app_user;
   
   CREATE OR REPLACE PROCEDURE app_public.service_status()
   RETURNS VARCHAR
   LANGUAGE SQL
   EXECUTE AS OWNER
   AS $$
      DECLARE
            service_status VARCHAR;
      BEGIN
            CALL SYSTEM$GET_SERVICE_STATUS('core.echo_service') INTO :service_status;
            RETURN PARSE_JSON(:service_status)[0]['status']::VARCHAR;
      END;
   $$;
   
   GRANT USAGE ON PROCEDURE app_public.service_status() TO APPLICATION ROLE app_user;
   

   Copy

アプリケーションパッケージのReadmeを作成します。¶

1. na-spcs-tutorial/app/README.md を次のように変更します。

   Welcome to your first app with containers!
   

   Copy

このReadmeファイルは、アプリをインストールしたコンシューマーに表示されます。

プロジェクト定義ファイルを作成する¶

このセクションでは、 Snowflake CLI で必要なプロジェクト定義ファイルを作成します。

1. na-spcs-tutorial/snowflake.yml を次のように変更します。

   definition_version: 2
   entities:
      na_spcs_tutorial_pkg:
         type: application package
         manifest: app/manifest.yml
         artifacts:
            - src: app/*
              dest: ./
            - service/echo_spec.yaml
         meta:
            role: tutorial_role
            warehouse: tutorial_warehouse
      na_spcs_tutorial_app:
         type: application
         from:
            target: na_spcs_tutorial_pkg
         debug: false
         meta:
            role: tutorial_role
            warehouse: tutorial_warehouse
   

   Copy

このセクションでは、 Snowflake Native App with Snowpark Container Services としてSnowflakeアカウントにデプロイできるローカルファイル構造を定義しました。次のセクションでは、 Snowflake CLI を使用してこのデプロイを実行します。

アプリケーションをデプロイする¶

ステージ開発モードでアプリケーションをデプロイするには、次を実行します。

1. na-spcs-tutorial フォルダー内で次のコマンドを実行し、アカウントにアプリケーションパッケージとオブジェクトを作成します。

   snow app run [-c connection_name]
   

   Copy

   このコマンドは、 na_spcs_tutorial_pkg というアプリケーションパッケージと、 na_spcs_tutorial_app というアプリケーションオブジェクトがアカウントに作成されたことの確認を表示します。これらの名前は、前のセクションで作成した snowflake.yml プロジェクト定義の名前に対応しています。

コンソールへの URL 出力を使用してアプリケーションを表示できます。ただし、最初にコンテナベースのサービスを作成するために必要なすべての権限があることを確認する必要があります。

これは次のセクションで実行します。

権限を付与し、アプリをテストする¶

このセクションでは、アプリに必要な権限を付与し、コンテナ内のサービスを呼び出してアプリをテストします。

Snowsight または Snowflake CLI のいずれかを使用して SQL コマンドを実行できます。

権限を付与してアプリをテストするには、次のステップを実行します。

注釈

Snowflake CLI で実行するには、次の構文を試してください。

snow sql -q "<sql>" --role tutorial_role --warehouse tutorial_warehouse

Copy

これまでのステップと同様に、 -c connection_name を追加して、デフォルト以外の接続を選択できます。

1. 次を実行して、アプリに CREATE COMPUTE POOL 権限を付与します。

   grant create compute pool on account to application na_spcs_tutorial_app;
   grant bind service endpoint on account to application na_spcs_tutorial_app;
   

   Copy

2. setup_script.sql ファイルで定義した app_public.start_app プロシージャを実行します。

   CALL na_spcs_tutorial_app.app_public.start_app();
   

   Copy

   このプロシージャでは、コンピューティングプールを作成し、サービスをインスタンス化して、サービス関数を作成します。

3. 次を実行して、関数が作成されたことを確認します。

   SHOW FUNCTIONS LIKE '%my_echo_udf%' IN APPLICATION na_spcs_tutorial_app;
   

   Copy

   注釈

   実行中のサービスは Snowflake Native App の一部として実行されるため、コンシューマーは見ることができません。たとえば、 SHOW SERVICES IN APPLICATION na_spcs_tutorial_app; を実行しても何も返されません。

4. サービスが作成され、正常であることを確認するには、次のコマンドを実行します。

   CALL na_spcs_tutorial_app.app_public.service_status();
   

   Copy

   このコマンドは、セットアップスクリプトで定義した app_public.service_status プロシージャを呼び出します。

   このプロシージャが READY を返したら、次のステップに進みます。

5. サービス関数を呼び出してサービスにリクエストを送信し、応答を確認するには、次のコマンドを実行します。

   SELECT na_spcs_tutorial_app.core.my_echo_udf('hello');
   

   Copy

   前のセクションでアップロードしたサービスからのメッセージ（Bob said hello）が表示されます。