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 müssen die Verbraucher 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 Ansicht im Clean Room, die auf dem angegebenen Quellobjekt basiert. Sie sollten jedoch bei allen Prozessen in Clean Rooms ein verknüpftes Objekt über seinen Quellennamen angeben und nicht über seinen internen Ansichtsnamen.

Auf Daten, die mit dem Clean Room verknüpft sind, können Clean Room-Teilnehmer nicht direkt zugreifen, sondern nur über eine Vorlage innerhalb des Clean Rooms.

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 enthaltendes 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. Die Registrierung erfolgt auf Kontoebene, nicht auf der Ebene des Clean Rooms. Die Registrierung ist in der UI leichter zu bewerkstelligen und zu verwalten. 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. Wenn Sie keine Verknüpfungsrichtlinien für Ihre Daten festlegen, sind standardmäßig alle Spalten verknüpfbar. Spalten, die durch eine Verknüpfungsrichtlinie geschützt sind, können nicht projiziert werden. Ihre eigenen Verknüpfungsrichtlinien schränken Ihre eigenen Abfragen nicht ein.

Clean Rooms unterstützen einige 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 Ansichten weitergegeben, die erstellt werden, wenn Sie Daten verknüpfen. 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 fast immer 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 die meisten davon können nur in der UI verwendet werden. Daher werden Sie wahrscheinlich Ihre eigenen benutzerdefinierten Vorlagen für die Verbraucher (oder sich selbst) schreiben, die Sie in der ausführen API-, ,.

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. Wenn Sie keine Spaltenrichtlinie für Ihre Daten angeben, können alle Ihre Spalten projiziert werden. 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¶

Der Anbieter definiert, wer als Verbraucher auf den Clean Room zugreifen kann. Bestimmte Verbraucher können erst nach der Veröffentlichung auf den Clean Room zugreifen. Nur vom Anbieter hinzugefügte Konten können auf den Clean Room zugreifen. Verbraucher können einen Clean Room nicht mit anderen Verbrauchern teilen.

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 Anbieter kann der Verbraucher jedoch die SAMOOHA_APP_ROLE-Rolle direkt für vollständigen API-Zugriff verwenden. Alternativ kann ein Clean Room-Administrator in diesem Konto eine eingeschränktere Rolle zuweisen, die Berechtigungen zum Ausführen einer Teilmenge der API für Verbraucher zuweist. Diese eingeschränkte Rolle, manchmal allgemein als „Ausführungsrolle“ bezeichnet, wird von einem Benutzer mit vollen Clean Room-Berechtigungen gewährt. Lesen 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 Verbraucher ermöglichen, seine eigenen Daten in eine Abfrage einzubinden, registriert der Verbraucher die Daten, verknüpft die Daten und legt Richtlinien fest, ähnlich wie der Anbieter. Stellen Sie sicher, dass Sie die consumer-Versionen dieser 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 machen sich die meisten Verbraucher nicht die Mühe, Richtlinien für die Tabellen festzulegen, für die sie Verknüpfungen durchführen.

Wir empfehlen dennoch, dass Sie das Hinzufügen von Richtlinien in Betracht ziehen, falls ein Anbieter später versucht, eine Vorlage auszuführen, da Sie vergessen könnten, die entsprechenden Richtlinien zu diesem Zeitpunkt hinzuzufügen. Wenn Sie keine Verknüpfungs- oder Spalteneigenschaften für Ihre Daten festlegen, sind alle Spalten verknüpfbar und projiziert.

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 templates available in this clean room.
-- Also shows the template 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
  )
);