開発者 APIs を使用して、結果をSnowflakeアカウントに送信し、アクティベーションを行う¶

プロバイダーは、クリーンルームにアクティベーションテンプレート（SQL Jinjaテンプレート）を追加し、分析結果をSnowflakeアカウントにプッシュしてアクティベーションを行うことができます。

プロバイダーが実行する分析の場合、プロバイダーは結果を自分のSnowflakeアカウントにプッシュできます（プロバイダーのアクティベーション）。コンシューマーが実行する分析の場合、コンシューマーは、プロバイダーがアクティベーションテンプレートをどのように構成したかに応じて、結果をプロバイダーのSnowflakeアカウント（プロバイダーのアクティベーション）または自分のアカウント（コンシューマーのアクティベーション）のいずれかにプッシュできます。

プロバイダーは、ユーザーがウェブアプリを使用してSnowflakeアカウントに結果をプッシュできるように、アクティベーションテンプレートにユーザーインターフェイスを追加できます。この場合、結果をプッシュするオプションは、他のアクティビティオプションと同様にアクティビティハブに表示されます。あるいは、プロバイダーとコンシューマーは、開発者 APIs を使用してアクティベーションテンプレートを使用し、結果をプッシュすることもできます。

プロバイダー¶

プロバイダーとして、以下のことを行う必要があります。

プロバイダーやコンシューマーがSnowflakeアカウントに結果をプッシュバックできるように、アクティベーションテンプレートをセットアップします。
プロバイダーのSnowflakeアカウントに結果をアクティブ化します。
Snowflakeアカウントで結果を表示

プロバイダーのセットアップ¶

このセクションでは、プロバイダーがクリーンルームでアクティベーションテンプレートを作成、追加、構成する手順について説明します。以下のセクションが含まれます。

プロバイダーのアクティベーション用テンプレートの作成
アクティベーションテンプレートでのテーブル定義
必要なテーブルをリンク（プロバイダーのアクティベーションのみ）
アクティベーションポリシーのセット
コンシューマーアクティベーションの有効化（コンシューマーが実行した分析のみ）
コンシューマーからのリクエスト許可（プロバイダーのアクティベーションのみ）
ウェブアプリでのアクティベーションのセットアップ（オプション）

プロバイダーのアクティベーション用テンプレートの作成¶

結果を有効にするために使用されるテンプレートは、分析を実行するために使用されるテンプレートと似ています。例えば、分析テンプレートのように provider.add_custom_sql_template コマンドでクリーンルームに追加します。しかし、アクティベーションテンプレートには次のような重要な違いがあります。

アクティベーションテンプレート名は、文字列 activation で始まらなければなりません。例えば、 activation_my_template という名前のアクティベーションテンプレートは、この要件を満たしています。
アクティベーションテンプレートは、特定の規約に従った名前のテーブルを作成し、テーブル名を明示的に返す必要があります。

アクティベーションテンプレートでのテーブル定義¶

クリーンルームでアクティベーションの結果を保持するために、すべてのアクティベーションテンプレートはテーブルを作成しなければなりません。このテーブルには2つの条件があります。

テーブル名は、文字列 cleanroom.activation_data_ で始まらなければならない。たとえば、 cleanroom.activation_data_analysis_results という名前のテーブルの場合、
テーブルを作成するテンプレート定義の部分は、テーブル名を形成するために cleanroom.activation_data_ に追加された文字列を返さなければなりません。例えば、テーブル名が cleanroom.activation_data_analysis_results の場合、文字列 analysis_results を返さなければなりません。

以下は、テーブルを定義し、それをエクスポートするためにテンプレート定義に含めなければならない内容の例です。

BEGIN
  CREATE OR REPLACE TABLE cleanroom.activation_data_analysis_results AS
    SELECT * FROM identifier({{ my_table[0] }})
  RETURN 'analysis_results';
END;

Copy

クリーンルームにアクティベーションテンプレートを追加するための provider.add_custom_sql_template コマンドの呼び出しの詳細については、 Snowflakeデータクリーンルーム：プロバイダーAPIリファレンスガイドをご参照ください。

必要なテーブルをリンク（プロバイダーのアクティベーションのみ）¶

プロバイダーまたはコンシューマーが結果をプロバイダーのSnowflakeアカウントにプッシュする場合、プロバイダーは samooha_by_snowflake_local_db.library.temp_public_key テーブルをクリーンルームにリンクする必要があります。例えば、必要なテーブルをクリーンルーム my_activation_cleanroom にリンクさせるには、以下を実行します。

CALL samooha_by_snowflake_local_db.provider.link_datasets(
    'my_activation_cleanroom',
    ['samooha_by_snowflake_local_db.library.temp_public_key']);

Copy

プロバイダーは、他のテーブルやビューをリンクする際に、必要なテーブルをリンクするために単一の呼び出しを使用することもできます。

アクティベーションポリシーのセット¶

アクティベーションポリシーは、どの列をアクティベーションテンプレートで使用できるかを定義します。これは、プロバイダーによって承認された列だけがアクティベーションテンプレートで使用できるようにするために、アクティベーションテンプレートで使用することができます。

プロバイダーは、 provider.set_activation_policy API を使用してアクティベーションポリシーをセットします。例:

CALL samooha_by_snowflake_local_db.provider.set_activation_policy('my_cleanroom', [
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:HASHED_EMAIL',
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:STATUS',
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:AGE_BAND',
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:DAYS_ACTIVE',
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:REGION_CODE' ]);

Copy

コンシューマーアクティベーションの有効化（コンシューマーが実行した分析のみ）¶

コンシューマーが結果を自分のアカウントにプッシュする場合、プロバイダーは provider.enable_template_for_consumer_activation API を実行しなければなりません。例:

CALL samooha_by_snowflake_local_db.provider.enable_template_for_consumer_activation(
    'my_cleanroom', 'activation_my_template');

Copy

コンシューマーからのリクエスト許可（プロバイダーのアクティベーションのみ）¶

プロバイダーが、自分自身またはコンシューマーが結果をプロバイダーのSnowflakeアカウントにプッシュできるようにアクティベーションテンプレートを構成する場合、プロバイダーは provider.request_provider_activation_consent API を実行する必要があります。この API は、この目的のためにコンシューマーにテンプレートの承認をリクエストします。例:

CALL samooha_by_snowflake_local_db.provider.request_provider_activation_consent('my_cleanroom', 'activation_my_template');

Copy

プロバイダーがプロバイダーの実行した分析の結果をアクティブ化する前に、コンシューマーはリクエストを承認する必要があります。

ウェブアプリでのアクティベーションのセットアップ（オプション）¶

プロバイダーがクリーンルームのユーザーインターフェイスを作成し、ユーザーがウェブアプリで分析を実行できるようにする場合、クリーンルームを構成し、ユーザーがウェブアプリのアクティベーションハブを使用して結果をアクティブ化できるようにすることもできます。プロバイダーが provider.add_ui_form_customizations API を実行してユーザーインターフェイスを作成するとき、アクティベーションテンプレートの名前と、そのテンプレートをプロバイダーのアクティベーション、コンシューマーのアクティベーション、またはその両方に使用するのかを指定します。

例えば、次の例では、ユーザーはプロバイダーのアクティベーションとコンシューマーのアクティベーションの両方にアクティベーションハブを使用できます。

CALL samooha_by_snowflake_local_db.provider.add_ui_form_customizations(
    $cleanroom_name,
    'prod_test_references_1',
    {
      'display_name': 'PROD TEST REFERENCE FIRST',
      'description': 'Use our customized ML techniques to find lookalike audiences.',
      'methodology': 'Specify your own seed audience, while matching against our users. Then customize the lookalike model across number of boosting rounds and removing outliers.',
      'render_table_dropdowns': {
          'render_consumer_table_dropdown': TRUE,
          'render_provider_table_dropdown': TRUE
        },
     'activation_template_name': 'activation_my_template',
     'enabled_activations': ['consumer', 'provider']
    },
    {
    'reference_provider_join': {
        'display_name': 'Provider join column',
        'order': 4,
        'description': 'Which provider col do you want to join on',
        'size': 'S',
        'group': 'Seed Audience Selection',
        'references': ['PROVIDER_JOIN_POLICY'],
        'provider_parent_table_field': 'source_table',
        'type': 'dropdown'
    },
    'reference_consumer_join': {
        'display_name': 'Consumer join column',
        'order': 4,
        'description': 'Which consumer col do you want to join on',
        'size': 'S',
        'group': 'Seed Audience Selection',
        'references': ['CONSUMER_COLUMNS'],
        'consumer_parent_table_field': 'my_table',
        'type': 'dropdown'
    }
  },
  {
    'measure_columns': ['count'],
    'default_output_type': 'BAR'
  });

Copy

プロバイダーが実行した分析の後にアクティブ化する¶

プロバイダーがクリーンルームを構成し、ユーザーがウェブアプリを使用して分析を実行し、結果をアクティブ化できるようにした場合、ユーザーは分析を実行した後に Activate ボタンを選択してアクティベーションハブを開き、そこで結果をプッシュするプロバイダーアカウントを選択できます。

プロバイダーが分析を実行するためにウェブアプリではなく開発者 APIs を使用している場合、 submit_analysis_request API を実行して結果をアクティブ化することができます。例:

CALL samooha_by_snowflake_local_db.submit_analysis_request(
  'my_clean_room',
  'CONSUMER_1_LOCATOR',
  'activation_custom_template',
  ['provider_source_table'],
  ['consumer_source_table'],
  object_construct(
    'dimensions', ['p.CAMPAIGN'],
    'where_clause', 'p.EMAIL=c.EMAIL'
));

Copy

プロバイダーとして起動した結果を表示する¶

コンシューマーまたはプロバイダーが結果をプロバイダーにアクティブ化した後、プロバイダーはSnowflakeアカウントでこれらの結果を表示できます（クリーンルーム環境ではありません）。

注釈

コンシューマーが結果をアクティブ化した場合、プロバイダーはクリーンルーム環境にサインインしてから、Snowflakeアカウントにサインインして結果を表示する必要があります。

詳細については、プロバイダーのSnowflakeアカウントで分析結果を表示するをご参照ください。

コンシューマー¶

コンシューマーとして、以下のことを行う必要があります。

プロバイダーおよび/またはコンシューマーがアクティベーションテンプレートを使用して、結果をSnowflakeアカウントにプッシュバックできるようにクリーンルームをセットアップします。
結果をSnowflakeアカウントにアクティブ化します。
Snowflakeアカウントで結果を表示

コンシューマーのセットアップ¶

コンシューマーは、結果をアクティブ化する前に、アクティベーションポリシーをセットする必要があります。プロバイダーのアクティベーションには、プロバイダーのリクエストを承認する必要もあります。

アクティベーションポリシーのセット¶

アクティベーションポリシーは、どの列をアクティベーションテンプレート内で使用できるかを定義します。このポリシーは、コンシューマーが承認した列のみがアクティベーションテンプレートで使用できるようにするために、アクティベーションテンプレートで使用することができます。

コンシューマーは consumer.set_activation_policy API を使用して、アクティベーションポリシーをセットします。例:

CALL samooha_by_snowflake_local_db.consumer.set_activation_policy('my_cleanroom', [
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:HASHED_EMAIL',
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:REGION_CODE' ]);

Copy

プロバイダーのリクエストを承認（プロバイダーのアクティベーションのみ）¶

プロバイダーが、プロバイダーのSnowflakeアカウントに結果を送信するために使用することを意図したアクティベーションテンプレートの provider.request_provider_activation_consent API を実行した場合、コンシューマーはリクエストを承認する必要があります。この承認は、プロバイダーのアカウントに結果を送信するのがプロバイダーであるかコンシューマーであるかにかかわらず必要です。

コンシューマーがウェブアプリを使用している場合、クリーンルームをインストールすることで、プロバイダーが必要とする同意が得られます。

コンシューマーが開発者 APIs を使用している場合、コンシューマーは consumer.approve_provider_activation_consent API を実行します。例:

CALL samooha_by_snowflake_local.consumer.approve_provider_activation_consent('my_cleanroom', 'activation_my_template');

Copy

コンシューマーが実行した分析後のアクティブ化¶

プロバイダーがクリーンルームを構成し、ユーザーがウェブアプリを使用して分析を実行し、結果をアクティブ化できるようにした場合、ユーザーは分析実行後に Activate ボタンを選択してアクティベーションハブを開き、プロバイダーアカウント（プロバイダーのアクティベーションが構成されている場合）またはコンシューマーアカウント（コンシューマーのアクティベーションが構成されている場合）を選択して結果をプッシュすることができます。

コンシューマーがウェブアプリの代わりに開発者 APIs を使用している場合、コンシューマーは consumer.run_activation コマンドを呼び出してアクティベーションテンプレートを実行することでSnowflakeアカウントに結果を送信します。これは consumer.run_analysis コマンドの実行と同様です。違いは第2引数で、アクティベーションの内容を識別するための文字列を指定します。

例えば、コンシューマーは電話をかけることができます。

CALL samooha_by_snowflake_local_db.consumer.run_activation(
  'activation_clean_room',
  'my_activation_segment',
  'activation_custom_template',
  ['consumer_source_table'],
  ['provider_source_table'],
  object_construct(
    'dimensions', ['p.CAMPAIGN'],
    'where_clause', 'p.EMAIL=c.EMAIL'
));

Copy

consumer.run_activation コマンドの詳細については、 Snowflakeデータクリーンルーム：コンシューマーAPIリファレンスガイドをご参照ください。

コンシューマーとしてアクティブ化した結果を表示する¶

コンシューマーが自分のSnowflakeアカウントに結果をプッシュした場合、 Snowsight で結果を表示することができます。