コンシューマーへの参照およびオブジェクトレベル権限のリクエスト

このトピックでは、プロバイダーがコンシューマーアカウント内にある既存のデータベースオブジェクトへのアクセスをリクエストする方法について説明します。

参照について

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

この場合、コンシューマーが Snowflake Native App にオブジェクトに対するアクセス権を付与するだけでは不十分です。 Snowflake Native App は、コンシューマーカウントに存在するスキーマとオブジェクトの名前を判断できません。追加情報については、 オブジェクト名の解決 をご参照ください。

Snowflake Native App がこの種のオブジェクトに接続できるように、 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:
- 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
Copy

この例では、テーブルに対する 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;
Copy

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

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

プロバイダーが 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.tab1', 'persistent', 'select', 'insert');
Copy

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

CALL app.config.register_single_callback(
 SYSTEM$REFERENCE('TABLE', 'db1.schema1.tab1', 'PERSISTENT', 'SELECT', 'INSERT'), 'ADD', null);
Copy

コンシューマーがコールバックストアドプロシージャを実行すると、 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 内で参照を使用する例

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

参照を使用したクエリの実行

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

SELECT * FROM reference('enrichment_table');
Copy
SELECT reference('encrypt_func')(t.c1) FROM my_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('<参照名>', '<参照文字列>')

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

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

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 は値を保存し、現在の値と既知の値を比較することができます。