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 entrepôts avec 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, 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 à l’intérieur de la salle blanche qui est basée sur l’objet source spécifié. Cependant, vous devez référencer un objet lié par son nom de 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 peuvent pas être consultées directement par les collaborateurs de la salle blanche. Pour accéder aux données un modèle dans la salle blanche est nécessaire.

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 contenant (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 l’API, et l’enregistrement se produit au niveau du compte, et non au niveau de la salle blanche. L’enregistrement est plus facile à effectuer et à gérer dans l’UI. 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. Si vous ne définissez aucune politique de jointure sur vos données, toutes les colonnes sont joignables par défaut. Les colonnes protégées par une politique de jointure ne peuvent pas être projetées. Vos propres politiques de jointure ne restreignent pas vos propres requêtes.

Les salles blanches prennent en charge quelques politiques de données que vous pouvez définir sur des 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 créées lorsque vous liez des données. 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 correspond presque toujours à 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 la plupart d’entre eux sont utilisables dans l’UI uniquement. Par conséquent, vous créerez probablement vos propres modèles personnalisés pour les consommateurs (ou vous-même) à exécuter dans l’API.

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. Si vous ne spécifiez pas de politique de colonnes pour vos données, toutes vos colonnes peuvent être projeté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¶

Le fournisseur définit qui peut accéder à la salle blanche en tant que consommateur. Les consommateurs désignés ne peuvent pas accéder à la salle blanche tant qu’elle n’a pas été publiée. Seuls les comptes ajoutés par le fournisseur peuvent accéder à la salle blanche. Les consommateurs ne peuvent pas partager une salle blanche avec d’autres consommateurs.

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 le rôle SAMOOHA_APP_ROLE directement pour un accès API complet, 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 API limité.

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 similaires à celles du fournisseur. Veillez à utiliser les versions consumer de ces procédures, comme le montre 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 définissent pas de politiques sur les tables auxquelles ils lient des données.

Néanmoins, nous vous recommandons d’envisager l’ajout de politiques au cas où un fournisseur demanderait à exécuter un modèle plus tard, parce que vous pourriez oublier d’ajouter des politiques appropriées à ce moment-là. Si vous ne définissez pas les propriétés des jointures ou des colonnes sur vos données, des données peuvent être jointes à toutes les colonnes et celles-ci sont projetables.

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 templates available in this clean room.
-- Also shows the template 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
  )
);