Análise de consumidores com vários provedores¶

Um consumidor pode executar uma análise em várias clean rooms pertencentes ao mesmo ou a vários provedores em uma única solicitação e ver os resultados combinados. Os resultados são uma junção de resultados de análise de cada clean room, não os dados do consumidor analisados em relação a uma junção de dados do provedor em várias clean rooms.

Os provedores podem ver todos os detalhes da solicitação, inclusive quais outras clean rooms estão sendo consultadas e o modelo antes de aprovar a solicitação. Os provedores não podem ver os dados de outras clean rooms, nem mesmo quais tabelas de provedores estão sendo consultadas em outras clean rooms. Os dados de cada clean room são acessados e manipulados com segurança e em conformidade com as políticas de junção, coluna e outras políticas de cada clean room.

Os resultados da análise de vários provedores podem ser ativados se a ativação estiver habilitada em todas as clean rooms.

Requisitos¶

Modelos: a análise de vários provedores pode ser executada em qualquer modelo personalizado ou fornecido pela Snowflake.
Ambientes: a análise de vários provedores pode ser implementada somente com o uso da API de Clean Room. Ela não pode ser executada na UI de clean rooms.
Faturamento: o consumidor paga pelas consultas de vários provedores.
Outros requisitos: todas as clean rooms em uma análise com vários provedores devem ter uma política de associação de provedores. Se a análise falhar em qualquer clean room, toda a solicitação falhará.

Visão geral da análise de vários provedores¶

Aqui está uma visão geral de alto nível de como funciona a análise de vários provedores. Consulte as amostras de código para obter um código de amostra executável.

O consumidor instala todas as clean rooms para usar no fluxo de vários provedores, da maneira padrão. As clean rooms em uma análise de vários provedores são clean rooms padrão.
O consumidor vincula conjuntos de dados e define políticas de junção da maneira padrão. Todas as clean rooms de provedor e consumidor devem ter políticas de junção definidas, independentemente de a política ser ou não verificada pelo modelo.
A solicitação é para um único modelo, e todas as clean rooms devem ter esse modelo instalado. Se o consumidor quiser usar um modelo personalizado, ele deverá passar pelo fluxo de solicitação de modelo de consumidor padrão:
1. O consumidor chama consumer.create_template_request em cada clean room, passando o modelo personalizado.
2. O provedor chama provider.list_pending_template_requests para ver as solicitações de modelos pendentes e, em seguida, chama provider.approve_template_request para aprovar a adição do modelo à sua clean room.
3. O consumidor chama consumer.list_template_requests para saber se a solicitação foi concedida.
Os provedores e o consumidor definem políticas de coluna para o modelo, da maneira padrão.
O provedor chama provider.enable_multiprovider_computation em cada clean room para atender às solicitações do consumidor. (As solicitações enviadas antes dessa chamada são colocadas na fila, mas não são visíveis para o provedor até que esse procedimento seja chamado)
O consumidor solicita aprovação para executar um modelo. Existem algumas variações no fluxo de solicitação e aprovação, mas este é o fluxo padrão:
1. O consumidor envia uma solicitação de vários provedores para todas as clean rooms, chamando consumer.prepare_multiprovider_flow. Essa solicitação especifica a lista de clean rooms, o modelo usado e todos os parâmetros do modelo, incluindo as tabelas de provedor e consumidor. A chamada é feita apenas uma vez e é transmitida para todas as clean rooms na solicitação. Cada clean room vê todos os detalhes da solicitação, mas a lista da tabela de provedores é filtrada para as tabelas de provedores dessa clean room. Ela retorna um ID de solicitação.
2. Cada provedor chama provider.view_multiprovider_requests para ver as solicitações de vários provedores enviadas pelo consumidor e, em seguida, chama provider.process_multiprovider_request para aprová-las.
Quando todas as clean rooms tiverem aprovado a solicitação, o consumidor chamará consumer.execute_multiprovider_flow para executar a solicitação. O modelo é executado em cada clean room com as informações fornecidas na solicitação consumer.prepare_multiprovider_flow mais recente, e os resultados combinados são enviados ao consumidor. O consumidor pode chamar execute_multiprovider_flow novamente sem outra aprovação até que um provedor revogue a permissão para a consulta ou o consumidor fique sem o orçamento de privacidade diferencial (se a privacidade diferencial estiver ativada).

Detalhes da solicitação e aprovação¶

Aqui estão os detalhes sobre o processo de solicitação e aprovação. Há diversas variações no processo.

Variações no fluxo de solicitação e aprovação¶

Há três fluxos possíveis ao executar uma análise de vários provedores:

Aprovação por solicitação (comportamento padrão):

O consumidor chama consumer.prepare_multiprovider_flow com os detalhes da consulta.
O provedor vê a consulta (provider.view_multiprovider_requests) e a aprova (provider.process_multiprovider_request). Essa etapa pode ser omitida se o provedor tiver aprovado previamente essa consulta.
O consumidor executa a consulta (consumer.execute_multiprovider_flow).

Aprovação por consumidor e por clean room:

O consumidor chama consumer.prepare_multiprovider_flow com os detalhes da consulta.
O provedor vê a consulta (provider.view_multiprovider_requests) e a aprova (provider.process_multiprovider_request), transmitindo -1 como o ID de consulta em vez do ID de consulta real. Como resultado, o consumidor ainda deve chamar consumer.prepare_multiprovider_flow em solicitações futuras, mas a aprovação será concedida automaticamente, sem aprovação adicional do provedor.
O consumidor executa a consulta (consumer.execute_multiprovider_flow).

Aprovação automatizada:

O provedor chama provider.resume_multiprovider_tasks na clean room. Todas as solicitações de consumidor com vários provedores nessa clean room serão aprovadas automaticamente.
O consumidor chama consumer.prepare_multiprovider_flow com os detalhes da consulta. A solicitação é aprovada automaticamente.
O consumidor executa a consulta (consumer.execute_multiprovider_flow).

Em todos os fluxos, você pode revogar qualquer aprovação de consulta concedida anteriormente.

Critérios para aprovação de consulta¶

consumer.execute_multiprovider_flow avalia a última consulta enviada para consumer.prepare_multiprovider_flow para verificar se ela já foi aprovada. Se for encontrada uma solicitação aprovada correspondente, a consulta prosseguirá. Se nenhuma solicitação correspondente anterior for encontrada, consumer.execute_multiprovider_flow falhará. (Se a aprovação geral tiver sido concedida a esse consumidor ou a todos os consumidores, a verificação de aprovação será ignorada) As aprovações anteriores são comparadas com os seguintes valores:

A lista de clean rooms que estão sendo consultadas.

Nomes de argumento enviados para a clean room. Todos os nomes de argumentos presentes na solicitação aprovada devem estar presentes na nova solicitação. Os valores dos argumentos não são verificados, apenas os nomes dos argumentos.

Nome do modelo que está sendo executado.

Além disso, o modelo deve estar em conformidade com todas as políticas de clean room, incluindo políticas de linha, políticas de coluna e privacidade diferencial (se ativada), independentemente de as aprovações gerais terem sido dadas ou não.

Histórico de aprovações¶

consumer.execute_multiprovider_flow tenta executar a última consulta enviada para consumer.prepare_multiprovider_flow. A consulta poderá ser executada se todas as verificações de segurança forem aprovadas e se uma consulta correspondente tiver sido aprovada no passado. Portanto, você pode ver um fluxo como este:

O consumidor prepara a consulta A.
O provedor aprova A.
O consumidor executa A.
O consumidor prepara a consulta B.
O provedor aprova B.
O consumidor executa B.
O consumidor prepara a consulta A novamente, com todos os mesmos parâmetros.
O consumidor pode executar A novamente sem a aprovação do provedor, porque já foi aprovado. Consulte a próxima seção para saber como a clean room determina se uma consulta já foi aprovada.

Ativação ou desativação das aprovações de consulta automatizada¶

As aprovações de consultas podem ser automatizadas por consumidor, ou para todos os consumidores, em uma clean room.

Para aprovar automaticamente todas as consultas de vários provedores de um determinado consumidor na clean room, o provedor chama provider.process_multiprovider_request com -1 como o ID de consulta. Todas as solicitações de vários provedores desse consumidor nessa clean room serão então aprovadas. (O consumidor ainda deve chamar consumer.prepare_multiprovider_flow ao alterar a consulta, e o provedor ainda verá todas as chamadas consumer.prepare_multiprovider_flow no histórico de solicitações provider.view_multiprovider_requests) Para desativar a aprovação automática concedida a um determinado usuário, você deve atualizar o log de aprovação.

Para aprovar automaticamente todas as consultas de vários provedores para todos os consumidores, o provedor chama provider.resume_multiprovider_tasks na clean room. Todas as solicitações de vários provedores de todos os consumidores serão então aprovadas automaticamente. (O consumidor ainda deve chamar consumer.prepare_multiprovider_flow ao alterar a consulta, e o provedor ainda verá todas as chamadas consumer.prepare_multiprovider_flow no histórico de solicitações provider.view_multiprovider_requests) Para desativar a aprovação automática concedida dessa forma, chame provider.suspend_multiprovider_tasks.

Projetando seu modelo¶

O fluxo de vários provedores é demorado para testar e tem muitas etapas que podem ocultar um erro de modelo; portanto, certifique-se de que seu modelo está correto antes de usá-lo, testando-o em um fluxo básico criado pelo provedor e executado pelo consumidor antes de usá-lo em um fluxo de vários provedores.

Cada clean room executa exatamente o mesmo modelo, mas a lista source_table passada para cada clean room pode variar em tamanho e nome de tabela, pois a lista é filtrada para mostrar apenas as tabelas de provedores dessa clean room. Portanto, dependendo da consulta, talvez seja necessário usar o looping e as instruções condicionais Jinja para lidar com a variação do tamanho da lista ou dos nomes das tabelas.

Gerenciamento de aprovações automatizadas e alteração do status de aprovação¶

Log do histórico de solicitações¶

Quando o provedor chama provider.enable_multiprovider_computation, isso cria uma tabela nomeada de registro samooha_cleanroom_cleanroom_ID.admin.request_log_multiprovider. Sempre que um provedor aprova uma análise de vários provedores para uma clean room, a solicitação é registrada aqui. Essa é a tabela que as clean rooms verificam quando um consumidor solicita a execução de uma consulta de vários provedores. A tabela inclui uma coluna approved que indica se a solicitação tem permissão para ser executada. Como uma consulta deve ser aprovada antes de ser adicionada à tabela, o status inicial approved será true, mas você pode alterá-lo posteriormente se decidir revogar a aprovação.

A tabela de registro contém as solicitações de consulta do consumidor em provider.process_multiprovider_request, e não as execuções de consulta pelo consumidor. As execuções de consultas do consumidor não são registradas.

Negação de uma solicitação previamente aprovada¶

Para negar uma solicitação previamente aprovada, você deve atualizar a coluna approved na tabela de registro de solicitações de vários provedores para FALSE.

Como um consumidor pode enviar a mesma consulta várias vezes, e qualquer aprovação para uma determinada consulta permite que ela seja executada, a maneira mais segura de desativar uma consulta de vários provedores é definir approved=false para todas as consultas de um determinado consumidor e, em seguida, dizer ao consumidor para reenviar todas as consultas que deseja executar chamando consumer.prepare_multiprovider_flow.

-- Revoke access to a query you had previously approved
UPDATE samooha_cleanroom_Samooha_Cleanroom_Multiprovider_Clean_Room_1.admin.request_log_multiprovider
  SET APPROVED=FALSE
  WHERE PARTY_ACCOUNT='<CONSUMER_LOCATOR>';

Copy

Habilitação de uma solicitação negada anteriormente¶

Se você aprovou uma solicitação anteriormente, depois a negou e deseja aprová-la novamente, geralmente é mais seguro pedir a um consumidor que reenvie sua solicitação de fluxo e, em seguida, aprová-la no fluxo padrão, em vez de atualizar a tabela de log de solicitações.

Revogação de aprovações automatizadas¶

Se você ativou a aprovação automática para todos os consumidores em uma clean room chamando provider.resume_multiprovider_tasks, chame provider.suspend_multiprovider_tasks para revogar as aprovações gerais para todos os usuários.
Se você ativou a aprovação automática para um consumidor específico em uma clean room, especificando -1 como o ID de consulta em provider.process_multiprovider_request, consulte Negação de uma solicitação previamente aprovada.

Amostras de código¶

Faça o download das seguintes pastas de trabalho para experimentar o fluxo de análise de vários provedores. Você precisa de duas contas Snowflake com a API de clean rooms instalada: uma para servir como provedor e outra como consumidor. A conta de provedor cria duas clean rooms, que se comportam de forma semelhante a ter vários provedores com uma clean room cada.