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

参照について¶

場合によっては、インストールされた 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 プロパティは、コンシューマーテーブルをこの参照定義にバインドするために使用されるストアドプロシージャを指定します。

複数のコンシューマー・オブジェクトを同じ参照にバインドするには、 multi_valued を使用します。このプロパティが指定されている場合、1つの値参照を持つオブジェクトに対して同じ操作が実行されます。このプロパティは、多値参照を持つオブジェクトにも使用できます。 Snowflake Native App Framework 参照操作の詳細については、 対応する参照関数 をご参照ください。

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, :ref_or_alias);
        WHEN 'CLEAR' THEN
          SELECT SYSTEM$REMOVE_ALL_REFERENCES(: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 という名前のストアドプロシージャを作成します。

オブジェクト構成を要求するためのコールバックストアドプロシージャを作成する¶

一部のオブジェクトタイプでは、プロバイダーは追加の構成を提供するために、セットアップスクリプトにストアドプロシージャを追加する必要があります。このコールバックは、コンシューマーが Snowsight を使用して参照を許可する場合に使用されます。

次の例は、 マニフェストファイルで参照を定義する に示されている参照に対して構成コールバックストアドプロシージャを定義する方法を示しています。

CREATE OR REPLACE CONFIG.GET_CONFIGURATION_FOR_REFERENCE(ref_name STRING)
  RETURNS STRING
  LANGUAGE SQL
  AS
  $$
  BEGIN
    CASE (ref_name)
      WHEN 'CONSUMER_EXTERNAL_ACCESS' THEN
        RETURN '{
          "type": "CONFIGURATION",
          "payload":{
            "host_ports":["google.com"],
            "allowed_secrets" : "LIST",
            "secret_references":["CONSUMER_SECRET"]}}';
      WHEN 'CONSUMER_SECRET' THEN
        RETURN '{
          "type": "CONFIGURATION",
          "payload":{
            "type" : "OAUTH2",
            "security_integration": {
              "oauth_scopes": ["https://www.googleapis.com/auth/analytics.readonly"],
              "oauth_token_endpoint": "https://oauth2.googleapis.com/token",
              "oauth_authorization_endpoint":
                "https://accounts.google.com/o/oauth2/auth"}}}';
     END CASE;
     RETURN '';
   END;
   $$;

GRANT USAGE ON PROCEDURE CONFIG.GET_CONFIGURATION_FOR_REFERENCE(STRING)
  TO APPLICATION ROLE app_admin;

この例では、 EXTERNAL ACCESS INTEGRATION または SECRET 参照型の参照を構築するために使用される JSON 形式の構成を返す GET_CONFIGURATION_FOR_REFERENCE という名前のストアドプロシージャを作成します。switchステートメント内のエントリは、 manifest.yml ファイル内の参照名にマップする必要があります。

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

プロバイダーが 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 は、この新しい参照を新しいバージョンのアプリで使用できます。

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

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 FUNCTION app.func(x INT)
  RETURNS STRING
  ...
  EXTERNAL_ACCESS_INTEGRATIONS = (reference('consumer_external_access_integration'), ...);
  SECRETS = ('cred1' = reference('consumer_secret'), ...);

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
      );

構成コールバック応答の JSON 形式¶

構成コールバック関数は、 JSON 形式で応答を返します。返される JSON 形式は、外部アクセス統合とシークレット参照では異なります。

{
  "type": "CONFIGURATION",
  "payload": {
    "host_ports": ["host_port_1", ...],
    "allowed_secrets": "NONE|ALL|LIST",
    "secret_references": ["ref_name_1", ...]
  }
}

{
  "type": "CONFIGURATION",
    "payload": {
            "type": "OAUTH2",
            "security_integration": {
                    "oauth_scopes": ["scope_1", "scope_2"],
                    "oauth_token_endpoint" : "token_endpoint",
                    "oauth_authorization_endpoint" : "auth_endpoint"
            }
    }
}

 {
   "type": "ERROR",
   "payload":{
     "message": "The reference is not available for configuration ..."
  }
}

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

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