コンシューマーへの参照およびオブジェクトレベル権限のリクエスト¶
このトピックでは、プロバイダーがコンシューマーアカウント内にある既存のデータベースオブジェクトへのアクセスをリクエストする方法について説明します。
参照について¶
場合によっては、インストールされた Snowflake Native App は、 APPLICATION オブジェクトの外部に存在するコンシューマーカウントの既存のオブジェクトにアクセスする必要があります。たとえば、 Snowflake Native App がコンシューマーデータベースの既存のテーブルにアクセスする必要が生じる場合があります。
この場合、コンシューマーが Snowflake Native App にオブジェクトに対するアクセス権を付与するだけでは不十分です。 Snowflake Native App は、コンシューマーカウントに存在するスキーマとオブジェクトの名前を判断できません。追加情報については、 オブジェクト名の解決 をご参照ください。
Snowflake Native App がこの種のオブジェクトに接続できるように、 Snowflake Native App Framework は、顧客がオブジェクトの名前を指定し、必要な権限を付与できる参照を提供します。
コンシューマーアカウント内の参照を定義するワークフロー¶
参照およびオブジェクトレベルの権限をリクエストするために、プロバイダーは Snowflake Native App の開発および公開時に以下を実行します。
マニフェストファイルで参照を定義 します。
マニフェストファイルで定義された各参照のコールバックを処理するために、セットアップスクリプトにストアドプロシージャを追加します。
Snowflake Native App のインストール後、コンシューマーは以下の操作を実行します。
Snowflake Native App で必要な参照を表示します。
SYSTEM$REFERENCE システム関数を呼び出して参照を作成します。
参照の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:
- my_table:
label: "My table"
description: "A table that exists outside the Snowflake Native App"
privileges:
- SELECT
object_type: TABLE
multi_valued: false
register_callback: config.register_reference
この例では、テーブルに対する SELECT 権限を必要とする my_table
という名前の参照を定義しています。 register_callback
プロパティは、オブジェクトを Snowflake Native App にバインドするためのストアドプロシージャを指定します。
参照のコールバックストアドプロシージャの作成¶
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_CALLBACK(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_CALLBACK(STRING, STRING, STRING)
TO APPLICATION ROLE app_admin;
この例では、ストアドプロシージャの引数として渡された参照に対して特定の操作を実行するシステム関数を呼び出す、 REGISTER_SINGLE_CALLBACK
という名前のストアドプロシージャを作成します。
アプリケーションで定義された参照の表示¶
プロバイダーが manifest.yml
ファイルで参照を定義すると、それらはインストールされた Snowflake Native App の一部として含まれます。
Snowflake Native App 用に定義された参照を表示するには、次の例に示すように SHOW REFERENCES コマンドを実行します。
SHOW REFERENCES IN APPLICATION hello_snowflake_app;
アプリケーションへのオブジェクトのバインド¶
Snowflake Native App の参照定義を表示した後、コンシューマーは、次の例に示すように SYSTEM$REFERENCE システム関数を実行して、参照の識別子を決定します。
SELECT SYSTEM$REFERENCE('table', 'db1.schema1.tab1', 'persistent', 'select', 'insert');
このコマンドは参照の識別子を返します。コンシューマーは、以下の例に示すように、参照用の識別子をコールバックストアドプロシージャに渡すことができます。
CALL app.config.register_single_callback(
SYSTEM$REFERENCE('TABLE', 'db1.schema1.tab1', 'PERSISTENT', 'SELECT', 'INSERT'), 'ADD', null);
コンシューマーがコールバックストアドプロシージャを実行すると、 Snowflake Native App はコンシューマーカウントのテーブルにアクセスできるようになります。
前のセクション のコールバックストアドプロシージャは、次の例に示すように SYSTEM$SET_REFERENCE システム関数を呼び出します。
SELECT SYSTEM$SET_REFERENCE(:ref_name, :ref_or_alias);
参照に関連するその他のシステム関数については、 サポートされている参照関数 をご参照ください。
参照を使用する際の考慮事項¶
Snowflakeは、バージョン間で参照定義を変更しないことをお勧めします。新しいバージョンで参照定義を更新する、たとえば、権限を SELECT から INSERT に変更するには、新しい参照定義を異なる名前で定義する必要があります。更新された Snowflake Native App は、この新しい参照を新しいバージョンのアプリで使用できます。
参照を別のオブジェクトに埋め込むには、たとえば参照を変数に代入するには、その参照がすでにコンシューマーカウントのオブジェクトにバインドされている必要があります。たとえば、最初にコンシューマーウェアハウスへの参照をバインドしない限り、タスクを作成することはできません。
名前付きステージのファイルを使用して開発モードで作成された APPLICATION オブジェクトでは、参照は機能しません。参照は、リストからインストールされたバージョンのある APPLICATION オブジェクト内、または異なるアカウントの Snowflake Native App 内のみで機能します。
Snowflake Native App 内で参照を使用する例¶
次のセクションでは、異なるコンテキストで参照を使用する例を示します。
参照を使用したクエリの実行¶
以下の例は、参照を使用したクエリの実行方法を示しています。
SELECT * FROM reference('enrichment_table');
SELECT reference('encrypt_func')(t.c1) FROM my_table t;
参照を使用したストアドプロシージャの呼び出し¶
次の例は、参照を使用してストアドプロシージャを呼び出す方法を示しています。
CALL reference('consumer_proc')(11, 'hello world');
参照を使用した DML コマンドの実行¶
以下の例では、参照を使用してテーブルのデータを変更する方法を示します。
INSERT INTO reference('data_export')(C1, C2)
SELECT T.C1, T.C2 FROM reference('other_table')
COPY INTO reference('the_table') ...
参照を使用した DESCRIBE コマンドの実行¶
次の例では、参照を使用して DESCRIBE 操作を実行する方法を示します。
DESCRIBE TABLE reference('the_table')
タスクでの参照の使用¶
CREATE TASK app_task
WAREHOUSE = reference('consumer_warehouse')
...;
ALTER TASK app_task SET WAREHOUSE = reference('consumer_warehouse');
ビュー定義での参照の使用¶
CREATE VIEW app_view
AS SELECT reference('function')(T.C1) FROM reference('table') AS T;
関数本文での参照の使用¶
CREATE FUNCTION app.func(x INT)
RETURNS STRING
AS $$ select reference('consumer_func')(x) $$;
外部関数での参照の使用¶
CREATE EXTERNAL FUNCTION app.func(x INT)
RETURNS STRING
...
API_INTEGRATION = reference('app_integration');
ポリシーでの参照の使用¶
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
);
サポートされている参照関数¶
Snowflake Native App Framework は、参照に関するさまざまな操作を実行するために、以下の関数をサポートしています。
システム関数 |
説明 |
---|---|
|
|
|
|
remove_reference |
|
|
|
|
|
|
|