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:

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 Namen activation_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 Namen cleanroom.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 Beispiel cleanroom.activation_data_analysis_results lautet, muss die Zeichenfolge analysis_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;
Copy

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.

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' ]);
Copy

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');
Copy

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');
Copy

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'
  });
Copy

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'
));
Copy

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' ]);
Copy

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');
Copy

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'
));
Copy

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.