使用开发者 APIs 将结果发送到 Snowflake 账户进行激活¶

提供商可以将激活模板（SQL Jinja 模板）添加到 clean room，以便可以将分析结果推送到 Snowflake 账户进行激活。

对于提供商运行分析，提供商可以将结果推送到自己的 Snowflake 账户（提供商激活）。对于使用者运行分析，使用者可以将结果推送到提供商的 Snowflake 账户（提供商激活）或自己的账户（使用者激活），具体取决于提供商如何配置激活模板。

提供商可以在激活模板中添加用户界面，以便用户可以使用 Web 应用程序将结果推送到 Snowflake 账户。在这种情况下，推送结果的选项会像其他激活选项一样显示在 Activation Hub。或者，提供商和使用者可以使用开发者 APIs，通过激活模板来推送结果。

提供商¶

作为提供商，您要执行以下步骤：

设置激活模板，以便提供商和/或使用者可以使用模板将结果推送回 Snowflake 账户。
将激活结果返回提供商的 Snowflake 账户。
在 Snowflake 账户中查看结果

提供商设置¶

本部分讨论提供商在 clean room 中创建、添加和配置激活模板的步骤。它包含以下部分：

创建提供商激活模板
在激活模板中定义表
链接所需表（仅提供商激活）
设置激活策略
启用使用者激活（仅使用者运行分析）
向使用者请求权限（仅提供商激活）
在 Web 应用程序中设置激活（可选）

创建提供商激活模板¶

用于激活结果的模板与用于运行分析的模板类似。例如，如同分析模板一样，使用 provider.add_custom_sql_template 命令将其添加到 clean room。但是，激活模板具有以下重要区别：

激活模板的名称必须以字符串 activation 开头。例如，名为 activation_my_template 的激活模板满足要求。
激活模板必须创建表，其名称必须符合特定约定并显式返回表名称。

在激活模板中定义表¶

要在 clean room 中保存激活结果，每个激活模板都必须创建表。此表有两个要求：

表的名称必须以字符串 cleanroom.activation_data_ 开头。例如，名为 cleanroom.activation_data_analysis_results 的表满足要求。
创建表的模板定义部分必须返回追加到 cleanroom.activation_data_ 的字符串以构成表的名称。例如，如果表名称是 cleanroom.activation_data_analysis_results，则必须返回字符串 analysis_results。

以下是一个示例，说明了定义表并将其导出必须包含在模板定义中的内容：

BEGIN
  CREATE OR REPLACE TABLE cleanroom.activation_data_analysis_results AS
    SELECT * FROM identifier({{ my_table[0] }})
  RETURN 'analysis_results';
END;

Copy

有关调用 provider.add_custom_sql_template 命令向 clean room 添加激活模板的更多信息，请参阅 Snowflake Data Clean Room：提供商 API 参考指南。

链接所需表（仅提供商激活）¶

如果提供商或使用者要将结果推送到提供商的 Snowflake 账户，提供商必须将 samooha_by_snowflake_local_db.library.temp_public_key 表链接到 clean room。例如，要将所需的表链接到 clean room my_activation_cleanroom，请执行：

CALL samooha_by_snowflake_local_db.provider.link_datasets(
    'my_activation_cleanroom',
    ['samooha_by_snowflake_local_db.library.temp_public_key']);

Copy

提供商还可以在链接其他表和视图时使用单个调用来链接所需的表。

设置激活策略¶

激活策略定义了哪些列可以在激活模板中使用。这可以与激活模板一起使用，以确保只有提供商批准的列可以与激活模板一起使用。

提供商使用 provider.set_activation_policy API 设置激活策略。例如：

CALL samooha_by_snowflake_local_db.provider.set_activation_policy('my_cleanroom', [
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAME.DEMO.CUSTOMERS:HASHED_EMAIL',
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAME.DEMO.CUSTOMERS:STATUS',
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAME.DEMO.CUSTOMERS:AGE_BAND',
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAME.DEMO.CUSTOMERS:DAYS_ACTIVE',
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAME.DEMO.CUSTOMERS:REGION_CODE' ]);

Copy

启用使用者激活（仅使用者运行分析）¶

如果使用者要将结果推送到自己的账户，提供商必须执行 provider.enable_template_for_consumer_activation API。例如：

CALL samooha_by_snowflake_local_db.provider.enable_template_for_consumer_activation(
    'my_cleanroom', 'activation_my_template');

Copy

向使用者请求权限（仅提供商激活）¶

如果提供商将激活模板配置为允许自己或使用者将结果推送到提供商的 Snowflake 账户，提供商必须执行 provider.request_provider_activation_consent API。此 API 请求使用者批准模板用于此目的。例如：

CALL samooha_by_snowflake_local_db.provider.request_provider_activation_consent('my_cleanroom', 'activation_my_template');

Copy

使用者必须批准请求，然后提供商才能激活提供商运行分析结果。

在 Web 应用程序中设置激活（可选）¶

如果提供商正在为 clean room 创建用户界面，以便用户可以在 Web 应用程序中运行分析，他们还可以配置 clean room，以便用户可以使用 Web 应用程序中的 Activation Hub 激活结果。提供商执行 provider.add_ui_form_customizations API 创建用户界面时，会指定激活模板的名称以及该模板是否用于提供商激活、使用者激活或两者兼有。

例如，以下示例允许用户使用 Activation Hub 进行提供商激活和使用者激活。

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

提供商运行分析后激活¶

如果提供商配置了 clean room 以便其用户可以使用 Web 应用程序运行分析和激活结果，那么用户可以在运行分析后选择 Activate 按钮以打开 Activation Hub，在此可以选择提供商账户来推送结果。

如果提供商使用开发者 APIs 而不是 Web 应用程序运行分析，他们可以执行 submit_analysis_request API 以激活结果。例如：

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

作为提供商查看已激活的结果¶

在使用者或提供商将结果激活到提供商之后，提供商可以在他们的 Snowflake 账户（不是 clean room 环境）中查看这些结果。

备注

如果使用者激活了结果，提供商必须在登录到其 Snowflake 账户查看结果之前登录到 clean room 环境。

有关更多信息，请参阅在提供商的 Snowflake 账户中查看分析结果。

使用者¶

作为使用者，您要执行以下步骤：

设置 clean room，以便提供商和/或使用者可以使用激活模板将结果推送回 Snowflake 账户。
将激活结果返回 Snowflake 账户。
在 Snowflake 账户中查看结果

使用者设置¶

使用者应在激活结果之前设置激活策略。对于提供商激活，他们还需要批准提供商的请求。

设置激活策略¶

激活策略定义了哪些列可以在激活模板中使用。此策略可以与激活模板一起使用，以确保只有使用者批准的列可以与激活模板一起使用。

使用者使用 consumer.set_activation_policy API 设置激活策略。例如：

CALL samooha_by_snowflake_local_db.consumer.set_activation_policy('my_cleanroom', [
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAME.DEMO.CUSTOMERS:HASHED_EMAIL',
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE_NAME.DEMO.CUSTOMERS:REGION_CODE' ]);

Copy

批准提供商的请求（仅提供商激活）¶

如果提供商执行了 provider.request_provider_activation_consent API，以激活模板将结果发送到提供商的 Snowflake 账户，那么使用者必须批准该请求。无论将结果发送到提供商账户的是提供商还是使用者，都需要此批准。

如果使用者使用的是 Web 应用程序，安装 clean room 需要征得提供商的同意。

如果使用者使用的是开发者 APIs，使用者将执行 consumer.approve_provider_activation_consent API。例如：

CALL samooha_by_snowflake_local.consumer.approve_provider_activation_consent('my_cleanroom', 'activation_my_template');

Copy

使用者运行分析后激活¶

如果提供商配置了 clean room 以便用户可以使用 Web 应用运行分析和激活结果，那么用户可以在运行分析后选择 Activate 按钮以打开 Activation Hub，在此可以选择提供商账户（如果配置了提供商激活）或使用者账户（如果配置了使用者激活）来推送结果。

如果使用者使用的是开发者 APIs 而不是 Web 应用程序，使用者将通过调用 consumer.run_activation 命令执行激活模板将结果发送到 Snowflake 账户，这与执行 consumer.run_analysis 命令类似。区别在于第二个实参，它指定帮助识别激活内容的字符串。

例如，使用者可以调用：

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

有关 consumer.run_activation 命令语法的更多信息，请参阅 Snowflake Data Clean Room：使用者 API 参考指南。

作为使用者查看已激活的结果¶

如果使用者将结果推送到自己的 Snowflake 账户，他们可以在 Snowsight 中查看结果。