Grundlegende Datenanalyse durch Verbraucher¶

Umgebung einrichten¶

Zur Verwendung der API müssen Sie ein Warehouse verwenden, in dem SAMOOHA_APP_ROLE Berechtigungen hat. app_wh ist eines von :ref:` mehreren Warehouses <label-cleanrooms_installation_details_warehouses>` mit Zugriff auf die API. Wählen Sie das Warehouse aus, das für Ihre Bedürfnisse geeignet ist. (Sie können auch Ihr eigenes Warehouse verwenden, wenn Sie möchten.)

Die Rolle SAMOOHA_APP_ROLE wird benötigt, um Zugriff auf die API zu erhalten.

USE WAREHOUSE app_wh;
USE ROLE SAMOOHA_APP_ROLE;

Reinraum erstellen¶

Der nächste Schritt besteht darin, einen neuen Clean Room zu erstellen. Dies geschieht mit einem einzigen API-Aufruf, der angibt, ob der Clean Room für die interne oder externe Verwendung bestimmt ist. Interne Clean Rooms können nur von Verbrauchern innerhalb derselben Organisation genutzt werden. Externe Clean Rooms können von Verbrauchern außerhalb der Organisation genutzt werden. Bei beiden Typen von Clean Rooms müssen die Verbrauchenden eingeladen werden, den Clean Room zu nutzen, um Zugang zu ihm zu erhalten.

Externe Clean Rooms lösen zusätzliche Sicherheitsprüfungen aus, wenn bestimmte Aktionen durchgeführt werden. Wenn dies geschieht, müssen Sie provider.view_cleanroom_scan_status aufrufen, um zu sehen, wann der Sicherheitsscan abgeschlossen ist. Dann können Sie mit der nächsten Aktion fortfahren.

Im folgenden Beispiel wird ein interner Clean Room erstellt:

CALL samooha_by_snowflake_local_db.provider.cleanroom_init($cleanroom_name, 'INTERNAL');

Daten mit dem Clean Room verknüpfen¶

Sowohl Anbieter als auch Verbraucher können Tabellen, Ansichten und weitere unterstützte Datenobjekte in einem Clean Room verknüpfen (importieren). Wenn Sie Daten verknüpfen, erstellt die API eine verdeckte, sichere Ansicht im Clean Room, die auf dem angegebenen Quellobjekt basiert. Sie referenzieren bei allen Prozessen in Clean Rooms das verknüpfte Objekt über seinen Quellennamen nicht über seinen internen Ansichtsnamen.

Auf die mit dem Clean Room verknüpften Daten kann kein Clean Room-Beteiligter direkt zugreifen. Der Zugriff auf verknüpfte Daten erfolgt über eine in den Clean Room importierte Vorlage (es sei denn, Sie aktivieren Freiform-SQL-Abfragen für Ihre Daten).

Bevor ein Objekt mit einem Clean Room verknüpft werden kann, muss das Objekt registriert werden. Durch die Registrierung eines Objekts werden die entsprechenden Zugriffsrechte für die SAMOOHA_APP_ROLE im Objekt gewährt. Sie können entweder ein Objekt direkt registrieren oder ein übergeordnetes Objekt (z. B. eine Datenbank oder ein Schema), um auf untergeordnete Objekte zuzugreifen. Sie können ein Objekt entweder in der UI oder der API registrieren.

Objekte werden auf Kontoebene registriert, nicht auf Clean Room-Ebene; Sie müssen ein Objekt nur einmal pro Konto registrieren und es kann mit jedem Clean Room im Konto verknüpft werden. (Sie können nur Objekte verknüpfen, die in Ihrem eigenen Konto registriert sind.) Nachdem Sie ein Objekt registriert haben, steht das Objekt für die Verknüpfung mit jedem Clean Room des Kontos zur Verfügung. Erfahren Sie mehr über die Registrierung.

Das folgenden Beispiel verknüpft die CUSTOMERS-Tabelle aus der Beispieldatenbank SAMOOHA_SAMPLE_DATABASE. Diese Datenbank wird automatisch registriert, wenn Sie die Clean Room-Umgebung in einem Konto installieren, sodass Sie sie nicht registrieren müssen. Sie können Objekte jederzeit in einem Clean Room verknüpfen oder entkoppeln. Die Ergebnisse werden schnell an alle Teilnehmer weitergegeben.

CALL samooha_by_snowflake_local_db.provider.link_datasets(
  $cleanroom_name,
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);

Verknüpfungsrichtlinie festlegen¶

Wenn Sie dem Clean Room eine Vorlage hinzufügen, die es dem Verbraucher ermöglicht, Ihre Daten zu verknüpfen, sollten Sie eine Clean Room-Verknüpfungsrichtlinie für Ihre Daten festlegen. Eine Clean Room-Verknüpfungsrichtlinie gibt an, welche Spalten in Abfragen von Teilnehmern verknüpft werden können. Ihre eigenen Verknüpfungsrichtlinien schränken Ihre eigenen Abfragen nicht ein.

Clean Rooms unterstützen einige Typen von Datenrichtlinien, die Sie für verknüpfte Daten festlegen können. Diese Richtlinien ähneln, sind aber nicht identisch mit den entsprechenden Snowflake-Richtlinien und werden nur auf die interne Ansicht angewendet, nicht auf die Quelldaten. Alle Snowflake-Richtlinien, die für die Quelldaten festgelegt wurden, werden an die mit einem Clean Room verknüpften Ansichten weitergegeben. Clean Room-Richtlinien werden nur für die verknüpften Daten festgelegt, nicht für die Quelldaten.

Sie können Richtlinien nur für die Daten festlegen, die Sie verknüpfen. Sie können keine Richtlinien für die Daten einer anderen Partei festlegen.

Das folgende Beispiel zeigt, wie Sie eine Verknüpfungsrichtlinie festlegen, die es ermöglicht, zwei Spalten aus der verknüpften Tabelle miteinander zu verknüpfen.

CALL samooha_by_snowflake_local_db.provider.set_join_policy(
  $cleanroom_name,
  ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:HASHED_EMAIL',
   'SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:HASHED_PHONE']);

Erfahren Sie mehr über Verknüpfungsrichtlinien.

Vorlagen zum Clean Room hinzufügen¶

Eine Clean Room-Vorlage ist eine gültige JinjaSQL-Vorlage, die in der Regel eineSQL-Abfrage bewertet. Einer Vorlage, manchmal auch als Analyse bezeichnet, können vom Aufrufer Argumente übergeben werden, und sie kann auf alle mit dem Clean Room verknüpften Daten zugreifen. Sowohl Anbieter als auch Verbraucher können Vorlagen in einen Clean Room einbinden und sie ausführen.

Snowflake bietet einige Standardvorlagen, aber Sie werden wahrscheinlich Ihre eigenen kundenspezifischen Vorlagen schreiben.

Alle Clean Room-Richtlinien, die Sie festlegen, werden nur durchgesetzt, wenn die Vorlage Richtlinienfilter in der Vorlage enthält. Stellen Sie also sicher, dass die Vorlagen, die Sie einem Clean Room hinzufügen, diese Filter enthalten. Weitere Informationen zu Richtlinien finden Sie unter Richtlinien für Clean Room-Tabellen.

Standardmäßig können Vorlagen nur von Verbrauchern ausgeführt werden. Wenn ein Anbieter eine Vorlage ausführen möchte, müssen sie den Verbraucher um eine Berechtigung bitten. Außerdem gilt: Wenn ein Verbraucher eine Vorlage hochladen möchte, muss er den Anbieter um Erlaubnis bitten.

Weitere Informationen zum Erstellen einer kundenspezifischen Vorlage finden Sie unter Kundenspezifische Vorlagen zu einem Clean Room hinzufügen und Referenz für benutzerdefinierte Clean Room-Vorlagen.

Das folgende Beispiel zeigt, wie Sie eine von Snowflake bereitgestellte Vorlage zum Clean Room hinzufügen:

CALL samooha_by_snowflake_local_db.provider.add_templates(
  $cleanroom_name,
  ['prod_overlap_analysis']);

Spaltenrichtlinien festlegen¶

Clean Room-Spaltenrichtlinien legen fest, welche Spalten aus Ihren Tabellen in Abfragen von Teilnehmern projiziert werden können. Eine Spaltenrichtlinie ist sowohl an eine Spalte als auch an eine Vorlage gebunden, sodass verschiedene Spalten mit verschiedenen Vorlagen als projiziert definiert werden können. Eine Vorlage muss in einem Clean Room vorhanden sein, bevor Sie Spaltenrichtlinien für diese Vorlage festlegen können.

Spaltenrichtlinien sind wie alle Richtlinien nur überschreiben. Das bedeutet, dass durch das Festlegen von Spaltenrichtlinien alle vorhandenen Spaltenrichtlinien, die von diesem Konto festgelegt wurden, vollständig überschrieben werden. Sowohl Anbieter als auch Verbraucher können Spaltenrichtlinien für ihre Daten festlegen. Erfahren Sie mehr über Spaltenrichtlinien.

Das folgende Beispiel zeigt, wie Sie die Projektion von vier Spalten aus der zuvor verknüpften Beispieldatenbank für Clean Rooms ermöglichen:

CALL samooha_by_snowflake_local_db.provider.set_column_policy($cleanroom_name, [
  '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']);

Freigabe für Verbraucher¶

Nur vom Anbietenden eingeladene Verbrauchende haben Zugriff auf den Clean Room. Verbraucher können einen Clean Room nicht mit anderen Verbrauchern teilen. Bestimmte Verbraucher können erst nach der Veröffentlichung auf den Clean Room zugreifen. Einladungen zum Beitritt zu einem Clean Room erfolgen auf Kontoebene, nicht auf Benutzerebene.

Das folgende Beispiel zeigt, wie Sie einen Clean Room für zwei Verbraucher freigeben. Die Prozedur benötigt zwei parallele, durch Kommas getrennte Listen von Verbraucherkonto-Locator und Data Sharing-Konto-IDs für Verbraucher.

CALL samooha_by_snowflake_local_db.provider.add_consumers(
  $cleanroom_name,
  'CONSUMER_LOCATOR1,CONSUMER_LOCATOR2',
  'CONSUMER_DATA_SHARING_ACCOUNT_ID1,CONSUMER_DATA_SHARING_ACCOUNT_ID2');

Standardversion verwenden¶

Clean Rooms sind versionierte native Anwendungen. Bestimmte Aktionen, wie das Hinzufügen von Code zu einem Clean Room, erzeugen eine neue Patchversion der Anwendung. Verbraucher müssen den Clean Room in ihrem Konto installieren. Die Version, die installiert wird, basiert auf der von Ihnen angegebenen Standardversionsnummer. Wenn Sie später eine neue Version des Clean Rooms veröffentlichen und die Standardversionsnummer erhöhen, werden alle von Verbrauchern installierten Versionen automatisch aktualisiert. Neue Installationen werden standardmäßig auf die neue Version umgestellt. Erfahren Sie mehr über die Versionierung von Clean Rooms.

Das folgende Beispiel zeigt, wie Sie die Standardversion eines Clean Rooms auf V1.0.0 einstellen. Das ist die erste Version eines Clean Rooms, wenn Sie keinen Code hochgeladen haben:

CALL samooha_by_snowflake_local_db.provider.set_default_release_directive(
  $cleanroom_name,
  'V1_0',          -- Version number: Never changes.
  '0'              -- Patch number: Can change.
  );

Clean Room veröffentlichen¶

Im folgenden Beispiel sehen Sie, wie Sie einen Clean Room veröffentlichen oder erneut veröffentlichen. Befolgen Sie diese Anweisung. Wenn dieser Prozess zum ersten Mal aufgerufen wird, macht er den Clean Room für alle Verbraucher, für die Sie ihn freigegeben haben, sichtbar und installierbar. Sie sollten diesen Prozess immer dann aufrufen, wenn Sie erhebliche Änderungen vornehmen, z. B. wenn Sie die Standardversion aktualisieren oder Änderungen speziell für die Clean Room UI vornehmen.

CALL samooha_By_snowflake_local_db.provider.create_or_update_cleanroom_listing(
  $cleanroom_name);

Jetzt kann der Verbraucher den Clean Room installieren, Daten verknüpfen, Richtlinien festlegen und Vorlagen ausführen, wie nachfolgend beschrieben.

Umgebung einrichten¶

Wie der Anbieter muss auch der Verbraucher ein Warehouse verwenden, auf das SAMOOHA_APP_ROLE zugreifen kann. Im Gegensatz zum Anbietenden kann der Verbrauchende jedoch die SAMOOHA_APP_ROLE-Rolle entweder direkt für den vollständigen API-Zugriff verwenden oder eine Person mit Administratorrechten für den Clean Room in diesem Konto kann eine eingeschränktere Rolle zuweisen, die Berechtigungen zum Ausführen einer Teilmenge der API für Verbrauchende zuweist. Diese eingeschränkte Rolle, manchmal allgemein als „Ausführungsrolle“ bezeichnet, wird von einem Benutzenden mit vollen Clean Room-Berechtigungen gewährt. Erfahren Sie, wie Sie begrenzten API-Zugriff erteilen können.

Mit einer Ausführungsrolle können Sie keinen Clean Room installieren, also müssen Sie SAMOOHA_APP_ROLE, wie im folgenden Beispiel gezeigt, verwenden:

USE WAREHOUSE app_wh;
USE ROLE SAMOOHA_APP_ROLE;

Reinraum installieren¶

Der folgende Ausschnitt zeigt, wie Sie alle installierten Clean Rooms auflisten, zu deren Installation Sie eingeladen wurden:

-- See all clean rooms, installed and not.
CALL samooha_by_snowflake_local_db.consumer.view_cleanrooms();

-- See only clean rooms that aren't installed.
CALL samooha_by_snowflake_local_db.consumer.view_cleanrooms() ->>
  SELECT * FROM $1
    WHERE IS_ALREADY_INSTALLED = false;

Installieren Sie den Clean Room, den der Anbieter für Sie freigegeben hat, wie im folgenden Beispiel gezeigt. Sie müssen den Konto-Locator des Anbieters angeben, wenn Sie einen Clean Room installieren.

CALL samooha_by_snowflake_local_db.consumer.install_cleanroom(
  $cleanroom_name,
  '<PROVIDER_ACCOUNT_LOCATOR>');

Daten hinzufügen und Richtlinien festlegen¶

Wenn die Clean Room-Vorlagen es dem Verbrauchenden ermöglichen, seine eigenen Daten in eine Abfrage einzubinden, registriert der Verbrauchende die Daten, verknüpft die Daten und legt wie der Anbietende Richtlinien fest. Stellen Sie sicher, dass Sie die consumer-Versionen der Prozesse, wie im folgenden Beispiel gezeigt, verwenden:

-- You must use a role with MANAGE GRANTS privilege on an object to register it.
USE ROLE ACCOUNTADMIN;
CALL samooha_by_snowflake_local_db.consumer.register_db('MY_DATABASE');

-- Link some tables.
CALL samooha_by_snowflake_local_db.consumer.link_datasets(
  $cleanroom_name,
  [
    'SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS',
    'MY_DATABASE.PUBLIC.EXPOSURES'
  ]);

Die Verknüpfungsrichtlinie des Anbieters zeigt, welche Anbieterspalten verknüpft werden können. Dieses Beispiel zeigt, wie Sie überprüfen, mit welchen Anbieterspalten Sie verknüpfen können:

CALL samooha_by_snowflake_local_db.consumer.view_provider_join_policy($cleanroom_name);

Ein Anbieter benötigt die Genehmigung des Verbrauchers, um eine Vorlage im Clean Room auszuführen. Daher verzichten die meisten Verbrauchenden darauf, Richtlinien für die verknüpften Tabellen festzulegen.Wir empfehlen dennoch, dass Sie das Hinzufügen von Richtlinien in Betracht ziehen, falls ein Anbietender später versucht, eine Vorlage auszuführen, da Sie vergessen könnten, die entsprechenden Richtlinien zu diesem Zeitpunkt hinzuzufügen.

Wenn Sie Richtlinien festlegen, werden diese nur durchgesetzt, wenn die Vorlage einen join_policy- oder column_policy-Filter für die Spalte in der Vorlage enthält. Stellen Sie also sicher, dass die Vorlagen, die Sie einem Clean Room hinzufügen, diese Filter enthalten, um Ihre Richtlinien durchzusetzen. Um die Vorlagen in einem Clean Room zu untersuchen, rufen Sie consumer.view_added_templates auf. Weitere Informationen zu Richtlinien finden Sie unter Richtlinien für Clean Room-Tabellen.

Analyse ausführen¶

Bevor Sie eine Vorlage ausführen, untersuchen Sie diese in der Regel, um festzustellen, was sie tut und welche Variablen sie akzeptiert. Anschließend prüfen Sie, welche Anbietertabellen im Clean Room verfügbar sind.

-- View the list of templates available in this clean room,
-- and the source code for each template.
CALL samooha_by_snowflake_local_db.consumer.view_added_templates($cleanroom_name);

-- Show which variables can be passed in when running the specified template.
CALL samooha_by_snowflake_local_db.consumer.get_arguments_from_template(
  $cleanroom_name,
  $template_name
);

-- See which datasets you have linked into the clean room.
CALL samooha_by_snowflake_local_db.consumer.view_consumer_datasets($cleanroom_name);

-- See which datasets the provider has linked into the clean room.
CALL samooha_by_snowflake_local_db.consumer.view_provider_datasets($cleanroom_name);

CALL samooha_by_snowflake_local_db.consumer.run_analysis(
$cleanroom_name,
$template_name,
[],                                              -- This template doesn't accept consumer tables.
['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],      -- Provider tables.
object_construct(                                -- Template-specific arguments.
  'dimensions', ['p.STATUS'],                    -- Template takes a variable named 'dimensions'.
  'where_clause', 'p.REGION_CODE=$$REGION_10$$'  -- Template allows you to pass in a WHERE clause.
                                                 -- $$ is used to wrap string literals
  )
);