Activation des résultats de la requête¶

Aperçu de l’activité¶

Le fournisseur ou le consommateur peut envoyer les résultats du modèle en dehors de la clean room dans le cadre d’une activité appelée activation. Snowflake supporte trois types d’activité :

Activation du fournisseur, où les résultats sont poussés vers une table dans le compte Snowflake du fournisseur.
Activation du consommateur, où les résultats sont poussés vers une table dans le compte Snowflake du consommateur.
Activation par un tiers, où le fournisseur ou le consommateur pousse les résultats vers un tiers approuvé par Snowflake, tel que LiveRamp ou Meta Ads Manager, par le biais d’un connecteur d’activation.

Dans tous les cas, le modèle doit prendre en charge l’activation, et les parties prenantes doivent approuver l’activation pour toutes les colonnes de leurs propres données qui seront activées. Les fournisseurs de données spécifient quelles colonnes de leurs données sont activées en définissant une politique d’activation. Pour en savoir plus sur les politiques de salle blanche, voir Comprendre les politiques relatives aux tables de clean room.

L’activation prend en charge la protection différentielle de la vie privée, si elle est activée, et respecte les règles et les budgets de protection différentielle de la vie privée.

Important

Si le consommateur et le fournisseur se trouvent dans des régions Cloud différentes, vous devez activer Exécution automatique inter-cloud dans les comptes et pour les deux salles blanches.

Activation des fournisseurs et des consommateurs¶

Vous pouvez configurer une clean room pour qu’elle enregistre les résultats du modèle dans le compte Snowflake du fournisseur ou du consommateur. Le fournisseur et le consommateur doivent tous deux approuver l’activation de toute donnée sortant de la clean room.

L’activation est mise en œuvre à l’aide d’un modèle d’activation dédié. Dans l’UI des salles blanches, un modèle d’activation peut être associé à un modèle d’analyse, et l’utilisateur peut exécuter le modèle d’analyse, voir les résultats, puis exécuter le modèle d’activation associé. Le flux Audience Overlap & Segmentation fourni par Snowflake fait cela.

Un modèle d’activation ne doit pas nécessairement être identique à un modèle d’analyse associé. Le modèle d’activation est souvent un sous-ensemble du modèle d’analyse.

Modèles pris en charge¶

Les modèles suivants permettent l’activation du fournisseur et du consommateur :

Audience Overlap & Segmentation
Modèles personnalisés

Combinaisons prises en charge¶

L’activation peut être lancée par le fournisseur ou par le consommateur. (En savoir plus sur les analyses effectuées par le fournisseur.)

Les combinaisons suivantes sont possibles :

	Activation du fournisseur	Activation du consommateur	Activation par un tiers
Gestion par le fournisseur	✅	❌	UI uniquement
Gestion par le consommateur	✅	✅	UI uniquement

Résultats¶

Les Résultats de l’activation du fournisseur sont enregistrés sur le compte du fournisseur dans la table SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.PROVIDER_ACTIVATION_SUMMARY.

Les Résultats de l’activation du consommateur sont enregistrés sur le compte du consommateur dans la table SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.CONSUMER_DIRECT_ACTIVATION_SUMMARY.

Reportez-vous à pour consulter les résultats afin de savoir comment lire les données.

Mise en œuvre de l’activation du fournisseur ou du consommateur¶

Configuration

L’activation lors des UI de clean room exige que le compte des clean rooms permette l’activation.
Pour l’activation par le fournisseur, la clean room doit être configurée pour prendre en charge l’analyse par le fournisseur.

1. Créez ou rejoignez une clean room

Lorsque vous créez ou rejoignez une clean room, à l’étape Configure Analysis & Query, sous Activation Settings, indiquez quelles colonnes doivent être ajoutées aux résultats activés sur votre compte.

2. Exécutez le modèle et activez les résultats

Pour exécuter l’activation associée à votre analyse, procédez comme suit :

Exécutez votre analyse.
Après avoir exécuté une analyse, sélectionnez Results » Activate.
Sous Activation Hub, sélectionnez le nom du compte fournisseur ou consommateur à activer.
Fournissez des informations spécifiques au modèle d’activation, par exemple en fournissant des noms de segmentation descriptifs ou en sélectionnant des colonnes d’activation.
Indiquez un nom de segment : il s’agit d’une chaîne arbitraire utilisée pour identifier un ensemble de résultats d’une exécution donnée. Vous pouvez fournir une chaîne différente pour chaque activation afin de regrouper les résultats de chaque exécution séparément ou vous pouvez utiliser le même nom de segment sur plusieurs exécutions si vous souhaitez combiner les résultats.
Sélectionnez Push Data.
Pour savoir comment afficher les résultats activés, voir Vue des résultats de l’activation des fournisseurs et des consommateurs.

L’activation est exécutée différemment selon la personne qui l’exécute et selon qu’il s’agit d’une activation de consommateur ou de fournisseur.

Important

La première fois qu’un consommateur active des données vers un compte de fournisseur dans une clean room, le fournisseur doit établir un pipeline de données en se connectant à l’UI de clean room pour ce compte et en restant connecté jusqu’à 30 minutes. Cette opération ne doit être effectuée qu’une seule fois par clean room et par consommateur. Tant que cela n’est pas fait, les données n’apparaîtront pas sur le compte du fournisseur, même si l’activation réussit.

Voici comment un consommateur peut envoyer des résultats à son propre compte Snowflake.

Fournisseur

Créez la clean room, créez des liens entre les ensembles de données et définissez des politiques de jonction, comme pour une clean room standard.

Choisissez un modèle standard Snowflake supporté par <label-dcr_activation_supported_templates>, ou ajoutez un modèle d’activation personnalisé <label-dcr_custom_templates_activation> à la clean room. Si cette clean room doit être utilisée dans l’UI, vous devez fournir une forme web avec les champs d’activation appropriés, comme décrit dans la documentation du modèle.

Activez le modèle pour l’activation du consommateur en appelant provider.enable_template_for_consumer_activation.

Pour spécifier les colonnes du fournisseur qui peuvent être activées, définissez la politique d’activation dans la salle blanche pour le modèle activé en appelant provider.set_activation_policy.

Ajoutez des collaborateurs consommateurs, définissez la directive de version par défaut et publiez la clean room, comme d’habitude.

Consommateur

Installez la clean room, créez des liens entre les ensembles de données et établissez des politiques de jonction, comme pour une clean room standard.

Pour spécifier les colonnes du consommateur qui peuvent être activées, définissez la politique d’activation dans la salle blanche pour ce modèle en appelant consumer.set_activation_policy.

Exécutez l’activité en appelant consumer.run_activation, le dernier paramètre étant défini sur TRUE pour indiquer qu’il s’agit d’une activation de consommateur.

Visualisez les résultats, comme décrit ci-dessous.

Exemples

Téléchargez les exemples suivants, puis chargez-les sous forme de fichiers de feuilles de calcul dans votre compte Snowflake. Vous avez besoin de comptes distincts pour le fournisseur et le consommateur, chacun avec l’API de salles blanches installée. Remplacez les informations comme indiqué dans les fichiers d’exemple. Voir les instructions pour charger une feuille de calcul SQL dans votre compte Snowflake.

:télécharger :Code d'exemple du fournisseur</samples/clean-rooms/c-run-c-activation-p.sql>
:télécharger :Code d'exemple pour les consommateurs</samples/clean-rooms/c-run-c-activation-c.sql>

Voici comment un consommateur peut envoyer des résultats au compte Snowflake d’un fournisseur.

Important

Si le consommateur et le fournisseur n’ont pas tous les deux les UI de clean room installées, et que le consommateur s’active auprès du fournisseur :

Le consommateur **** doit exécuter la commande SQL suivante :
```
ALTER SHARE SAMOOHA_INTERNAL_GOVERNANCE_SUMMARY_SHARE_NAV2
  ADD ACCOUNTS = $provider_account_data_sharing_id;
```
Copy
où $provider_account_data_sharing_id est l’identificateur de compte de partage de données du fournisseur <label-account_name_data_sharing>
Le fournisseur doit exécuter la procédure suivante :
```
CALL samooha_by_snowflake_local_db.provider.mount_provider_activations_share(
  $consumer_account_data_sharing_id, TRUE, FALSE);
```
Copy
où $consumer_account_data_sharing_id est l’identificateur de compte de partage de données du consommateur.

1. Fournisseur

Créez la clean room de la manière habituelle.

Link datasets. The provider must also link the SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.LIBRARY.TEMP_PUBLIC_KEY table into the clean room.

Paramétrez la politique de jonction de la manière habituelle.

Choisissez un modèle standard Snowflake pris en charge, ou ajoutez un modèle d’activation personnalisé vers la salle blanche. Si cette salle blanche doit être utilisée dans l’UI des salles blanches, vous devez fournir un formulaire Web avec les champs d’activation appropriés.

Pour spécifier les colonnes du fournisseur qui peuvent être activées, définissez la politique d’activation dans la salle blanche pour ce modèle en appelant provider.set_activation_policy.

Ajoutez des collaborateurs consommateurs, définissez la directive de version par défaut et publiez la clean room, comme d’habitude. (Si le programme d’installation de l’UI de clean room n’est pas installé, appelez provider.setup_provider_activation_share_mount_task après avoir ajouté des consommateurs)

2. Consommateur

Installez la clean room, créez des liens entre les ensembles de données et établissez des politiques de jonction, comme pour une clean room standard.

Définissez la politique d’activation dans la salle blanche pour ce modèle afin de spécifier quelles colonnes de consommateurs peuvent être activées en appelant consumer.set_activation_policy.

Exécutez l’activation en appelant consumer.run_activation, avec le dernier argument fixé à FALSE pour indiquer une activation de fournisseur.

Note

Une version chiffrée des données activées est stockée sur le compte du consommateur pendant 28 jours dans la table. SAMOOHA_LOCAL_DB_NAME_PLACEHOLDER.PUBLIC.CONSUMER_ACTIVATION_SUMMARY. Les données datant de plus de 28 jours sont effacées du compte du consommateur.

3. Fournisseur

La première fois qu’un consommateur active des données sur votre compte, vous devez vous connecter aux UI de clean room pour ce compte pendant environ 30 minutes après l’activation des données par le consommateur. Ensuite, les données apparaîtront dans votre compte. Cette opération n’est effectuée qu’une seule fois par clean room et par compte consommateur. Les activations ultérieures par le même consommateur dans la même clean room ne nécessitent pas cette étape.

Les résultats doivent être déchiffrés avant d’être enregistrés sur votre compte, ce qui peut prendre un certain temps. La tâche de déchiffrement s’arrête au bout de 60 minutes ; dans ce cas, appelez provider.update_activation_warehouse pour augmenter la taille de l’entrepôt utilisé pour le déchiffrement.

Visualisez les résultats, comme décrit ci-dessous.

Exemples

:télécharger :Code d'exemple fournisseur </samples/clean-rooms/c-run-p-activation-p.sql>
:télécharger :Code d'exemple consommateurs </samples/clean-rooms/c-run-p-activation-c.sql>

Voici comment un fournisseur peut pousser les résultats de son propre compte Snowflake. Il s’agit d’une combinaison de plusieurs techniques, notamment les modèles personnalisés, l’analyse effectuée par le fournisseur et l’activation du fournisseur, ce qui implique plusieurs cycles de requête et d’approbation entre le fournisseur et le consommateur.

1. Fournisseur

Créez la clean room, liez les ensembles de données et définissez les politiques de jonction, comme pour une clean room standard, à une exception près : vous devez établir un lien dans la table samooha_by_snowflake_local_db.library.temp_public_key. Les données du fournisseur sont chiffrées, ce qui permet le chiffrement et le déchiffrement des résultats.

Choisissez un modèle standard Snowflake supporté par <label-dcr_activation_supported_templates>, ou ajoutez un modèle d’activation personnalisé <label-dcr_custom_templates_activation> à la clean room. Si cette clean room doit être utilisée dans l’UI, vous devez fournir une forme web avec les champs appropriés pour permettre l’activation, comme décrit dans la documentation du modèle.

Définissez la politique d’activation dans la salle blanche pour ce modèle afin de spécifier quelles colonnes de fournisseurs peuvent être activées en appelant provider.set_activation_policy.

Ajoutez des collaborateurs consommateurs de la manière habituelle. Si l’UI de clean room n’est pas installée, vous devez appeler provider.setup_provider_activation_share_mount_task après avoir ajouté des utilisateurs.

Autorisez les analyses effectuées par le fournisseur dans la clean room en appelant provider.enable_provider_run_analysis. Cela doit être fait après l’ajout de collaborateurs mais avant l’installation de la clean roompar les collaborateurs. Si vous modifiez ce paramètre après l’installation de la clean room par un consommateur, ce dernier doit réinstaller la clean room pour que la modification prenne effet.

Paramétrez la directive de version par défaut et publiez la clean room, comme d’habitude.

2. Consommateur

Installez la clean room, créez des liens entre les ensembles de données et établissez des politiques de jonction comme dans une clean room standard.

Définissez la politique d’activation dans la salle blanche pour ce modèle afin de spécifier quelles colonnes de consommateurs peuvent être activées en appelant consumer.set_activation_policy.

3. Fournisseur

Demandez l’autorisation au consommateur d’exécuter votre modèle d’activation en appelant provider.request_provider_activation_consent.

4. Consommateur

Accordez au fournisseur l’autorisation d’exécuter un modèle donné dans cette clean room en appelant consumer.enable_templates_for_provider_run.

Accordez au fournisseur l’autorisation d’activer les résultats d’un modèle donné dans cette clean room en appelant consumer.approve_provider_activation_consent.

5. Fournisseur

Autorisez le partage des données des consommateurs lors de l’activation d’un fournisseur en appelant provider.mount_request_logs_for_all_consumers.

Exécutez le modèle d’activation en appelant provider.submit_analysis_request). Il faut plusieurs minutes pour que la requête apparaisse dans les connecteurs ; vérifiez le statut en appelant provider.check_analysis_status. Notez que même lorsque le statut est signalé comme SUCCESS, un délai supplémentaire est nécessaire pour que les résultats soient déchiffrés et enregistrés dans la table Snowflake du fournisseur. Toutes les données déchiffrées sont ajoutées en une seule fois à la table des résultats. Consultez périodiquement la table des résultats de votre ID d’activité ou segment. La tâche de déchiffrement s’arrête au bout de 60 minutes ; dans ce cas, appelez provider.update_activation_warehouse pour augmenter la taille de l’entrepôt utilisé pour le déchiffrement.

Note

Pour modifier un modèle après son approbation par le consommateur, vous devez suivre les étapes suivantes, sinon provider.submit_analysis_request continuera à exécuter la dernière version approuvée du modèle.

Le fournisseur met à jour le modèle en appelant provider.add_custom_sql_template. Inutile de rappeler create_or_update_cleanroom_listing.

Le consommateur appelle consumer.enable_templates_for_provider_run.

Le consommateur appelle consumer.approve_provider_activation_consent.

Le modèle mis à jour est maintenant prêt à être activé par le fournisseur.

Erreurs courantes

Object cleanroom_name.CLEANROOM.TEMP_RESULT_DATA does not exist or not authorized - La table temporaire des résultats n’a pas pu être générée pour une raison quelconque. Il peut s’agir d’une erreur SQL dans le modèle, ou bien votre modèle n’a pas explicitement généré une table ; consultez les détails de l’erreur.
Query validation checks failed - Certaines colonnes utilisées dans le modèle ne figuraient pas dans les politiques d’activation.

Exemples

:télécharger :Code d'exemple fournisseur </samples/clean-rooms/p-run-p-activation-p.sql>
:télécharger :Code d'exemple consommateurs </samples/clean-rooms/p-run-p-activation-c.sql>

Vue des résultats de l’activation des fournisseurs et des consommateurs¶

Emplacement et format des résultats de l’activation¶

Tous les résultats de l’activation sont ajoutés à une table désignée de salle blanche dans le compte du fournisseur ou du consommateur. Chaque ligne de la table correspond à une ligne du résultat de la requête. Les résultats de chaque exécution sont ajoutés à la table (la table n’est pas effacée avant chaque exécution). Vous pouvez différencier les différentes exécutions par la colonne ACTIVATION_ID, qui est unique par activation, ou par la colonne SEGMENT, qui peut être spécifiée par l’appelant pour chaque cycle d’activation.

Note

Les résultats de l’activation du fournisseur sont écrits au format chiffré dans une table temporaire dans la localDB du consommateur. Les résultats sont ensuite copiés sur le compte du fournisseur et déchiffrés avant d’être enregistrés. Cette étape supplémentaire de déplacement et de déchiffrement peut entraîner des retards dans les ensembles de résultats importants.

Les résultats de l’activation du fournisseur sont stockés dans SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.PROVIDER_ACTIVATION_SUMMARY dans le compte du fournisseur.
Les résultats de l’activation du consommateur sont stockés dans SAMOOHA_BY_SNOWFLAKE_LOCAL_DB.PUBLIC.CONSUMER_DIRECT_ACTIVATION_SUMMARY dans le compte du consommateur.

Ces tables contiennent les colonnes suivantes :

USER_ID:: Une ligne de résultats, au format JSON, où les clés sont les noms des colonnes et les valeurs la valeur de cette colonne dans cette ligne. L’objet contient également une colonne pour chaque argument transmis au modèle.
ACTIVATION_ID:: Un ID unique pour chaque requête. L’ID est renvoyé lorsque la requête d’activation a abouti. Vous pouvez filtrer par cette colonne pour obtenir tous les résultats de la même activité, ou par SEGMENT si vous réutilisez le même nom de segment dans plusieurs activités. C’est la même chose que l’ID de requête renvoyé par submit_analysis_request ou run_activation.
CLEANROOM_NAME:: Nom de la clean room où la requête a été exécutée.
CONSUMER:: (Activation du fournisseur uniquement) Le consommateur qui a approuvé cette activation.
PROVIDER:: (Activation du consommateur uniquement) Le fournisseur qui a approuvé cette activation.
SEGMENT:: Une valeur de chaîne arbitraire que vous attribuez lorsque vous exécutez l’activation. Cette colonne vous permet de joindre les résultats de plusieurs requêtes.
TIMESTAMP:: Quand l’activité a été exécutée.

Exemple d’activation du fournisseur

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
...

Lecture des résultats de l’activation du fournisseur ou du consommateur¶

Exécutez la commande SQL appropriée pour voir les résultats activés sur votre compte Snowflake :

Voir les résultats de l’activation fournisseur

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

Copy

Voir les résultats de l’activation consommateur

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

Copy

Chaque ligne de données est combinée en un objet dans la colonne USER_ID. Vous pouvez aplatir les résultats à l’aide d’une requête comme la suivante :

-- 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

Voir les 10 dernières lignes de résultats dans Snowsight :

Connectez-vous à Snowsight.

Dans le menu de navigation, sélectionnez Catalog » Database Explorer.

**Pour l’activation du fournisseur **, naviguez jusqu’à SAMOOHA_BY_SNOWFLAKE_LOCAL_DB » PUBLIC » Tables » PROVIDER_ACTIVATION_SUMMARY.

Pour l’activation du consommateur, naviguez jusqu’à SAMOOHA_BY_SNOWFLAKE_LOCAL_DB » PUBLIC » Tables » CONSUMER_DIRECT_ACTIVATION_SUMMARY.

Sélectionnez Data Preview.

Activation par un tiers¶

L’activation par un tiers dépose les résultats de la requête sur le compte d’un tiers approuvé par Snowflake à l’aide d’un connecteur d’activation par un tiers.

L’activation par un tiers n’est possible que dans les UI de clean rooms, et non à l’aide de modèles personnalisés.

L’activation lors de l’utilisation des UI de clean rooms n’est possible que si le compte des clean rooms permet l’activation.

L’administrateur de la clean room doit configurer l’environnement pour qu’il prenne en charge les connecteurs d’activation tiers, sélectionner les connecteurs autorisés et les configurer, avant qu’ils ne puissent être utilisés dans une clean room.

L’activation par un tiers soutient les analyses gérées par les consommateurs et les fournisseurs.

Modèles pris en charge¶

Les modèles suivants prennent en charge l’activation par un tiers :

Audience Overlap & Segmentation

Mise en œuvre de l’activation par un tiers¶

Créez ou rejoignez la clean room : lors de la création ou de l’adhésion à la clean room, à l’étape Configure Analysis & Query, sous Activation Settings, indiquez quelles colonnes doivent être ajoutées aux résultats activés sur votre compte.
Activer les résultats :
1. Exécutez votre analyse.
2. Après avoir exécuté une analyse, sélectionnez Results » Activate.
3. Sous Activation Hub, sélectionnez le nom du fournisseur tiers à activer.
4. Fournissez des informations spécifiques au fournisseur. Il peut s’agir de fournir des noms descriptifs ou de sélectionner les colonnes à activer. Les infobulles de la page devraient fournir des informations supplémentaires pour ce fournisseur.
5. Sélectionnez Push Data.