Analyse de base des données exécutées par les consommateurs¶

Mise en place de l’environnement¶

Pour utiliser l’API, vous devez utiliser un entrepôt pour lequel SAMOOHA_APP_ROLE dispose de privilèges. app_wh est l’un des nombreux entrepôts ayant accès à l’API. Choisissez l’entrepôt qui correspond à vos besoins. (Vous pouvez également utiliser votre propre entrepôt, si vous le souhaitez).

Le rôle SAMOOHA_APP_ROLE est nécessaire pour accéder à l’API.

USE WAREHOUSE app_wh;
USE ROLE SAMOOHA_APP_ROLE;

Créer la salle blanche¶

L’étape suivante consiste à créer une nouvelle salle blanche. Il suffit pour cela d’utiliser un seul appel API qui spécifie si la salle blanche est destinée à une utilisation interne ou externe. Les salles blanches internes ne sont accessibles qu’aux consommateurs de la même organisation. Les salles blanches externes peuvent être utilisées par des consommateurs extérieurs à l’organisation. Pour les deux types de salles blanches, les consommateurs doivent être invités à utiliser la salle blanche pour pouvoir y accéder.

Les salles blanches externes déclenchent des contrôles de sécurité supplémentaires lorsque certaines actions sont effectuées. Lorsque cela se produit, vous devez appeler provider.view_cleanroom_scan_status pour voir quand l’analyse de sécurité est terminée, et vous pouvez passer à l’action suivante.

L’exemple suivant crée une salle blanche interne :

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

Lier les données à la salle blanche¶

Le fournisseur et le consommateur peuvent tous les deux lier (importer) des tables, des vues et d’autres objets de données pris en charge dans une salle blanche. Lorsque vous liez des données, l’API crée une vue cachée et sécurisée à l’intérieur de la salle blanche qui est basée sur l’objet source lié. Vous référencez l’objet lié par son nom source, et non par son nom de vue interne, dans toutes les procédures de salle blanche.

Les données liées à la salle blanche ne sont pas directement accessibles par aux collaborateurs de la salle blanche. Les données liées sont accessibles à l’aide d’un modèle importé dans la salle blanche (à moins que vous n’activiez les requêtes SQL de forme libre sur vos données).

Avant qu’un objet puisse être lié à une salle blanche, l’objet doit être enregistré. L’enregistrement d’un objet accorde des privilèges d’accès appropriés au rôle SAMOOHA_APP_ROLE sur l’objet. Vous pouvez soit enregistrer directement un objet, soit enregistrer un objet parent (tel qu’une base de données ou un schéma) pour accéder à des objets enfants. Vous pouvez enregistrer un objet dans l’UI ou dans l’API.

Les objets sont enregistrés au niveau du compte, et non au niveau de la salle blanche ; vous devez enregistrer un objet une seule fois par compte, et celui-ci peut être lié à n’importe quelle salle blanche du compte. (Vous ne pouvez lier que des objets enregistrés dans votre propre compte.) Une fois que vous avez enregistré un objet, celui-ci est disponible peut être lié par n’importe quelle salle blanche du compte. En savoir plus sur l’enregistrement.

L’exemple suivant lie des données dans la table CUSTOMERS de la base de données exemple SAMOOHA_SAMPLE_DATABASE. Cette base de données est enregistrée automatiquement lorsque vous installez l’environnement de salle blanche dans un compte, vous n’avez donc pas besoin de l’enregistrer. Vous pouvez lier ou dissocier des objets à tout moment dans une salle blanche, et les résultats se propagent rapidement à tous les collaborateurs.

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

Définir la politique de jointure¶

Si vous ajoutez un modèle à la salle blanche qui permet au consommateur de joindre des données à vos données, vous devez définir une politique de jointure de salle blanche sur vos données. Une politique de jointure de salle blanche spécifie les colonnes sur lesquelles joindre des données dans les requêtes exécutées par les collaborateurs. Vos propres politiques de jointure ne restreignent pas vos propres requêtes.

Les salles blanches prennent en charge quelques types de politiques de données que vous pouvez définir sur les données liées. Ces politiques sont similaires aux politiques équivalentes de Snowflake, sans être les mêmes, et s’appliquent uniquement à la vue interne, et non aux données source. Toutes les politiques Snowflake définies sur les données source sont propagées aux vues liées à une salle blanche. Les politiques de salle blanche sont définies sur les données liées uniquement, et non sur les données source.

Vous pouvez définir des politiques uniquement sur les données que vous liez ; vous ne pouvez pas définir de politiques sur les données d’autres personnes.

L’exemple suivant montre comment définir une politique de jointure qui permet à deux colonnes de la table liée d’être jointes :

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

En savoir plus sur les politiques de jointure.

Ajouter des modèles à une salle blanche¶

Un modèle de salle blanche est un modèle JinjaSQL valide qui évalue généralement une requête SQL. Un modèle, parfois appelé analyse, peut recevoir des arguments de l’appelant, et peut accéder à toutes les données liées dans la salle blanche. Les fournisseurs et les consommateurs peuvent tous deux ajouter des modèles dans une salle blanche et les exécuter.

Snowflake fournit quelques modèles standard, mais vous écrirez probablement vos propres modèles personnalisés.

Toutes les politiques de salle blanche que vous définissez ne sont appliquées que si le modèle inclut des filtres de politiques dans le modèle, alors assurez-vous que les modèles que vous ajoutez à une salle blanche incluent ces filtres. Pour plus d’informations sur les politiques, consultez Comprendre les politiques relatives aux tables de clean room.

Par défaut, seuls les consommateurs peuvent exécuter des modèles. Si un fournisseur veut exécuter un modèle, il doit demander l’autorisation au consommateur. De même, si un consommateur veut télécharger un modèle, il doit demander l’autorisation au fournisseur.

Pour plus d’informations sur la création d’un modèle personnalisé, voir Ajouter des modèles personnalisés à une salle blanche et Référence d’un modèle de salle blanche personnalisé.

L’exemple suivant montre comment ajouter un modèle fourni par Snowflake à la salle blanche :

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

Définir des politiques de colonnes¶

Les politiques de colonnes de salle blanche spécifient quelles colonnes de vos tables peuvent être projetées dans les requêtes exécutées par les collaborateurs. Une politique de colonnes est liée à la fois à une colonne et à un modèle, de sorte que différentes colonnes peuvent être définies comme projetables avec différents modèles. Un modèle doit être présent dans une salle blanche pour que vous puissiez définir des politiques de colonnes pour ce modèle.

Les politiques de colonnes, comme toutes les politiques, sont overwrite-only ; cela signifie que la définition de politiques de colonnes écrase complètement toutes les politiques de colonnes existantes définies par ce compte. Le fournisseur et le consommateur peuvent tous deux définir des politiques de colonnes sur leurs données. En savoir plus sur les politiques de colonnes.

L’exemple suivant montre comment autoriser la projection de quatre colonnes à partir de la base de données exemple des salles blanches qui a été liée précédemment :

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

Partager avec des consommateurs¶

Seuls les consommateurs invités par le fournisseur peuvent accéder à la salle blanche. Les consommateurs ne peuvent pas partager une salle blanche avec d’autres consommateurs. Les consommateurs désignés ne peuvent pas accéder à la salle blanche tant qu’elle n’a pas été publiée. Les invitations à rejoindre une salle blanche sont envoyées au niveau du compte, et non au niveau de l’utilisateur.

L’exemple suivant montre comment partager une salle blanche avec deux consommateurs. La procédure utilise deux listes parallèles, délimitées par des virgules, de localisateurs de comptes consommateurs et d’IDs de comptes de partage de données consommateur.

CALL samooha_by_snowflake_local_db.provider.add_consumers(
  $cleanroom_name,
  'CONSUMER_LOCATOR1,CONSUMER_LOCATOR2',
  'CONSUMER_DATA_SHARING_ACCOUNT_ID1,CONSUMER_DATA_SHARING_ACCOUNT_ID2');

Définir la version par défaut¶

Les salles blanches sont des applications natives versionnées. Certaines actions, telles que l’ajout de code à une salle blanche, génèrent une nouvelle version corrective de l’application. Les consommateurs doivent installer la salle blanche dans leur compte. La version qu’ils installent est basée sur le numéro de version par défaut que vous spécifiez. Si vous publiez ultérieurement une nouvelle version de la salle blanche et que vous incrémentez le numéro de version par défaut, toutes les versions installées par les consommateurs seront automatiquement mises à jour et les nouvelles installations seront par défaut la nouvelle version. En savoir plus sur la gestion des versions des salles blanches.

L’exemple suivant montre comment définir la version par défaut d’une salle blanche sur V1.0.0, qui est la version initiale d’une salle blanche, si vous n’avez pas importé de code :

CALL samooha_by_snowflake_local_db.provider.set_default_release_directive(
  $cleanroom_name,
  'V1_0',          -- Version number: Never changes.
  '0'              -- Patch number: Can change.
  );

Publier la salle blanche¶

Publiez ou republiez la salle blanche comme indiqué dans l’exemple suivant. La première fois que cette procédure est appelée, elle rend la salle blanche visible et installable par tous les consommateurs avec lesquels vous l’avez partagée. Vous devez appeler cette procédure chaque fois que vous apportez des modifications importantes, par exemple lorsque vous mettez à jour la version par défaut ou lorsque vous apportez des modifications spécifiques à l’UI de salle blanche.

CALL samooha_By_snowflake_local_db.provider.create_or_update_cleanroom_listing(
  $cleanroom_name);

Le consommateur peut désormais installer la salle blanche, lier des données, définir des politiques et exécuter des modèles, comme décrit ci-dessous.

Mise en place de l’environnement¶

Comme le fournisseur, le consommateur doit utiliser un entrepôt auquel le rôle SAMOOHA_APP_ROLE peut accéder. Toutefois, contrairement au fournisseur, le consommateur peut utiliser directement le rôle SAMOOHA_APP_ROLE pour un accès complet à l’API, ou un administrateur de salle blanche dans ce compte peut accorder un rôle plus limité qui donne des privilèges pour exécuter un sous-ensemble de l’API pour les consommateurs. Ce rôle limité, parfois appelé de manière générique « rôle d’exécution », est accordé par un utilisateur disposant des privilèges complets de salle blanche. Découvrez comment accorder un accès limité à l’API.

Un rôle d’exécution ne vous permet pas d’installer une salle blanche, vous devez donc utiliser le rôle SAMOOHA_APP_ROLE, comme le montre l’exemple suivant :

USE WAREHOUSE app_wh;
USE ROLE SAMOOHA_APP_ROLE;

Installer la salle blanche¶

L’extrait suivant montre comment répertorier toutes les salles blanches qui sont installées et celles que vous êtes invité à installer :

-- See all clean rooms, installed and not.
CALL samooha_by_snowflake_local_db.consumer.view_cleanrooms();

-- See only clean rooms that aren't installed.
CALL samooha_by_snowflake_local_db.consumer.view_cleanrooms() ->>
  SELECT * FROM $1
    WHERE IS_ALREADY_INSTALLED = false;

Installez la salle blanche que le fournisseur a partagée avec vous, comme indiqué dans l’exemple suivant. Vous devez spécifier le localisateur de compte du fournisseur lorsque vous installez une salle blanche.

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

Ajouter des données et définir des politiques¶

Si les modèles de salle blanche permettent au consommateur d’inclure ses propres données dans une requête, le consommateur enregistre les données, lie les données et définit des politiques comme le fait le fournisseur. Veillez à utiliser les versions consumer de ces procédures, comme montré dans l’exemple suivant :

-- You must use a role with MANAGE GRANTS privilege on an object to register it.
USE ROLE ACCOUNTADMIN;
CALL samooha_by_snowflake_local_db.consumer.register_db('MY_DATABASE');

-- Link some tables.
CALL samooha_by_snowflake_local_db.consumer.link_datasets(
  $cleanroom_name,
  [
    'SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS',
    'MY_DATABASE.PUBLIC.EXPOSURES'
  ]);

La politique de jointure du fournisseur indique sur quelles colonnes du fournisseur il est possible de joindre des données. Cet exemple montre comment vérifier les colonnes des fournisseurs sur lesquelles vous pouvez joindre d’autres colonnes :

CALL samooha_by_snowflake_local_db.consumer.view_provider_join_policy($cleanroom_name);

Un fournisseur a besoin de l’approbation du consommateur pour exécuter un modèle dans la salle blanche. Par conséquent, la plupart des consommateurs ne prennent pas la peine de définir des politiques sur les tables qui sont liées. Néanmoins, nous vous recommandons d’envisager d’ajouter des politiques au cas où un fournisseur demanderait d’exécuter un modèle ultérieurement, car vous pourriez oublier d’ajouter les politiques appropriées à ce moment-là.

Si vous définissez des politiques, elles ne sont appliquées que si le modèle inclut un filtre join_policy ou column_policy dans la colonne du modèle, alors assurez-vous que les modèles que vous ajoutez à une salle blanche incluent ces filtres pour appliquer vos politiques. Pour examiner les modèles dans une salle blanche, appelez consumer.view_added_templates. Pour plus d’informations sur les politiques, consultez Comprendre les politiques relatives aux tables de clean room.

Effectuer l’analyse¶

Avant d’exécuter un modèle, vous l’examinez généralement pour voir ce qu’il fait et quelles variables il accepte, puis vous examinez quelles tables de fournisseurs sont disponibles dans la salle blanche.

-- View the list of templates available in this clean room,
-- and the source code for each template.
CALL samooha_by_snowflake_local_db.consumer.view_added_templates($cleanroom_name);

-- Show which variables can be passed in when running the specified template.
CALL samooha_by_snowflake_local_db.consumer.get_arguments_from_template(
  $cleanroom_name,
  $template_name
);

-- See which datasets you have linked into the clean room.
CALL samooha_by_snowflake_local_db.consumer.view_consumer_datasets($cleanroom_name);

-- See which datasets the provider has linked into the clean room.
CALL samooha_by_snowflake_local_db.consumer.view_provider_datasets($cleanroom_name);

CALL samooha_by_snowflake_local_db.consumer.run_analysis(
$cleanroom_name,
$template_name,
[],                                              -- This template doesn't accept consumer tables.
['SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS'],      -- Provider tables.
object_construct(                                -- Template-specific arguments.
  'dimensions', ['p.STATUS'],                    -- Template takes a variable named 'dimensions'.
  'where_clause', 'p.REGION_CODE=$$REGION_10$$'  -- Template allows you to pass in a WHERE clause.
                                                 -- $$ is used to wrap string literals
  )
);