Utiliser les APIs de développement pour envoyer les résultats à un compte Snowflake pour activation¶

Créer un modèle pour l’activation du fournisseur¶

Un modèle utilisé pour activer les résultats est similaire à un modèle utilisé pour exécuter une analyse. Par exemple, il est ajouté à la salle blanche avec la commande provider.add_custom_sql_template comme modèle d’analyse. Cependant, un modèle d’activation présente les différences importantes suivantes :

• Le nom du modèle d’activation doit commencer par la chaîne activation. Par exemple, un modèle d’activation nommé activation_my_template répond à l’exigence.

• Le modèle d’activation doit créer une table avec un nom conforme aux conventions spécifiques et renvoyer explicitement le nom de la table.

Définir la table dans un modèle d’activation¶

Pour conserver les résultats d’activation dans la salle blanche, chaque modèle d’activation doit créer une table. Il y a deux exigences pour ce tableau :

• Le nom de la table doit commencer par la chaîne cleanroom.activation_data_. Par exemple, une table nommée cleanroom.activation_data_analysis_results répond à l’exigence.

• La partie de la définition du modèle qui crée la table doit renvoyer la chaîne qui a été ajoutée à cleanroom.activation_data_ pour former le nom de la table. Par exemple, si le nom de la table est cleanroom.activation_data_analysis_results, alors la chaîne analysis_results doit être retournée.

Voici un exemple de ce qui doit être inclus dans la définition du modèle pour définir une table et l’exporter :

BEGIN
  CREATE OR REPLACE TABLE cleanroom.activation_data_analysis_results AS
    SELECT * FROM identifier({{ my_table[0] }})
  RETURN 'analysis_results';
END;

Pour plus d’informations sur l’appel de la commande provider.add_custom_sql_template pour ajouter un modèle d’activation à une salle blanche, voir Snowflake Data Clean Rooms : guide de référence pour l’API fournisseurs.

Créer un lien vers la table requise (activation du fournisseur uniquement)¶

Si le fournisseur ou le consommateur veut pousser des résultats vers le compte Snowflake du fournisseur, ce dernier doit établir un lien entre la table samooha_by_snowflake_local_db.library.temp_public_key et la salle blanche. Par exemple, pour relier la table requise à une salle blanche my_activation_cleanroom, exécutez :

CALL samooha_by_snowflake_local_db.provider.link_datasets(
    'my_activation_cleanroom',
    ['samooha_by_snowflake_local_db.library.temp_public_key']);

Le fournisseur pourrait également utiliser un seul appel pour lier la table requise lors de la liaison de ses autres tables et vues.

Définir une politique d’activation¶

Une politique d’activation définit les colonnes qui peuvent être utilisées dans les modèles d’activation. Cette option peut être utilisée avec les modèles d’activation pour garantir que seules les colonnes approuvées par le fournisseur peuvent être utilisées avec le modèle d’activation.

Un fournisseur utilise l’API provider.set_activation_policy pour définir la politique d’activation. Par exemple :

CALL samooha_by_snowflake_local_db.provider.set_activation_policy('my_cleanroom', [
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:HASHED_EMAIL',
    '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' ]);

Activer le consommateur (uniquement pour les analyses gérées par le consommateur)¶

Si le consommateur doit envoyer les résultats sur son propre compte, le fournisseur doit exécuter l’API provider.enable_template_for_consumer_activation. Par exemple :

CALL samooha_by_snowflake_local_db.provider.enable_template_for_consumer_activation(
    'my_cleanroom', 'activation_my_template');

Demander l’autorisation au consommateur (activation du fournisseur uniquement)¶

Si le fournisseur configure le modèle d’activation pour s’autoriser ou autoriser le consommateur à envoyer des résultats au compte Snowflake du fournisseur, ce dernier doit exécuter l’API provider.request_provider_activation_consent. Cette API demande au consommateur d’approuver le modèle à cette fin. Par exemple,

CALL samooha_by_snowflake_local_db.provider.request_provider_activation_consent('my_cleanroom', 'activation_my_template');

Le consommateur doit approuver la requête avant que le fournisseur puisse activer les résultats d’une analyse effectuée par le fournisseur.

Définir l’activation dans l’application Web (Facultatif)¶

Si le fournisseur crée une interface utilisateur pour la salle blanche afin que les utilisateurs puissent exécuter des analyses dans l’application Web, il peut également configurer la salle blanche pour que les utilisateurs puissent activer les résultats à l’aide du hub d’activation dans l’application Web. Lorsque le fournisseur exécute l’API provider.add_ui_form_customizations pour créer l’interface utilisateur, il spécifie le nom du modèle d’activation et précise si le modèle est utilisé pour l’activation du fournisseur, l’activation du consommateur ou les deux.

Par exemple, l’exemple suivant permet aux utilisateurs d’utiliser le hub d’activation à la fois pour l’activation du fournisseur et pour l’activation du consommateur.

CALL samooha_by_snowflake_local_db.provider.add_ui_form_customizations(
    $cleanroom_name,
    'prod_test_references_1',
    {
      'display_name': 'PROD TEST REFERENCE FIRST',
      'description': 'Use our customized ML techniques to find lookalike audiences.',
      'methodology': 'Specify your own seed audience, while matching against our users. Then customize the lookalike model across number of boosting rounds and removing outliers.',
      'render_table_dropdowns': {
          'render_consumer_table_dropdown': TRUE,
          'render_provider_table_dropdown': TRUE
        },
     'activation_template_name': 'activation_my_template',
     'enabled_activations': ['consumer', 'provider']
    },
    {
    'reference_provider_join': {
        'display_name': 'Provider join column',
        'order': 4,
        'description': 'Which provider col do you want to join on',
        'size': 'S',
        'group': 'Seed Audience Selection',
        'references': ['PROVIDER_JOIN_POLICY'],
        'provider_parent_table_field': 'source_table',
        'type': 'dropdown'
    },
    'reference_consumer_join': {
        'display_name': 'Consumer join column',
        'order': 4,
        'description': 'Which consumer col do you want to join on',
        'size': 'S',
        'group': 'Seed Audience Selection',
        'references': ['CONSUMER_COLUMNS'],
        'consumer_parent_table_field': 'my_table',
        'type': 'dropdown'
    }
  },
  {
    'measure_columns': ['count'],
    'default_output_type': 'BAR'
  });

Définir la politique d’activation¶

Une politique d’activation définit les colonnes qui peuvent être utilisées dans les modèles d’activation. Cette politique peut être utilisée avec les modèles d’activation pour garantir que seules les colonnes approuvées par le consommateur peuvent être utilisées avec le modèle d’activation.

Un consommateur utilise l’API consumer.set_activation_policy pour définir la politique d’activation. Par exemple :

CALL samooha_by_snowflake_local_db.consumer.set_activation_policy('my_cleanroom', [
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:HASHED_EMAIL',
    'prod_overlap_analysis:SAMOOHA_SAMPLE_DATABASE.DEMO.CUSTOMERS:REGION_CODE' ]);

Approuver la requête du fournisseur (activation du fournisseur uniquement)¶

Si le fournisseur a exécuté l’API provider.request_provider_activation_consent pour un modèle d’activation destiné à être utilisé pour envoyer des résultats au compte Snowflake du fournisseur, le consommateur doit approuver la requête. Cette approbation s’applique indépendamment du fait que ce soit le fournisseur ou le consommateur qui envoie les résultats sur le compte du fournisseur.

Si le consommateur utilise l’application Web, l’installation de la salle blanche fournit le consentement dont le fournisseur a besoin.

Si le consommateur utilise les APIs de développement, il exécute l’API consumer.approve_provider_activation_consent. Par exemple :

CALL samooha_by_snowflake_local.consumer.approve_provider_activation_consent('my_cleanroom', 'activation_my_template');