マルチプロバイダーのコンシューマー分析¶
コンシューマーは、1回のリクエストで、同一または複数のプロバイダーが所有する複数のclean roomで分析を実行し、統合された結果を見ることができます。結果は各clean roomの分析結果を統合したものであり、複数のclean roomのプロバイダーデータを統合したものに対してコンシューマーデータを分析した結果ではありません。
プロバイダーは、リクエストを承認する前に、他のどのclean roomがクエリされるかや、テンプレートなど、リクエストのすべての詳細を確認できます。プロバイダーは、他のclean roomのデータは確認できません。また、他のclean roomでどのプロバイダーテーブルがクエリされるかも確認できません。各clean roomのデータは、参加、列、その他に関する各clean roomのポリシーに従って安全にアクセスおよび処理されます。
マルチプロバイダーの分析結果は、すべてのclean roomでアクティベーションが有効になっている場合にアクティブにできます。
要件¶
テンプレート: マルチプロバイダー分析は、Snowflakeが提供するテンプレートまたはカスタムテンプレートで実行できます。
環境: マルチプロバイダー分析は、clean room API を使用した場合にのみ実装できます。clean room UI では実行できません。
請求: コンシューマーにはマルチプロバイダークエリの費用が請求されます。
その他の要件: マルチプロバイダー分析のすべてのclean roomに、プロバイダーの参加ポリシーが必要です。いずれかのclean roomで分析が失敗すると、リクエスト全体が失敗します。
マルチプロバイダー分析の概要¶
ここでは、マルチプロバイダー分析について概要を説明します。サンプルコードについては、 こちら をご参照ください。
コンシューマーは、マルチプロバイダーのフローで使用するすべてのclean roomを標準的な方法でインストールします。マルチプロバイダー分析に含まれるClean roomは、標準のclean roomです。
コンシューマーは標準的な方法でデータセットをリンクし、参加ポリシーをセットします。 プロバイダーとコンシューマーのclean roomには必ず、参加ポリシーを定義する必要があります (ポリシーがテンプレートでチェックされるかどうかは関係ありません)。
1つのテンプレートに対してリクエストが行われ、すべてのclean roomにそのテンプレートがインストールされている必要があります。コンシューマーがカスタムテンプレートを使用する場合は、以下の 標準的なコンシューマーテンプレートリクエストのフロー に従う必要があります:
コンシューマーが各clean roomで
consumer.create_template_request
を呼び出し、カスタムテンプレートを渡します。プロバイダーが
provider.list_pending_template_requests
を呼び出して保留中のテンプレートリクエストを確認し、provider.approve_template_request
を呼び出して、clean roomにテンプレートを追加することを承認します。コンシューマーが
consumer.list_template_requests
を呼び出して、リクエストが許可されたかどうかを確認します。
プロバイダーとコンシューマーが、標準的な方法でテンプレートの列ポリシーをセットします。
プロバイダーが各clean roomで
provider.enable_multiprovider_computation
を呼び出して、コンシューマーからのリクエストを表面化します。(この呼び出しの前に送られたリクエストはキューに入りますが、このプロシージャを呼び出すまではプロバイダーからは見えません)。コンシューマーがテンプレート実行の承認をリクエストします。 リクエストと承認のフローにはいくつかのバリエーションがありますが、デフォルトのフローは以下のようになります:
コンシューマーが
consumer.prepare_multiprovider_flow
を呼び出して、すべてのclean roomにマルチプロバイダーリクエストを送信します。このリクエストには、clean roomのリスト、使用するテンプレート、すべてのテンプレートパラメーター(プロバイダーテーブル、コンシューマーテーブルなど)を指定します。この呼び出しは一度だけ行われ、リクエスト内のすべてのclean roomにブロードキャストされます。各clean roomはすべてのリクエスト詳細を確認しますが、プロバイダーテーブルリストはそのclean roomのプロバイダーテーブルにフィルターされます。リクエスト ID が返されます。各プロバイダーは
provider.view_multiprovider_requests
を呼び出して、コンシューマーから送信されたマルチプロバイダーリクエストを確認し、provider.process_multiprovider_request
を呼び出してそれを承認します。
すべてのclean roomがリクエストを承認すると、コンシューマーは
consumer.execute_multiprovider_flow
を呼び出してリクエストを実行します。各clean roomでテンプレートが、前回のconsumer.prepare_multiprovider_flow
リクエストで入手した情報を使用して実行され、その結果を統合したものがコンシューマーに送信されます。コンシューマーは、プロバイダーがクエリの権限を取り消すまで、あるいはコンシューマーが差分プライバシーバジェットを使い果たすまで(差分プライバシーが有効になっている場合)、新たにリクエストの承認を得ることなくexecute_multiprovider_flow
を再度呼び出します。
リクエストと承認について¶
以降では、リクエストと承認のプロセスについて説明します。このプロセスにはいくつかのバリエーションがあります。
リクエストと承認のフローのバリエーション¶
マルチプロバイダー分析を実行するフローには、以下の3つが考えられます:
- リクエストごとに承認する(デフォルト動作):
コンシューマー がクエリの情報を使用して
consumer.prepare_multiprovider_flow
を呼び出します。プロバイダー がクエリ (
provider.view_multiprovider_requests
) を確認し、それを承認します (provider.process_multiprovider_request
)。プロバイダーが このクエリを過去に承認している場合、このステップは省略されます。コンシューマー がクエリを実行します (
consumer.execute_multiprovider_flow
)。
- コンシューマーとclean roomごとに承認する:
コンシューマー がクエリの情報を使用して
consumer.prepare_multiprovider_flow
を呼び出します。プロバイダー がクエリ (
provider.view_multiprovider_requests
) を確認して承認し (provider.process_multiprovider_request
)、実際のクエリ ID ではなく、クエリ ID として-1
を渡します。その結果、コンシューマーは以降のリクエストでもconsumer.prepare_multiprovider_flow
を呼び出すことが必要になります。ただし、自動的に承認され、プロバイダーが再度承認する必要はありません。コンシューマー がクエリを実行します (
consumer.execute_multiprovider_flow
)。
- 自動承認:
プロバイダー がclean roomで
provider.resume_multiprovider_tasks
を呼び出します。このclean roomでのコンシューマーのマルチプロバイダーリクエストが、すべて自動的に承認されます。コンシューマー がクエリの情報を使用して
consumer.prepare_multiprovider_flow
を呼び出します。リクエストが自動的に承認されます、コンシューマー がクエリを実行します (
consumer.execute_multiprovider_flow
)。
どのフローでも、 過去に付与したクエリ承認を取り消すことができます。
クエリ承認の基準¶
consumer.execute_multiprovider_flow
は consumer.prepare_multiprovider_flow
に送信された前回のクエリを評価し、それが承認されたかどうかを調べます。承認されたリクエストの中に一致するものが見つかると、クエリが続行されます。見つからなかった場合は、 consumer.execute_multiprovider_flow
が失敗します。(包括的承認 がこのコンシューマーまたはすべてのコンシューマーに付与されている場合は、承認チェックがスキップされます)。過去に承認されたものの中から、以下の値に一致するものを探します:
クエリされるclean roomのリスト。
clean roomに送信される引数名。承認されたリクエストに含まれるすべての引数名が、新しいリクエストにも存在しなければなりません。引数の値はチェックされず、引数名のみがチェックされます。
実行されるテンプレートの名前。
さらに、テンプレートは、包括的承認が与えられているかどうかに関わらず、行ポリシー、列ポリシー、および差分プライバシー(有効な場合)を含む、すべてのclean roomポリシーに準拠していなければなりません。
承認履歴¶
consumer.execute_multiprovider_flow
は consumer.prepare_multiprovider_flow
に前回送信されたクエリの実行を試みます。クエリがすべてのセキュリティチェックに合格し、一致するクエリが過去に承認されている場合に実行できます。つまり、次のような流れになります:
コンシューマーがクエリAを準備する。
プロバイダーがAを承認する。
コンシューマーがAを実行する。
コンシューマーがクエリBを準備する。
プロバイダーがBを承認する。
コンシューマーがBを実行する。
コンシューマーがクエリAを、すべて同じパラメーターで準備する。
コンシューマーがプロバイダーの承認なしに(前回承認されているため)Aを再度実行できる。次のセクションでは、クエリが過去に承認されているかどうかをclean roomが判断する方法について説明します。
自動クエリ承認の有効化または無効化¶
clean roomでのクエリ承認の自動化を、コンシューマーごとに、またはすべてのコンシューマーに対して設定できます。
特定のコンシューマー からの、clean roomでのマルチプロバイダークエリをすべて自動で承認するには、プロバイダーが -1
をクエリ ID として指定し、 provider.process_multiprovider_request
を呼び出します。そのclean roomでの、同じコンシューマーからのマルチプロバイダーリクエストはすべて承認されます。(ただし、コンシューマーはクエリを変更する際に consumer.prepare_multiprovider_flow
を呼び出し、プロバイダーは provider.view_multiprovider_requests
リクエスト履歴にあるすべての consumer.prepare_multiprovider_flow
呼び出しを確認する必要があります)。特定のユーザーに付与された自動承認を無効にするには、 承認ログを更新 する必要があります。
すべてのマルチプロバイダーのクエリを、 すべてのコンシューマーに対して 自動で承認するには、プロバイダーがclean roomに対して provider.resume_multiprovider_tasks
を呼び出す必要があります。これにより、すべてのコンシューマーからのマルチプロバイダーリクエストは自動的に承認されます。(ただし、コンシューマーはクエリを変更する際に consumer.prepare_multiprovider_flow
を呼び出し、プロバイダーは provider.view_multiprovider_requests
リクエスト履歴にあるすべての consumer.prepare_multiprovider_flow
呼び出しを確認する必要があります)。この方法で付与される自動承認を無効にするには、 provider.suspend_multiprovider_tasks
を呼び出します。
テンプレートのデザイン¶
マルチプロバイダーフローはテストに時間がかかり、多くのステップでテンプレートのエラーが見つかりにくいため、プロバイダーが作成しコンシューマーが実行する基本的なフローでテンプレートをテストし、正しいことを確認してから、マルチプロバイダーフローで使用してください。
clean roomはいずれもまったく同じテンプレートを実行しますが、各clean roomに渡される source_table
リストは、そのclean roomのプロバイダーテーブルのみを表示するようにフィルターされているため、長さやテーブル名が異なる場合があります。そのため、クエリによっては、Jinjaのループや条件ステートメントを使用して、リストの長さやテーブル名の変化に対応することが必要になる場合があります。
自動承認の管理と承認ステータスの変更¶
リクエスト履歴ログ¶
プロバイダーが provider.enable_multiprovider_computation
を呼び出すと、 samooha_cleanroom_cleanroom_ID.admin.request_log_multiprovider
という名前のログテーブルが作成されます。プロバイダーがclean roomのマルチプロバイダー分析を承認するたびに、リクエストのログがこのテーブルに作成されます。このテーブルを、コンシューマーがマルチプロバイダークエリの実行をリクエストした際に、clean roomがチェックします。このテーブルに含まれる approved
列 は、リクエストの実行が許可されているかどうかを示します。クエリは承認されなければテーブルに追加できないため、最初の approved
ステータスは true
になりますが、承認を取り消す場合は 後で変更する ことができます。
ログテーブルは、コンシューマーによるクエリ実行ではなく、 provider.process_multiprovider_request
からのコンシューマークエリリクエストを保持します。コンシューマークエリの実行はログに記録されません。
過去に承認されたリクエストの拒否¶
過去に承認されたリクエストを拒否するには、マルチプロバイダーリクエストログテーブルの approved
列を FALSE に変更する必要があります。
コンシューマーは同じクエリを複数回送信することができ、いずれかのクエリが承認されれば実行が許可されるため、マルチプロバイダークエリを最も安全な方法で無効にするには、特定のコンシューマーからのすべてのクエリに対して approved=false
をセットし、 consumer.prepare_multiprovider_flow
を呼び出して、実行したいクエリを再送信するようにコンシューマーに指示する必要があります。
-- Revoke access to a query you had previously approved
UPDATE samooha_cleanroom_Samooha_Cleanroom_Multiprovider_Clean_Room_1.admin.request_log_multiprovider
SET APPROVED=FALSE
WHERE PARTY_ACCOUNT='<CONSUMER_LOCATOR>';
過去に拒否されたリクエストを有効にする¶
過去にリクエストを承認し、その後拒否して、再度承認したい場合は、リクエストログテーブルを更新するのではなく、コンシューマーにフローリクエストを再送信するように依頼して、標準フローで承認するのが多くの場合に安全です。
自動承認を取り消す¶
clean roomでの すべてのコンシューマーに対する 自動承認を、
provider.resume_multiprovider_tasks
を呼び出すことで有効にしている場合は、provider.suspend_multiprovider_tasks
を呼び出して、すべてのユーザーに対する包括的承認を取り消します。clean roomでの 特定のコンシューマーに対する 自動承認を、
provider.process_multiprovider_request
でクエリ ID に-1
を指定することで有効にしている場合は、 過去に承認されたリクエストの拒否 を参照してください。
コードサンプル¶
マルチプロバイダー分析フローをお試しになる場合は、以下のワークブックをダウンロードしてください。clean room API がインストールされた2つのSnowflakeアカウント(1つはプロバイダーとして、もう1つはコンシューマーとして使用)が必要です。プロバイダーアカウントによって2つのclean roomが作成され、1つのclean roomを持つ複数のプロバイダーと同様の動作をします。