clean roomにアクティベーションを実装する¶
アクティベーションの概要¶
プロバイダーまたはコンシューマーは、 アクティベーション と呼ばれるプロセスで、clean roomの外部にテンプレート結果を送信することができます。Snowflakeは3タイプのアクティビティをサポートしています：
プロバイダーアクティベーション、結果がプロバイダーのSnowflakeアカウントのテーブルにプッシュされます。
コンシューマーアクティベーション、結果がコンシューマーのSnowflakeアカウントのテーブルにプッシュされます。
サードパーティアクティベーション、プロバイダーまたはコンシューマーは、 アクティベーションコネクタ を介して、結果をLiveRamp やMeta Ads ManagerなどのSnowflakeが承認したサードパーティにプッシュします。
どのような場合でも、アクティベーションをテンプレートがサポートしている必要があり、相手側はエクスポートされる自身のデータの列のアクティビティを承認する必要があります。
Data providers can limit which columns of their data are activated by setting an activation policy. Learn more about clean room policies: clean roomテーブルのポリシーを理解する.
アクティベーションは差分プライバシーを（有効であれば）サポートし、差分プライバシーのルールとバジェットに従います。
重要
コンシューマーとプロバイダーが異なるクラウドリージョンにある場合は、両方のアカウントと両方のクリーンルームで クロスクラウドの自動フルフィルメント を有効にする必要があります。
プロバイダーとコンシューマーのアクティベーション¶
clean roomを構成すると、プロバイダーまたはコンシューマーのSnowflakeアカウントにテンプレートの結果を保存できます。プロバイダーとコンシューマーの双方が、clean room外のデータのアクティベーションを承認する必要があります。
アクティベーションは、専用のアクティベーションテンプレートを使用して実装されます。clean room UI では、分析テンプレートを分析テンプレートに関連付けたり、ユーザーが分析テンプレートを実行して結果を表示し、関連付けたアクティベーションテンプレートの結果を実行およびアクティベートしたりできます。この処理は、Snowflakeが提供するAudience Overlap & Segmentationフローにより実行されます。
アクティベーションテンプレートが、関連する分析テンプレートと同一である必要はありません。アクティベーションテンプレートは多くの場合、分析テンプレートのサブセットです。
サポートされるテンプレート¶
以下のテンプレートはプロバイダーとコンシューマーのアクティベーションをサポートしています：
Audience Overlap & Segmentation
サポートされる組み合わせ¶
アクティベーションはプロバイダーでもコンシューマーでも実行できます。プロバイダーとコンシューマーのアクティベーションにより、プロバイダーとコンシューマーの分析実行をさまざまに組み合わせることができます。(プロバイダーが実行する分析 について詳細をご参照ください。)
以下の組み合わせをサポートしています：
プロバイダーのアクティベーション |
コンシューマーアクティベーション |
サードパーティアクティベーション |
|
|---|---|---|---|
プロバイダーが実行 |
✅ |
❌ |
UI only |
コンシューマーが実行 |
✅ |
✅ |
UI only |
結果¶
プロバイダーのアクティベーション結果 は、 SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.PROVIDER_ACTIVATION_SUMMARY テーブルのプロバイダーアカウントに保存されます。
コンシューマーのアクティベーション結果 は、 SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.CONSUMER_DIRECT_ACTIVATION_SUMMARY テーブルのコンシューマーのアカウントに保存されます。
データの読み方については、 結果の表示 をご参照ください。
プロバイダーまたはコンシューマーアクティベーションを実装する¶
設定
clean roomの UI 使用時にアクティベーションするには、clean roomのアカウントが アクティベーションを許可 している必要があります。
アクティベーションをプロバイダーが実行するには、clean roomは プロバイダーが実行する分析をサポートするよう構成 されている必要があります。
1.clean roomの作成または参加
clean roomを作成または参加する際、 Configure Analysis & Query ステップの Activation Settings で、どの列を自分のアカウントにアクティベートされた結果に追加するかを指定します。
2.テンプレートの実行と結果のアクティベート
分析に関連付けたアクティビティを実行するには、以下の手順に従ってください：
分析を実行します。
分析の実行後、Results » Activate を選択します。
Activation Hub で、アクティベートするプロバイダーまたはコンシューマーアカウントの名前を選択します。
セグメンテーションのわかりやすい名前を入力する、アクティベーションの列を選択するなど、アクティベーションテンプレートに固有の情報を入力します。
セグメント名を指定します。結果セットを識別するための任意の文字列を入力してください。アクティベーションごとに異なる文字列を指定して、各実行の結果を個別にグループ化したり、入力内容を変えた複数の実行で同じセグメント名を使用し、それらの結果を組み合わせたりできます。
Push Data を選択します。
To learn how to view activated results, see プロバイダーとコンシューマーのアクティベーション結果を表示する.
アクティベーションのパフォーマンスは、誰が実行するかによっても、コンシューマーとプロバイダーのどちらのアクティベーションかによっても異なります。
重要
コンシューマーが初めてclean roomのプロバイダーアカウントに対してデータをアクティベートする場合、プロバイダーはそのアカウントのclean room UI にサインインし、最大30分間サインインし続けることで、データパイプラインを確立する必要があります。この作業は、1コンシューマーの1つのclean roomにつき1回のみ行う必要があります。それが完了するまでは、アクティベーションが成功しても、データはプロバイダーのアカウントに表示されません。
コンシューマーが自分のSnowflakeアカウントに結果をプッシュする方法は以下のとおりです。
プロバイダー
標準的なclean roomとして、clean roomを作成し、データセットをリンク付けして、結合ポリシーを設定します。
サポートされているSnowflake標準テンプレート を選択するか、 カスタムアクティベーションテンプレート をclean roomに追加します。このclean roomを UI で使用する場合は、テンプレートのドキュメントに記載されているように、適切なアクティベーションフィールドを持つウェブフォームを提供する必要があります。
provider.enable_template_for_consumer_activationを呼び出して、コンシューマーアクティベーション用のテンプレートを有効にします。To specify which provider columns can be activated, set the activation policy in the clean room for the enabled template by calling
provider.set_activation_policy.コンシューマーコラボレーターを追加し、デフォルトのリリースディレクティブをセットして、clean roomを公開します。
コンシューマー
clean roomをインストールし、データセットをリンクさせて、標準的なclean roomに対する結合ポリシーを設定します。
To specify which consumer columns can be activated, set the activation policy in the clean room for that template by calling
consumer.set_activation_policy.最後のパラメーターに、コンシューマーアクティベーションを示す TRUE をセットし、
consumer.run_activationを呼び出してアクティベーションを実行します。下記のように結果を表示します。
例
以下の例をダウンロードし、Snowflakeアカウントにワークシートファイルとしてアップロードします。プロバイダー用とコンシューマー用に別々のアカウントを用意し、それぞれにclean room API をインストールする必要があります。サンプルファイルに記載されている情報を置き換えてください。
コンシューマーがプロバイダーのSnowflakeアカウントに結果をプッシュする方法は以下のとおりです。
重要
コンシューマーとプロバイダーの どちらにも clean room UI がインストールされおらず、コンシューマーがプロバイダーをアクティベートしている場合：
コンシューマー は以下の SQL コマンドを実行する必要があります：
ALTER SHARE SAMOOHA_INTERNAL_GOVERNANCE_SUMMARY_SHARE_NAV2 ADD ACCOUNTS = $provider_account_data_sharing_id;
$provider_account_data_sharing_idがプロバイダーの データ共有アカウント識別子 である場合プロバイダー は以下のプロシージャを実行する必要があります：
CALL samooha_by_snowflake_local_db.provider.mount_provider_activations_share( $consumer_account_data_sharing_id, TRUE, FALSE);
$consumer_account_data_sharing_idがコンシューマーの データ共有アカウント識別子 である場合
1.プロバイダー
標準的な方法でclean roomを作成します。
データセットをリンク付けします。また、プロバイダーは
samooha_by_snowflake_local_db.library.temp_public_keyテーブルをclean roomにリンク付けする必要があります。標準的な方法で結合ポリシーを設定します。
サポートされているSnowflake標準テンプレート を選択するか、 カスタムアクティベーションテンプレート をクリーンルームに追加します。このクリーンルームをクリーンルーム UI 内で使用する場合は、適切なアクティベーションフィールドを備えた Webフォームを提供 する必要があります。
To specify which provider columns can be activated, set the activation policy in the clean room for that template by calling
provider.set_activation_policy.コンシューマーコラボレーターを追加し、デフォルトのリリースディレクティブをセットして、clean roomを公開します。(clean room UI がインストールされていない場合は、コンシューマーを追加した後に、
provider.setup_provider_activation_share_mount_taskを呼び出します。)
2.コンシューマー
clean roomをインストールし、データセットをリンクさせて、標準的なclean roomに対する結合ポリシーを設定します。
Set the activation policy in the clean room for that template to specify which consumer columns can be activated by calling
consumer.set_activation_policy.最後の引数にプロバイダーアクティベーションを示す FALSE をセットし、
consumer.run_activationを呼び出して、アクティベーションを実行します。注釈
有効化されたデータの暗号化されたバージョンは、コンシューマーのアカウントの SAMOOHA_LOCAL_DB_NAME_PLACEHOLDER.PUBLIC.CONSUMER_ACTIVATION_SUMMARY テーブルに28日間格納されます。28日より古いデータはコンシューマーのアカウントから削除されます。
3.プロバイダー
コンシューマーが初めて自分のアカウントに対してデータをアクティベートする場合、コンシューマーがデータをアクティベートした後、そのアカウントのclean room UI におよそ30分間サインインする必要があります。その後、データが自分のアカウントに表示されます。これは、1コンシューマーアカウントの1つのclean roomにつき1回のみ行われます。同じclean roomで同じコンシューマーが後でアクティベーションを行う場合、このステップは必要ありません。
結果をアカウントに保存する前に復号化する必要がありますが、それには時間がかかる場合があります。復号化タスクは60分後にタイムアウトします。タイムアウトした場合は、 provider.update_activation_warehouse を呼び出して、復号化に使用するウェアハウスのサイズを増やします。
下記のように結果を表示します。
例
以下の例をダウンロードし、Snowflakeアカウントにワークシートファイルとしてアップロードします。プロバイダー用とコンシューマー用に別々のアカウントを用意し、それぞれにclean room API をインストールする必要があります。サンプルファイルに記載されている情報を置き換えてください。
プロバイダーが自分のSnowflakeアカウントに結果をプッシュする方法は以下のとおりです。これは、カスタムテンプレート、プロバイダーが実行する分析、プロバイダーアクティベーションなど、いくつかのテクニックを組み合わせたもので、プロバイダーとコンシューマーの間でリクエストと承認が何度も繰り返されます。
1.プロバイダー
標準的なclean roomとして、clean roomを作成し、データセットをリンク付けして、結合ポリシーを設定しますが、 例外として、テーブル
samooha_by_snowflake_local_db.library.temp_public_keyでリンクさせる必要があります。プロバイダーが実行するデータは暗号化されており、結果の暗号化と復号化を可能にしています。サポートされているSnowflake標準テンプレート を選択するか、 カスタムアクティベーションテンプレート をclean roomに追加します。このclean roomを UI で使用する場合は、テンプレートのドキュメントに記載されているように、適切なフィールドを持ちアクティベーションをサポートするウェブフォームを指定する必要があります。
Set the activation policy in the clean room for that template to specify which provider columns can be activated by calling
provider.set_activation_policy.標準的な方法でコンシューマーコラボレーターを追加します。clean room UI がインストールされていない場合は、ユーザーを追加した後に
provider.setup_provider_activation_share_mount_taskを呼び出す必要があります。
provider.enable_provider_run_analysisを呼び出すことで、プロバイダーが実行する分析をclean roomで有効にします。これは、コラボレーターを追加した 後 で、かつコラボレーターがclean roomをインストールする 前 に行う必要があります。コンシューマーがclean roomをインストールした後にこの設定を変更する場合、コンシューマーはこの変更を適用するためにclean roomを再びインストールする必要があります。デフォルトのリリースディレクティブを設定し、通常どおりclean roomを公開します。
2.コンシューマー
標準的なclean roomとして、clean roomをインストールし、データセットをリンク付けして、結合ポリシーを設定します。
Set the activation policy in the clean room for that template to specify which consumer columns can be activated by calling
consumer.set_activation_policy.
3.プロバイダー
provider.request_provider_activation_consentを呼び出して、アクティベーションテンプレートを実行するための許可をコンシューマーにリクエストしてください。
4.コンシューマー
consumer.enable_templates_for_provider_runを呼び出し、このclean roomで指定されたテンプレートを実行するための許可をプロバイダーに付与します。
consumer.approve_provider_activation_consentを呼び出し、このclean roomで指定されたテンプレートから結果をアクティベートするための許可をプロバイダーに付与します。
5.プロバイダー
provider.mount_request_logs_for_all_consumersを呼び出し、プロバイダーアクティベーションでのコンシューマーデータの共有を有効にします。
provider.submit_analysis_requestを呼び出して、アクティベーションテンプレートを実行します。リクエストがログに表示されるまで数分かかります。provider.check_analysis_statusを呼び出してステータスをチェックしてください。ステータスが SUCCESS と報告された後でも、結果が復号化されてプロバイダーのSnowflakeテーブルに書き込まれるまで、さらに時間がかかります。復号化されたすべてのデータが、結果テーブルに一度に追加されます。セグメントやアクティベーション ID の結果テーブルを定期的にチェックしてください。復号化タスクは60分後にタイムアウトします。タイムアウトした場合は、 provider.update_activation_warehouse を呼び出して、復号化に使用するウェアハウスのサイズを増やします。注釈
コンシューマーが承認した後にテンプレートを変更するには、以下の手順を実行する必要があります。実行しない場合、
provider.submit_analysis_requestは最後に承認されたバージョンのテンプレートを実行し続けます。
プロバイダーは、
provider.add_custom_sql_templateを呼び出してテンプレートを更新します。create_or_update_cleanroom_listingを再度呼び出す必要はありません。コンシューマーが
consumer.enable_templates_for_provider_runを呼び出します。コンシューマーが
consumer.approve_provider_activation_consentを呼び出します。テンプレートが更新され、プロバイダーアクティベーションが可能になります。
よくあるエラー
Object cleanroom_name.CLEANROOM.TEMP_RESULT_DATA does not exist or not authorized- 何らかの理由で仮結果テーブルを生成できませんでした。テンプレートの SQL エラーか、テンプレートが明示的にテーブルを生成していない可能性があります。エラーの詳細をご覧ください。Query validation checks failed- アクティベーション・ポリシーにない列がテンプレートで使用されています。
例
以下の例をダウンロードし、Snowflakeアカウントにワークシートファイルとしてアップロードします。プロバイダー用とコンシューマー用に別々のアカウントを用意し、それぞれにclean room API をインストールする必要があります。サンプルファイルに記載されている情報を置き換えてください。
プロバイダーとコンシューマーのアクティベーション結果を表示する¶
アクティベーション結果の場所と形式¶
プロバイダーのアクティベーション結果はすべて、Snowflake指定のテーブルに追加されます。テーブルの各行は、クエリ結果の行にマッピングされます。追加のクエリ結果はテーブルに追加されます。アクティベーションごとに一意である ACTIVATION_ID 列と、アクティベーション実行ごとに呼び出し元が指定する SEGMENT 列によって、異なる実行を区別できます。
プロバイダーのアクティベーション結果 は、プロバイダーのアカウントの SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.PROVIDER_ACTIVATION_SUMMARY に保存されます。
コンシューマーのアクティベーション結果 は、コンシューマーのアカウントの SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.CONSUMER_DIRECT_ACTIVATION_SUMMARY に保存されます。
これらのテーブルには以下の列があります：
- USER_ID:
JSON 形式の1行の結果。キーが列名、値がその行のその列の値。このオブジェクトはまた、テンプレートに渡される各引数の列を含みます。
- ACTIVATION_ID:
リクエストごとに一意な ID 。ID は、アクティベーションリクエストに成功した場合に返されます。この列でフィルターをかけると、同じアクティベーションのすべての結果を取得できます。また、複数の実行で同じセグメント名を再利用する場合は、 SEGMENT でフィルターをかけることができます。これは、
submit_analysis_requestまたはrun_activationが返すクエリリクエスト ID と同じです。- CLEANROOM_NAME:
クエリが実行されたclean roomの名前。
- CONSUMER:
(プロバイダーアクティベーションのみ) このアクティベーションを承認したコンシューマー。
- PROVIDER:
(コンシューマーアクティベーションのみ) このアクティベーションを承認したプロバイダー。
- SEGMENT:
アクティベーション実行時に割り当てる任意の文字列値。この列を使用すると、複数のクエリを実行した結果を結合できます。
- TIMESTAMP:
アクティビティが実行されたとき。
プロバイダーアクティベーションの例
SELECT * FROM SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.PROVIDER_ACTIVATION_SUMMARY WHERE segment = 'my_segment';
USER_ID | CLEANROOM_NAME | SEGMENT | CONSUMER | TIMESTAMP | ACTIVATION_ID
"{""AGE_BAND"":55,""ITEM_COUNT"":2328,""STATUS"":""MEMBER""}" | test activation | my_segment | ABC1234 | 2025-04-01 16:27:14.068 | cleanroomactivationdataanalysisresults20250401231728469
"{""AGE_BAND"":20,""ITEM_COUNT"":88,""STATUS"":""PLATINUM""}" | test activation | my_segment | ABC1234 | 2025-04-01 16:27:14.068 | cleanroomactivationdataanalysisresults20250401231728469
"{""AGE_BAND"":80,""ITEM_COUNT"":18,""STATUS"":""GOLD""}" | test activation | my_segment | ABC1234 | 2025-04-01 16:27:14.068 | cleanroomactivationdataanalysisresults20250401231728469
...
プロバイダーまたはコンシューマーのアクティベーション結果を読み取る¶
適切な SQL コマンドを実行して、Snowflake アカウントにアクティベートされた結果を表示します：
プロバイダーアクティベーションの結果を表示
SELECT *
FROM SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.PROVIDER_ACTIVATION_SUMMARY
[WHERE segment = <SEGMENT_NAME>] [AND activation_id = <ACTIVATION_ID>];
コンシューマーアクティベーションの結果を表示
SELECT *
FROM SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.CONSUMER_DIRECT_ACTIVATION_SUMMARY
[WHERE segment = <SEGMENT_NAME>] [AND activation_id = <ACTIVATION_ID>];
各行のデータは、 USER_ID 列のオブジェクトに結合されます。次のようなクエリを使用して結果をフラット化できます：
-- Assuming columns AGE_BAND, STATUS, and ITEM_COUNT
SELECT
item:"AGE_BAND",
item:"STATUS",
item:"ITEM_COUNT"
FROM (SELECT parse_json(user_id)
AS item
FROM SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.PROVIDER_ACTIVATION_SUMMARY
WHERE segment = $segment_name)
ORDER BY item:"AGE_BAND", item:"STATUS" ASC
LIMIT 20 ;
最新の結果10行をSnowsightに表示する:
Snowsight にサインインします。
ナビゲーションメニューで Catalog » Database Explorer を選択します。
プロバイダーアクティベーションの場合
SAMOOHA_BY_SNOWFLAKE_LOCAL_DB»PUBLIC»Tables»PROVIDER_ACTIVATION_SUMMARYに移動します。コンシューマーアクティベーションの場合
SAMOOHA_BY_SNOWFLAKE_LOCAL_DB»PUBLIC»Tables»CONSUMER_DIRECT_ACTIVATION_SUMMARYに移動します。Data Preview を選択します。
サードパーティアクティベーション¶
サードパーティアクティベーションは、 サードパーティアクティベーションコネクタ を使用して、Snowflakeが承認したサードパーティのアカウントにクエリ結果をデポジットします。
サードパーティアクティベーションは、clean room UI でのみサポートされ、カスタムテンプレートは使用できません。
clean room UI 使用中のアクティベーションは、clean roomのアカウント がアクティベーション を許可する場合のみサポートされます。
clean room管理者は、サードパーティのアクティビティコネクタをサポートするように環境を構成し、許可されたコネクタを選択して、それらを構成してから、clean roomで使用する必要があります。
サードパーティアクティベーションは、コンシューマーとプロバイダーの両方が実行する分析をサポートします。
サポートされるテンプレート¶
以下のテンプレートは、サードパーティアクティベーションをサポートしています：
Audience Overlap & Segmentation
サードパーティアクティベーションを実装する¶
clean roomを作成または結合する: clean roomを作成または結合する際、 Configure Analysis & Query ステップの Activation Settings で、どの列を自分のアカウントにアクティベートされた結果に追加するかを指定します。
結果をのアクティベート
分析を実行します。
分析の実行後、Results » Activate を選択します。
Activation Hub で、アクティベートするサードパーティプロバイダーの名前を選択します。
プロバイダー固有の情報を入力します。たとえば、わかりやすい名前を指定したり、アクティベートする列を選択したりします。ページのツールチップには、そのプロバイダーの追加情報が表示されます。
Push Data を選択します。