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

参照について¶

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

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

Snowflake Native App がこの種のオブジェクトに接続できるように、 Snowflake Native App Framework は、顧客がオブジェクトの名前を指定し、必要な権限を付与できる参照を提供します。

マニフェストファイルでの参照の定義¶

次の例は、 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');

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

COPY INTO reference('the_table') ...

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 は、参照に関するさまざまな操作を実行するために、以下の関数をサポートしています。