コンシューマーから参照およびオブジェクトレベル権限をリクエストする

このトピックでは、プロバイダーが、 APPLICATION オブジェクトの外部に存在するコンシューマーアカウントのオブジェクトへのアクセスをリクエストするために、 Snowflake Native App を構成する方法について説明します。

参照について

場合によっては、インストールされた Snowflake Native App は、 APPLICATION オブジェクトの外部に存在するコンシューマーカウントの既存のオブジェクトにアクセスする必要があります。たとえば、アプリがコンシューマーデータベースの既存のテーブルにアクセスする必要が生じる場合があります。

この場合、アプリがコンシューマーアカウントのスキーマ名とオブジェクト名を判断できないため、コンシューマーがオブジェクトに APPLICATION オブジェクトへのアクセス権を付与するだけでは不十分です。

Snowflake Native App が APPLICATION オブジェクトの外部にある既存のオブジェクトにアクセスできるようにするために、 Snowflake Native App Framework は、顧客がオブジェクトの名前とスキーマを指定し、オブジェクトへのアクセスを可能にする参照を提供します。

コンシューマーアカウント内の参照を定義するワークフロー

参照およびオブジェクトレベルの権限をリクエストするために、プロバイダーは Snowflake Native App の開発および公開時に以下を実行します。

  1. 参照が必要なオブジェクトとそれに対応する権限を決定 します。

  2. マニフェストファイルで参照を定義 します。

  3. マニフェストファイルで定義された各参照のコールバックを処理するために、セットアップスクリプトにストアドプロシージャを追加します。

Snowflake Native App のインストール後、コンシューマーは以下の操作を実行します。

  1. Snowflake Native App で必要な参照を表示します。

  2. SYSTEM$REFERENCE システム関数を呼び出して参照を作成します。

  3. 参照のIDを渡してコールバックのストアドプロシージャを実行します。

コンシューマーがコールバックストアドプロシージャを実行すると、 Snowflake Native App はリクエストされたオブジェクトにアクセスできるようになります。

このワークフローは、コンシューマーが手動で参照を作成するプロセスの概要を示しています。 Snowsight を使用してインターフェイスを作成し、コンシューマーが参照を作成して権限を付与する方法については、 権限および参照をリクエストするユーザーインターフェイスを作成する をご参照ください。

参照に含めることのできるオブジェクトの型および権限

以下のテーブルに、参照に含めることのできるオブジェクトの型と、各オブジェクトに許可される権限を示します。

オブジェクト型

許可される権限

TABLE

SELECT, INSERT, UPDATE, DELETE, TRUNCATE, REFERENCES

VIEW

SELECT, REFERENCES

EXTERNAL TABLE

SELECT, REFERENCES

FUNCTION

USAGE

PROCEDURE

USAGE

WAREHOUSE

MODIFY, MONITOR, USAGE, OPERATE

API INTEGRATION

USAGE

マニフェストファイルで参照を定義する

次の例は、 APPLICATION オブジェクトの外部に存在するコンシューマーアカウントのテーブル用に manifest.yml ファイルで参照を定義する方法を示しています。

references:
- consumer_table:
  label: "Consumer table"
  description: "A table in the consumer account that exists outside the APPLICATION object."
  privileges:
  - INSERT
  - SELECT
  object_type: TABLE
  multi_valued: false
  register_callback: config.register_single_reference
Copy

この例では、コンシューマーアカウントのテーブルで INSERT および SELECT 権限を必要とする consumer_table という名前の参照を定義しています。 register_callback プロパティは、コンシューマーテーブルをこの参照定義にバインドするために使用されるストアドプロシージャを指定します。

参照定義を削除する

注釈

Snowflakeは、アプリの新バージョンでマニフェストファイルから参照定義を削除しないことを推奨しています。定義された参照を削除する必要がある場合は、削除された参照を使用するコードを同じバージョンリリースで更新し、 README ファイルでコンシューマーに通知します。

アプリが参照を定義した後に、それ以降のバージョンのアプリから参照定義が削除された場合は、削除された参照をまだ使用している関数やプロシージャを呼び出すと、コンシューマーにはエラーが発生します。たとえば、アプリ my_app のバージョンV1のマニフェストファイルには、 REF_TO_TABLE の参照定義と、テーブル参照 REF_TO_TABLE を使用してビュー VIEW_SELECT_FROM_DEFINED_REF を作成するストアドプロシージャ CREATE_VIEW_FROM_TABLE が含まれます。

my_app のバージョンV2では、 REF_TO_TABLE の参照定義がマニフェストファイルから削除されています。コンシューマーが、インストールされているアプリ my_app をバージョンV2にアップグレードした場合、 CREATE_VIEW_FROM_TABLE プロシージャを呼び出すと以下のエラーが発生します。

Reference definition '<REF_DEF_NAME>' cannot be found in the current version of the application '<APP_NAME>'

参照のコールバックストアドプロシージャを作成する

manifest.yml ファイルで参照を定義した後、プロバイダーはセットアップスクリプトにストアドプロシージャを追加して、参照のコールバックを登録する必要があります。

次の例は、 マニフェストファイルで参照を定義する に表示される参照のコールバックを処理するために使用されるストアドプロシージャを示しています。

CREATE APPLICATION ROLE app_admin;

CREATE OR ALTER VERSIONED SCHEMA config;
GRANT USAGE ON SCHEMA config TO APPLICATION ROLE app_admin;

CREATE PROCEDURE CONFIG.REGISTER_SINGLE_REFERENCE(ref_name STRING, operation STRING, ref_or_alias STRING)
  RETURNS STRING
  LANGUAGE SQL
  AS $$
    BEGIN
      CASE (operation)
        WHEN 'ADD' THEN
          SELECT SYSTEM$SET_REFERENCE(:ref_name, :ref_or_alias);
        WHEN 'REMOVE' THEN
          SELECT SYSTEM$REMOVE_REFERENCE(:ref_name);
        WHEN 'CLEAR' THEN
          SELECT SYSTEM$REMOVE_REFERENCE(:ref_name);
      ELSE
        RETURN 'unknown operation: ' || operation;
      END CASE;
      RETURN NULL;
    END;
  $$;

GRANT USAGE ON PROCEDURE CONFIG.REGISTER_SINGLE_REFERENCE(STRING, STRING, STRING)
  TO APPLICATION ROLE app_admin;
Copy

この例では、ストアドプロシージャの引数として渡された参照に対して特定の操作を実行するシステム関数を呼び出す、 REGISTER_SINGLE_REFERENCE という名前のストアドプロシージャを作成します。

注釈

ストアドプロシージャは SYSTEM$SET_REFERENCE システム関数を使用するため、ストアドプロシージャは記述に単一の値を持つ参照に対してのみ機能します。参照を複数の値に関連付けるには、 SYSTEM$ADD_REFERENCE システム関数を使用します。

アプリケーションで定義された参照を表示する

プロバイダーが manifest.yml ファイルで参照を定義すると、それらはインストールされた Snowflake Native App の一部として含まれます。

Snowflake Native App 用に定義された参照を表示するには、次の例に示すように SHOW REFERENCES コマンドを実行します。

SHOW REFERENCES IN APPLICATION hello_snowflake_app;
Copy

アプリケーションにオブジェクトをバインドする

Snowflake Native App の参照定義を表示した後、コンシューマーは、次の例に示すように SYSTEM$REFERENCE システム関数を実行して、参照を作成します。

SELECT SYSTEM$REFERENCE('table', 'db1.schema1.table1', 'persistent', 'select', 'insert');
Copy

このコマンドは参照の識別子を返します。コンシューマーは、以下の例に示すように、参照用の識別子をコールバックストアドプロシージャに渡すことができます。

CALL app.config.register_single_reference(
  'consumer_table' , 'ADD', SYSTEM$REFERENCE('TABLE', 'db1.schema1.table1', 'PERSISTENT', 'SELECT', 'INSERT'));
Copy

この例では、 consumer_tablemanifest.yml ファイルで定義されている参照の名前です。コンシューマーが参照に関連付けられたストアドプロシージャを実行すると、 Snowflake Native App はコンシューマーカウントのテーブルにアクセスできるようになります。

前のセクション のコールバックストアドプロシージャは、次の例に示すように SYSTEM$SET_REFERENCE システム関数を呼び出します。

SELECT SYSTEM$SET_REFERENCE(:ref_name, :ref_or_alias);
Copy

参照に関連するその他のシステム関数については、 サポートされている参照関数 をご参照ください。

参照を使用する際の考慮事項

Snowflakeは、バージョン間で参照定義を変更しないことをお勧めします。新しいバージョンで参照定義を更新する、たとえば、権限を SELECT から INSERT に変更するには、新しい参照定義を異なる名前で定義する必要があります。更新された Snowflake Native App は、この新しい参照を新しいバージョンのアプリで使用できます。

参照を別のオブジェクトに埋め込むには、たとえば参照を変数に代入するには、その参照がすでにコンシューマーカウントのオブジェクトにバインドされている必要があります。たとえば、最初にコンシューマーウェアハウスへの参照をバインドしない限り、タスクを作成することはできません。

名前付きステージのファイルを使用して開発モードで作成された APPLICATION オブジェクトでは、参照は機能しません。参照は、リストからインストールされたバージョンのある APPLICATION オブジェクト内、または異なるアカウントの Snowflake Native App 内のみで機能します。

Snowflake Native App 内で参照を使用する例

次のセクションでは、異なるコンテキストで参照を使用する例を示します。

注釈

以下の例の reference() 関数は、 APPLICATION オブジェクトのストアドプロシージャ内でのみ呼び出すことができます。

参照を使用してクエリを実行する

以下の例は、参照を使用したクエリの実行方法を示しています。

SELECT * FROM reference('consumer_table');
Copy
SELECT reference('encrypt_func')(t.c1) FROM consumer_table t;
Copy

参照を使用してストアドプロシージャを呼び出す

次の例は、参照を使用してストアドプロシージャを呼び出す方法を示しています。

CALL reference('consumer_proc')(11, 'hello world');
Copy

参照を使用して DML コマンドを実行する

以下の例では、参照を使用してテーブルのデータを変更する方法を示します。

INSERT INTO reference('data_export')(C1, C2)
  SELECT T.C1, T.C2 FROM reference('other_table')
Copy
COPY INTO reference('the_table') ...
Copy

参照を使用して DESCRIBE コマンドを実行する

次の例では、参照を使用して DESCRIBE 操作を実行する方法を示します。

DESCRIBE TABLE reference('the_table')
Copy

タスクで参照を使用する

CREATE TASK app_task
  WAREHOUSE = reference('consumer_warehouse')
  ...;

ALTER TASK app_task SET WAREHOUSE = reference('consumer_warehouse');
Copy

ビュー定義で参照を使用する

CREATE VIEW app_view
  AS SELECT reference('function')(T.C1) FROM reference('table') AS T;
Copy

関数本文で参照を使用する

CREATE FUNCTION app.func(x INT)
  RETURNS STRING
  AS $$ select reference('consumer_func')(x) $$;
Copy

外部関数で参照を使用する

CREATE EXTERNAL FUNCTION app.func(x INT)
  RETURNS STRING
  ...
  API_INTEGRATION = reference('app_integration');
Copy

ポリシーで参照を使用する

CREATE ROW ACCESS POLICY app_policy
  AS (sales_region varchar) RETURNS BOOLEAN ->
  'sales_executive_role' = reference('get_sales_team')
    or exists (
      select 1 from reference('sales_table')
        where sales_manager = reference('get_sales_team')()
        and region = sales_region
      );
Copy

サポートされている参照関数

Snowflake Native App Framework は、参照に関するさまざまな操作を実行するために、以下の関数をサポートしています。

システム関数

説明

set_reference

SYSTEM$SET_REFERENCE('<参照名>', '<参照文字列>')

  • 単一の参照のみをサポートします。同じ名前ですでに参照が作成されている場合、既存の参照は上書きされます。

  • 参照用にシステムが生成した一意のエイリアスを返します。

add_reference

SYSTEM$ADD_REFERENCE('<参照名>', '<参照文字列>')

  • 単一値および複数値の参照両方をサポートします。単一値の参照の場合、この関数は、 reference_name で指定されたのと同じ値を使用してすでに参照が作成されているとエラーを返します。

  • 参照用にシステムが生成した一意のエイリアスを返します。

remove_reference

SYSTEM$REMOVE_REFERENCE('<参照名>'[, '<エイリアス>'])

  • 単一値および複数値の参照両方をサポートします。複数値の参照を削除するには、<エイリアス>が必要です。

  • 複数値の参照との関連を削除します。

remove_all_references

SYSTEM$REMOVE_ALL_REFERENCES('<リファレンス名>')

  • 参照に対するすべての関連付けを削除します。

get_all_references

SYSTEM$GET_ALL_REFERENCES('<リファレンス名>')

  • 参照名に関連付けられたエンティティの、システムが生成したエイリアスの配列を返します。

    • 参照名がエンティティにバインドされていない場合は空のリスト

    • 複数値の参照の関連付けすべて

    • 単一値の参照に対する1または0の関連付け

    • 戻り値にコンシューマーのオブジェクト名を含まない

  • ループ内で複数値の参照の関連付けすべてを反復処理するために使用します。

get_referenced_object_id_hash

SYSTEM$GET_REFERENCED_OBJECT_ID_HASH('<参照名>'[, '<エイリアス>'])

  • 複数の参照のためにシステムが生成したエイリアスを取得します。

  • バインドされているオブジェクトのエンティティIDのハッシュを返します。これは、最初に参照が作成されたときに解決されたエンティティの識別子です。

  • Snowflake Native App にとってこの関数は、参照にバインドされているオブジェクトが変更されているかどうかを判断するのに便利です。 Snowflake Native App は値を保存し、現在の値と既知の値を比較することができます。