Spécification de l’offre de données¶

Définit un ensemble de tables qu’un fournisseur est prêt à partager avec les gestionnaires d’analyses, ainsi que des règles de partage, telles que des politiques, des formats de colonnes et la possibilité d’utiliser la table avec un modèle.

Le fournisseur de données soumet cette spécification en appelant REGISTER_DATA_OFFERING, qui renvoie un ID d’offre qui peut être utilisé dans la spécification de la collaboration.

Une offre de données ne sera pas disponible dans une collaboration tant que le compte qui a enregistré l’offre de données ne rejoindra pas la collaboration.

Vous devez disposer du privilège de compte REGISTER DATA OFFERING pour rejoindre toute collaboration dans laquelle vous pouvez activer des données (c’est-à-dire que vous êtes un gestionnaire d’analyses et que la spécification de la collaboration inclut un champ activation_destinations). Pour plus d’informations, consultez le guide de référence de l’API de gestion des accès.

Schéma :

api_version: 2.0.0              # Required: Must be "2.0.0"
spec_type: data_offering        # Required: Must be "data_offering"
name: <data_offering_name>      # Required: Unique name (max 75 chars)
version: <version_string>       # Required: Version identifier (max 20 chars)
description: <data_offering_description>  # Optional: Description (max 1,000 chars)

datasets:                       # Required: Tables to share
  - alias: <dataset_name>       # One or more dataset items...
    data_object_fqn: <database.schema.table_name>  # Required: Fully-qualified table name
    allowed_analyses: <allowed_analysis_type>      # Required: template_only or template_and_freeform_sql
    object_class: <object_class>    # Optional: ads_log or custom
    schema_and_template_policies:   # Required: Column definitions
      <column_name>:                # One or more column definitions...
        category: <category_type>   # Required: join_standard, join_custom, timestamp, passthrough, or event_type
        column_type: <format_type>  # Required for join_standard category, omitted for other categories.
        activation_allowed: <true_or_false>  # Optional: Whether column can be used for activation
    freeform_sql_policies:      # Optional: Policies for freeform SQL queries
      aggregation_policy:       # Optional: Single aggregation policy
        name: <fully_qualified_policy_name>
        entity_keys:            # Optional: Entity key columns
          - <column_name>       # One or more POSSIBLY RENAMED column names...
      join_policy:              # Optional: Single join policy
        name: <fully_qualified_policy_name>
        columns:                # Optional: Columns this policy applies to
          - <column_name>       # One or more POSSIBLY RENAMED column names...
      masking_policies:         # Optional: Masking policies
        - name: <fully_qualified_policy_name>  # One or more masking policy items...
          columns:              # Optional: Columns this policy applies to
            - <column_name>     # One or more POSSIBLY RENAMED column names...
      projection_policies:      # Optional: Projection policies
        - name: <fully_qualified_policy_name>  # One or more projection policy items...
          columns:              # Optional: Columns this policy applies to
            - <column_name>     # One or more POSSIBLY RENAMED column names...
      row_access_policy:        # Optional: Row access policy
        name: <fully_qualified_policy_name>
        columns:              # Optional: Columns this policy applies to
          - <column_name>     # One or more POSSIBLY RENAMED column names...
    require_freeform_sql_policy: <true_or_false>  # Optional: Require a policy for freeform SQL

api_version

Version de l’API de collaboration utilisée. Doit être 2.0.0.

spec_type

Identificateur du type de spécification. Doit être data_offering.

name: data_offering_name

Nom d’un ensemble de tables et de colonnes à exposer aux collaborateurs. Ce nom est utilisé comme valeur de référence pour l’offre de données dans une spécification de collaboration. Vous pouvez créer plusieurs offres de données avec des tables et des colonnes qui se chevauchent pour différents cas d’utilisation. Doit suivre les règles des identificateurs Snowflake avec un maximum de 75 caractères et être unique au sein de votre compte de salles blanches de données Snowflake. La paire name_version doit être unique pour toutes les offres de données de ce compte.

version

Identificateur de version personnalisé pour cette spécification d’offre de données (20 caractères maximum). Doit suivre les règles des identificateurs Snowflake. La chaîne de version reçoit sa propre colonne dans la réponse à VIEW_DATA_OFFERINGS et VIEW_REGISTERED_DATA_OFFERINGS ; utilisez donc une valeur qui peut être triée par ordre croissant. Exemple : V0

description: data_offering_description (Facultatif)

Description de l’offre de données (1 000 caractères maximum).

datasets

Liste d’un ou plusieurs ensembles de données à mettre à la disposition de la collaboration.

alias: dataset_name

Nom pour cet objet de données, utilisé dans collaboration.run. Doit suivre les règles des identificateurs Snowflake et être unique au sein de cette offre. 75 caractères maximum

data_object_fqn: fully_qualified_table_name

Décrit une seule table disponible pour les collaborateurs. Indiquez le nom pleinement qualifié de l’objet source dans votre compte (database.schema.table_name). La longueur maximale est de 773 caractères.

allowed_analyses: allowed_analysis_type

Le type d’analyses que les collaborateurs peuvent effectuer sur cette table. Champ obligatoire avec les valeurs suivantes :

template_only : Le gestionnaire d’analyses peut effectuer des requêtes dans cette table uniquement en utilisant un modèle répertorié dans la spécification de la collaboration.
template_and_freeform_sql : Le gestionnaire d’analyses peut interroger cette table en utilisant un modèle répertorié dans la spécification de la collaboration, ou en utilisant des requêtes SQL de forme libre dans un environnement de code.

object_class (Facultatif)

Type d’objet. Une des valeurs suivantes :

ads_log : Les tables et les colonnes listées ici doivent répondre aux exigences du journal des annonces.
custom : Ensemble personnalisé de tables et de colonnes qui n’a pas d’exigences particulières.

schema_and_template_policies

Fournissez une liste des noms de colonnes de la table listée par data_object_fqn et définissez les politiques et le format de chaque colonne. Seules les colonnes listées ici sont disponibles pour les collaborateurs. Chaque colonne possède les descripteurs suivants :

category: category_type

La catégorie détermine si un renommage de colonne est appliqué et si une contrainte de format de données doit être appliquée. category et column_type déterminent le nom de la colonne exposée au gestionnaire d’analyses. Les valeurs suivantes sont prises en charge :

join_standard : Il s’agit d’une colonne joignable avec des données dans un format spécifié dans le champ column_type. Cette colonne est renommée en valeur column_type dans l’offre de données partagées. Cette colonne est ajoutée à la politique de jointure de la salle blanche.
join_custom : Il s’agit d’une colonne joignable dans n’importe quel format. Utilisez ceci lorsqu’il n’existe pas de column_type approprié pour votre colonne de jointure. Le nom de colonne d’origine est utilisé dans l’offre de données partagées. Cette colonne est ajoutée à la politique de jointure de la salle blanche.
timestamp : Il s’agit d’une colonne projetable qui spécifie un horodatage pour tout événement. La colonne est renommée timestamp dans l’offre de données partagées.
passthrough : Il s’agit d’une colonne projetable de tout autre type. Le nom de colonne d’origine est utilisé dans l’offre de données partagées.
event_type : Il s’agit d’une colonne projetable qui enregistre une classification de type d’événement pour cette ligne, par exemple : « achat », « inscription », « impression », « clic », etc.

column_type: <format_type> (Obligatoire lorsque catégorie=join_standard, ignoré pour les autres types de catégories)

Format des données. Si les données ne sont pas conformes à ce format, votre appel à REGISTER_DATA_OFFERING échouera. Fournissez ce champ pour les colonnes où category = join_standard. category et column_type déterminent le nom de la colonne exposée au gestionnaire d’analyses. Vous ne pouvez pas attribuer la même valeur column_type à plusieurs colonnes d’une même table. Les types de formats suivants sont pris en charge :

email : Adresse e-mail brute.
hashed_email_sha256 : E-mail haché SHA256.
hashed_email_b64_encoded : E-mail haché codé en base64.
phone : Numéro de téléphone sans ponctuation. Par exemple : 2015551212.
hashed_phone_sha256 : Numéro de téléphone haché SHA256. Le numéro d’origine doit être au format phone.
hashed_phone_b64_encoded : Numéro de téléphone haché codé en base64.
device_id : Un ID d’appareil brut, comme un ID publicitaire mobile ou un ID d’appareil CTV.
hashed_device_id_sha256 : ID d’appareil haché SHA256. L’identifiant d’origine doit être au format device_id.
hashed_device_b64_encoded : ID d’appareil haché codé en base64.
ip_address : Adresse IP brute au format IPv4.
hashed_ip_address_sha256 : adresse IPv4 hachée SHA256. L’adresse IP d’origine doit être au format ip_address.
hashed_ip_address_b64_encoded : Adresse IP hachée codée en base64.
first_name : Un prénom brut.
hashed_first_name_sha256 : Un prénom haché en SHA256. L’adresse IP d’origine doit être au format first_name.
hashed_first_name_b64_encoded : Un prénom haché codé en base64.
last_name : Un nom de famille brut.
hashed_last_name_sha256 : Un nom de famille haché en SHA256. L’adresse IP d’origine doit être au format last_name.
hashed_last_name_b64_encoded : Un nom de famille haché codé en base64.

activation_allowed (Facultatif)

Indique si cette colonne peut être utilisée à des fins d’activation. La valeur par défaut est false.

freeform_sql_policies (Facultatif)
Si allowed_analyses correspond à template_and_freeform_sql, ce champ facultatif répertorie toutes les politiques de Snowflake qui doivent être appliquées sous forme de requêtes SQL de forme libre exécutées sur cette offre de données. Pour plus d’informations, voir Appliquer la politique de Snowflake à l’offre de données (utilisation des requêtes à forme libre uniquement).

Les types suivants sont pris en charge :

aggregation_policy (Facultatif)
Configuration unique de la politique d’agrégation.

name : Nom pleinement qualifié de la politique.

entity_keys (Facultatif) : Liste des noms de colonnes qui servent de clés d’entité pour la politique d’agrégation.NOTE : si ces colonnes ont été renommées, vous devez utiliser le nom de colonne généré.

join_policy (Facultatif)
Configuration unique de la politique de jointure.

name : Nom pleinement qualifié de la politique.NOTE : si cette colonne a été renommée, vous devez utiliser le nom de colonne généré.

columns (Facultatif) : Liste des noms de colonnes auxquels cette politique s’applique.

masking_policies (Facultatif)
Tableau des configurations de la politique de masquage.

name : Nom pleinement qualifié de la politique.NOTE : si cette colonne a été renommée, vous devez utiliser le nom de colonne généré.

columns (Facultatif) : Liste des noms de colonnes auxquels cette politique s’applique.

projection_policies (Facultatif)
Tableau des configurations de la politique de projection.

name : Nom pleinement qualifié de la politique.NOTE : si cette colonne a été renommée, vous devez utiliser le nom de colonne généré.

columns (Facultatif) : Liste des noms de colonnes auxquels cette politique s’applique.

row_access_policy (Facultatif)
Un objet qui décrit une configuration de politique d’accès aux lignes.

name : Nom pleinement qualifié de la politique.NOTE : si cette colonne a été renommée, vous devez utiliser le nom de colonne généré.

columns (Facultatif) : Liste des noms de colonnes auxquels cette politique s’applique.

require_freeform_sql_policy (Facultatif)
Si cette source de données doit définir freeform_sql_policies. Ce type est utilisé comme un Fail-safe pour empêcher la liaison d’une source de données qui prend en charge les requêtes SQL de forme libre sans lui attribuer de politiques.