Como usar as APIs de desenvolvedor para enviar resultados a uma conta Snowflake para ativação¶

Criação de um modelo para ativação do provedor¶

Um modelo usado para ativar resultados é semelhante a um modelo usado para executar uma análise. Por exemplo, ele é adicionado à sala limpa com o comando provider.add_custom_sql_template como um modelo de análise. No entanto, um modelo de ativação tem as seguintes diferenças importantes:

• O nome do modelo de ativação deve começar com a cadeia de caracteres activation. Por exemplo, um modelo de ativação chamado activation_my_template atende ao requisito.

• O modelo de ativação deve criar uma tabela com um nome que esteja em conformidade com convenções específicas e retorne explicitamente o nome da tabela.

Definição da tabela em um modelo de ativação¶

Para armazenar os resultados da ativação na sala limpa, cada modelo de ativação deve criar uma tabela. Existem dois requisitos para esta tabela:

• O nome da tabela deve começar com a cadeia de caracteres cleanroom.activation_data_. Por exemplo, uma tabela chamada cleanroom.activation_data_analysis_results atende ao requisito.

• A parte da definição do modelo que cria a tabela deve retornar a cadeia de caracteres que foi anexada em cleanroom.activation_data_ para formar o nome da tabela. Por exemplo, se o nome da tabela for cleanroom.activation_data_analysis_results, a cadeia de caracteres analysis_results deverá ser retornada.

A seguir está um exemplo do que deve ser incluído na definição do modelo para definir uma tabela e exportá-la:

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

Para obter mais informações sobre como chamar o comando provider.add_custom_sql_template para adicionar um modelo de ativação a uma sala limpa, consulte Snowflake Data Clean Rooms: Guia de referência da API do provedor.

Vinculação da tabela necessária (somente ativação do provedor)¶

Se o provedor ou consumidor for enviar os resultados para a conta Snowflake do provedor, ele deverá vincular a tabela samooha_by_snowflake_local_db.library.temp_public_key à sala limpa. Por exemplo, para vincular a tabela necessária a uma sala limpa my_activation_cleanroom, execute:

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

O provedor também poderia usar uma única chamada para vincular a tabela necessária ao vincular suas outras tabelas e exibições.

Definição de uma política de ativação¶

Uma política de ativação define quais colunas podem ser usadas nos modelos de ativação. Isso pode ser usado com modelos de ativação para garantir que somente as colunas aprovadas pelo provedor possam ser usadas com o modelo de ativação.

Um provedor usa a API provider.set_activation_policy para definir a política de ativação. Por exemplo:

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

Habilitação da ativação do consumidor (somente análises executadas pelo consumidor)¶

Se o consumidor for enviar os resultados para sua própria conta, o provedor deverá executar a API provider.enable_template_for_consumer_activation. Por exemplo:

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

Solicitação de permissão do consumidor (somente ativação do provedor)¶

Se o provedor configurar o modelo de ativação para permitir que ele próprio ou o consumidor envie resultados para a conta Snowflake do provedor, o provedor deverá executar a API provider.request_provider_activation_consent. Esta API solicita que o consumidor aprove o modelo para essa finalidade. Por exemplo,

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

O consumidor precisa aprovar a solicitação antes que o provedor possa ativar os resultados de uma análise executada pelo provedor.

Configuração da ativação no aplicativo da Web (opcional)¶

Se o provedor estiver criando uma interface de usuário para a sala limpa para que os usuários possam executar análises no aplicativo da Web, ele também poderá configurar a sala limpa para que os usuários possam ativar os resultados usando o hub de ativação no aplicativo da Web. Quando o provedor executa a API provider.add_ui_form_customizations para criar a interface de usuário, ele especifica o nome do modelo de ativação e se o modelo está sendo usado para ativação do provedor, do consumidor ou de ambos.

Por exemplo, o exemplo a seguir permite que os usuários usem o hub de ativação tanto para a ativação do provedor quanto para a ativação do consumidor.

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

Definição da política de ativação¶

Uma política de ativação define quais colunas podem ser usadas nos modelos de ativação. Essa política pode ser usada com modelos de ativação para garantir que somente as colunas aprovadas pelo consumidor possam ser usadas com o modelo de ativação.

Um consumidor usa a API consumer.set_activation_policy para definir a política de ativação. Por exemplo:

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

Aprovação da solicitação do provedor (somente ativação do provedor)¶

Se o provedor tiver executado a API provider.request_provider_activation_consent para um modelo de ativação destinado a ser usado para enviar resultados para a conta Snowflake do provedor, o consumidor deverá aprovar a solicitação. Essa aprovação é necessária independentemente de ser o provedor ou o consumidor que está enviando os resultados para a conta do provedor.

Se o consumidor estiver usando o aplicativo da Web, a instalação da sala limpa fornecerá o consentimento de que o provedor precisa.

Se o consumidor estiver usando as APIs de desenvolvedor, ele executará a API consumer.approve_provider_activation_consent. Por exemplo:

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