Snowflake Data Clean Rooms : exécuter une analyse en tant que fournisseur¶

Mise en place de l’environnement¶

Avant d’utiliser les APIs du développeur, vous devez assumer le rôle SAMOOHA_APP_ROLE et spécifier l’entrepôt utilisé pour exécuter les APIs. Si vous n’avez pas le rôle SAMOOHA_APP_ROLE, contactez votre administrateur de compte.

Exécutez les commandes suivantes pour configurer votre environnement :

USE ROLE samooha_app_role;
USE WAREHOUSE app_wh;

Créer la salle blanche¶

Créez un nom pour la salle blanche. Saisissez un nouveau nom de salle blanche pour éviter toute collision avec des noms de salle blanche existants. Notez que les noms des salles blanches ne peuvent être que alphanumériques. Les noms des salles blanches ne peuvent pas contenir de caractères spéciaux autres que des espaces et des traits de soulignement.

Tout d’abord, exécutez la commande suivante pour définir un nom de salle blanche pour l’exemple de salle blanche :

SET cleanroom_name = 'Provider Run Analysis Overlap';

Si une salle blanche portant le nom spécifié existe déjà, ce processus échoue.

L’exécution de cette procédure peut prendre un peu plus de temps, généralement une demi-minute environ.

Le deuxième argument de provider.cleanroom_init est la distribution de la salle blanche. Il peut s’agir de INTERNAL ou de EXTERNAL. À des fins de test, si vous partagez la salle blanche avec un compte de la même organisation, vous pouvez utiliser INTERNAL pour contourner l’analyse de sécurité automatisée qui doit avoir lieu avant qu’un paquet d’applications ne soit publié aux collaborateurs. Cependant, si vous partagez cette salle blanche avec un compte dans une autre organisation, vous devez utiliser une distribution de salle blanche EXTERNAL.

CALL samooha_by_snowflake_local_db.provider.cleanroom_init($cleanroom_name, 'INTERNAL');

Pour voir le statut de l’analyse de sécurité, exécutez la commande suivante :

CALL samooha_by_snowflake_local_db.provider.view_cleanroom_scan_status($cleanroom_name);

Une fois que vous avez créé votre salle blanche, vous devez définir sa directive de version avant de pouvoir la partager avec un collaborateur. Toutefois, si votre distribution a été définie sur EXTERNAL, vous devez d’abord attendre la fin de l’analyse de sécurité avant de définir la directive de version. Vous pouvez continuer à exécuter le reste des étapes et revenir ici avant l’étape provider.create_cleanroom_listing pendant que l’analyse s’exécute.

Pour définir la directive de version, exécutez la commande suivante :

CALL samooha_by_snowflake_local_db.provider.set_default_release_directive($cleanroom_name, 'V1_0', '0');

Lier l’ensemble de données¶

Vous pouvez lier des tables à la salle blanche en spécifiant des noms de table pleinement qualifiés (<Base de données>.<Schéma>.<Table>) sous la forme d’un tableau. Par exemple, pour relier une table aux deux salles blanches, exécutez la commande suivante :

CALL samooha_by_snowflake_local_db.provider.link_datasets($cleanroom_name, ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);

USE ROLE accountadmin;
CALL samooha_by_snowflake_local_db.provider.register_db('<DATABASE_NAME>');
USE ROLE samooha_app_role;

Vous pouvez vérifier que les ensembles de données ont été liés à la salle blanche en exécutant la commande suivante :

CALL samooha_by_snowflake_local_db.provider.view_provider_datasets($cleanroom_name);

Définir la politique de jointure pour l’ensemble de données¶

Pour déterminer les colonnes à utiliser comme politique de jointure, vous pouvez examiner votre ensemble de données pour déterminer les colonnes PII. Par exemple, pour voir les 10 premières lignes d’une table, exécutez la requête suivante :

SELECT * FROM SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS LIMIT 10;

Ensuite, indiquez les colonnes sur lesquelles le consommateur est autorisé à se joindre lorsqu’il exécute des modèles dans la salle blanche. Cette procédure doit être appelée sur les colonnes d’identité comme l’adresse e-mail. Si vous définissez la politique de jointure une deuxième fois, la politique de jointure définie précédemment est entièrement remplacée par la nouvelle.

CALL samooha_by_snowflake_local_db.provider.set_join_policy($cleanroom_name, ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:HEM']);

Si vous souhaitez voir la politique de jointure qui a été ajoutée à la salle blanche, exécutez la commande suivante :

CALL samooha_by_snowflake_local_db.provider.view_join_policy($cleanroom_name);

Ajouter un modèle d’analyse à la salle blanche¶

Les modèles déterminent le type d’analyses qui peuvent être exécutées dans une salle blanche. Dans cet exemple, vous utilisez un modèle prédéfini qui permet aux collaborateurs d’exécuter une analyse sur le chevauchement entre les ensembles de données du fournisseur et les ensembles de données du consommateur.

Notez que ce modèle implémente nativement les garanties de sécurité supplémentaires fournies par la confidentialité différentielle.

CALL samooha_by_snowflake_local_db.provider.add_templates($cleanroom_name, ['prod_overlap_analysis']);

Définir la politique des colonnes pour chaque table¶

Avant de définir une politique de colonne sur une table, exécutez une requête pour afficher les colonnes de la table. Par exemple, pour voir les 10 premières lignes, exécutez la commande suivante :

SELECT * FROM SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS LIMIT 10;

Pour chaque combinaison de table et de modèle, définissez les colonnes que l’analyste peut utiliser dans une analyse, par exemple les colonnes sur lesquelles il peut faire des groupes ou des agrégats. Cela offre une certaine souplesse, de sorte qu’une même table peut permettre différentes sélections de colonnes en fonction du modèle sous-jacent. Attendez d’avoir ajouté un modèle pour définir la politique de colonne d’une table.

Notez que la politique de colonnes est remplacement uniquement, donc si la fonction est appelée à nouveau, la politique de colonnes précédemment définie est complètement remplacée par la nouvelle.

La politique de colonnes ne doit pas être utilisée pour les colonnes d’identité telles que l’adresse e-mail, HEM ou RampID, car vous ne souhaitez pas que l’analyste puisse effectuer des groupes en fonction de ces colonnes. Dans l’environnement de production, Snowflake déduit des colonnes PII et bloque cette opération, mais cette inférence n’est pas disponible dans un environnement sandbox. Elle ne doit être utilisée que pour les colonnes par lesquelles vous souhaitez que l’analyste puisse faire des agrégations et des groupes, comme le statut, la tranche d’âge, le code de région ou le nombre de jours d’activité.

Pour définir la politique de colonne pour une combinaison modèle/table, exécutez la commande suivante :

CALL samooha_by_snowflake_local_db.provider.set_column_policy($cleanroom_name, [
'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']);

Si vous souhaitez voir la politique de colonne qui a été ajoutée à la salle blanche, exécutez la commande suivante :

call samooha_by_snowflake_local_db.provider.view_column_policy($cleanroom_name);

Partager avec un consommateur¶

Enfin, ajoutez un consommateur de données à la salle blanche en ajoutant son localisateur de compte Snowflake et ses noms de compte, comme indiqué ci-dessous. Le nom du compte Snowflake doit être de la forme suivante : <ORGANIZATION>.<ACCOUNT_NAME>.

SHOW VERSIONS IN APPLICATION PACKAGE samooha_cleanroom_Provider_Run_Analysis_Overlap;

Pour partager la salle blanche avec un consommateur, exécutez les commandes suivantes :

CALL samooha_by_snowflake_local_db.provider.add_consumers($cleanroom_name, '<CONSUMER_ACCOUNT_LOCATOR>', '<CONSUMER_ACCOUNT_NAME>');
CALL samooha_By_snowflake_local_db.provider.create_cleanroom_listing($cleanroom_name, '<CONSUMER_ACCOUNT_NAME>');

Plusieurs localisateurs de comptes de consommateurs peuvent être transmis à la fonction provider.add_consumers sous la forme d’une chaîne séparée par des virgules ou sous la forme d’appels distincts à provider.add_consumers.

Si vous souhaitez voir les consommateurs qui ont été ajoutés à la salle blanche, exécutez la commande suivante :

CALL samooha_by_snowflake_local_db.provider.view_consumers($cleanroom_name);

Configuration des personnes autorisées à effectuer des analyses¶

Pour cet exemple, vous allez configurer la salle blanche afin que le fournisseur puisse exécuter des analyses, mais pas le consommateur. Cela signifie que le consommateur pourra uniquement ajouter des ensembles de données et définir des politiques de sécurité.

Pour configurer la salle blanche afin que le fournisseur puisse exécuter une analyse, exécutez la commande suivante :

CALL samooha_by_snowflake_local_db.provider.enable_provider_run_analysis($cleanroom_name, ['<CONSUMER_ACCOUNT_LOCATOR>']);

Par défaut, un consommateur peut exécuter des analyses dans une salle blanche. Pour configurer la salle blanche afin d’empêcher le consommateur d’exécuter des analyses, exécutez la commande suivante :

CAll samooha_by_snowflake_local_db.provider.disable_consumer_run_analysis($cleanroom_name, ['<CONSUMER_ACCOUNT_LOCATOR>']);

Mise en place de l’environnement¶

Avant d’utiliser les APIs du développeur, vous devez assumer le rôle SAMOOHA_APP_ROLE et spécifier l’entrepôt utilisé pour exécuter les APIs. Si vous n’avez pas le rôle SAMOOHA_APP_ROLE, contactez votre administrateur de compte.

Exécutez les commandes suivantes pour configurer votre environnement :

USE ROLE samooha_app_role;
USE WAREHOUSE app_wh;

Installer la salle blanche¶

Avant d’installer la salle blanche que le fournisseur a partagée avec vous, attribuez un nom à la salle blanche.

SET cleanroom_name = 'Provider Run Analysis Overlap';

La commande suivante installe les salles blanches dans le compte du consommateur :

CALL samooha_by_snowflake_local_db.consumer.install_cleanroom($cleanroom_name, '<PROVIDER_ACCOUNT_LOCATOR>');

Lier l’ensemble de données¶

Vous pouvez désormais relier certains de vos ensembles de données à la salle blanche. Le fournisseur utilisera ces données lorsqu’il effectuera une analyse dans la salle blanche.

CALL samooha_by_snowflake_local_db.consumer.link_datasets($cleanroom_name, ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS']);

USE ROLE accountadmin;
CALL samooha_by_snowflake_local_db.provider.register_db('<DATABASE_NAME>');
USE ROLE samooha_app_role;

Si vous souhaitez voir les ensembles de données que vous avez ajoutés à la salle blanche, appelez la procédure suivante.

CALL samooha_by_snowflake_local_db.consumer.view_consumer_datasets($cleanroom_name);

Définir les politiques de jointure sécurisée pour votre ensemble de données¶

Dans cette section, vous spécifierez les colonnes que le fournisseur est autorisé à joindre lors de l’exécution d’analyses dans la salle blanche. Vous devez exécuter la commande suivante sur les colonnes d’identité comme l’adresse e-mail. La politique de jointure est de type « remplacement uniquement », donc si la fonction est appelée à nouveau, la politique de jointure précédemment définie est entièrement remplacée par la nouvelle.

CALL samooha_by_snowflake_local_db.consumer.set_join_policy($cleanroom_name, ['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:HEM']);

Définir des politiques de colonnes pour votre ensemble de données¶

Pour chaque combinaison de table et de modèle, définissez les colonnes que le fournisseur peut utiliser dans une analyse, par exemple les colonnes sur lesquelles il peut faire des groupes ou des agrégats. Cela offre une certaine souplesse, de sorte qu’une même table peut permettre différentes sélections de colonnes en fonction du modèle sous-jacent. Attendez d’avoir ajouté un modèle pour définir la politique de colonne d’une table.

Notez que la politique de colonnes est remplacement uniquement, donc si la fonction est appelée à nouveau, la politique de colonnes précédemment définie est complètement remplacée par la nouvelle.

Les politiques de colonnes ne doivent pas être utilisées pour les colonnes d’identité telles que l’adresse e-mail, HEM ou RampID, car vous ne souhaitez pas que le fournisseur puisse effectuer des groupes en fonction de ces colonnes. Dans l’environnement de production, Snowflake déduit des colonnes PII et bloque cette opération, mais cette inférence n’est pas disponible dans un environnement sandbox. Elle ne doit être utilisée que pour les colonnes par lesquelles vous souhaitez que le fournisseur puisse faire des agrégations et des groupes, comme le statut, la tranche d’âge, le code de région ou le nombre de jours d’activité.

Pour définir la politique de colonne pour une combinaison modèle/table, exécutez la commande suivante :

CALL samooha_by_snowflake_local_db.consumer.set_column_policy($cleanroom_name, [
    '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'
]);

Autoriser le fournisseur à exécuter des analyses¶

Un consommateur doit approuver explicitement la capacité d’un fournisseur à exécuter des analyses modèle par modèle. Sans cette approbation, le fournisseur ne peut pas exécuter une analyse, même s’il a configuré la salle blanche à cet effet.

Tout d’abord, vous pouvez vérifier si le fournisseur a configuré la salle blanche afin de pouvoir exécuter des analyses.

CALL samooha_by_snowflake_local_db.library.is_provider_run_enabled($cleanroom_name)

Ensuite, vous pouvez exécuter la commande suivante pour permettre au fournisseur d’exécuter des analyses. Vous devez exécuter la commande pour chaque modèle que vous souhaitez que le fournisseur puisse utiliser. Vous devez donner votre approbation après avoir défini les politiques de jointure et de colonne pour empêcher le fournisseur d’exécuter une analyse sur des données non protégées.

CALL samooha_by_snowflake_local_db.consumer.enable_templates_for_provider_run($cleanroom_name, ['prod_overlap_analysis']);

Accéder aux informations des consommateurs¶

L’exécution d’une analyse en tant que fournisseur traite les données du compte du consommateur. Pour récupérer les résultats de l’analyse, le fournisseur doit avoir accès aux informations qui lui parviennent du consommateur. Exécutez la commande suivante pour accéder aux informations provenant du consommateur :

CALL samooha_by_snowflake_local_db.provider.mount_request_logs_for_all_consumers($cleanroom_name);

Effectuer l’analyse¶

Le fournisseur exécute la commande provider.submit_analysis_request lorsqu’il veut exécuter une analyse.

CALL samooha_by_snowflake_local_db.provider.submit_analysis_request(
    $cleanroom_name, 
    '<CONSUMER_ACCOUNT>',
    'prod_overlap_analysis', 
    ['SAMOOHA_SAMPLE_DATABASE.demo.customers'], 
    ['SAMOOHA_SAMPLE_DATABASE.demo.customers'], 
    object_construct(       
      'dimensions', ['c.REGION_CODE'],        
      'measure_type', ['AVG'],           
      'measure_column', ['c.DAYS_ACTIVE'],
      'where_clause', 'p.hem=c.hem'                                         
    ));

La commande provider.submit_analysis_request renvoie un identifiant de requête. Vous devez enregistrer cet identifiant afin de pouvoir vérifier le statut de la requête d’analyse et récupérer les résultats de l’analyse. Par exemple, vous pouvez exécuter la commande suivante pour enregistrer l’identifiant dans une variable locale :

SET request_id = '<REQUEST_ID>';

Après avoir soumis la requête pour effectuer une analyse, vous pouvez consulter le statut de la requête en exécutant la commande suivante. Notez qu’il peut y avoir un délai lorsque vous exécutez la commande pour la première fois.

CALL samooha_by_snowflake_local_db.provider.check_analysis_status(
    $cleanroom_name, 
    $request_id, 
    '<CONSUMER_ACCOUNT_LOCATOR>'
);

Lorsque le statut renvoyé par la commande provider.check_analysis_status est COMPLETED, vous pouvez récupérer les résultats de l’analyse en exécutant la commande suivante :

CALL samooha_by_snowflake_local_db.provider.get_analysis_result(
    $cleanroom_name, 
    $request_id, 
    '<CONSUMER_ACCOUNT_LOCATOR>'
);