Verwenden Sie Entwickler-APIs, um Ergebnisse zur Aktivierung an ein Snowflake-Konto zu senden¶
Anbieter können Aktivierungsvorlagen (SQL Jinja-Vorlagen) zu einem Reinraum hinzufügen, sodass Analyseergebnisse zur Aktivierung an ein Snowflake-Konto übertragen werden können.
Bei vom Anbieter durchgeführten Analysen kann der Anbieter die Ergebnisse an sein eigenes Snowflake-Konto senden (Anbieteraktivierung). Bei von Verbrauchern durchgeführten Analysen kann der Verbraucher die Ergebnisse entweder auf das Snowflake-Konto des Anbieters (Anbieteraktivierung) oder auf sein eigenes Konto (Verbraucheraktivierung) übertragen, je nachdem, wie der Anbieter die Aktivierungsvorlage konfiguriert hat.
Der Anbieter kann der Aktivierungsvorlage eine Weboberfläche hinzufügen, sodass Benutzer die Web-App verwenden können, um Ergebnisse an das Snowflake-Konto zu senden. In diesem Fall werden die Optionen zum Senden von Ergebnissen im Aktivierungs-Hub wie andere Aktivierungsoptionen angezeigt. Alternativ können Anbieter und Verbraucher mithilfe der Entwickler-APIs die Aktivierungsvorlage verwenden, um Ergebnisse zu senden.
Anbieter¶
Als Anbieter möchten Sie Folgendes tun:
Richten Sie die Aktivierungsvorlage so ein, dass sie vom Anbieter und/oder Verbraucher verwendet werden kann, um Ergebnisse an ein Snowflake-Konto zurückzuschicken.
Aktivieren Sie das Zurücksenden der Ergebnisse zum Snowflake-Konto des Anbieters.
Ergebnisse im Snowflake-Konto anzeigen
Einrichten durch den Anbieter¶
In diesem Abschnitt werden die Schritte erläutert, die ein Anbieter unternehmen kann, um eine Aktivierungsvorlage in einem Reinraum zu erstellen, hinzuzufügen und zu konfigurieren. Er enthält die folgenden Abschnitte:
Verknüpfen Sie die gewünschte Tabelle (nur Anbieteraktivierung)
Aktivieren Sie die Verbraucheraktivierung (nur von Verbrauchern durchgeführte Analysen)
Berechtigung vom Verbraucher anfragen (nur Anbieteraktivierung)
Erstellen einer Vorlage für die Anbieteraktivierung¶
Eine Vorlage zum Aktivieren von Ergebnissen ist ähnlich wie eine Vorlage zum Ausführen einer Analyse. Sie wird zum Beispiel mit dem Befehl provider.add_custom_sql_template
wie eine Analysevorlage zum Reinraum hinzugefügt. Eine Aktivierungsvorlage weist jedoch die folgenden wichtigen Unterschiede auf:
Der Name der Aktivierungsvorlage muss mit der Zeichenfolge
activation
beginnen. Eine Aktivierungsvorlage mit dem Namenactivation_my_template
erfüllt zum Beispiel die Anforderung.Die Aktivierungsvorlage muss eine Tabelle mit einem Namen erstellen, der bestimmten Konventionen entspricht und den Tabellennamen explizit zurückgibt.
Definieren Sie die Tabelle in einer Aktivierungsvorlage¶
Um die Aktivierungsergebnisse im Reinraum zu halten, muss jede Aktivierungsvorlage eine Tabelle erstellen. Für diese Tabelle gibt es zwei Anforderungen:
Der Name der Tabelle muss mit der Zeichenfolge
cleanroom.activation_data_
beginnen. Eine Tabelle mit dem Namencleanroom.activation_data_analysis_results
erfüllt zum Beispiel die Anforderung.Der Teil der Vorlagendefinition, der die Tabelle erstellt, muss die Zeichenfolge zurückgeben, die an
cleanroom.activation_data_
angehängt wurde, um den Namen der Tabelle zu bilden. Wenn der Tabellenname zum Beispielcleanroom.activation_data_analysis_results
lautet, muss die Zeichenfolgeanalysis_results
zurückgegeben werden.
Im Folgenden finden Sie ein Beispiel dafür, was in der Vorlagendefinition enthalten sein muss, um eine Tabelle zu definieren und zu exportieren:
BEGIN
CREATE OR REPLACE TABLE cleanroom.activation_data_analysis_results AS
SELECT * FROM identifier({{ my_table[0] }})
RETURN 'analysis_results';
END;
Weitere Informationen über den Aufruf des Befehls provider.add_custom_sql_template
, um eine Aktivierungsvorlage zu einem Reinraum hinzuzufügen, finden Sie unter Snowflake Data Clean Rooms: Anbieter-API-Referenzhandbuch.
Verknüpfen Sie die gewünschte Tabelle (nur Anbieteraktivierung)¶
Wenn der Anbieter oder Verbraucher Ergebnisse an das Snowflake-Konto des Anbieters weiterleiten möchte, muss der Anbieter die Tabelle samooha_by_snowflake_local_db.library.temp_public_key
mit dem Reinraum verknüpfen. Um zum Beispiel die gewünschte Tabelle mit dem Reinraum my_activation_cleanroom
führen Sie Folgendes aus:
CALL samooha_by_snowflake_local_db.provider.link_datasets(
'my_activation_cleanroom',
['samooha_by_snowflake_local_db.library.temp_public_key']);
Der Anbieter könnte auch einen einzigen Aufruf zur Verknüpfung der gewünschten Tabelle verwenden, wenn er seine anderen Tabellen und Ansichten verknüpft.
Legen Sie eine Aktivierungsrichtlinie fest¶
Eine Aktivierungsrichtlinie legt fest, welche Spalten in Aktivierungsvorlagen verwendet werden können. Dies kann bei Aktivierungsvorlagen verwendet werden, um sicherzustellen, dass nur die vom Anbieter freigegebenen Spalten mit der Aktivierungsvorlage verwendet werden können.
Ein Anbieter verwendet die provider.set_activation_policy
API, um die Aktivierungsrichtlinie festzulegen. Beispiel:
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' ]);
Aktivieren Sie die Verbraucheraktivierung (nur von Verbrauchern durchgeführte Analysen)¶
Wenn der Verbraucher die Ergebnisse an sein eigenes Konto senden will, muss der Anbieter die provider.enable_template_for_consumer_activation
API ausführen. Beispiel:
CALL samooha_by_snowflake_local_db.provider.enable_template_for_consumer_activation(
'my_cleanroom', 'activation_my_template');
Berechtigung vom Verbraucher anfragen (nur Anbieteraktivierung)¶
Wenn der Anbieter die Aktivierungsvorlage so konfiguriert, dass er sich selbst oder dem Verbraucher erlaubt, Ergebnisse an das Snowflake-Konto des Anbieters zu senden, muss der Anbieter die provider.request_provider_activation_consent
API ausführen. Diese API fragt beim Verbraucher an, die Vorlage zu diesem Zweck zu genehmigen. Beispiel:
CALL samooha_by_snowflake_local_db.provider.request_provider_activation_consent('my_cleanroom', 'activation_my_template');
Der Verbraucher muss die Anfrage genehmigen, bevor der Anbieter die Ergebnisse einer vom Anbieter durchgeführten Analyse aktivieren kann.
Aktivierung in der Web-App einrichten (optional)¶
Wenn der Anbieter eine Weboberfläche für den Reinraum erstellt, damit die Benutzer in der Web-App Analysen durchführen können, kann er den Reinraum auch so konfigurieren, dass die Benutzer die Ergebnisse über den Activation Hub in der Web-App aktivieren können. Wenn der Anbieter die provider.add_ui_form_customizations
API ausführt, um die Benutzeroberfläche zu erstellen, gibt er den Namen der Aktivierungsvorlage an und ob die Vorlage für die Anbieteraktivierung, die Verbraucheraktivierung oder beides verwendet werden soll.
Im folgenden Beispiel können Benutzer den Activation Hub sowohl für die Anbieter- als auch für die Verbraucheraktivierung verwenden.
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'
});
Aktivieren nach einer vom Anbieter durchgeführten Analyse¶
Wenn der Anbieter den Reinraum so konfiguriert hat, dass seine Benutzer die Web-App verwenden können, um Analysen auszuführen und Ergebnisse zu aktivieren, können die Benutzer nach der Ausführung einer Analyse die Schaltfläche Activate wählen, um den Activation Hub zu öffnen, wo sie das Konto des Anbieters auswählen können, um die Ergebnisse zu senden.
Wenn der Anbieter nicht die Web-App, sondern die Entwickler-APIs verwendet, um Analysen durchzuführen, kann er die submit_analysis_request
API ausführen, um die Ergebnisse zu aktivieren. Beispiel:
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'
));
Aktivierte Ergebnisse als Anbieter anzeigen¶
Nachdem der Verbraucher oder Anbieter die Ergebnisse für den Anbieter aktiviert hat, kann der Anbieter diese Ergebnisse in seinem Snowflake-Konto (nicht in der Reinraumumgebung) einsehen.
Bemerkung
Wenn der Verbraucher die Ergebnisse aktiviert hat, muss sich der Anbieter bei seiner Reinraumumgebung anmelden, bevor er sich bei seinem Snowflake-Konto anmelden kann, um die Ergebnisse zu sehen.
Weitere Informationen dazu finden Sie unter Analyseergebnisse im Snowflake-Konto des Anbieters anzeigen.
Verbraucher¶
Als Verbraucher möchten Sie Folgendes tun:
Richten Sie den Reinraum so ein, dass die Aktivierungsvorlage vom Anbieter und/oder Verbraucher verwendet werden kann, um Ergebnisse an ein Snowflake-Konto zurückzuschicken.
Aktivieren Sie das Zurücksenden der Ergebnisse zu einem Snowflake-Konto.
Ergebnisse im Snowflake-Konto anzeigen
Einrichten durch den Verbraucher¶
Verbraucher sollten eine Aktivierungsrichtlinie einrichten, bevor sie die Ergebnisse aktivieren. Für die Aktivierung des Anbieters müssen sie außerdem die Anfrage des Anbieters genehmigen.
Aktivierungsrichtlinie festlegen¶
Eine Aktivierungsrichtlinie legt fest, welche Spalten in Aktivierungsvorlagen verwendet werden können. Diese Richtlinie kann mit Aktivierungsvorlagen verwendet werden, um sicherzustellen, dass nur die Spalten, die vom Verbraucher genehmigt wurden, mit der Aktivierungsvorlage verwendet werden können.
Ein Verbraucher verwendet die consumer.set_activation_policy
API, um die Aktivierungsrichtlinie festzulegen. Beispiel:
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' ]);
Anfrage des Anbieters genehmigen (nur Anbieteraktivierung)¶
Wenn der Anbieter die provider.request_provider_activation_consent
API für eine Aktivierungsvorlage ausgeführt hat, die dazu dienen soll, Ergebnisse an das Snowflake-Konto des Anbieters zu senden, muss der Verbraucher die Anfrage genehmigen. Diese Genehmigung ist unabhängig davon erforderlich, ob es der Anbieter oder der Verbraucher ist, der die Ergebnisse auf das Konto des Anbieters sendet.
Wenn der Verbraucher die Web-App verwendet, ist die Installation des Reinraums die Zustimmung, die der Anbieter benötigt.
Wenn der Verbraucher die Entwickler-APIs verwendet, führt der Verbraucher die consumer.approve_provider_activation_consent
API aus. Beispiel:
CALL samooha_by_snowflake_local.consumer.approve_provider_activation_consent('my_cleanroom', 'activation_my_template');
Aktivieren nach einer Verbraucheranalyse¶
Wenn der Anbieter den Reinraum so konfiguriert hat, dass die Benutzer die Web-App verwenden können, um Analysen auszuführen und Ergebnisse zu aktivieren, können die Benutzer nach der Ausführung einer Analyse die Schaltfläche Activate auswählen, um den Activation Hub zu öffnen, wo sie das Konto des Anbieters (wenn die Anbieteraktivierung konfiguriert wurde) oder das Konto des Verbrauchers (wenn die Verbraucheraktivierung konfiguriert wurde) auswählen können, um Ergebnisse zu senden.
Wenn der Verbraucher nicht die Web-App, sondern die Entwickler-APIs verwendet, sendet er die Ergebnisse an ein Snowflake-Konto, indem er den Befehl consumer.run_activation
aufruft, um die Aktivierungsvorlage auszuführen, was der Ausführung des Befehls consumer.run_analysis
ähnelt. Der Unterschied ist das zweite Argument, das eine Zeichenfolge angibt, mit deren Hilfe der Inhalt der Aktivierung identifiziert werden kann.
Der Verbraucher kann zum Beispiel Folgendes aufrufen:
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'
));
Weitere Informationen über die Syntax des Befehls consumer.run_activation
finden Sie unter Snowflake Data Clean Rooms: Verbraucher-API-Referenzhandbuch.
Aktivierte Ergebnisse als Verbraucher anzeigen¶
Wenn der Verbraucher die Ergebnisse in sein eigenes Snowflake-Konto übertragen hat, kann er die Ergebnisse in Snowsight anzeigen.