Implementação da ativação em sua clean room¶

Visão geral da ativação¶

O provedor ou consumidor pode enviar os resultados do modelo para fora da clean room em um processo chamado ativação. O Snowflake é compatível com três tipos de ativação:

A ativação do provedor, em que os resultados são enviados para uma tabela na conta Snowflake do provedor.
A ativação do consumidor, em que os resultados são enviados para uma tabela na conta Snowflake do consumidor.
Ativação de terceiros, em que o provedor ou o consumidor envia os resultados para um terceiro aprovado pelo Snowflake, como o LiveRamp ou o Meta Ads Manager, por meio de um conector de ativação.

Em todos os casos, o modelo deve oferecer suporte à ativação e a outra parte deve aprovar a ativação de quaisquer colunas de seus próprios dados que serão exportados.

A ativação é compatível com a privacidade diferencial, se ativada, e respeita as regras e os orçamentos de privacidade diferencial.

Para ativar os dados de um colaborador em uma região de nuvem diferente, você deve ativar o preenchimento automático entre nuvens.

Ativação de provedor e consumidor¶

Você pode configurar uma clean room para salvar os resultados do modelo na conta Snowflake do provedor ou do consumidor. Tanto o provedor quanto o consumidor devem aprovar a ativação de quaisquer dados fora da clean room.

A ativação é implementada usando um modelo de ativação dedicado. Na UI das clean rooms, um modelo de análise pode ser associado a um modelo de análise, e o usuário pode executar o modelo de análise e visualizar os resultados e, em seguida, executar e ativar os resultados do modelo de ativação associado. O fluxo do Audience Overlap & Segmentation fornecido pelo Snowflake faz isso.

Um modelo de ativação não precisa ser idêntico ao modelo de análise associado. O modelo de ativação geralmente é um subconjunto do modelo de análise.

Modelos compatíveis¶

Os modelos a seguir oferecem suporte à ativação de provedores e consumidores:

Audience Overlap & Segmentation
Consulta SQL (somente na UI)
Modelos personalizados

Combinações compatíveis¶

A ativação pode ser executada pelo provedor ou consumidor. Você pode combinar várias combinações de análises conduzidas por provedor e consumidor com a ativação de provedor e consumidor. (Saiba mais sobre análises realizadas por provedores.)

As seguintes combinações são compatíveis:

	Ativação do provedor	Ativação do consumidor
Executada pelo provedor	✅	❌
Executada pelo consumidor	✅	✅

Resultados¶

Os resultados da ativação do provedor são salvos na tabela SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.CONSUMER_DIRECT_ACTIVATION_SUMMARY da conta de provedor.

Os resultados da ativação do consumidor são salvos na conta de consumidor na tabela SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.PROVIDER_ACTIVATION_SUMMARY.

Consulte os resultados de exibição para saber como ler os dados.

Implementação da ativação de provedor ou consumidor¶

Configuração

A ativação ao usar a UI de clean rooms exige que a conta das clean rooms permita a ativação.
Para a ativação executada pelo provedor, a clean room deve ser configurada para oferecer suporte à análise executada pelo provedor.

1. Criar ou ingressar em uma clean room

Ao criar ou ingressar em uma clean room, na etapa Configure Analysis & Query, em Activation Settings, especifique quais colunas devem ser adicionadas aos resultados ativados em sua conta.

2. Execute o modelo e ative os resultados

Para executar a ativação associada à sua análise, conclua as etapas a seguir:

Faça sua análise.
Depois de executar uma análise, selecione Results » Activate.
Em Activation Hub, selecione o nome da conta de provedor ou consumidor a ser ativada.
Forneça informações específicas ao modelo de ativação, como nomes descritivos de segmentação ou a seleção de colunas de ativação.
Forneça um nome de segmento: essa é uma cadeia de caracteres arbitrária usada para identificar um conjunto de resultados. Você pode fornecer uma cadeia de caracteres diferente para cada ativação e agrupar os resultados de cada execução separadamente ou pode usar o mesmo nome de segmento em várias execuções com variações de entrada se quiser combinar esses resultados.
Selecione Push Data.
Consulte a próxima seção para saber como visualizar os resultados ativados.

A ativação é realizada de forma diferente, dependendo de quem a executa e se é uma ativação de consumidor ou provedor.

Importante

Na primeira vez em que um consumidor ativar dados para uma conta de provedor em uma clean room, o provedor deverá estabelecer um pipeline de dados entrando na UI de clean room para essa conta e permanecendo conectado por até 30 minutos. Isso precisa ser feito apenas uma vez por clean room e por consumidor. Até que isso seja feito, os dados não aparecerão na conta de provedor, mesmo que a ativação seja bem-sucedida.

Veja como um consumidor pode enviar resultados para sua própria conta Snowflake.

Provedor

Crie a clean room, vincule conjuntos de dados e defina políticas de junção, como em uma clean room padrão.

Você pode escolher um modelo padrão Snowflake compatível ou adicionar um modelo de ativação personalizado à clean room. Se essa clean room for usada na UI, você deverá fornecer um formulário Web com os campos de ativação adequados, conforme descrito na documentação do modelo.

Acione o modelo para ativação do consumidor chamando provider.enable_template_for_consumer_activation.

Defina a política de ativação na clean room para esse modelo para especificar quais colunas do provedor podem ser ativadas. Todas as colunas usadas no modelo de ativação devem estar na política de ativação, sejam elas projetadas ou não.

Adicione colaboradores consumidores, defina a diretiva de lançamento padrão e publique a clean room, como de costume.

Consumidor

Instale a clean room, vincule conjuntos de dados e defina políticas de junção, como em uma clean room padrão.

Defina a política de ativação na clean room para esse modelo para especificar quais colunas do consumidor podem ser ativadas. Todas as colunas usadas no modelo de ativação devem estar na política de ativação, sejam elas projetadas ou não.

Execute a ativação chamando consumer.run_activation, com o último parâmetro definido como TRUE para indicar uma ativação do consumidor.

Veja os resultados, conforme descrito abaixo.

Exemplos

Faça o download dos exemplos a seguir e carregue-os como arquivos de planilha em sua conta Snowflake. Você precisará de contas separadas para o provedor e consumidor, cada uma com a API de clean rooms instalada. Substitua as informações conforme indicado nos arquivos de amostra.

Veja como um consumidor pode enviar resultados para a conta Snowflake de um provedor.

Importante

Se o consumidor e o provedor não tiverem ambos a UI de clean rooms instalada, e o consumidor estiver ativando para o provedor:

O consumidor deve executar o seguinte comando SQL:
```
ALTER SHARE SAMOOHA_INTERNAL_GOVERNANCE_SUMMARY_SHARE_NAV2
  ADD ACCOUNTS = $provider_account_data_sharing_id;
```
Copy
em que $provider_account_data_sharing_id é o identificador de conta do Data Sharing do provedor
O provedor deve executar o seguinte procedimento:
```
CALL samooha_by_snowflake_local_db.provider.mount_provider_activations_share(
  $consumer_account_data_sharing_id, TRUE, FALSE);
```
Copy
em que $consumer_account_data_sharing_id é o identificador de conta do Data Sharing do consumidor.

1. Provedor

Crie a clean room da maneira padrão.

Vincule os conjuntos de dados. O provedor também deve vincular a tabela samooha_by_snowflake_local_db.library.temp_public_key à clean room.

Defina a política de junção da maneira padrão.

Você pode escolher um modelo padrão Snowflake compatível ou adicionar um modelo de ativação personalizado à clean room. Se essa clean room for usada na UI de clean room, você deverá fornecer um formulário Web com os campos de ativação adequados.

Defina a política de ativação na clean room para esse modelo para especificar quais colunas do provedor podem ser ativadas. Todas as colunas usadas no modelo de ativação devem estar na política de ativação, sejam elas projetadas ou não.

Adicione colaboradores consumidores, defina a diretiva de lançamento padrão e publique a clean room, como de costume. (Se você não tiver a UI de clean room instalada, chame provider.setup_provider_activation_share_mount_task após adicionar os consumidores)

2. Consumidor

Instale a clean room, vincule conjuntos de dados e defina políticas de junção, como em uma clean room padrão.

Defina a política de ativação na clean room para esse modelo para especificar quais colunas do consumidor podem ser ativadas. Todas as colunas usadas no modelo de ativação devem estar na política de ativação, sejam elas projetadas ou não.

Execute a ativação chamando consumer.run_activation, com o último argumento definido como FALSE para indicar uma ativação de provedor.

3. Provedor

Na primeira vez em que um consumidor ativar os dados em sua conta, você deverá permanecer conectado na UI das clean rooms para essa conta por cerca de 30 minutos após o consumidor ter ativado os dados. Depois disso, os dados aparecerão em sua conta. Isso é feito apenas uma vez por clean room e por conta de consumidor. As ativações posteriores pelo mesmo consumidor na mesma clean room não precisam dessa etapa.

Os resultados devem ser descriptografados antes de serem salvos em sua conta, o que pode levar algum tempo. A tarefa de descriptografia atinge o tempo limite após 60 minutos; se isso acontecer, chame provider.update_activation_warehouse para aumentar o tamanho do warehouse usado para descriptografia.

Veja os resultados, conforme descrito abaixo.

Exemplos

Veja como um provedor pode enviar resultados para sua própria conta Snowflake. Isso combina várias técnicas, incluindo modelos personalizados, análise executada pelo provedor e ativação do provedor, e, portanto, envolve várias rodadas de solicitação e aprovação entre o provedor e o consumidor.

1. Provedor

Crie a clean room, vincule conjuntos de dados e defina políticas de junção, como em uma clean room padrão, com uma exceção: você deve criar o link na tabela samooha_by_snowflake_local_db.library.temp_public_key. Os dados executados pelo provedor são criptografados, o que permite a criptografia e descriptografia dos resultados.

Você pode escolher um modelo padrão Snowflake compatível ou adicionar um modelo de ativação personalizado à clean room. Se essa clean room for usada na UI, você deverá fornecer um formulário Web com os campos adequados para oferecer suporte à ativação, conforme descrito na documentação do modelo.

Defina a política de ativação na clean room para esse modelo para especificar quais colunas do provedor podem ser ativadas. Todas as colunas usadas no modelo de ativação devem estar na política de ativação, sejam elas projetadas ou não.

Adicione colaboradores consumidores da maneira padrão. Se você não tiver a UI da clean room instalada, deverá chamar provider.setup_provider_activation_share_mount_task após adicionar usuários.

Permita a análise executada pelo provedor na clean room, chamando provider.enable_provider_run_analysis. Isso deve ser feito após adicionar colaboradores, mas antes de os colaboradores instalarem a clean room. Se você alterar essa configuração depois que um consumidor instalar a clean room, o consumidor deverá reinstalar a clean room para que a alteração tenha efeito.

Defina a diretiva de lançamento padrão e publique a clean room, como de costume.

2. Consumidor

Instale a clean room, vincule os conjuntos de dados e defina as políticas de junção como em uma clean room padrão.

Defina a política de ativação na clean room para esse modelo para especificar quais colunas do consumidor podem ser ativadas. Todas as colunas usadas no modelo de ativação devem estar na política de ativação, sejam elas projetadas ou não.

3. Provedor

Solicite permissão do consumidor para executar seu modelo de ativação, chamando provider.request_provider_activation_consent.

4. Consumidor

Conceda ao provedor permissão para executar um determinado modelo nessa clean room, chamando consumer.enable_templates_for_provider_run.

Conceda ao provedor permissão para ativar os resultados de um determinado modelo nessa clean room, chamando consumer.approve_provider_activation_consent.

5. Provedor

Permita que os dados do consumidor sejam compartilhados em uma ativação de provedor, chamando provider.mount_request_logs_for_all_consumers.

Execute o modelo de ativação chamando provider.submit_analysis_request). A solicitação leva vários minutos para aparecer nos registros; verifique o status chamando provider.check_analysis_status. Observe que, mesmo após o status ser informado como SUCCESS, é necessário um tempo adicional para que os resultados sejam descriptografados e gravados na tabela Snowflake do provedor. Todos os dados descriptografados são anexados de uma só vez à tabela de resultados. Continue verificando periodicamente a tabela de resultados de seu ID de segmento ou ativação. A tarefa de descriptografia atinge o tempo limite após 60 minutos; se isso acontecer, chame provider.update_activation_warehouse para aumentar o tamanho do warehouse usado para descriptografia.

Nota

Para modificar um modelo após a aprovação do consumidor, você deve seguir os seguintes passos, caso contrário, provider.submit_analysis_request continuará executando a última versão aprovada do modelo.

O provedor atualiza o modelo chamando provider.add_custom_sql_template. Não é necessário chamar create_or_update_cleanroom_listing novamente.

O consumidor chama consumer.enable_templates_for_provider_run.

O consumidor chama consumer.approve_provider_activation_consent.

O modelo atualizado agora está pronto para ser ativado pelo provedor.

Erros comuns

Object cleanroom_name.CLEANROOM.TEMP_RESULT_DATA does not exist or not authorized – A tabela de resultados temporários não pôde ser gerada por algum motivo. Pode ser um erro de SQL no modelo ou seu modelo não gerou explicitamente uma tabela; veja os detalhes do erro.
Query validation checks failed – Algumas colunas usadas no modelo que não estavam nas políticas de ativação.

Exemplos

Exibição dos resultados da ativação de provedor e consumidor¶

Local e formato dos resultados da ativação¶

Todos os resultados de ativação do provedor são anexados a uma tabela designada pelo Snowflake. Cada linha da tabela é mapeada para uma linha no resultado de consulta. Os resultados de consulta adicionais são anexados à tabela. Você pode distinguir entre diferentes execuções pela coluna ACTIVATION_ID, que é exclusiva por ativação, e a coluna SEGMENT, que é especificada pelo chamador para cada execução de ativação.

Os resultados da ativação do provedor são armazenados em SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.PROVIDER_ACTIVATION_SUMMARY na conta de provedor.
Os resultados da ativação do consumidor são armazenados em SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.CONSUMER_DIRECT_ACTIVATION_SUMMARY na conta de consumidor.

Essas tabelas contêm as seguintes colunas:

USER_ID:: Uma linha de resultados, no formato JSON, em que as chaves são os nomes das colunas e os valores são o valor dessa coluna nessa linha. O objeto também contém uma coluna para cada argumento passado para o modelo.
ACTIVATION_ID:: Um ID exclusivo para cada solicitação. O ID é retornado de uma solicitação de ativação bem-sucedida. Você pode filtrar por essa coluna para obter todos os resultados da mesma execução de ativação ou filtrar por SEGMENT se reutilizar o mesmo nome de segmento em várias execuções. Isso é o mesmo que o ID de solicitação de consulta retornado por submit_analysis_request ou run_activation.
CLEANROOM_NAME:: Nome da clean room onde a consulta foi executada.
CONSUMER:: (Somente ativação do provedor) O consumidor que aprovou essa ativação.
PROVIDER:: (Somente ativação do consumidor) O provedor que aprovou essa ativação.
SEGMENT:: Um valor de cadeia de caracteres arbitrário que você atribui quando executa a ativação. Essa coluna permite que você junte os resultados de várias execuções de consulta.
TIMESTAMP:: Quando a ativação foi executada.

Exemplo de ativação do provedor

SELECT * FROM SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.PROVIDER_ACTIVATION_SUMMARY WHERE segment = 'my_segment';

                             USER_ID                          |   CLEANROOM_NAME |   SEGMENT  | CONSUMER |          TIMESTAMP      |  ACTIVATION_ID
"{""AGE_BAND"":55,""ITEM_COUNT"":2328,""STATUS"":""MEMBER""}" |  test activation | my_segment | ABC1234  | 2025-04-01 16:27:14.068 | cleanroomactivationdataanalysisresults20250401231728469
"{""AGE_BAND"":20,""ITEM_COUNT"":88,""STATUS"":""PLATINUM""}" |  test activation | my_segment | ABC1234  | 2025-04-01 16:27:14.068 | cleanroomactivationdataanalysisresults20250401231728469
"{""AGE_BAND"":80,""ITEM_COUNT"":18,""STATUS"":""GOLD""}"     |  test activation | my_segment | ABC1234  | 2025-04-01 16:27:14.068 | cleanroomactivationdataanalysisresults20250401231728469
...

Leitura dos resultados da ativação do provedor ou consumidor¶

Execute o comando SQL apropriado para visualizar os resultados ativados em sua conta Snowflake:

Veja os resultados da ativação do provedor

SELECT *
   FROM SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.PROVIDER_ACTIVATION_SUMMARY
   [WHERE segment = <SEGMENT_NAME>] [AND activation_id = <ACTIVATION_ID>];

Copy

Veja os resultados da ativação do consumidor

SELECT *
   FROM SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.CONSUMER_DIRECT_ACTIVATION_SUMMARY
   [WHERE segment = <SEGMENT_NAME>] [AND activation_id = <ACTIVATION_ID>];

Copy

Cada linha de dados é combinada em um objeto na coluna USER_ID. Você pode nivelar os resultados usando uma consulta como a seguinte:

-- Assuming columns AGE_BAND, STATUS, and ITEM_COUNT
SELECT
  item:"AGE_BAND",
  item:"STATUS",
  item:"ITEM_COUNT"
FROM (SELECT parse_json(user_id)
      AS item
      FROM SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.PROVIDER_ACTIVATION_SUMMARY
      WHERE segment = $segment_name)
ORDER BY item:"AGE_BAND", item:"STATUS" ASC
LIMIT 20 ;

Copy

Veja as últimas 10 linhas de resultados no Snowsight:

Abra o Snowsight e navegue até Data » Database.

Para a ativação do provedor, navegue até SAMOOHA_BY_SNOWFLAKE_LOCAL_DB » PUBLIC » Tables » PROVIDER_ACTIVATION_SUMMARY.

Para a ativação do consumidor, navegue até SAMOOHA_BY_SNOWFLAKE_LOCAL_DB » PUBLIC » Tables » CONSUMER_DIRECT_ACTIVATION_SUMMARY.

Selecione Data Preview.

Ativação de terceiros¶

A ativação de terceiros deposita os resultados de consulta na conta de um terceiro aprovado pelo Snowflake usando um conector de ativação de terceiros.

A ativação de terceiros é compatível apenas com a UI das clean rooms, e não com o uso de modelos personalizados.

A ativação durante o uso da UI das clean rooms é compatível somente se a conta das clean rooms permitir a ativação.

O administrador de clean rooms deve configurar o ambiente para oferecer suporte a conectores de ativação de terceiros, selecionar os conectores permitidos e configurá-los, antes que possam ser usados em qualquer clean room.

A ativação de terceiros oferece suporte a análises conduzidas por consumidor e provedor.

Modelos compatíveis¶

Os modelos a seguir oferecem suporte à ativação de terceiros:

Audience Overlap & Segmentation
Consulta SQL

Implementação da ativação de terceiros¶

Crie ou ingresse na clean room: ao criar ou ingressar na clean room, na etapa Configure Analysis & Query, em Activation Settings, especifique quais colunas devem ser adicionadas aos resultados ativados em sua conta.
Ativar resultados:
1. Faça sua análise.
2. após executar uma análise, selecione Results » Activate.
3. Em Activation Hub, selecione o nome do provedor de terceiros para o qual deseja ativar.
4. Forneça informações específicas ao provedor. Isso pode ser feito fornecendo nomes descritivos ou selecionando quais colunas serão ativadas. As dicas de ferramentas na página devem fornecer informações adicionais sobre esse provedor.
5. Selecione Push Data.