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

参照について¶

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

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

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

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

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

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

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

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;

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

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

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

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

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

この例では、 consumer_table は manifest.yml ファイルで定義されている参照の名前です。コンシューマーが参照に関連付けられたストアドプロシージャを実行すると、 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('consumer_table');

SELECT reference('encrypt_func')(t.c1) FROM consumer_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 は、参照に関するさまざまな操作を実行するために、以下の関数をサポートしています。