Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Qu'est-ce que c'est AWS Clean Rooms ?
AWS Clean Rooms vous permet, à vous et à vos partenaires, d'analyser et de collaborer sur vos ensembles de données collectifs afin d'obtenir de nouvelles informations sans révéler les données sous-jacentes les uns aux autres. AWS Clean Rooms est un espace de travail collaboratif sécurisé, dans lequel vous pouvez créer vos propres salles blanches en quelques minutes et analyser vos ensembles de données collectifs en quelques étapes seulement. Vous choisissez les partenaires avec lesquels vous souhaitez collaborer, sélectionnez leurs ensembles de données et configurez des contrôles renforçant la confidentialité pour ces partenaires.
Avec AWS Clean Rooms, vous pouvez collaborer avec des milliers d'entreprises qui l'utilisent déjà AWS. La collaboration ne nécessite pas de déplacer des données AWS ou de les charger vers un autre fournisseur de services cloud. Lorsque vous exécutez des requêtes ou des tâches, AWS Clean Rooms lisez les données à partir de leur emplacement d'origine et appliquez des règles d'analyse intégrées pour vous aider à garder le contrôle sur ces données.
AWS Clean Rooms fournit des contrôles d'accès aux données intégrés et des contrôles d'assistance à l'audit que vous pouvez configurer. Ces contrôles incluent :
+ [Règles d'analyse](analysis-rules.md) pour restreindre les requêtes SQL et fournir des contraintes de sortie.
+ [L'informatique cryptographique permet de Clean Rooms crypter les données, même pendant](crypto-computing.md) le traitement des requêtes, afin de respecter les politiques strictes de traitement des données.
+ Des [journaux d'analyse](query-logs.md) pour examiner les requêtes et les tâches AWS Clean Rooms et aider à soutenir les audits.
+ [Confidentialité différentielle](differential-privacy.md) pour protéger contre les tentatives d'identification des utilisateurs. AWS Clean Rooms La confidentialité différentielle est une fonctionnalité entièrement gérée qui protège la confidentialité de vos utilisateurs grâce à des techniques mathématiques et à des commandes intuitives que vous pouvez appliquer en quelques étapes.
+ [AWS Clean Rooms ML](machine-learning.md) permet à deux parties d'identifier des utilisateurs similaires dans leurs données sans avoir à partager leurs données entre elles. La première partie crée et configure un modèle similaire à partir de ses données d'entraînement. Les données de départ sont ensuite transmises à la collaboration pour créer un segment similaire aux données d'entraînement.
La vidéo suivante explique plus en détail AWS Clean Rooms.
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/0S6icreVCO0)
## Utilisez-vous pour la première fois AWS Clean Rooms ?
Si vous utilisez ce service pour la première fois AWS Clean Rooms, nous vous recommandons de commencer par lire les sections suivantes :
+ [Comment AWS Clean Rooms fonctionne](#how-it-works)
+ [Accès AWS Clean Rooms](#accessing-service)
+ [Con AWS Clean Rooms figuration](setting-up.md)
+ [AWS Clean Rooms Glossaire](glossary.md)
## Comment AWS Clean Rooms fonctionne
Dans AWS Clean Rooms, vous créez une collaboration et ajoutez celle Comptes AWS que vous souhaitez inviter, ou vous créez un abonnement pour rejoindre une collaboration à laquelle vous avez été invité. Vous liez ensuite les ressources de données nécessaires à votre cas d'utilisation : tables configurées pour les données d'événements, modèles configurés pour la modélisation ML ou espaces de noms d'identification pour la résolution d'entités. Vous avez la possibilité de créer ou d'approuver des modèles d'analyse afin de convenir à l'avance des requêtes et des tâches exactes que vous souhaitez autoriser dans le cadre d'une collaboration. Enfin, vous analysez les données conjointes en exécutant des requêtes ou des PySpark tâches SQL sur les tables configurées, en effectuant la résolution des entités dans les tables de mappage d'identifiants ou en utilisant la modélisation ML pour générer des segments d'audience similaires.
Le schéma suivant montre comment AWS Clean Rooms cela fonctionne.
![\[Schéma expliquant le AWS Clean Rooms fonctionnement\]](http://docs.aws.amazon.com/fr_fr/clean-rooms/latest/userguide/images/how-it-works.png)
## Services connexes
### AWS services
Les éléments suivants Services AWS sont liés à AWS Clean Rooms :
+ **Amazon Athena**
Les membres de la collaboration peuvent stocker les données qu'ils introduisent AWS Clean Rooms sous forme de AWS Glue Data Catalog vues dans Amazon Athena. Pour plus d’informations, consultez les rubriques suivantes :
Pour plus d’informations, consultez les rubriques suivantes :
[Préparation des tables de données pour les requêtes dans AWS Clean Rooms](prepare-data.md)
[Création d'une table configurée — Source de données Amazon Athena](create-config-table-athena.md)
[Qu'est-ce qu'Amazon Athena ?](https://docs.aws.amazon.com/athena/latest/ug/what-is.html) dans le guide de l'utilisateur d'*Amazon Athena*
+ **CloudFormation**
Créez les ressources suivantes dans CloudFormation : collaborations, tables configurées, associations de tables configurées et adhésions
Pour de plus amples informations, veuillez consulter [Création de AWS Clean Rooms ressources avec AWS CloudFormation](creating-resources-with-cloudformation.md).
+ **AWS CloudTrail**
AWS Clean Rooms Utilisez-le avec CloudTrail les journaux pour améliorer votre analyse de Service AWS l'activité.
Pour de plus amples informations, veuillez consulter [Journalisation des appels AWS Clean Rooms d'API à l'aide AWS CloudTrail](logging-using-cloudtrail.md).
+ **Résolution des entités AWS**
Utilisez AWS Clean Rooms avec Résolution des entités AWS pour effectuer la résolution d'entités.
Pour de plus amples informations, veuillez consulter [Résolution des entités AWS dans AWS Clean Rooms](working-with-entity-resolution.md).
+ **AWS Glue**
Les membres de la collaboration peuvent créer AWS Glue des tables à partir de leurs données dans Amazon S3 pour les utiliser dans AWS Clean Rooms.
Pour plus d’informations, consultez les rubriques suivantes :
[Préparation des tables de données pour les requêtes dans AWS Clean Rooms](prepare-data.md)
[Qu'est-ce que AWS Glue ?](https://docs.aws.amazon.com/glue/latest/dg/what-is-glue.html)dans le *Guide du développeur AWS Glue *
+ **Amazon Simple Storage Service (Amazon S3)**
Les membres de la collaboration peuvent stocker les données qu'ils AWS Clean Rooms introduisent dans Amazon S3.
Pour plus d’informations, consultez les rubriques suivantes :
[Préparation des tables de données pour les requêtes dans AWS Clean Rooms](prepare-data.md)
[Création d'une table configurée — Source de données Amazon S3](create-config-table-s3.md)
[Qu’est-ce qu'Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html) dans le *Guide de l'utilisateur Amazon Simple Storage Service*.
+ **AWS Secrets Manager**
Les membres de la collaboration peuvent créer des secrets pour accéder aux données stockées dans Snowflake et les lire.
Pour plus d’informations, consultez les rubriques suivantes :
[Créez un rôle de service pour lire les données de Snowflake](setting-up-roles.md#create-service-role-third-party)
[Préparation des tables de données pour les requêtes dans AWS Clean Rooms](prepare-data.md)
[Qu'est-ce que AWS Secrets Manager ?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) dans le *Guide de l'utilisateur AWS Secrets Manager *
### Services tiers
Le service tiers suivant est lié à AWS Clean Rooms :
+ **Snowflake**
Les membres de la collaboration peuvent stocker les données qu'ils introduisent AWS Clean Rooms dans un entrepôt Snowflake.
Pour plus d’informations, consultez les rubriques suivantes :
[Préparation des tables de données pour les requêtes dans AWS Clean Rooms](prepare-data.md)
[Création d'une table configurée — Source de données Snowflake](create-config-table-snowflake.md)
## Accès AWS Clean Rooms
Vous pouvez y accéder AWS Clean Rooms via les options suivantes :
+ Directement via la AWS Clean Rooms console à l'adresse [https://console.aws.amazon.com/cleanrooms/](https://console.aws.amazon.com/cleanrooms/).
+ Par programmation via l'API. AWS Clean Rooms Pour plus d’informations, consultez la [Référence des API *AWS Clean Rooms *](https://docs.aws.amazon.com/clean-rooms/latest/apireference/Welcome.html).
## Tarification pour AWS Clean Rooms
Pour de plus amples informations sur la tarification, veuillez consulter [AWS Clean Rooms Pricing](https://aws.amazon.com/clean-rooms/pricing/) (français non garanti).
**Note**
Pour les membres de la collaboration qui ont associé des données stockées dans Snowflake, leur fournisseur d'entrepôt de données ou leur fournisseur de cloud respectif vous factureront à la fois la sortie des données et le calcul chaque fois qu'une requête utilisant des données stockées dans ces emplacements est exécutée.
## Facturation pour AWS Clean Rooms
AWS Clean Rooms permet au créateur de la collaboration de désigner le membre qui prend en charge les coûts de calcul des requêtes ou des tâches dans le cadre de la collaboration.
Dans la plupart des cas, le [membre autorisé à effectuer une requête](glossary.md#glossary-member-who-can-query) et le [membre payant les frais de calcul des requêtes](glossary.md#glossary-member-paying-for-query-compute) sont les mêmes. Toutefois, si le membre autorisé à effectuer des requêtes et le membre payant les frais de calcul des requêtes sont différents, alors, lorsque le membre habilité à effectuer des requêtes exécute des requêtes sur sa propre ressource d'adhésion, la ressource d'adhésion du membre payant les coûts de calcul des requêtes est facturée.
Le membre qui paie les frais de calcul des requêtes ne voit aucun événement lié aux requêtes exécutées dans son historique des CloudTrail événements, car le payeur n'est ni celui qui exécute les requêtes ni le propriétaire de la ressource sur laquelle les requêtes sont exécutées. Cependant, le payeur perçoit des frais sur ses ressources d'adhésion pour toutes les requêtes exécutées par le membre qui peut exécuter des requêtes dans le cadre de la collaboration.
Pour plus d'informations sur la façon de créer une collaboration et de configurer le membre payant les coûts de calcul des requêtes, consultez[Création d'une collaboration](create-collaboration.md).
# Règles d'analyse dans AWS Clean Rooms
Dans le cadre de l'activation d'une table à des AWS Clean Rooms fins d'analyse de collaboration, le membre de la collaboration doit configurer une *règle d'analyse*.
Une règle d'analyse est un contrôle renforçant la confidentialité que chaque propriétaire de données met en place sur une table configurée. Une règle d'analyse détermine la manière dont la table configurée peut être analysée.
La règle d'analyse est un contrôle au niveau du compte sur la table configurée (une ressource au niveau du compte) et est appliquée dans toute collaboration où la table configurée est associée. Si aucune règle d'analyse n'est configurée, la table configurée peut être associée à des collaborations, mais elle ne peut pas être interrogée. Les requêtes peuvent uniquement faire référence à des tables configurées avec le même type de règle d'analyse.
Pour configurer une règle d'analyse, vous devez d'abord sélectionner un type d'analyse, puis spécifier la règle d'analyse. Pour les deux étapes, vous devez prendre en compte le cas d'utilisation que vous souhaitez activer et la manière dont vous souhaitez protéger vos données sous-jacentes.
AWS Clean Rooms applique les contrôles les plus restrictifs à toutes les tables configurées référencées dans une requête.
Les exemples suivants illustrent les contrôles restrictifs.
**Example Contrôle restrictif : contrainte de sortie**
+ Le collaborateur A a une contrainte de sortie sur la colonne d'identificateur de 100.
+ Le collaborateur B a une contrainte de sortie sur la colonne d'identificateur de 150.
Une requête d'agrégation qui fait référence aux deux tables configurées nécessite au moins 150 valeurs distinctes d'identifier dans une ligne de sortie pour qu'elle soit affichée dans la sortie de la requête. Le résultat de la requête n'indique pas que les résultats sont supprimés en raison de la contrainte de sortie.
**Example Contrôle restrictif : modèle d'analyse non approuvé**
+ Le collaborateur A a autorisé un modèle d'analyse avec une requête qui fait référence aux tables configurées du collaborateur A et du collaborateur B dans leur règle d'analyse personnalisée.
+ Le collaborateur B n'a pas autorisé le modèle d'analyse.
Le collaborateur B n'ayant pas autorisé le modèle d'analyse, le membre autorisé à effectuer une requête ne peut pas exécuter ce modèle d'analyse.
## Types de règles d'analyse
Il existe trois types de règles d'analyse : les règles d'[agrégation](analysis-rules-aggregation.md), les règles de [liste](analysis-rules-list.md) et les règles [personnalisées](analysis-rules-custom.md). Les tableaux suivants comparent les types de règles d'analyse. Chaque type comporte une section distincte qui décrit la spécification de la règle d'analyse.
**Note**
Il existe un type de règle d'analyse appelé règle d'analyse de table de mappage d'identifiants. Cependant, cette règle d'analyse est gérée par AWS Clean Rooms et ne peut pas être modifiée. Pour de plus amples informations, veuillez consulter [Règle d'analyse des tables de mappage d'identifiants](analysis-rules-id-mapping-table.md).
Les sections suivantes décrivent les cas d'utilisation et les contrôles pris en charge pour chaque type de règle d'analyse.
### Cas d'utilisation pris en charge
Les tableaux suivants présentent un résumé comparatif des cas d'utilisation pris en charge pour chaque type de règle d'analyse.
| Cas d’utilisation | [Agrégation](analysis-rules-aggregation.md) | [List](analysis-rules-list.md) | [Personnalisé](analysis-rules-custom.md) |
| --- | --- | --- | --- |
| Analyses prises en charge | Requêtes qui regroupent des statistiques à l'aide des fonctions COUNT, SUM et AVG selon des dimensions facultatives | Requêtes qui produisent des listes au niveau des lignes indiquant le chevauchement entre plusieurs tables | Toute analyse personnalisée, à condition que le modèle d'analyse ou le créateur de l'analyse aient été revus et autorisés |
| Cas d'utilisation courants | Analyse des segments, mesure, attribution | Enrichissement, création de segments | Attribution directe, analyses incrémentielles, découverte de l'audience |
| Constructions SQL | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/clean-rooms/latest/userguide/analysis-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/clean-rooms/latest/userguide/analysis-rules.html) | La plupart des fonctions et constructions SQL sont disponibles avec la commande SELECT |
| Sous-requêtes et expressions de table communes () CTEs | Non | Non | Oui |
| Modèles d'analyse | Non | Non | Oui |
### Contrôles pris en charge
Les tableaux suivants présentent un résumé comparatif de la manière dont chaque type de règle d'analyse protège vos données sous-jacentes.
| Contrôle | [Agrégation](analysis-rules-aggregation.md) | [List](analysis-rules-list.md) | [Personnalisé](analysis-rules-custom.md) |
| --- | --- | --- | --- |
| Mécanisme de commande | Contrôler la manière dont les données de la table peuvent être utilisées dans une requête*(Par exemple, autorisez COUNT et SUM de la colonne hashed\$1email.)* | Contrôler la manière dont les données de la table peuvent être utilisées dans une requête*(Par exemple, autorisez l'utilisation de la colonne hashed\$1email uniquement pour la connexion.)* | Contrôler les requêtes autorisées à s'exécuter sur la table*(Par exemple, autorisez uniquement les requêtes définies dans les modèles d'analyse « Requête personnalisée 1 ».)* |
| Techniques intégrées d'amélioration de la confidentialité | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/clean-rooms/latest/userguide/analysis-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/clean-rooms/latest/userguide/analysis-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/clean-rooms/latest/userguide/analysis-rules.html) |
| Vérifiez la requête avant de pouvoir l'exécuter | Non | Non | Oui, en utilisant des modèles d'analyse |
Pour plus d'informations sur les règles d'analyse disponibles dans AWS Clean Rooms, consultez les rubriques suivantes.
+ [Règle d'analyse d'agrégation](analysis-rules-aggregation.md)
+ [Règle d'analyse des listes](analysis-rules-list.md)
+ [Règle d'analyse personnalisée dans AWS Clean Rooms](analysis-rules-custom.md)
# Règle d'analyse d'agrégation
Dans AWS Clean Rooms, une *règle d'analyse d'agrégation* génère des statistiques agrégées à l'aide des fonctions COUNT, SUM, and/or AVG et de dimensions facultatives. Lorsque la règle d'analyse d'agrégation est ajoutée à une table configurée, elle permet au membre habilité à effectuer des requêtes sur la table configurée.
La règle d'analyse d'agrégation prend en charge les cas d'utilisation tels que la planification de campagnes, la portée médiatique, la mesure de fréquence et l'attribution.
La structure et la syntaxe de requête prises en charge sont définies dans[Structure et syntaxe des requêtes d'agrégation](#agg-query-structure-syntax).
Les paramètres de la règle d'analyse, définis dans[Règle d'analyse d'agrégation : contrôles des requêtes](#agg-query-controls), incluent les contrôles de requête et les contrôles de résultats de requête. Ses contrôles de requête incluent la possibilité d'exiger qu'une table configurée soit jointe à au moins une table configurée appartenant au membre qui peut effectuer une requête, directement ou de manière transitive. Cette exigence vous permet de vous assurer que la requête est exécutée à l'intersection (INNERJOIN) de votre table et de la leur.
## Structure et syntaxe des requêtes d'agrégation
Les requêtes sur les tables dotées d'une règle d'analyse d'agrégation doivent respecter la syntaxe suivante.
```
--select_aggregate_function_expression
SELECT
aggregation_function(column_name) [[AS] column_alias ] [, ...]
--select_grouping_column_expression
[, {column_name|scalar_function(arguments)} [[AS] column_alias ]][, ...]
--table_expression
FROM table_name [[AS] table_alias ]
[[INNER] JOIN table_name [[AS] table_alias] ON join_condition] [...]
--where_expression
[WHERE where_condition]
--group_by_expression
[GROUP BY {column_name|scalar_function(arguments)}, ...]]
--having_expression
[HAVING having_condition]
--order_by_expression
[ORDER BY {column_name|scalar_function(arguments)} [{ASC|DESC}]] [,...]]
```
Le tableau suivant explique chaque expression répertoriée dans la syntaxe précédente.
| Expression | Définition | Exemples |
| --- | --- | --- |
| select\$1aggregate\$1function\$1expression | Une liste séparée par des virgules contenant les expressions suivantes : [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/clean-rooms/latest/userguide/analysis-rules-aggregation.html) Il doit y en avoir au moins un `select_aggregation_function_expression` dans le`select_aggregate_expression`. | `SELECT SUM(PRICE), user_segment` |
| select\$1aggregation\$1function\$1expression | Une ou plusieurs fonctions d'agrégation prises en charge sont appliquées à une ou plusieurs colonnes. Seules les colonnes sont autorisées comme arguments des fonctions d'agrégation. Il doit y en avoir au moins un `select_aggregation_function_expression` dans le`select_aggregate_expression`. | `AVG(PRICE)` `COUNT(DISTINCT user_id)` |
| select\$1grouping\$1column\$1expression | Expression qui peut contenir n'importe quelle expression utilisant les éléments suivants : [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/clean-rooms/latest/userguide/analysis-rules-aggregation.html) `select_aggregate_expression`peut créer un alias pour les colonnes avec ou sans le `AS` paramètre. Pour plus d'informations, consultez la [référence AWS Clean Rooms SQL](https://docs.aws.amazon.com/clean-rooms/latest/sql-reference/sql-reference.html). | `TRUNC(timestampColumn)` `UPPER(campaignName)` |
| table\$1expression | Table, ou jointure de tables, reliant des expressions conditionnelles de jointure à`join_condition`. `join_condition`renvoie une valeur booléenne. Les `table_expression` supports : [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/clean-rooms/latest/userguide/analysis-rules-aggregation.html) | FROM consumer_table
INNER JOIN provider_table
ON
consumer_table.identifier1 = provider_table.identifier1
AND
consumer_table.identifier2 = provider_table.identifier2
|
| where\$1expression | Expression conditionnelle qui renvoie une valeur booléenne. Il peut être composé des éléments suivants : [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/clean-rooms/latest/userguide/analysis-rules-aggregation.html) Les conditions de comparaison prises en charge sont (`=, >, <, <=, >=, <>, !=, NOT, IN, NOT IN, LIKE, IS NULL, IS NOT NULL`). Les opérateurs logiques pris en charge sont (`AND, OR`). L’option `where_expression` est facultative. | `WHERE where_condition` `WHERE price > 100` `WHERE TRUNC(timestampColumn) = '1/1/2022'` `WHERE timestampColumn = timestampColumn2 - 14` |
| group\$1by\$1expression | Liste d'expressions séparées par des virgules qui répondent aux exigences du. `select_grouping_column_expression` | `GROUP BY TRUNC(timestampColumn), UPPER(campaignName), segment` |
| having\$1expression | Expression conditionnelle qui renvoie une valeur booléenne. Ils disposent d'une fonction d'agrégation prise en charge appliquée à une seule colonne (par exemple,`SUM(price)`) et sont comparés à un littéral numérique. Les conditions prises en charge sont (`=, >, <, <=, >=, <>, !=`). Les opérateurs logiques pris en charge sont (`AND, OR`). L’option `having_expression` est facultative. | `HAVING SUM(SALES) > 500` |
| order\$1by\$1expression | Liste d'expressions séparées par des virgules qui est compatible avec les mêmes exigences définies dans la section `select_aggregate_expression` définie précédemment. L’option `order_by_expression` est facultative. `order_by_expression`autorisations `ASC` et `DESC` paramètres. Pour plus d'informations, consultez la section Paramètres ASC DESC dans le manuel [AWS Clean Rooms SQL](https://docs.aws.amazon.com/clean-rooms/latest/sql-reference/sql-reference.html) Reference. | `ORDER BY SUM(SALES), UPPER(campaignName)` |
En ce qui concerne la structure et la syntaxe des requêtes d'agrégation, tenez compte des points suivants :
+ Les commandes SQL autres que ne SELECT sont pas prises en charge.
+ Les sous-requêtes et les expressions de table communes (par exemple,WITH) ne sont pas prises en charge.
+ Les opérateurs qui combinent plusieurs requêtes (par exemple,UNION) ne sont pas pris en charge.
+ TOPLIMIT, et les OFFSET paramètres ne sont pas pris en charge.
## Règle d'analyse d'agrégation : contrôles des requêtes
Grâce aux commandes de requête d'agrégation, vous pouvez contrôler la manière dont les colonnes de votre table sont utilisées pour interroger la table. Par exemple, vous pouvez contrôler quelle colonne est utilisée pour la jointure, quelle colonne peut être comptée ou quelle colonne peut être utilisée dans WHERE les instructions.
Les sections suivantes expliquent chaque contrôle.
**Topics**
+ [Contrôles d'agrégation](#agg-functions)
+ [Commandes de jointure](#join-controls)
+ [Contrôles dimensionnels](#dimension-controls)
+ [Fonctions scalaires](#scalar-functions)
### Contrôles d'agrégation
À l'aide *des contrôles d'agrégation*, vous pouvez définir les fonctions d'agrégation à autoriser et les colonnes auxquelles elles doivent être appliquées. Les fonctions d'agrégation peuvent être utilisées dans les ORDER BY expressions SELECTHAVING, et.
| Contrôle | Définition | Usage |
| --- | --- | --- |
| aggregateColumns | Colonnes de colonnes de table configurées que vous autorisez à utiliser dans les fonctions d'agrégation. | `aggregateColumns`peut être utilisé dans une fonction d'agrégation dans les ORDER BY expressions SELECTHAVING,, et. Certains `aggregateColumns` peuvent également être classés dans la catégorie « A » `joinColumn` (définis ultérieurement). Given ne `aggregateColumn` peut pas également être classé dans la catégorie `dimensionColumn` (défini ultérieurement). |
| function | Les fonctions COUNT, SUM et AVG que vous autorisez à utiliser en plus deaggregateColumns. | `function`peut être appliqué à un `aggregateColumns` objet qui lui est associé. |
### Commandes de jointure
Une `JOIN` clause est utilisée pour combiner les lignes de deux tables ou plus, sur la base d'une colonne associée entre elles.
Vous pouvez utiliser les *commandes de jointure* pour contrôler la manière dont votre table peut être jointe aux autres tables du`table_expression`. AWS Clean Rooms uniquement des supports INNERJOIN. INNERJOINles instructions ne peuvent utiliser que des colonnes explicitement classées comme telles `joinColumn` dans votre règle d'analyse, sous réserve des contrôles que vous définissez.
Ils INNER JOIN doivent opérer à `joinColumn` partir d'une table configurée et `joinColumn` à partir d'une autre table configurée dans la collaboration. Vous décidez quelles colonnes de votre tableau peuvent être utilisées`joinColumn`.
Chaque condition de correspondance contenue dans la ON clause est requise pour utiliser la condition de comparaison d'égalité (`=`) entre deux colonnes.
Plusieurs conditions de correspondance au sein d'une même ON clause peuvent être les suivantes :
+ Combiné à l'aide de l'opérateur `AND` logique
+ Séparé à l'aide de l'opérateur `OR` logique
**Note**
Toutes les JOIN conditions de match doivent correspondre à une ligne de chaque côté duJOIN. Toutes les conditions connectées par un opérateur `OR` ou un opérateur `AND` logique doivent également respecter cette exigence.
Voici un exemple de requête avec un opérateur `AND` logique.
```
SELECT some_col, other_col
FROM table1
JOIN table2
ON table1.id = table2.id AND table1.name = table2.name
```
Voici un exemple de requête avec un opérateur `OR` logique.
```
SELECT some_col, other_col
FROM table1
JOIN table2
ON table1.id = table2.id OR table1.name = table2.name
```
| Contrôle | Définition | Usage |
| --- | --- | --- |
| joinColumns | Les colonnes (le cas échéant) que vous souhaitez autoriser le membre autorisé à effectuer une requête à utiliser dans la INNER JOIN déclaration. | Un spécifique `joinColumn` peut également être classé dans la catégorie `aggregateColumn` (voir[Contrôles d'agrégation](#agg-functions)). La même colonne ne peut pas être utilisée à la fois comme `joinColumn` et `dimensionColumns` (voir plus loin). À moins qu'il n'ait également été classé dans la catégorie un`aggregateColumn`, a ne `joinColumn` peut être utilisé dans aucune autre partie de la requête que dans le INNERJOIN. |
| joinRequired | Déterminez si vous avez besoin INNER JOIN d'une table configurée de la part du membre qui peut effectuer la requête. | Si vous activez ce paramètre, un INNER JOIN est requis. Si vous n'activez pas ce paramètre, un INNER JOIN est facultatif. En supposant que vous activiez ce paramètre, le membre autorisé à effectuer une requête doit inclure une table qu'il possède dans le INNERJOIN. Ils doivent joindre JOIN votre table à la leur, soit directement, soit de manière transitive (c'est-à-dire joindre leur table à une autre table, elle-même jointe à la vôtre). |
Voici un exemple de transitivité.
```
ON
my_table.identifer = third_party_table.identifier
....
ON
third_party_table.identifier = member_who_can_query_table.id
```
**Note**
Le membre qui peut effectuer une requête peut également utiliser le `joinRequired` paramètre. Dans ce cas, la requête doit joindre sa table à au moins une autre table.
### Contrôles dimensionnels
Les *contrôles de dimension* contrôlent la colonne le long de laquelle les colonnes d'agrégation peuvent être filtrées, groupées ou agrégées.
| Contrôle | Définition | Usage |
| --- | --- | --- |
| dimensionColumns | Les colonnes (le cas échéant) que vous autorisez le membre autorisé à effectuer une requête à utiliser dans SELECTWHERE, GROUPBY, et ORDERBY. | A `dimensionColumn` peut être utilisé dans SELECT (`select_grouping_column_expression`)WHERE, GROUPBY, et ORDERBY. La même colonne ne peut pas être à la fois a `dimensionColumn``joinColumn`, a et and/or an`aggregateColumn`. |
### Fonctions scalaires
*Les fonctions scalaires contrôlent les fonctions* scalaires qui peuvent être utilisées sur les colonnes de dimension.
| Contrôle | Définition | Usage |
| --- | --- | --- |
| scalarFunctions | Les fonctions scalaires qui peuvent être utilisées `dimensionColumns` dans la requête. | Spécifie les fonctions scalaires (le cas échéant) auxquelles vous autorisez (par exempleCAST) l'`dimensionColumns`application. Les fonctions scalaires ne peuvent pas être utilisées par-dessus d'autres fonctions ou au sein d'autres fonctions. Les arguments des fonctions scalaires peuvent être des colonnes, des chaînes littérales ou des littéraux numériques. |
Les fonctions scalaires suivantes sont prises en charge :
+ Fonctions mathématiques : ABS, PLAFOND, PLANCHER, BOIS, LN, ROND, SQRT
+ Fonctions de formatage des types de données — CAST, CONVERT, TO\$1CHAR, TO\$1DATE, TO\$1NUMBER, TO\$1TIMESTAMP
+ Fonctions de chaîne : LOWER, UPPER, TRIM, RTRIM, SUBSTRING
+ Pour RTRIM, les jeux de caractères personnalisés à découper ne sont pas autorisés.
+ Expressions conditionnelles — COALESCE
+ Fonctions de date : EXTRACT, GETDATE, CURRENT\$1DATE, DATEADD
+ Autres fonctions — TRUNC
Pour plus de détails, consultez la [référence AWS Clean Rooms SQL](https://docs.aws.amazon.com/clean-rooms/latest/sql-reference/sql-reference.html).
## Règle d'analyse d'agrégation : contrôles des résultats des requêtes
Avec les contrôles des résultats des requêtes d'agrégation, vous pouvez contrôler les résultats renvoyés en spécifiant une ou plusieurs conditions que chaque ligne de sortie doit remplir pour être renvoyée. AWS Clean Rooms prend en charge les contraintes d'agrégation sous la forme de`COUNT (DISTINCT column) >= X`. Ce formulaire exige que chaque ligne agrège au moins X valeurs distinctes d'un choix dans votre table configurée (par exemple, un nombre minimum de `user_id` valeurs distinctes). Ce seuil minimum est automatiquement appliqué, même si la requête soumise elle-même n'utilise pas la colonne spécifiée. Ils sont appliqués collectivement sur chaque table configurée dans la requête à partir des tables configurées de chaque membre de la collaboration.
Chaque table configurée doit comporter au moins une contrainte d'agrégation dans sa règle d'analyse. Les propriétaires de tables configurées peuvent en ajouter plusieurs `columnName` et `minimum` les associer, et elles sont appliquées collectivement.
### Contraintes d'agrégation
*Les contraintes d'agrégation* contrôlent les lignes renvoyées dans les résultats de la requête. Pour être renvoyée, une ligne doit respecter le nombre minimum de valeurs distinctes spécifié dans chaque colonne spécifiée dans la contrainte d'agrégation. Cette exigence s'applique même si la colonne n'est pas explicitement mentionnée dans la requête ou dans d'autres parties de la règle d'analyse.
| Contrôle | Définition | Usage |
| --- | --- | --- |
| columnName | Le `aggregateColumn` qui est utilisé dans la condition que chaque ligne de sortie doit remplir. | Il peut s'agir de n'importe quelle colonne de la table configurée. |
| minimum | Le nombre minimum de valeurs distinctes associées `aggregateColumn` que la ligne de sortie doit avoir (par exemple, COUNT DISTINCT) pour qu'elle soit renvoyée dans les résultats de la requête. | La valeur `minimum` doit être au moins égale à 2. |
## Structure des règles d'analyse d'agrégation
L'exemple suivant montre une structure prédéfinie pour une règle d'analyse d'agrégation.
Dans l'exemple suivant, *`MyTable`* fait référence à votre table de données. Vous pouvez remplacer chacune d'entre elles *user input placeholder* par vos propres informations.
```
{
"aggregateColumns": [
{
"columnNames": [MyTable column names], "function": [Allowed Agg Functions]
},
],
"joinRequired": ["QUERY_RUNNER"],
"joinColumns": [MyTable column names],
"dimensionColumns": [MyTable column names],
"scalarFunctions": [Allowed Scalar functions],
"outputConstraints": [
{
"columnName": [MyTable column names], "minimum": [Numeric value]
},
]
}
```
## Règle d'analyse d'agrégation - exemple
L'exemple suivant montre comment deux entreprises peuvent collaborer à AWS Clean Rooms l'aide de l'analyse d'agrégation.
L'entreprise A possède des données sur les clients et les ventes. L'entreprise A souhaite comprendre l'activité de retour de produits. L'entreprise B est l'un des détaillants de l'entreprise A et possède des données sur les retours. L'entreprise B possède également des attributs de segment relatifs aux clients qui sont utiles à l'entreprise A (par exemple, achat de produits connexes, utilisation du service client du détaillant). L'entreprise B ne souhaite pas fournir de données de retour client au niveau des lignes ni d'informations sur les attributs. L'entreprise B souhaite uniquement activer un ensemble de requêtes pour que l'entreprise A obtienne des statistiques agrégées sur les clients qui se chevauchent à un seuil d'agrégation minimum.
L'entreprise A et l'entreprise B décident de collaborer afin que l'entreprise A puisse comprendre l'activité de retour des produits et fournir de meilleurs produits à l'entreprise B et à d'autres canaux.
Pour créer la collaboration et exécuter une analyse d'agrégation, les entreprises procèdent comme suit :
1. L'entreprise A crée une collaboration et crée une adhésion. La collaboration a la société B comme autre membre de la collaboration. L'entreprise A active la journalisation des requêtes dans la collaboration, et elle permet la journalisation des requêtes dans son compte.
1. L'entreprise B crée une adhésion à la collaboration. Il permet la journalisation des requêtes dans son compte.
1. La société A crée une table configurée pour les ventes.
1. La société A ajoute la règle d'analyse d'agrégation suivante au tableau des ventes configuré.
```
{
"aggregateColumns": [
{
"columnNames": [
"identifier"
],
"function": "COUNT_DISTINCT"
},
{
"columnNames": [
"purchases"
],
"function": "AVG"
},
{
"columnNames": [
"purchases"
],
"function": "SUM"
}
],
"joinColumns": [
"hashedemail"
],
"dimensionColumns": [
"demoseg",
"purchasedate",
"productline"
],
"scalarFunctions": [
"CAST",
"COALESCE",
"TRUNC"
],
"outputConstraints": [
{
"columnName": "hashedemail",
"minimum": 2,
"type": "COUNT_DISTINCT"
},
]
}
```
`aggregateColumns`— L'entreprise A souhaite compter le nombre de clients uniques entre les données de vente et les données de retours. L'entreprise A souhaite également additionner le nombre de `purchases` produits fabriqués pour le comparer au nombre de`returns`.
`joinColumns`— L'entreprise A souhaite utiliser pour faire correspondre `identifier` les clients à partir des données de vente aux clients à partir des données de retours. Cela aidera l'entreprise A à faire correspondre les retours aux bons achats. Cela aide également l'entreprise A à segmenter les clients qui se recoupent.
`dimensionColumns`— L'entreprise A filtre en `dimensionColumns` fonction du produit spécifique, compare les achats et les retours sur une certaine période, s'assure que la date de retour est postérieure à la date du produit et aide à segmenter les clients qui se recoupent.
`scalarFunctions`— L'entreprise A sélectionne une fonction `CAST` scalaire pour aider à mettre à jour les formats des types de données si nécessaire en fonction de la table configurée que l'entreprise A associe à la collaboration. Il ajoute également des fonctions scalaires pour aider à formater les colonnes si nécessaire.
`outputConstraints`— L'entreprise A définit des contraintes de sortie minimales. Il n'est pas nécessaire de restreindre les résultats car l'analyste est autorisé à voir les données au niveau des lignes depuis son tableau des ventes
**Note**
L'entreprise A n'est pas incluse `joinRequired` dans la règle d'analyse. Cela permet à leur analyste d'interroger seul le tableau des ventes.
1. La société B crée une table de retours configurée.
1. La société B ajoute la règle d'analyse d'agrégation suivante à la table des retours configurés.
```
{
"aggregateColumns": [
{
"columnNames": [
"identifier"
],
"function": "COUNT_DISTINCT"
},
{
"columnNames": [
"returns"
],
"function": "AVG"
},
{
"columnNames": [
"returns"
],
"function": "SUM"
}
],
"joinColumns": [
"hashedemail"
],
"joinRequired": [
"QUERY_RUNNER"
],
"dimensionColumns": [
"state",
"popularpurchases",
"customerserviceuser",
"productline",
"returndate"
],
"scalarFunctions": [
"CAST",
"LOWER",
"UPPER",
"TRUNC"
],
"outputConstraints": [
{
"columnName": "hashedemail",
"minimum": 100,
"type": "COUNT_DISTINCT"
},
{
"columnName": "producttype",
"minimum": 2,
"type": "COUNT_DISTINCT"
}
]
}
```
`aggregateColumns`— L'entreprise B permet à l'entreprise A de `returns` faire la somme pour comparer le nombre d'achats. Ils ont au moins une colonne d'agrégation car ils activent une requête d'agrégation.
`joinColumns`— L'entreprise B permet à l'entreprise A de se joindre à elle `identifier` pour faire correspondre les clients à partir des données de retour aux clients à partir des données de vente. `identifier`les données sont particulièrement sensibles et leur utilisation `joinColumn` garantit qu'elles ne seront jamais sorties dans une requête.
`joinRequired`— L'entreprise B exige que les requêtes sur les données de retour soient recoupées avec les données de vente. Ils ne veulent pas permettre à l'entreprise A d'interroger tous les individus de leur ensemble de données. Ils ont également convenu de cette restriction dans leur accord de collaboration.
`dimensionColumns`— L'entreprise B permet à l'entreprise A de filtrer et de regrouper par `state``popularpurchases`, et `customerserviceuser` qui sont des attributs uniques qui pourraient aider à effectuer l'analyse pour l'entreprise A. L'entreprise B permet à l'entreprise A d'utiliser `returndate` pour filtrer les résultats en fonction de `returndate` ce qui se produit après`purchasedate`. Grâce à ce filtrage, le résultat est plus précis pour évaluer l'impact du changement de produit.
`scalarFunctions`— La société B permet ce qui suit :
+ TRUNC pour les dates
+ INFÉRIEUR et SUPÉRIEUR au cas où ils `producttype` sont saisis dans un format différent dans leurs données
+ CASTsi l'entreprise A doit convertir les types de données des ventes pour qu'ils soient identiques aux types de données des retours
La société A n'active pas d'autres fonctions scalaires car elle ne pense pas qu'elles soient nécessaires pour les requêtes.
`outputConstraints`— L'entreprise B impose des contraintes de production minimales `hashedemail` afin de réduire la capacité à réidentifier les clients. Cela ajoute également une contrainte de sortie minimale afin `producttype` de réduire la capacité de réidentifier les produits spécifiques qui ont été renvoyés. Certains types de produits peuvent être plus dominants en fonction des dimensions de la sortie (par exemple,`state`). Leurs contraintes de sortie seront toujours appliquées, quelles que soient les contraintes de sortie ajoutées par l'entreprise A à ses données.
1. L'entreprise A crée une table de vente associée à la collaboration.
1. L'entreprise B crée une association de tables de retours à la collaboration.
1. L'entreprise A exécute des requêtes, comme dans l'exemple suivant, pour mieux comprendre le nombre de retours dans l'entreprise B par rapport au total des achats par site en 2022.
```
SELECT
companyB.state,
SUM(companyB.returns),
COUNT(DISTINCT companyA.hashedemail)
FROM
sales companyA
INNER JOIN returns companyB ON companyA.identifier = companyB.identifier
WHERE
companyA.purchasedate BETWEEN '2022-01-01' AND '2022-12-31' AND
TRUNC(companyB.returndate) > companyA.purchasedate
GROUP BY
companyB.state;
```
1. Les entreprises A et B examinent les journaux de requêtes. L'entreprise B vérifie que la requête est conforme à ce qui a été convenu dans l'accord de collaboration.
## Résolution des problèmes liés aux règles d'analyse d'agrégation
Utilisez les informations présentées ici pour vous aider à diagnostiquer et à résoudre les problèmes courants liés à l'utilisation des règles d'analyse d'agrégation.
**Topics**
+ [Ma requête n'a renvoyé aucun résultat](#query-no-results)
### Ma requête n'a renvoyé aucun résultat
Cela peut se produire en l'absence de résultats correspondants ou lorsque les résultats correspondants n'atteignent pas un ou plusieurs seuils d'agrégation minimaux.
Pour plus d'informations sur les seuils d'agrégation minimaux, consultez[Règle d'analyse d'agrégation - exemple](#agg-analysis-rule-example).
# Règle d'analyse des listes
Dans AWS Clean Rooms, une *règle d'analyse de liste* produit des listes au niveau des lignes indiquant le chevauchement entre la table configurée à laquelle elle est ajoutée et les tables configurées du membre qui peut effectuer la requête. Le membre habilité à effectuer des requêtes exécute des requêtes qui incluent une règle d'analyse de liste.
Le type de règle d'analyse de liste prend en charge les cas d'utilisation tels que l'enrichissement et la création d'audience.
Pour plus d'informations sur la structure de requête et la syntaxe prédéfinies pour cette règle d'analyse, consultez[Structure prédéfinie des règles d'analyse des listes](#intersection-list-params-template).
Les paramètres de la règle d'analyse de liste, définis dans[Règle d'analyse des listes : contrôles des requêtes](#parameters-list-query-controls), comportent des contrôles de requête. Ses commandes de requête incluent la possibilité de sélectionner les colonnes qui peuvent être répertoriées dans la sortie. La requête doit comporter au moins une jointure avec une table configurée provenant du membre qui peut effectuer la requête, directement ou de manière transitive.
Il n'existe aucun contrôle des résultats de requête comme c'est le cas pour la [règle d'analyse d'agrégation](analysis-rules-aggregation.md).
Les requêtes de liste ne peuvent utiliser que des opérateurs mathématiques. Ils ne peuvent pas utiliser d'autres fonctions (telles que l'agrégation ou le scalaire).
**Topics**
+ [Structure et syntaxe des requêtes de liste](#list-query-controls)
+ [Règle d'analyse des listes : contrôles des requêtes](#parameters-list-query-controls)
+ [Structure prédéfinie des règles d'analyse des listes](#intersection-list-params-template)
+ [Règle d'analyse des listes - exemple](#list-example)
## Structure et syntaxe des requêtes de liste
Les requêtes sur les tables dotées d'une règle d'analyse de liste doivent respecter la syntaxe suivante.
```
--select_list_expression
SELECT DISTINCT column_name [[AS] column_alias ] [, ...]
--table_expression
FROM table_name [[AS] table_alias ]
[[INNER] JOIN table_name [[AS] table_alias] ON join_condition] [...]
--where_expression
[WHERE where_condition]
--limit_expression
[LIMIT number]
```
Le tableau suivant explique chaque expression répertoriée dans la syntaxe précédente.
| Expression | Définition | Exemples |
| --- | --- | --- |
| select\$1list\$1expression | Liste séparée par des virgules contenant au moins un nom de colonne de table. Un `DISTINCT` paramètre est obligatoire. Ils `select_list_expression` peuvent aliaser les colonnes avec ou sans le `AS` paramètre. Pour plus d'informations, consultez la [référence AWS Clean Rooms SQL](https://docs.aws.amazon.com/clean-rooms/latest/sql-reference/sql-reference.html). | `SELECT DISTINCT segment` |
| table\$1expression | Une table, ou une jointure de tables, `join_condition` à laquelle la connecter`join_condition`. `join_condition`renvoie un booléen. Les `table_expression` supports : [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/clean-rooms/latest/userguide/analysis-rules-list.html) | FROM consumer_table
INNER JOIN provider_table
ON
consumer_table.identifier1 = provider_table.identifier1
AND
consumer_table.identifier2 = provider_table.identifier2
|
| where\$1expression | Expression conditionnelle qui renvoie une valeur booléenne. Il peut être composé des éléments suivants :[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/clean-rooms/latest/userguide/analysis-rules-list.html)Les conditions de comparaison prises en charge sont (`=, >, <, <=, >=, <>, !=, NOT, IN, NOT IN, LIKE, IS NULL, IS NOT NULL`). Les opérateurs logiques pris en charge sont (`AND, OR`).L’option `where_expression` est facultative. | `WHERE state + '_' + city = 'NY_NYC'` `WHERE timestampColumn = timestampColumn2 - 14` |
| limit\$1expression | Cette expression doit prendre un entier positif. L’option `limit_expression` est facultative. | `LIMIT 100` |
En ce qui concerne la structure et la syntaxe des requêtes de liste, tenez compte des points suivants :
+ Les commandes SQL autres que SELECT ne sont pas prises en charge.
+ Les sous-requêtes et les expressions de table communes (par exemple,WITH) ne sont pas prises en charge
+ Les BY clauses GROUP BY HAVING, et ORDER ne sont pas prises en charge
+ Le paramètre OFFSET n'est pas pris en charge
## Règle d'analyse des listes : contrôles des requêtes
Avec les commandes de requête de liste, vous pouvez contrôler la manière dont les colonnes de votre table sont utilisées pour interroger la table. Par exemple, vous pouvez contrôler quelle colonne est utilisée pour la jointure ou quelle colonne peut être utilisée dans l'instruction et la WHERE clause SELECT.
Les sections suivantes expliquent chaque contrôle.
**Topics**
+ [Commandes de jointure](#list-controls-join-controls)
+ [Contrôles de liste](#list-controls)
### Commandes de jointure
Avec *les commandes Join*, vous pouvez contrôler la manière dont votre table peut être jointe aux autres tables de la **table\$1expression**. AWS Clean Rooms supporte uniquement INNER JOIN. Dans la règle d'analyse de liste, au moins un INNER JOIN est requis et le membre qui peut effectuer une requête doit inclure une table qu'il possède dans le INNER JOIN. Cela signifie qu'ils doivent joindre votre table à la leur, directement ou de manière transitionnelle.
Voici un exemple de transitivité.
```
ON
my_table.identifer = third_party_table.identifier
....
ON
third_party_table.identifier = member_who_can_query_table.id
```
INNERLes instructions JOIN ne peuvent utiliser que des colonnes explicitement classées comme telles `joinColumn` dans votre règle d'analyse.
Le INNER JOIN doit fonctionner sur une table `joinColumn` à partir de votre table configurée et `joinColumn` à partir d'une autre table configurée dans la collaboration. Vous décidez quelles colonnes de votre tableau peuvent être utilisées`joinColumn`.
Chaque condition de correspondance contenue dans la ON clause est requise pour utiliser la condition de comparaison d'égalité (`=`) entre deux colonnes.
Plusieurs conditions de correspondance au sein d'une ON clause peuvent être les suivantes :
+ Combiné à l'aide de l'opérateur `AND` logique
+ Séparé à l'aide de l'opérateur `OR` logique
**Note**
Toutes les JOIN conditions de match doivent correspondre à une ligne de chaque côté duJOIN. Toutes les conditions connectées par un opérateur `OR` ou un opérateur `AND` logique doivent également respecter cette exigence.
Voici un exemple de requête avec un opérateur `AND` logique.
```
SELECT some_col, other_col
FROM table1
JOIN table2
ON table1.id = table2.id AND table1.name = table2.name
```
Voici un exemple de requête avec un opérateur `OR` logique.
```
SELECT some_col, other_col
FROM table1
JOIN table2
ON table1.id = table2.id OR table1.name = table2.name
```
| Contrôle | Définition | Usage |
| --- | --- | --- |
| joinColumns | Les colonnes que vous souhaitez autoriser le membre autorisé à effectuer une requête à utiliser dans l'instruction INNER JOIN. | La même colonne ne peut pas être classée à la fois comme a `joinColumn` et `listColumn` (voir[Contrôles de liste](#list-controls)). `joinColumn`ne peut être utilisé dans aucune autre partie de la requête que INNER JOIN. |
### Contrôles de liste
Les *contrôles de liste* contrôlent les colonnes qui peuvent être répertoriées dans le résultat de la requête (c'est-à-dire utilisées dans l'instruction SELECT) ou utilisées pour filtrer les résultats (c'est-à-dire utilisées dans l'WHEREinstruction).
| Contrôle | Définition | Usage |
| --- | --- | --- |
| listColumns | Les colonnes que vous autorisez le membre qui peut effectuer une requête à utiliser dans le SELECT et WHERE | A listColumn peut être utilisé dans SELECT etWHERE.La même colonne ne peut pas être utilisée à la fois comme `listColumn` et`joinColumn`. |
## Structure prédéfinie des règles d'analyse des listes
L'exemple suivant inclut une structure prédéfinie qui montre comment exécuter une règle d'analyse de liste.
Dans l'exemple suivant, *`MyTable`* fait référence à votre table de données. Vous pouvez remplacer chacune *user input placeholder* par vos propres informations.
```
{
"joinColumns": [MyTable column name(s)],
"listColumns": [MyTable column name(s)],
}
```
## Règle d'analyse des listes - exemple
L'exemple suivant montre comment deux entreprises peuvent collaborer à AWS Clean Rooms l'aide de l'analyse de listes.
L'entreprise A dispose de données de gestion de la relation client (CRM). L'entreprise A souhaite obtenir des données sectorielles supplémentaires sur ses clients pour en savoir plus sur leurs clients et éventuellement utiliser des attributs comme données d'entrée dans d'autres analyses. L'entreprise B possède des données de segment composées d'attributs de segment uniques qu'elle a créés sur la base de ses données de première partie. L'entreprise B souhaite fournir les attributs de segment uniques à l'entreprise A uniquement pour les clients dont les données se chevauchent avec celles de l'entreprise A.
Les entreprises décident de collaborer afin que l'entreprise A puisse enrichir les données qui se chevauchent. L'entreprise A est le membre qui peut interroger, et l'entreprise B est le contributeur.
Pour créer une collaboration et exécuter une analyse de liste en collaboration, les entreprises procèdent comme suit :
1. L'entreprise A crée une collaboration et crée une adhésion. La collaboration a la société B comme autre membre de la collaboration. L'entreprise A active la journalisation des requêtes dans la collaboration, et elle active la journalisation des requêtes dans son compte.
1. L'entreprise B crée une adhésion à la collaboration. Il permet la journalisation des requêtes dans son compte.
1. L'entreprise A crée une table configurée pour le CRM
1. L'entreprise A ajoute la règle d'analyse à la table configurée par le client, comme indiqué dans l'exemple suivant.
```
{
"joinColumns": [
"identifier1",
"identifier2"
],
"listColumns": [
"internalid",
"segment1",
"segment2",
"customercategory"
]
}
```
`joinColumns`— L'entreprise A souhaite utiliser `hashedemail` and/or `thirdpartyid` (obtenu auprès d'un fournisseur d'identité) pour faire correspondre les clients à partir des données CRM aux clients à partir de données segmentées. Cela permettra de garantir que l'entreprise A associe des données enrichies aux bons clients. Ils ont deux JoinColumns pour potentiellement améliorer le taux de correspondance de l'analyse.
`listColumns`— L'entreprise A utilise `listColumns` pour obtenir des colonnes enrichies à côté d'une colonne `internalid` qu'elle utilise dans ses propres systèmes. Ils ajoutent `segment1` et limitent potentiellement l'enrichissement `customercategory` à des segments spécifiques en les utilisant dans des filtres. `segment2`
1. La société B crée une table configurée par segments.
1. L'entreprise B ajoute la règle d'analyse à la table des segments configurés.
```
{
"joinColumns": [
"identifier2"
],
"listColumns": [
"segment3",
"segment4"
]
}
```
`joinColumns`— L'entreprise B permet à l'entreprise A de se joindre à elle pour `identifier2` faire correspondre les clients, qu'il s'agisse de données segmentées ou de données CRM. Les sociétés A et B ont travaillé avec le fournisseur d'identité pour `identifier2` déterminer laquelle correspondrait à cette collaboration. Ils n'en ont pas ajouté d'autres `joinColumns` parce qu'ils pensaient `identifier2` que c'était le taux de correspondance le plus élevé et le plus précis possible et qu'aucun autre identifiant n'était requis pour les requêtes.
`listColumns`— L'entreprise B permet à l'entreprise A d'enrichir ses données `segment3` et ses `segment4` attributs, qui sont des attributs uniques qu'elle a créés, collectés et sur lesquels elle s'est alignée (avec le client A) afin de participer à l'enrichissement des données. Ils souhaitent que l'entreprise A obtienne ces segments pour le chevauchement au niveau des lignes, car il s'agit d'une collaboration d'enrichissement des données.
1. L'entreprise A crée une association de tables CRM pour la collaboration.
1. L'entreprise B crée une association de tables de segments pour la collaboration.
1. L'entreprise A exécute des requêtes, telles que la suivante, pour enrichir les données clients qui se recoupent.
```
SELECT companyA.internalid, companyB.segment3, companyB.segment4
INNER JOIN returns companyB
ON companyA.identifier2 = companyB.identifier2
WHERE companyA.customercategory > 'xxx'
```
1. Les entreprises A et B examinent les journaux de requêtes. L'entreprise B vérifie que la requête est conforme à ce qui a été convenu dans l'accord de collaboration.
# Règle d'analyse personnalisée dans AWS Clean Rooms
Dans AWS Clean Rooms, une *règle d'analyse personnalisée* est un nouveau type de règle d'analyse qui permet d'exécuter des requêtes personnalisées sur la table configurée. Les requêtes SQL personnalisées sont toujours limitées à la SELECT commande, mais elles peuvent utiliser davantage de constructions SQL que les requêtes d'[agrégation](analysis-rules-aggregation.md#agg-query-controls) et de [liste](analysis-rules-list.md#list-query-controls) (par exemple, des fonctions de fenêtre, OUTER JOIN ou des sous-requêtes ; voir la [référence AWS Clean Rooms SQL](https://docs.aws.amazon.com/clean-rooms/latest/sql-reference/sql-reference.html) pour une liste complète). CTEs Les requêtes SQL personnalisées ne doivent pas nécessairement suivre une structure de requête telle que les requêtes d'[agrégation](analysis-rules-aggregation.md#agg-query-structure-syntax) et de [liste](analysis-rules-list.md#list-query-controls).
La règle d'analyse personnalisée prend en charge des cas d'utilisation plus avancés que ceux qui peuvent être pris en charge par la règle d'agrégation et d'analyse de liste, tels que l'analyse d'attribution personnalisée, le benchmarking, l'analyse d'incrémentalité et la découverte d'audience. Cela s'ajoute à un surensemble des cas d'utilisation pris en charge par les règles d'agrégation et d'analyse de listes.
La règle d'analyse personnalisée prend également en charge la confidentialité différentielle. La confidentialité différentielle est un cadre mathématiquement rigoureux pour la protection de la confidentialité des données. Pour de plus amples informations, veuillez consulter [AWS Clean Rooms Confidentialité différentielle](differential-privacy.md). Lorsque vous créez un modèle d'analyse, AWS Clean Rooms Differential Privacy vérifie le modèle pour déterminer s'il est compatible avec la structure de requête à usage général pour AWS Clean Rooms Differential Privacy. Cette validation garantit que vous ne créez pas de modèle d'analyse non autorisé avec une table protégée par la confidentialité différentielle.
Pour configurer la règle d'analyse personnalisée, les propriétaires de données peuvent choisir d'autoriser l'exécution de requêtes personnalisées spécifiques, stockées dans des [modèles d'analyse](create-analysis-template.md), sur leurs tables configurées. Les propriétaires de données examinent les modèles d'analyse avant de les ajouter au contrôle d'analyse autorisé dans la règle d'analyse personnalisée. Les modèles d'analyse sont disponibles et visibles uniquement dans la collaboration dans laquelle ils ont été créés (même si la table est associée à d'autres collaborations) et ne peuvent être exécutés que par le membre qui peut effectuer des requêtes dans cette collaboration.
Les membres peuvent également choisir d'autoriser d'autres membres (fournisseurs de requêtes) à créer des requêtes sans révision. Les membres ajoutent les comptes des fournisseurs de requêtes que les fournisseurs de requêtes autorisés contrôlent dans la règle d'analyse personnalisée. Si le fournisseur de requêtes est le membre habilité à effectuer une requête, il peut exécuter n'importe quelle requête directement sur la table configurée. Les fournisseurs de requêtes peuvent également créer des requêtes en [créant des modèles d'analyse](create-analysis-template.md). Toutes les requêtes créées par les fournisseurs de requêtes sont automatiquement autorisées à s'exécuter sur la table dans toutes les collaborations dans lesquelles elles sont présentes et où la table est associée. Compte AWS
Les propriétaires de données peuvent uniquement autoriser les modèles d'analyse ou les comptes à créer des requêtes, et non les deux. Si le propriétaire des données le laisse vide, le membre autorisé à effectuer des requêtes ne peut pas exécuter de requêtes sur la table configurée.
**Topics**
+ [Structure prédéfinie des règles d'analyse personnalisées](#custom-predefined-structure)
+ [Exemple de règle d'analyse personnalisée](#custom-example)
+ [Règle d'analyse personnalisée avec confidentialité différentielle](#custom-diff-privacy)
## Structure prédéfinie des règles d'analyse personnalisées
L'exemple suivant inclut une structure prédéfinie qui vous montre comment exécuter une règle d'analyse personnalisée avec la confidentialité différentielle activée. La `userIdentifier` valeur est la colonne qui identifie de manière unique vos utilisateurs, telle que *user\$1id*. Lorsque la confidentialité différentielle est activée sur deux tables ou plus dans le cadre d'une collaboration, AWS Clean Rooms cela vous oblige à configurer la même colonne que la colonne d'identifiant utilisateur dans les deux règles d'analyse afin de maintenir une définition cohérente des utilisateurs entre les tables.
```
{
"allowedAnalyses": ["ANY_QUERY"] | string[],
"allowedAnalysisProviders": [],
"differentialPrivacy": {
"columns": [
{
"name": "userIdentifier"
}
]
}
}
```
Vous avez le choix entre les options suivantes :
+ Ajoutez un modèle ARNs d'analyse au contrôle des analyses autorisées. Dans ce cas, le `allowedAnalysisProviders` contrôle n'est pas inclus.
```
{
allowedAnalyses: string[]
}
```
+ Ajoutez un membre Compte AWS IDs au `allowedAnalysisProviders` contrôle. Dans ce cas, vous ajoutez `ANY_QUERY` au `allowedAnalyses` contrôle.
```
{
allowedAnalyses: ["ANY_QUERY"],
allowedAnalysisProviders: string[]
}
```
## Exemple de règle d'analyse personnalisée
L'exemple suivant montre comment deux entreprises peuvent collaborer à AWS Clean Rooms l'aide de la règle d'analyse personnalisée.
L'entreprise A possède des données sur les clients et les ventes. L'entreprise A souhaite comprendre l'augmentation des ventes d'une campagne publicitaire sur le site de l'entreprise B. L'entreprise B possède des données d'audience et des attributs de segment utiles à l'entreprise (par exemple, l'appareil utilisé pour visionner la publicité).
L'entreprise A souhaite exécuter une requête d'incrémentalité spécifique dans le cadre de la collaboration.
Pour créer une collaboration et exécuter une analyse personnalisée en collaboration, les entreprises procèdent comme suit :
1. L'entreprise A crée une collaboration et crée une adhésion. La collaboration a la société B comme autre membre de la collaboration. L'entreprise A active la journalisation des requêtes dans la collaboration, et elle active la journalisation des requêtes dans son compte.
1. L'entreprise B crée une adhésion à la collaboration. Il permet la journalisation des requêtes dans son compte.
1. L'entreprise A crée une table configurée pour le CRM
1. La société A ajoute une règle d'analyse personnalisée vide à la table configurée des ventes.
1. L'entreprise A associe la table configurée des ventes à la collaboration.
1. La société B crée une table configurée pour le nombre de vues.
1. La société B ajoute une règle d'analyse personnalisée vide à la table configurée par le nombre de vues.
1. La société B associe la table configurée en termes de nombre de vues à la collaboration.
1. L'entreprise A consulte le tableau des ventes et le tableau d'audience associés à la collaboration et crée un modèle d'analyse, en ajoutant la requête d'incrémentalité et le paramètre pour le mois de la campagne.
```
{
"analysisParameters": [
{
"defaultValue": ""
"type": "DATE"
"name": "campaign_month"
}
],
"description": "Monthly incrementality query using sales and viewership data"
"format": "SQL"
"name": "Incrementality analysis"
"source":
"WITH labeleddata AS
(
SELECT hashedemail, deviceid, purchases, unitprice, purchasedate,
CASE
WHEN testvalue IN ('value1', 'value2', 'value3') THEN 0
ELSE 1
END AS testgroup
FROM viewershipdata
)
SELECT labeleddata.purchases, provider.impressions
FROM labeleddata
INNER JOIN salesdata
ON labeleddata.hashedemail = provider.hashedemail
WHERE MONTH(labeleddata.purchasedate) > :campaignmonth
AND testgroup = :group
"
}
```
1. L'entreprise A ajoute son compte (par exemple, 444455556666) au contrôle du fournisseur d'analyse autorisé dans la règle d'analyse personnalisée. Ils utilisent le contrôle du fournisseur d'analyse autorisé car ils souhaitent autoriser l'exécution de toutes les requêtes qu'ils créent sur leur table configurée pour les ventes.
```
{
"allowedAnalyses": [
"ANY_QUERY"
],
"allowedAnalysisProviders": [
"444455556666"
]
}
```
1. L'entreprise B voit le modèle d'analyse créé dans la collaboration et en examine le contenu, y compris la chaîne de requête et le paramètre.
1. L'entreprise B détermine que le modèle d'analyse répond au cas d'utilisation de l'incrémentalité et répond à ses exigences de confidentialité quant à la manière dont sa table configurée d'audience peut être interrogée.
1. La société B ajoute l'ARN du modèle d'analyse au contrôle d'analyse autorisé dans la règle d'analyse personnalisée de la table d'audience. Ils utilisent le contrôle d'analyse autorisé car ils souhaitent uniquement autoriser l'exécution de la requête d'incrémentalité sur leur table configurée par affichage.
```
{
"allowedAnalyses": [
"arn:aws:cleanrooms:us-east-1:111122223333:membership/41327cc4-bbf0-43f1-b70c-a160dddceb08/analysistemplate/1ff1bf9d-781c-418d-a6ac-2b80c09d6292"
]
}
```
1. L'entreprise A exécute le modèle d'analyse et utilise la valeur du paramètre`05-01-2023`.
## Règle d'analyse personnalisée avec confidentialité différentielle
Dans AWS Clean Rooms, la règle d'analyse personnalisée prend en charge la confidentialité différentielle. La confidentialité différentielle est un cadre mathématiquement rigoureux pour la protection de la confidentialité des données qui vous aide à protéger vos données contre les tentatives de réidentification.
La confidentialité différentielle prend en charge les analyses agrégées telles que la planification de campagnes publicitaires, les post-ad-campaign mesures, l'analyse comparative dans un consortium d'institutions financières et les tests A/B pour la recherche dans le domaine de la santé.
La structure et la syntaxe de requête prises en charge sont définies dans[Structure et syntaxe des requêtes](#dp-query-structure-syntax).
### Exemple de règle d'analyse personnalisée avec confidentialité différentielle
**Note**
AWS Clean Rooms La confidentialité différentielle n'est disponible que pour les collaborations dans lesquelles les données sont stockées dans Amazon S3.
Examinez l'[exemple de règle d'analyse personnalisée](#custom-example) présenté dans la section précédente. Cet exemple montre comment vous pouvez utiliser la confidentialité différentielle pour protéger vos données contre les tentatives de réidentification tout en permettant à votre partenaire de tirer des informations critiques de vos données. Supposons que l'entreprise B, qui possède les données d'audience, souhaite protéger ses données en utilisant une confidentialité différentielle. Pour terminer la configuration de la confidentialité différentielle, l'entreprise B effectue les étapes suivantes :
1. L'entreprise B active la confidentialité différentielle tout en ajoutant une règle d'analyse personnalisée au tableau configuré par le nombre de vues. L'entreprise B sélectionne `viewershipdata.hashedemail` comme colonne d'identifiant utilisateur.
1. L'entreprise B [ajoute une politique de confidentialité différentielle](configure-differential-privacy.md) à la collaboration afin de rendre sa table de données d'audience disponible pour les requêtes. L'entreprise B sélectionne la politique par défaut pour terminer rapidement la configuration.
L'entreprise A, qui souhaite comprendre l'augmentation des ventes d'une campagne publicitaire sur le site de l'entreprise B, exécute le modèle d'analyse. La requête étant compatible avec la [structure de requête](#dp-query-structure-syntax) à usage général de AWS Clean Rooms Differential Privacy, elle s'exécute correctement.
### Structure et syntaxe des requêtes
Les requêtes contenant au moins une table dont la confidentialité différentielle est activée doivent respecter la syntaxe suivante.
```
query_statement:
[cte, ...] final_select
cte:
WITH sub_query AS (
inner_select
[ UNION | INTERSECT | UNION_ALL | EXCEPT/MINUS ]
[ inner_select ]
)
inner_select:
SELECT [user_id_column, ] expression [, ...]
FROM table_reference [, ...]
[ WHERE condition ]
[ GROUP BY user_id_column[, expression] [, ...] ]
[ HAVING condition ]
final_select:
SELECT [expression, ...] | COUNT | COUNT_DISTINCT | SUM | AVG | STDDEV
FROM table_reference [, ...]
[ WHERE condition ]
[ GROUP BY expression [, ...] ]
[ HAVING COUNT | COUNT_DISTINCT | SUM | AVG | STDDEV | condition ]
[ ORDER BY column_list ASC | DESC ]
[ OFFSET literal ]
[ LIMIT literal ]
expression:
column_name [, ...] | expression AS alias | aggregation_functions | window_functions_on_user_id | scalar_function | CASE | column_name math_expression [, expression]
window_functions_on_user_id:
function () OVER (PARTITION BY user_id_column, [column_name] [ORDER BY column_list ASC|DESC])
```
**Note**
En ce qui concerne la structure et la syntaxe différentielles des requêtes de confidentialité, tenez compte des points suivants :
Les sous-requêtes ne sont pas prises en charge.
Les expressions de table communes (CTEs) doivent émettre la colonne d'identifiant utilisateur si une table ou un CTE implique des données protégées par une confidentialité différentielle. Les filtres, les regroupements et les agrégations doivent être effectués au niveau de l'utilisateur.
Final\$1select autorise les fonctions d'agrégation COUNT DISTINCT, COUNT, SUM, AVG et STDDEV.
Pour plus de détails sur les mots clés SQL pris en charge pour une confidentialité différentielle, consultez[Fonctionnalités SQL de AWS Clean Rooms Differential Privacy](dp-sql-capabilities.md).
# Règle d'analyse des tables de mappage d'identifiants
Dans AWS Clean Rooms, une *règle d'analyse de table de mappage d'identifiants* n'est pas une règle d'analyse autonome. Ce type de règle d'analyse est géré AWS Clean Rooms et utilisé pour joindre des données d'identité disparates afin de faciliter les requêtes. Il est automatiquement ajouté aux tables de mappage des identifiants et ne peut pas être modifié. Elle hérite des comportements des autres règles d'analyse de la collaboration, à condition que ces règles d'analyse soient homogènes.
La règle d'analyse des tables de mappage d'identifiants renforce la sécurité d'une table de mappage d'identifiants. Cela empêche un membre de la collaboration de sélectionner ou d'inspecter directement la population ne se chevauchant pas entre les ensembles de données des deux membres à l'aide de la table de mappage des identifiants. La règle d'analyse de la table de mappage d'identifiants est utilisée pour protéger les données sensibles de la table de mappage d'identifiants lorsqu'elles sont utilisées implicitement dans des requêtes avec d'autres règles d'analyse.
Avec la règle d'analyse de la table de mappage d'identifiants, AWS Clean Rooms impose un chevauchement des deux côtés de la table de mappage d'identifiants dans le SQL étendu. Cela vous permet d'effectuer les tâches suivantes :
+ Utilisez le chevauchement de la table de mappage des identifiants dans JOIN les instructions.
AWS Clean Rooms autorise une INNER RIGHT jointure ou une jointure sur la table de mappage des identifiants si elle respecte le chevauchement. LEFT Pour protéger les informations de mappage sensibles, la table de mappage des identifiants doit toujours se trouver du côté inner « » de toute JOIN opération. Par exemple, les JOIN opérations suivantes sont valides :
+ table LEFT JOIN id\$1mapping\$1table
+ id\$1mapping\$1table RIGHT JOIN table
+ table INNER JOIN id\$1mapping\$1table
Les JOIN opérations suivantes ne sont pas valides :
+ id\$1mapping\$1table LEFT JOIN table
+ table RIGHT JOIN id\$1mapping\$1table
Cela évite d'exposer les enregistrements cartographiques qui ne présentent pas de correspondance correspondante dans votre ensemble de données. L'autorisation de telles opérations pourrait potentiellement révéler des informations sensibles sur les mappages de données des autres membres de la collaboration.
+ Utilisez les colonnes de la table de mappage dans JOIN les instructions.
Vous ne pouvez pas utiliser les colonnes de la table de mappage dans les instructions suivantes :SELECT,, WHERE HAVINGGROUP BY, ou ORDER BY (sauf si les protections sont modifiées sur l'association d'espace de noms d'ID source ou sur l'association d'espace de noms d'ID cible).
+ Dans le SQL étendu OUTERJOIN, prend AWS Clean Rooms également en charge l'implicite et JOIN le CROSSJOIN. Ces jointures ne peuvent pas satisfaire aux exigences de chevauchement. AWS Clean Rooms Utilisez-le plutôt `requireOverlap` pour spécifier les colonnes qui doivent être jointes.
La structure et la syntaxe de requête prises en charge sont définies dans. [Structure et syntaxe des requêtes de la table de mappage d'identifiants](#id-mapping-table-query-controls)
Les paramètres de la règle d'analyse, définis dans[Contrôles des requêtes des règles d'analyse des tables de mappage d'identifiants](#parameters-id-mapping-query-controls), incluent les contrôles des requêtes et les contrôles des résultats des requêtes. Ses contrôles de requête incluent la possibilité d'exiger le chevauchement de la table de mappage des identifiants dans JOIN les instructions (c'est-à-dire,`requireOverlap`).
**Topics**
+ [Structure et syntaxe des requêtes de la table de mappage d'identifiants](#id-mapping-table-query-controls)
+ [Contrôles des requêtes des règles d'analyse des tables de mappage d'identifiants](#parameters-id-mapping-query-controls)
+ [Structure prédéfinie des règles d'analyse des tables de mappage d'identifiants](#id-mapping-table-predefined-structure)
+ [Règle d'analyse des tables de mappage d'identifiants — exemple](#id-mapping-table-example)
## Structure et syntaxe des requêtes de la table de mappage d'identifiants
Les requêtes sur les tables dotées d'une règle d'analyse des tables de mappage d'ID doivent respecter la syntaxe suivante.
```
--select_list_expression
SELECT
provider.data_col, consumer.data_col
--table_expression
FROM provider
JOIN idMappingTable idmt ON provider.id = idmt.sourceId
JOIN consumer ON consumer.id = idmt.targetId
```
### Tables de collaboration
Les tableaux suivants représentent les tables configurées qui existent dans une AWS Clean Rooms collaboration. La colonne **id** des tables **cr\$1drivers\$1license et **cr\$1insurance**** représente une colonne correspondant à la table de mappage des identifiants.
**cr\$1drivers\$1license**
| | | |
| --- |--- |--- |
| id | nom\$1pilote | état\$1d'enregistrement |
| 1 | Eduard | TX |
| 2 | Dana | MA |
| 3 | Gweneth | IL |
**cr\$1insurance**
| | | |
| --- |--- |--- |
| id | courriel\$1du titulaire de la police | numéro\$1politique |
| a | eduardo@internal.company.com | 17f9d04e-f5be-4426-bdc4-250ed59c6529 |
| b | gwen@internal.company.com | 3f0092db-2316-48a8-8d44-09cf8f6e6c64 |
| c | rosa@internal.company.com | d7692e84-3d3c-47b8-b46d-a0d5345f0601 |
### Table de mappage des identifiants
**Le tableau suivant représente une table de mappage d'identifiants existante qui correspond aux tables **cr\$1drivers\$1license et cr\$1insurance**.** Toutes les entrées ne seront pas disponibles IDs pour les deux tables de collaboration.
| | |
| --- |--- |
| cr\$1drivers\$1license\$1id | cr\$1insurance\$1id |
| 1 | a |
| 2 | null |
| 3 | b |
| null | c |
La règle d'analyse de la table de mappage d'identifiants autorise uniquement l'exécution de requêtes sur l'ensemble de données qui se chevauchent, qui se présente comme suit :
| | | | | | |
| --- |--- |--- |--- |--- |--- |
| cr\$1drivers\$1license\$1id | cr\$1insurance\$1id | nom\$1pilote | état\$1d'enregistrement | courriel\$1du titulaire de la police | numéro\$1politique |
| 1 | a | Eduard | TX | eduardo@internal.company.com | 17f9d04e-f5be-4426-bdc4-250ed59c6529 |
| 3 | b | Gweneth | IL | gwen@internal.company.com | 3f0092db-2316-48a8-8d44-09cf8f6e6c64 |
### Exemples de requêtes
Les exemples suivants montrent des emplacements valides pour les jointures de tables de mappage d'identifiants :
```
-- Single ID mapping table
SELECT
[ select_items ]FROM
cr_drivers_license cr_dl
[ INNER | LEFT ] JOIN cr_identity_mapping_table idmt ON idmt.cr_drivers_license_id = cr_dl.id
[ INNER | RIGHT ] JOIN cr_insurance cr_in ON idmt.cr_insurance_id = cr_in.id
;
-- Single ID mapping table (Subquery)
SELECT
[ select_items ]FROM (
SELECT
[ select_items ]
FROM
cr_drivers_license cr_dl
[ INNER | LEFT ] JOIN cr_identity_mapping_table idmt ON idmt.cr_drivers_license_id = cr_dl.id
[ INNER | RIGHT ] JOIN cr_insurance cr_in ON idmt.cr_insurance_id = cr_in.id
)
;
-- Single ID mapping table (CTE)
WITH
matched_ids AS (
SELECT
[ select_items ]
FROM
cr_drivers_license cr_dl
[ INNER | LEFT ] JOIN cr_identity_mapping_table idmt ON idmt.cr_drivers_license_id = cr_dl.id
[ INNER | RIGHT ] JOIN cr_insurance cr_in ON idmt.cr_insurance_id = cr_in.id
)SELECT
[ select_items ]FROM
matched_ids
;
```
### Considérations
En ce qui concerne la structure et la syntaxe des requêtes de la table de mappage d'identifiants, tenez compte des points suivants :
+ Vous ne pouvez pas le modifier.
+ Il est appliqué à la table de mappage des identifiants par défaut.
+ Il utilise une association d'espaces de noms d'ID source et cible au sein de la collaboration.
+ La table de mappage des identifiants est configurée par défaut pour fournir des protections par défaut à la colonne provenant de l'espace de noms des identifiants. Vous pouvez modifier cette configuration afin que la colonne provenant de l'espace de noms ID (soit`targetID`) `sourceID` soit autorisée n'importe où dans la requête. Pour de plus amples informations, veuillez consulter [Espaces de noms d'ID dans AWS Clean Rooms](working-with-id-namespaces.md).
+ La règle d'analyse des tables de mappage d'identifiants hérite des restrictions SQL des autres règles d'analyse de la collaboration.
## Contrôles des requêtes des règles d'analyse des tables de mappage d'identifiants
Avec les commandes de requête de table de mappage d'ID, vous AWS Clean Rooms contrôlez la manière dont les colonnes de votre table sont utilisées pour interroger la table. Par exemple, il contrôle quelles colonnes sont utilisées pour la jointure et quelles colonnes doivent être superposées. La règle d'analyse des tables de mappage d'identifiants inclut également des fonctionnalités qui vous permettent d'autoriser la `targetID` projection du ou des deux sans nécessiter de JOIN. `sourceID`
Le tableau suivant explique chaque contrôle.
| Contrôle | Définition | Usage |
| --- | --- | --- |
| joinColumns | Les colonnes que le membre autorisé à interroger peut utiliser dans l'instruction INNER JOIN. | Vous ne pouvez pas l'utiliser joinColumns dans d'autres parties de la requête que dans INNER JOIN.Pour de plus amples informations, veuillez consulter [Commandes de jointure](analysis-rules-aggregation.md#join-controls). |
| dimensionColumns | Les colonnes (le cas échéant) que le membre autorisé à interroger peut utiliser dans les instructions SELECT et GROUP BY. | A `dimensionColumn` peut être utilisé dans SELECT et GROUPBY. A `dimensionColumn` peut apparaître sous la forme`joinKeys`. Vous ne pouvez l'utiliser `dimensionColumns` dans la clause JOIN que si vous la spécifiez entre crochets. |
| queryContraints:RequireOverlap | Les colonnes de la table de mappage d'identifiants qui doivent être jointes pour que la requête puisse être exécutée. | Ces colonnes doivent être utilisées pour REJOINDRE la table de mappage des identifiants et une table de collaboration. |
## Structure prédéfinie des règles d'analyse des tables de mappage d'identifiants
La structure prédéfinie d'une règle d'analyse de table de mappage d'identifiants est assortie de protections par défaut appliquées au et. `sourceID` `targetID` Cela signifie que la colonne avec les protections appliquées doit être utilisée dans les requêtes.
Vous pouvez configurer la règle d'analyse de la table de mappage d'identifiants de la manière suivante :
+ À la fois `sourceID` et `targetID` protégé
Dans cette configuration, le `sourceID` et ne `targetID` peuvent pas être projetés tous les deux. Le `sourceID` et `targetID` doit être utilisé dans un JOIN lorsque la table de mappage d'ID est référencée.
+ `targetID`Protégé uniquement
Dans cette configuration, le ne `targetID` peut pas être projeté. Le `targetID` doit être utilisé dans un JOIN lorsque la table de mappage d'ID est référencée. Le `sourceID` peut être utilisé dans une requête.
+ `sourceID`Protégé uniquement
Dans cette configuration, le ne `sourceID` peut pas être projeté. Le `sourceID` doit être utilisé dans un JOIN lorsque la table de mappage d'ID est référencée. Le `targetID` peut être utilisé dans une requête.
+ Ni l'`sourceID`un ni l'`targetID`autre
Dans cette configuration, la table de mappage des identifiants n'est soumise à aucune application spécifique pouvant être utilisée dans la requête.
L'exemple suivant montre une structure prédéfinie pour une règle d'analyse de table de mappage d'identifiants avec les protections par défaut appliquées au et. `sourceID` `targetID` Dans cet exemple, la règle d'analyse de la table de mappage d'identifiants autorise uniquement un INNER JOIN à la fois sur la `sourceID` colonne et sur la `targetID` colonne.
```
{
"joinColumns": [
"source_id",
"target_id"
],
"queryConstraints": [
{
"requireOverlap": {
"columns": [
"source_id",
"target_id"
]
}
}
],
"dimensionColumns": [] // columns that can be used in SELECT and JOIN
}
```
L'exemple suivant montre une structure prédéfinie pour une règle d'analyse de table de mappage d'identifiants avec des protections appliquées au. `targetID` Dans cet exemple, la règle d'analyse de la table de mappage d'ID n'autorise qu'un INNER JOIN sur la `sourceID` colonne.
```
{
"joinColumns": [
"source_id",
"target_id"
],
"queryConstraints": [
{
"requireOverlap": {
"columns": [
"target_id"
]
}
}
],
"dimensionColumns": [
"source_id"
]
}
```
L'exemple suivant montre une structure prédéfinie pour une règle d'analyse de table de mappage d'identifiants avec des protections appliquées au. `sourceID` Dans cet exemple, la règle d'analyse de la table de mappage d'ID n'autorise qu'un INNER JOIN sur la `targetID` colonne.
```
{
"joinColumns": [
"source_id",
"target_id"
],
"queryConstraints": [
{
"requireOverlap": {
"columns": [
"source_id"
]
}
}
],
"dimensionColumns": [
"target_id"
]
}
```
L'exemple suivant montre une structure prédéfinie pour une règle d'analyse de table de mappage d'identifiants sans protection appliquée au ou. `sourceID` `targetID` Dans cet exemple, la règle d'analyse de la table de mappage d'ID autorise un INNER JOIN à la fois sur la `sourceID` colonne et sur la `targetID` colonne.
```
{
"joinColumns": [
"source_id",
"target_id"
],
"queryConstraints": [
{
"requireOverlap": {
"columns": []
}
}
],
"dimensionColumns": [
"source_id",
"target_id"
]
}
```
## Règle d'analyse des tables de mappage d'identifiants — exemple
Plutôt que de rédiger une longue déclaration en cascade faisant référence à des informations personnelles identifiables (PII), par exemple, les entreprises peuvent utiliser la règle d'analyse des tables de mappage d'identifiants pour utiliser le transcodage multipartite LiveRamp . L'exemple suivant montre comment vous pouvez collaborer en AWS Clean Rooms utilisant la règle d'analyse des tables de mappage d'identifiants.
L'entreprise A est un annonceur qui dispose de données sur les clients et les ventes, qui seront utilisées comme source. La société A effectue également le transcodage pour le compte des parties à la collaboration et apporte les LiveRamp informations d'identification.
L'entreprise B est un éditeur qui possède des données sur les événements, qui seront utilisées comme cible.
**Note**
La société A ou la société B peuvent fournir des informations d'identification pour le LiveRamp transcodage et effectuer le transcodage.
Pour créer une collaboration permettant d'analyser la table de mappage des identifiants en collaboration, les entreprises procèdent comme suit :
1. L'entreprise A crée une collaboration et crée une adhésion. Elle ajoute la société B, qui crée également une adhésion à la collaboration.
1. La société A associe une source d'espace de noms d'ID existante ou en crée une nouvelle en Résolution des entités AWS utilisant la AWS Clean Rooms console.
L'entreprise A crée une table configurée avec ses données de vente et une colonne saisie sur le `sourceId` dans la table de mappage des identifiants.
La source de l'espace de noms ID fournit les données à transcoder.
1. La société B associe une cible d'espace de noms ID existante ou en crée une nouvelle en Résolution des entités AWS utilisant la AWS Clean Rooms console.
La société B crée une table configurée avec ses données d'événements et une colonne saisie sur le `targetId` dans la table de mappage des identifiants.
La cible de l'espace de noms ID ne fournit pas de données à transcoder, mais uniquement des métadonnées relatives à la LiveRamp configuration.
1. L'entreprise A découvre les deux espaces de noms d'identification associés à la collaboration et crée et remplit une table de mappage d'identifiants.
1. L'entreprise A exécute une requête sur les deux ensembles de données en les joignant sur la table de mappage des identifiants.
```
--- this would be valid for Custom or List
SELECT provider.data_col, consumer.data_col
FROM provider
JOIN idMappingTable-123123123123-myMappingWFName idmt
ON provider.id = idmt.sourceId
JOIN consumer
ON consumer.id = idmt.targetId
```
# AWS Clean Rooms Confidentialité différentielle
AWS Clean Rooms La confidentialité différentielle vous aide à protéger la vie privée de vos utilisateurs grâce à une technique basée sur des mathématiques qui est mise en œuvre avec des commandes intuitives en quelques clics. En tant que fonctionnalité entièrement gérée, aucune expérience préalable en matière de confidentialité différentielle n'est nécessaire pour vous aider à empêcher la réidentification de vos utilisateurs. AWS Clean Rooms ajoute automatiquement une quantité de bruit soigneusement calibrée aux résultats de la requête lors de l'exécution afin de protéger vos données au niveau individuel.
AWS Clean Rooms La confidentialité différentielle prend en charge un large éventail de requêtes analytiques et convient parfaitement à une grande variété de cas d'utilisation, dans lesquels une petite quantité d'erreur dans les résultats des requêtes ne compromet pas l'utilité de votre analyse. Grâce à elle, vos partenaires peuvent générer des informations critiques sur les campagnes publicitaires, les décisions d'investissement, la recherche clinique, etc., le tout sans nécessiter de configuration supplémentaire de la part de vos partenaires.
AWS Clean Rooms La confidentialité différentielle protège contre le débordement ou les erreurs de diffusion non valides qui utilisent des fonctions scalaires ou des symboles d'opérateurs mathématiques de manière malveillante.
Pour plus d'informations sur la confidentialité AWS Clean Rooms différentielle, consultez les rubriques suivantes.
**Topics**
+ [Confidentialité différentielle](#dp-overview)
+ [Comment AWS Clean Rooms fonctionne la confidentialité différentielle](#dp-how-it-works)
+ [Politique de confidentialité différentielle](dp-settings.md)
+ [Fonctionnalités SQL de AWS Clean Rooms Differential Privacy](dp-sql-capabilities.md)
+ [Conseils et exemples de requêtes relatives à la confidentialité différentielle](dp-query-tips-examples.md)
+ [Limites de la confidentialité AWS Clean Rooms différentielle](dp-limitations.md)
## Confidentialité différentielle
La confidentialité différentielle ne permet que des informations agrégées et masque la contribution des données individuelles à ces informations. La confidentialité différentielle protège les données de collaboration du membre qui peut recevoir des résultats en découvrant une personne en particulier. Sans confidentialité différentielle, le membre qui peut recevoir des résultats peut tenter de déduire des données utilisateur individuelles en ajoutant ou en supprimant des enregistrements concernant un individu et en observant la différence entre les résultats des requêtes.
Lorsque la confidentialité différentielle est activée, une quantité spécifiée de bruit est ajoutée aux résultats de la requête pour masquer la contribution des utilisateurs individuels. Si le membre qui peut recevoir des résultats essaie d'observer la différence entre les résultats de la requête après avoir supprimé des enregistrements concernant un individu de son ensemble de données, la variabilité du résultat de la requête empêche l'identification des données de l'individu. AWS Clean Rooms Differential Privacy utilise le [SampCert](https://github.com/leanprover/SampCert)sampler, une implémentation d'échantillonneur correcte et éprouvée développée par. AWS
## Comment AWS Clean Rooms fonctionne la confidentialité différentielle
Le flux de travail dans lequel vous souhaitez activer la confidentialité différentielle AWS Clean Rooms nécessite les étapes supplémentaires suivantes lors de [l'exécution du flux de travail pour AWS Clean Rooms](what-is.md#how-it-works) :
1. Vous activez la confidentialité différentielle lorsque vous ajoutez une [règle d'analyse personnalisée](analysis-rules-custom.md).
1. [Vous configurez la politique de confidentialité différentielle pour la collaboration](configure-differential-privacy.md) afin que vos tables de données protégées par une confidentialité différentielle soient disponibles pour les requêtes.
Une fois ces étapes terminées, le membre habilité à effectuer des requêtes peut commencer à exécuter des requêtes sur des données protégées par la confidentialité différentielle. AWS Clean Rooms renvoie des résultats conformes à la politique de confidentialité différentielle. AWS Clean Rooms La confidentialité différentielle permet de suivre le nombre estimé de requêtes restantes que vous pouvez exécuter, comme la jauge d'essence d'une voiture qui vous indique le niveau de carburant actuel de la voiture. Le nombre de requêtes que le membre qui peut interroger peut exécuter est limité par le **budget de confidentialité** et le **bruit ajouté par requête**, paramètres définis dans le[Politique de confidentialité différentielle](dp-settings.md).
### Considérations
Lorsque vous utilisez la confidentialité différentielle dans AWS Clean Rooms, tenez compte des points suivants :
+ Le membre qui peut recevoir les résultats ne peut pas utiliser la confidentialité différentielle. Ils configureront une règle d'analyse personnalisée avec la confidentialité différentielle désactivée pour leurs tables configurées.
+ Le membre qui peut effectuer une requête ne peut pas joindre les tables de deux fournisseurs de données ou plus lorsque la confidentialité différentielle est activée dans les deux cas.
# Politique de confidentialité différentielle
La politique de confidentialité différentielle contrôle le nombre de fonctions d'agrégation que le membre qui peut interroger est autorisé à exécuter dans le cadre d'une collaboration. Le **budget de confidentialité** définit une ressource commune limitée qui est appliquée à toutes les tables d'une collaboration. Le **bruit ajouté par requête** détermine le taux d'épuisement du budget de confidentialité.
Une politique de confidentialité différentielle est requise pour que vos tables protégées par la confidentialité différentielle soient disponibles pour les requêtes. Il s'agit d'une étape unique dans le cadre d'une collaboration qui inclut deux contributions :
+ **Budget de confidentialité** — Quantifié en termes d'epsilon, le budget de confidentialité contrôle le niveau de protection de la vie privée. Il s'agit d'une ressource commune limitée qui est appliquée à toutes vos tables protégées par une confidentialité différentielle dans le cadre de la collaboration, car l'objectif est de préserver la confidentialité de vos utilisateurs dont les informations peuvent être présentes dans plusieurs tables.
Le **budget de confidentialité** est consommé chaque fois qu'une requête est exécutée sur vos tables. Lorsque le budget de confidentialité est totalement épuisé, le membre de la collaboration qui peut effectuer des requêtes ne peut pas exécuter de requêtes supplémentaires tant qu'il n'est pas augmenté ou actualisé. En établissant un budget de confidentialité plus important, le membre qui peut recevoir les résultats peut réduire son incertitude quant aux individus contenus dans les données. Choisissez un budget de confidentialité qui équilibre vos exigences en matière de collaboration et vos besoins en matière de confidentialité, après avoir consulté les décideurs commerciaux.
Vous pouvez sélectionner **Actualiser le budget de confidentialité tous les mois** pour créer automatiquement un nouveau budget de confidentialité chaque mois calendaire, si vous prévoyez d'intégrer régulièrement de nouvelles données à la collaboration. Le choix de cette option permet de révéler des quantités arbitraires d'informations sur les lignes de données lorsqu'elles sont demandées à plusieurs reprises lors des actualisations. Évitez de choisir cette option si les mêmes lignes doivent être consultées à plusieurs reprises entre les actualisations du budget de confidentialité.
+ **Le bruit ajouté par requête** est mesuré en fonction du nombre d'utilisateurs dont vous souhaitez masquer les contributions. Cette valeur détermine le taux d'épuisement du budget de confidentialité. Une valeur de bruit plus élevée réduit le taux d'épuisement du budget de confidentialité et permet donc d'exécuter davantage de requêtes sur vos données. Cependant, cela doit être contrebalancé par la publication d'informations moins précises. Tenez compte de la précision souhaitée pour les informations sur la collaboration lorsque vous définissez cette valeur.
Vous pouvez utiliser la politique de confidentialité différentielle par défaut pour terminer rapidement la configuration ou personnaliser votre politique de confidentialité différentielle en fonction de votre cas d'utilisation. AWS Clean Rooms La confidentialité différentielle fournit des commandes intuitives pour configurer la politique. AWS Clean Rooms La confidentialité différentielle vous permet de prévisualiser l'utilitaire en termes de nombre d'agrégations possibles pour toutes les requêtes portant sur vos données et d'estimer le nombre de requêtes pouvant être exécutées dans le cadre d'une collaboration sur les données.
Vous pouvez utiliser les exemples interactifs pour comprendre l'impact des différentes valeurs du **budget de confidentialité** et **du bruit ajouté par requête** sur les résultats des différents types de requêtes SQL. En général, vous devez trouver un équilibre entre vos besoins en matière de confidentialité, le nombre de requêtes que vous souhaitez autoriser et l'exactitude de ces requêtes. Un **budget de confidentialité** réduit ou une augmentation **du bruit ajouté par requête** permet de mieux protéger la confidentialité des utilisateurs, mais fournit des informations moins pertinentes à vos partenaires de collaboration.
Si vous augmentez le **budget de confidentialité** tout en conservant le même paramètre de **bruit ajouté par requête**, le membre autorisé à effectuer une requête peut exécuter davantage d'agrégations sur vos tables dans le cadre de la collaboration. Vous pouvez augmenter le **budget de confidentialité** à tout moment au cours de la collaboration. Si vous réduisez le **budget de confidentialité** tout en conservant le même paramètre de **bruit ajouté par requête**, le membre autorisé à effectuer une requête peut exécuter moins d'agrégations. Vous ne pouvez pas réduire le **budget consacré à la confidentialité** une fois que le membre habilité à interroger a commencé à analyser vos données.
Si vous augmentez le **niveau de bruit ajouté par requête** tout en conservant le même niveau d'entrée relatif au **budget de confidentialité**, le membre autorisé à effectuer des requêtes peut exécuter davantage d'agrégations sur vos tables dans le cadre de la collaboration. Si vous réduisez le **bruit ajouté par requête** tout en conservant le même **montant d'entrée relatif au budget de confidentialité**, le membre autorisé à effectuer une requête peut exécuter moins d'agrégations. Vous pouvez augmenter ou diminuer le **bruit ajouté par requête** à tout moment au cours de la collaboration.
La politique de confidentialité différentielle est gérée par les actions de l'API du modèle de budget de confidentialité.
# Fonctionnalités SQL de AWS Clean Rooms Differential Privacy
AWS Clean Rooms La confidentialité différentielle utilise une structure de requête polyvalente pour prendre en charge les requêtes SQL complexes. Les modèles d'analyse personnalisés sont validés par rapport à cette structure afin de garantir qu'ils peuvent être exécutés sur des tables protégées par une confidentialité différentielle. Le tableau suivant indique les fonctions prises en charge. Pour plus d’informations, consultez [Structure et syntaxe des requêtes](analysis-rules-custom.md#dp-query-structure-syntax).
| Catégorie | Constructions SQL prises en charge par le moteur d'analyse Spark | Expressions de table courantes (CTEs) | Clause SELECT finale |
| --- |--- |--- |--- |
| Fonctions d’agrégation | Fonction ANY\$1VALUE Fonction APPROXIMATE PERCENTILE\$1DISC Fonction AVG Fonctions COUNT et COUNT DISTINCT Fonction MAX Fonction MEDIAN Fonction MIN Fonction PERCENTILE\$1CONT Fonctions STDDEV\$1SAMP et STDDEV\$1POP Fonctions SUM et SUM DISTINCT Fonctions VAR\$1SAMP et VAR\$1POP | Soutenu à la condition que l' CTEs utilisation de tables protégées par la confidentialité différentielle doit aboutir à des données contenant des enregistrements au niveau de l'utilisateur. Vous devez écrire l'expression SELECT dans ceux qui CTEs utilisent le `SELECT userIdentifierColumn...' format. | Agrégations prises en charge : AVG, COUNT, COUNT DISTINCT, STDDEV et SUM. |
| CTEs | clause WITH, sous-requête de clause WITH | Soutenu à la condition que l' CTEs utilisation de tables protégées par la confidentialité différentielle doit aboutir à des données contenant des enregistrements au niveau de l'utilisateur. Vous devez écrire l'expression SELECT dans ceux qui CTEs utilisent le `SELECT userIdentifierColumn...' format. | N/A |
| Sous-requêtes | SELECT HAVING JOIN Condition d'adhésion FROM WHERE | Vous pouvez avoir n'importe quelle sous-requête qui ne fait pas référence à des relations de confidentialité différentielles dans ces constructions. Vous pouvez avoir n'importe quelle sous-requête qui fait référence à des relations de confidentialité différentielles uniquement dans une clause FROM et JOIN. |
| Clauses d'adhésion | JOINT INTÉRIEUR JOINTURE GAUCHE DEMI-JOINT GAUCHE ANTI-JOINTURE GAUCHE JOINTURE DROITE ADHÉSION COMPLÈTE [JOIN] OU opérateur CROSS JOIN | Supportée à la condition que seules les fonctions JOIN qui sont des jointures égales sur les colonnes d'identifiant utilisateur soient prises en charge et soient obligatoires lors de l'interrogation de deux tables ou plus avec la confidentialité différentielle activée. Assurez-vous que les conditions d'équijointure obligatoires sont correctes. Vérifiez que le propriétaire de la table a configuré la même colonne d'identifiant utilisateur dans toutes les tables afin que la définition d'un utilisateur reste cohérente d'une table à l'autre. Les fonctions CROSS JOIN ne sont pas prises en charge lors de la combinaison de deux relations ou plus lorsque la confidentialité différentielle est activée. |
| Définir les opérateurs | UNION, UNION ALL, INTERSECT, EXCEPT \$1 MINUS (ce sont des synonymes) | UNION, UNION ALL, INTERSECT, EXCEPT \$1 MINUS (ce sont des synonymes) | Non pris en charge |
| Fonctions de fenêtrage | Fonctions d’agrégation Fonction de fenêtrage AVG Fonction de fenêtrage COUNT Fonction de fenêtrage CUME\$1DIST Fonction de fenêtrage DENSE\$1RANK Fonction de fenêtrage FIRST\$1VALUE Fonction de fenêtrage LAG Fonction de fenêtrage LAST\$1VALUE Fonction de fenêtrage LEAD Fonctions de fenêtre MAX Fonctions de la fenêtre MEDIAN Fonctions de la fenêtre MIN Fonction de fenêtrage NTH\$1VALUE Fonctions de fenêtre STDDEV\$1SAMP et STDDEV\$1POP (STDDEV\$1SAMP et STDDEV sont des synonymes) Fonctions de la fenêtre SUM Fonctions de fenêtre VAR\$1SAMP et VAR\$1POP (VAR\$1SAMP et VARIANCE sont des synonymes) Fonctions de classement Fonction de fenêtrage DENSE\$1RANK Fonction de fenêtrage NTILE Fonction de fenêtrage PERCENT\$1RANK Fonction de fenêtrage RANK Fonction de fenêtrage ROW\$1NUMBER | Tous sont pris en charge à condition que la colonne d'identifiant utilisateur de la clause de partition de la fonction de fenêtre soit requise lorsque vous interrogez une relation avec la confidentialité différentielle activée. | Non pris en charge |
| Expressions conditionnelles | Expression de condition CASE Expression COALESCE Fonctions GREATEST et LEAST Fonctions NVL et COALESCE NVL2 fonction Fonction NULLIF | Tous sont pris en charge | Tous sont pris en charge |
| Conditions | Condition de comparaison Conditions logiques Conditions de correspondance de modèles ENTRE les conditions de gamme Condition null | EXISTSet ne IN peuvent pas être utilisés car ils nécessitent des sous-requêtes. Tous les autres sont pris en charge. | Tous sont pris en charge |
| Fonctions date-heure | Fonctions date et heure dans les transactions Opérateur de concaténation Fonctions ADD\$1MONTHS Fonction CONVERT\$1TIMEZONE Fonction CURRENT\$1DATE Fonction DATEADD Fonction DATEDIFF fonctions DATE\$1PART Fonction DATE\$1TRUNC Fonction EXTRACT Fonction TO\$1TIMESTAMP Parties de date pour les fonctions de date ou d’horodatage | Tous sont pris en charge | Tous sont pris en charge |
| Fonctions de chaîne | opérateur \$1\$1 (concaténation) Fonction BTRIM Fonction CHAR\$1LENGTH Fonction CHARACTER\$1LENGTH Fonction CONCAT Fonctions LEFT et RIGHT Fonction LEN Fonction LENGTH Fonction LOWER Fonctions LPAD et RPAD Fonction LTRIM Fonctions POSITION Fonction REGEXP\$1COUNT Fonction REGEXP\$1INSTR Fonction REGEXP\$1REPLACE Fonction REGEXP\$1SUBSTR Fonction REPEAT Fonction REPLACE Fonction REVERSE Fonction RTRIM Fonction SPLIT\$1PART Fonction SUBSTRING Fonction TRANSLATE Fonctions TRIM Fonction UPPER | Tous sont pris en charge | Tous sont pris en charge |
| Fonctions de formatage des types de données | Fonction CAST TO\$1CHAR Fonction TO\$1DATE TO\$1NUMBER Chaînes de format datetime Chaînes de format numériques | Tous sont pris en charge | Tous sont pris en charge |
| Fonctions de hachage | AES\$1ENCRYPT AES\$1DECRYPT ENCODE DECODE MD5 fonction SHA1 fonction SHA2 fonction XX\$1 HASH64 | Tous sont pris en charge | Tous sont pris en charge |
| Symboles d’opérateurs mathématiques | \$1, -, \$1,/, % et @ | Tous sont pris en charge | Tous sont pris en charge |
| Fonctions mathématiques | Fonction ABS Fonction ACOS Fonction ASIN Fonction ATAN ATAN2 fonction Fonction CBRT Fonction CEILING (ou CEIL) Fonction COS Fonction COT Fonction DEGREES Fonction LTRIM Fonction EXP Fonction FLOOR Fonction LN Fonction LOG Fonction MOD Fonction PI Fonction POWER Fonction RADIANS Fonction RANDOM Fonction ROUND Fonction SIGN Fonction SIN Fonctions SQRT Fonction TRUNC | Tous sont pris en charge | Tous sont pris en charge |
| Fonctions VARBYTE | UNHEX, UNBASE64 SORT HLL\$1SKETCH\$1AGG, HLL\$1SKETCH\$1ESTIMATE HL\$1UNION HL\$1UNION\$1AGG | Tous sont pris en charge | Tous sont pris en charge |
| JSON | TO\$1JSON GET\$1JSON\$1OBJECT | Tous sont pris en charge | Tous sont pris en charge |
| Fonctions de tableau | ARRAY\$1CONTAINS ARRAY\$1DISTINCT ARRAY\$1EXCEPTÉ ARRAY\$1INTERSECT ARRAY\$1JOIN ARRAY\$1REMOVE ARRAY\$1SORT ARRAY\$1UNION | Non pris en charge | Non pris en charge |
| GROUPE PAR ÉTENDU | ENSEMBLES DE REGROUPEMENT, ROLLUP, CUBE | Non pris en charge | Non pris en charge |
| Opération de tri | ORDER BY | Supportée à la condition qu'une clause ORDER BY ne soit prise en charge dans la clause de partition d'une fonction de fenêtre que lors de l'interrogation de tables avec la confidentialité différentielle activée. | Pris en charge |
| Limites de lignes | LIMITE, DÉCALAGE | Non pris en charge CTEs lors de l'utilisation de tables protégées par la confidentialité différentielle | Tous sont pris en charge |
| Aliasing de tables et de colonnes | | Pris en charge | Pris en charge |
| Fonctions mathématiques sur les fonctions d'agrégation | | Pris en charge | Pris en charge |
| Fonctions scalaires dans les fonctions d'agrégation | | Pris en charge | Pris en charge |
## Alternatives courantes pour les constructions SQL non prises en charge
| Catégorie | construction SQL | Autrement |
| --- |--- |--- |
| Fonctions de fenêtrage | LISTAGG PERCENTILE\$1CONT PERCENTILE\$1DISC | Vous pouvez utiliser la fonction d'agrégation équivalente avec GROUP BY. |
| Symboles d’opérateurs mathématiques | \$1column \$1\$1/ 2 \$1column \$1/ 2 \$1column ^ 2 | CBRT SQRT PUISSANCE (\$1column, 2) |
| Fonctions scalaires | SYSDATE \$1column : :entier convertir (type, \$1column) | CURRENT\$1DATE CAST \$1column EN TANT QU'entier Type CAST \$1column AS |
| Littéraux | INTERVALLE « 1 SECONDE » | INTERVALLE « 1 » SECONDE |
| Limitation des lignes | STOP n | LIMITE n |
| Joindre | USING NATURAL | La clause ON doit contenir explicitement un critère de jointure. |
# Conseils et exemples de requêtes relatives à la confidentialité différentielle
AWS Clean Rooms La confidentialité différentielle utilise une [structure de requête polyvalente](dp-sql-capabilities.md) pour prendre en charge une grande variété de constructions SQL telles que les expressions de table communes (CTEs) pour la préparation des données et les fonctions d'agrégation couramment utilisées telles que`COUNT`, ou. `SUM` Afin de masquer la contribution de tout utilisateur potentiel à vos données en ajoutant du bruit aux résultats des requêtes agrégées au moment de l'exécution, la confidentialité AWS Clean Rooms différentielle exige que les fonctions d'agrégation finales `SELECT statement` soient exécutées sur des données au niveau de l'utilisateur.
L'exemple suivant utilise deux tables nommées `socialco_impressions` et `socialco_users` provenant d'un éditeur multimédia qui souhaite protéger les données en utilisant une confidentialité différentielle tout en collaborant avec une marque sportive utilisant `athletic_brand_sales` des données. L'éditeur multimédia a configuré la `user_id` colonne comme colonne d'identifiant utilisateur tout en activant la confidentialité différentielle dans AWS Clean Rooms. L'annonceur n'a pas besoin d'une protection différentielle de la confidentialité et souhaite exécuter une requête en utilisant CTEs des données combinées. Comme son CTE utilise des tables protégées de confidentialité différentielles, l'annonceur inclut la colonne d'identifiant d'utilisateur de ces tables protégées dans la liste des colonnes CTE et joint les tables protégées dans la colonne d'identifiant d'utilisateur.
```
WITH matches_table AS(
SELECT si.user_id, si.campaign_id, s.sale_id, s.sale_price
FROM socialco_impressions si
JOIN socialco_users su
ON su.user_id = si.user_id
JOIN athletic_brand_sales s
ON s.emailsha256 = su.emailsha256
WHERE s.timestamp > si.timestamp
UNION ALL
SELECT si.user_id, si.campaign_id, s.sale_id, s.sale_price
FROM socialco_impressions si
JOIN socialco_users su
ON su.user_id = si.user_id
JOIN athletic_brand_sales s
ON s.phonesha256 = su.phonesha256
WHERE s.timestamp > si.timestamp
)
SELECT COUNT (DISTINCT user_id) as unique_users
FROM matches_table
GROUP BY campaign_id
ORDER BY COUNT (DISTINCT user_id) DESC
LIMIT 5
```
De même, si vous souhaitez exécuter des fonctions de fenêtre sur des tables de données protégées par la confidentialité différentielle, vous devez inclure la colonne d'identifiant utilisateur dans la `PARTITION BY` clause.
```
ROW_NUMBER() OVER (PARTITION BY conversion_id, user_id ORDER BY match_type, match_age) AS row
```
# Limites de la confidentialité AWS Clean Rooms différentielle
AWS Clean Rooms La confidentialité différentielle ne permet pas de résoudre les situations suivantes :
1. AWS Clean Rooms La confidentialité différentielle prend uniquement en charge les requêtes utilisant des tables basées sur Amazon S3. AWS Glue Il ne prend pas en charge les requêtes avec les tables Snowflake ou Amazon Athena.
1. AWS Clean Rooms La confidentialité différentielle ne permet pas de lutter contre les attaques temporelles. Par exemple, ces attaques sont possibles dans les scénarios où un utilisateur individuel fournit un grand nombre de lignes et où l'ajout ou la suppression de cet utilisateur modifie de manière significative le temps de calcul de la requête.
1. AWS Clean Rooms La confidentialité différentielle ne garantit pas une confidentialité différentielle lorsqu'une requête SQL peut entraîner un débordement ou des erreurs de diffusion non valides au moment de l'exécution en raison de l'utilisation de certaines constructions SQL.
Le tableau suivant répertorie certaines constructions SQL, mais pas toutes, susceptibles de générer des erreurs d'exécution et qui doivent être vérifiées dans les modèles d'analyse. Nous vous recommandons d'approuver les modèles d'analyse qui minimisent les risques de telles erreurs d'exécution et de consulter régulièrement les journaux de requêtes pour déterminer si les requêtes sont conformes à l'accord de collaboration.
Les constructions SQL suivantes sont vulnérables aux erreurs de débordement :
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/clean-rooms/latest/userguide/dp-limitations.html)
1. La fonction de formatage du type de données CAST est vulnérable aux erreurs de conversion non valides.
Vous pouvez configurer [CloudWatch pour créer un filtre métrique pour un groupe de journaux](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CreateMetricFilterProcedure.html), puis [créer une CloudWatch alarme](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Alarm-On-Logs.html) sur ce filtre métrique afin de recevoir des alertes en cas de dépassement potentiel ou d'erreur de casting.
Plus précisément, vous devez surveiller les codes d'erreur`CastError`,`OverflowError`,`ConversionError`. La présence de ces codes d'erreur indique une attaque potentielle par canal secondaire, mais peut également indiquer une requête SQL erronée.
Pour de plus amples informations, veuillez consulter [Connexion à une analyse AWS Clean Rooms](query-logs.md).
# AWS Clean Rooms ML
AWS Clean Rooms ML permet à deux ou plusieurs parties d'exécuter des modèles d'apprentissage automatique sur leurs données sans avoir à partager leurs données entre elles. Le service fournit des contrôles renforçant la confidentialité qui permettent aux propriétaires de données de protéger leurs données et leur adresse IP de modèle. Vous pouvez utiliser des AWS modèles créés par des créateurs ou apporter votre propre modèle personnalisé.
Pour une explication plus détaillée de son fonctionnement, voir[Emplois multi-comptes](ml-behaviors.md#ml-behaviors-cross-account-jobs).
Pour plus d'informations sur les fonctionnalités des modèles Clean Rooms ML, consultez les rubriques suivantes.
**Topics**
+ [Terminologie AWS Clean Rooms ML](#ml-terminology)
+ [Comment AWS Clean Rooms ML fonctionne avec les AWS modèles](#ml-how-it-works)
+ [Comment AWS Clean Rooms ML fonctionne avec les modèles personnalisés](#custML-how-it-works)
+ [AWS modèles dans Clean Rooms ML](aws-models.md)
+ [Modèles personnalisés dans Clean Rooms ML](custom-models.md)
## Terminologie AWS Clean Rooms ML
Il est important de comprendre la terminologie suivante lors de l'utilisation de Clean Rooms ML :
+ *Fournisseur de données de formation* : partie qui fournit les données de formation, crée et configure un modèle similaire, puis associe ce modèle similaire à une collaboration.
+ *Fournisseur de données sur les semences* : partie qui fournit les données sur les semences, génère un segment similaire et exporte son segment similaire.
+ *Données d'entraînement* : données du fournisseur de données de formation, utilisées pour générer un modèle similaire. Les données d'entraînement sont utilisées pour mesurer la similitude des comportements des utilisateurs.
Les données d'entraînement doivent contenir un ID utilisateur, un ID d'élément et une colonne d'horodatage. Les données d'entraînement peuvent éventuellement contenir d'autres interactions sous forme de caractéristiques numériques ou catégoriques. Des exemples d'interactions sont une liste de vidéos regardées, d'articles achetés ou d'articles lus.
+ *Données de départ* : données du fournisseur de données de départ, utilisées pour créer un segment similaire. Les données de départ peuvent être fournies directement ou provenir des résultats d'une AWS Clean Rooms requête. Le résultat du segment similaire est un ensemble d'utilisateurs issu des données d'entraînement qui ressemble le plus aux utilisateurs initiaux.
+ *Modèle similaire : modèle* d'apprentissage automatique des données d'entraînement utilisé pour rechercher des utilisateurs similaires dans d'autres ensembles de données.
Lors de l'utilisation de l'API, le terme « *modèle d'audience* » est utilisé de manière équivalente à « modèle similaire ». Par exemple, vous utilisez l'[CreateAudienceModel](https://docs.aws.amazon.com/cleanrooms-ml/latest/APIReference/API_CreateAudienceModel.html)API pour créer un modèle similaire.
+ *Segment similaire* : sous-ensemble des données d'entraînement qui ressemble le plus aux données de départ.
Lorsque vous utilisez l'API, vous créez un segment similaire avec l'[StartAudienceGenerationJob](https://docs.aws.amazon.com/cleanrooms-ml/latest/APIReference/API_StartAudienceGenerationJob.html)API.
Les données du fournisseur de données de formation ne sont jamais partagées avec le fournisseur de données de départ et les données du fournisseur de données de départ ne sont jamais partagées avec le fournisseur de données de formation. La sortie du segment similaire est partagée avec le fournisseur de données de formation, mais jamais avec le fournisseur de données de départ.
## Comment AWS Clean Rooms ML fonctionne avec les AWS modèles
![\[Vue d'ensemble de la façon dont AWS Clean Rooms ML fonctionne avec AWS les modèles.\]](http://docs.aws.amazon.com/fr_fr/clean-rooms/latest/userguide/images/howItWorksML.png)
L'utilisation de modèles similaires nécessite que deux parties, un fournisseur de données de formation et un fournisseur de données de départ, travaillent de manière séquentielle AWS Clean Rooms pour intégrer leurs données dans une collaboration. Voici le flux de travail que le fournisseur de données de formation doit effectuer en premier :
1. Les données du fournisseur de données de formation doivent être stockées dans une table de catalogue de AWS Glue données répertoriant les interactions entre les utilisateurs et les éléments. Les données d'entraînement doivent au minimum contenir une colonne d'ID utilisateur, une colonne d'identifiant d'interaction et une colonne d'horodatage.
1. Le fournisseur de données de formation enregistre les données de formation auprès de AWS Clean Rooms.
1. Le fournisseur de données de formation crée un modèle similaire qui peut être partagé avec plusieurs fournisseurs de données initiales. Le modèle similaire est un réseau neuronal profond dont l'entraînement peut prendre jusqu'à 24 heures. Il n'est pas automatiquement réentraîné et nous vous recommandons de le réentraîner chaque semaine.
1. Le fournisseur de données de formation configure le modèle de similarité, notamment en indiquant s'il convient de partager les indicateurs de pertinence et l'emplacement des segments de sortie sur Amazon S3. Le fournisseur de données de formation peut créer plusieurs modèles similaires configurés à partir d'un seul modèle similaire.
1. Le fournisseur de données de formation associe le modèle d'audience configuré à une collaboration partagée avec un fournisseur de données de départ.
Il s'agit du flux de travail que le fournisseur de données de départ doit effectuer ensuite :
1. Les données du fournisseur de données de base peuvent être stockées dans un compartiment Amazon S3 ou peuvent provenir des résultats d'une requête.
1. Le fournisseur de données de départ ouvre la collaboration qu'il partage avec le fournisseur de données de formation.
1. Le fournisseur de données de départ crée un segment similaire à partir de l'onglet Clean Rooms ML de la page de collaboration.
1. Le fournisseur de données de base peut évaluer les indicateurs de pertinence, s'ils ont été partagés, et exporter le segment similaire pour une utilisation externe AWS Clean Rooms.
## Comment AWS Clean Rooms ML fonctionne avec les modèles personnalisés
Avec Clean Rooms ML, les membres d'une collaboration peuvent utiliser un algorithme de modèle personnalisé dockerisé stocké dans Amazon ECR pour analyser conjointement leurs données. Pour ce faire, le *fournisseur de modèles* doit créer une image et la stocker dans Amazon ECR. Suivez les étapes décrites dans le [guide de l'utilisateur d'Amazon Elastic Container Registry](https://docs.aws.amazon.com/AmazonECR/latest/userguide/) pour créer un référentiel privé qui contiendra le modèle de ML personnalisé.
Tout membre d'une collaboration peut être le *fournisseur de modèles*, à condition de disposer des autorisations appropriées. Tous les membres d'une collaboration peuvent apporter des données d'entraînement, des données d'inférence ou les deux au modèle. Aux fins du présent guide, les membres fournissant des données sont appelés *fournisseurs de données*. Le membre qui crée la collaboration est le *créateur de la collaboration*, et ce membre peut être le *fournisseur de modèles*, l'un des *fournisseurs de données* ou les deux.
Au plus haut niveau, voici les étapes à suivre pour effectuer une modélisation ML personnalisée :
1. Le créateur de la collaboration crée une collaboration et attribue à chaque membre les capacités et la configuration de paiement appropriées. Le créateur de la collaboration doit attribuer au membre la capacité de recevoir les sorties du modèle ou de recevoir les résultats d'inférence au membre approprié au cours de cette étape, car il ne peut pas être mis à jour une fois la collaboration créée. Pour de plus amples informations, veuillez consulter [Création et adhésion à la collaboration dans AWS Clean Rooms ML](create-custom-ml-collaboration.md).
1. Le fournisseur de modèles configure et associe son modèle de machine learning conteneurisé à la collaboration et s'assure que les contraintes de confidentialité sont définies pour les données exportées. Pour de plus amples informations, veuillez consulter [Configuration d'un algorithme de modèle dans AWS Clean Rooms ML](configure-model-algorithm.md).
1. Les fournisseurs de données fournissent leurs données à la collaboration et veillent à ce que leurs besoins en matière de confidentialité soient spécifiés. Les fournisseurs de données doivent autoriser le modèle à accéder à leurs données. Pour plus d’informations, consultez [Contribution de données de formation dans AWS Clean Rooms ML](custom-model-training-data.md) et [Associer l'algorithme du modèle configuré dans AWS Clean Rooms ML](associate-model-algorithm.md).
1. Un membre de la collaboration crée la configuration ML, qui définit l'endroit vers lequel les artefacts du modèle ou les résultats d'inférence sont exportés.
1. Un membre de la collaboration crée un canal d'entrée ML qui fournit des informations au conteneur de formation ou au conteneur d'inférence. Le canal d'entrée ML est une requête qui définit les données à utiliser dans le contexte de l'algorithme du modèle.
1. Un membre de la collaboration invoque l'entraînement du modèle à l'aide du canal d'entrée ML et de l'algorithme de modèle configuré. Pour de plus amples informations, veuillez consulter [Création d'un modèle entraîné dans AWS Clean Rooms ML](create-trained-model.md).
1. (Facultatif) Le modèle d'entraînement lance la tâche d'exportation du modèle et les artefacts du modèle sont envoyés au récepteur des résultats du modèle. Seuls les membres dotés d'une configuration ML valide et capables de recevoir les résultats du modèle peuvent recevoir des artefacts du modèle. Pour de plus amples informations, veuillez consulter [Exportation d'artefacts de modèles depuis AWS Clean Rooms ML](export-model-artifacts.md).
1. (Facultatif) Un membre de la collaboration invoque l'inférence de modèle à l'aide du canal d'entrée ML, de l'ARN du modèle entraîné et de l'algorithme de modèle configuré par inférence. Les résultats d'inférence sont envoyés au récepteur de sortie d'inférence. Seuls les membres dotés d'une configuration ML valide et capables de recevoir des résultats d'inférence peuvent recevoir des résultats d'inférence.
Voici les étapes qui doivent être effectuées par le *fournisseur de modèles* :
1. Créez une image de docker Amazon ECR compatible avec l' SageMaker IA. Clean Rooms ML ne prend en charge que les images docker compatibles avec l' SageMaker IA.
1. Après avoir créé une image docker compatible avec l' SageMaker IA, transférez-la vers Amazon ECR. Suivez les instructions du [guide de l'utilisateur d'Amazon Elastic Container Registry](https://docs.aws.amazon.com/AmazonECR/latest/userguide/) pour créer une image de formation sur les conteneurs.
1. Configurez l'algorithme du modèle à utiliser dans Clean Rooms ML.
1. Fournissez le lien du référentiel Amazon ECR et tous les arguments nécessaires pour configurer l'algorithme du modèle.
1. Fournissez un rôle d'accès au service qui permet à Clean Rooms ML d'accéder au référentiel Amazon ECR.
1. Associez l'algorithme du modèle configuré à la collaboration. Cela inclut la fourniture d'une politique de confidentialité qui définit les contrôles pour les journaux des conteneurs, les journaux des défaillances, CloudWatch les métriques et les limites relatives à la quantité de données pouvant être exportées à partir des résultats des conteneurs.
Voici les étapes que le *fournisseur de données* doit suivre pour collaborer avec un modèle de machine learning personnalisé :
1. Configurez une AWS Glue table existante avec une règle d'analyse personnalisée. Cela permet à un ensemble spécifique de requêtes préapprouvées ou de comptes préapprouvés d'utiliser vos données.
1. Associez votre table configurée à une collaboration et fournissez un rôle d'accès au service qui peut accéder à vos AWS Glue tables.
1. [Ajoutez une règle d'analyse de collaboration](add-collaboration-analysis-rule.md) à la table qui permet à l'association d'algorithmes du modèle configuré d'accéder à la table configurée.
1. Une fois le modèle et les données associés et configurés dans Clean Rooms ML, le membre capable d'exécuter des requêtes fournit une requête SQL et sélectionne l'algorithme du modèle à utiliser.
Une fois l'entraînement du modèle terminé, ce membre lance l'exportation des artefacts d'entraînement du modèle ou des résultats d'inférence. Ces artefacts ou résultats sont envoyés au membre capable de recevoir les résultats du modèle entraîné. Le récepteur des résultats doit les configurer `MachineLearningConfiguration` avant de pouvoir recevoir la sortie du modèle.
# AWS modèles dans Clean Rooms ML
AWS Clean Rooms ML fournit une méthode préservant la confidentialité permettant à deux parties d'identifier des utilisateurs similaires dans leurs données sans avoir à partager leurs données entre elles. La première partie apporte les données d'entraînement AWS Clean Rooms afin de créer et de configurer un modèle similaire et de l'associer à une collaboration. Les données de départ sont ensuite transmises à la collaboration pour créer un segment similaire aux données d'entraînement.
Pour une explication plus détaillée de son fonctionnement, voir[Emplois multi-comptes](ml-behaviors.md#ml-behaviors-cross-account-jobs).
Les rubriques suivantes fournissent des informations sur la création et la configuration de AWS modèles dans Clean Rooms ML.
**Topics**
+ [Protection de la confidentialité d'AWS Clean Rooms ML](ml-privacy.md)
+ [Exigences relatives aux données de formation pour Clean Rooms ML](ml-training-data-requirements.md)
+ [Exigences relatives aux données de base pour Clean Rooms ML](ml-seed-data-requirements.md)
+ [Mesures d'évaluation du modèle AWS Clean Rooms ML](ml-metrics.md)
# Protection de la confidentialité d'AWS Clean Rooms ML
Clean Rooms ML est conçu pour réduire le risque d'*attaques par inférence d'adhésion*, dans le cadre desquelles le fournisseur de données de formation peut savoir qui figure dans les données de départ et le fournisseur de données de départ peut savoir qui figure dans les données d'entraînement. Plusieurs mesures sont prises pour empêcher cette attaque.
Tout d'abord, les fournisseurs de données de départ n'observent pas directement les résultats de Clean Rooms ML et les fournisseurs de données de formation ne peuvent jamais observer les données de départ. Les fournisseurs de données de départ peuvent choisir d'inclure les données de départ dans le segment de sortie.
Ensuite, le modèle similaire est créé à partir d'un échantillon aléatoire des données d'entraînement. Cet échantillon inclut un nombre important d'utilisateurs qui ne correspondent pas à l'audience initiale. Ce processus rend plus difficile de déterminer si un utilisateur ne figurait pas dans les données, ce qui constitue un autre moyen de déduire son appartenance.
De plus, plusieurs clients de semences peuvent être utilisés pour chaque paramètre de la formation d'un modèle similaire spécifique à une graine. Cela limite le surajustement du modèle, et donc ce qui peut être déduit à propos d'un utilisateur. Par conséquent, nous recommandons que la taille minimale des données de départ soit de 500 utilisateurs.
Enfin, les indicateurs au niveau des utilisateurs ne sont jamais fournis aux fournisseurs de données de formation, ce qui élimine toute autre possibilité d'attaque par inférence d'adhésion.
# Exigences relatives aux données de formation pour Clean Rooms ML
Pour réussir à créer un modèle similaire, vos données d'entraînement doivent répondre aux exigences suivantes :
+ Les données d'entraînement doivent être au format Parquet, CSV ou JSON.
**Note**
Les données Parquet compressées au format Zstandard (ZSTD) ne sont pas prises en charge.
+ Vos données d'entraînement doivent être cataloguées dans. AWS Glue Pour plus d'informations, consultez [Getting started with the AWS Glue Data Catalog](https://docs.aws.amazon.com//glue/latest/dg/start-data-catalog.html) dans le manuel du AWS Glue développeur. Nous vous recommandons d'utiliser AWS Glue des robots d'exploration pour créer vos tables, car le schéma est déduit automatiquement.
+ Le compartiment Amazon S3 qui contient les données d'entraînement et les données de départ se trouve dans la même AWS région que vos autres ressources Clean Rooms ML.
+ Les données d'entraînement doivent contenir au moins 100 000 utilisateurs uniques IDs ayant chacun au moins deux interactions avec des éléments.
+ Les données d'entraînement doivent contenir au moins 1 million d'enregistrements.
+ Le schéma spécifié dans l'[CreateTrainingDataset](https://docs.aws.amazon.com/cleanrooms-ml/latest/APIReference/API_CreateTrainingDataset.html)action doit être aligné sur le schéma défini lors de la création de la AWS Glue table.
+ Les champs obligatoires, tels que définis dans le tableau fourni, sont définis dans l'[CreateTrainingDataset](https://docs.aws.amazon.com/cleanrooms-ml/latest/APIReference/API_CreateTrainingDataset.html)action.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/clean-rooms/latest/userguide/ml-training-data-requirements.html)
+ Vous pouvez éventuellement fournir jusqu'à 10 caractéristiques catégorielles ou numériques au total.
Voici un exemple d'ensemble de données d'entraînement valide au format CSV
```
USER_ID,ITEM_ID,TIMESTAMP,EVENT_TYPE(CATEGORICAL FEATURE),EVENT_VALUE (NUMERICAL FEATURE)
196,242,881250949,click,15
186,302,891717742,click,13
22,377,878887116,click,10
244,51,880606923,click,20
166,346,886397596,click,10
```
# Exigences relatives aux données de base pour Clean Rooms ML
Les données de départ d'un modèle similaire peuvent provenir directement d'un compartiment Amazon S3 ou des résultats d'une requête SQL.
Les données sur les semences fournies directement doivent répondre aux exigences suivantes :
+ Les données de départ doivent être au format de lignes JSON avec une liste d'utilisateurs IDs.
+ La taille de la graine doit être comprise entre 25 et 500 000 utilisateurs uniques IDs.
+ Le nombre minimum d'utilisateurs de départ doit correspondre à la valeur de taille de départ minimale correspondante spécifiée lors de la création du modèle d'audience configuré.
Voici un exemple d'ensemble de données d'entraînement valide au format CSV
```
{"user_id": "abc"}
{"user_id": "def"}
{"user_id": "ghijkl"}
{"user_id": "123"}
{"user_id": "456"}
{"user_id": "7890"}
```
# Mesures d'évaluation du modèle AWS Clean Rooms ML
Clean Rooms ML calcule le *score de *rappel* et de pertinence* pour déterminer les performances de votre modèle. Recall compare la similitude entre les données similaires et les données d'entraînement. Le score de pertinence est utilisé pour déterminer la taille de l'audience, et non pour déterminer si le modèle est performant.
Le *rappel* est une mesure impartiale de la similitude entre le segment similaire et les données d'entraînement. Le rappel est le pourcentage d'utilisateurs les plus similaires (par défaut, les 20 % les plus similaires) à partir d'un échantillon de données de formation inclus dans l'audience initiale par la tâche de génération d'audience. Les valeurs vont de 0 à 1, les valeurs les plus élevées indiquent une meilleure audience. Une valeur de rappel approximativement égale au pourcentage maximal de bacs indique que le modèle d'audience est équivalent à une sélection aléatoire.
Nous considérons qu'il s'agit d'un meilleur indicateur d'évaluation que l'exactitude, la précision et les scores F1, car Clean Rooms ML n'a pas correctement étiqueté les utilisateurs réellement négatifs lors de la création de son modèle.
Le *score de pertinence* au niveau du segment est une mesure de similarité avec des valeurs allant de -1 (le moins similaire) à 1 (le plus similaire). Clean Rooms ML calcule un ensemble de scores de pertinence pour différentes tailles de segment afin de vous aider à déterminer la meilleure taille de segment pour vos données. Les scores de pertinence diminuent de façon monotone à mesure que la taille du segment augmente. Ainsi, lorsque la taille du segment augmente, il peut être moins similaire aux données de départ. Lorsque le score de pertinence au niveau du segment atteint 0, le modèle prédit que tous les utilisateurs du segment similaire appartiennent à la même distribution que les données initiales. L'augmentation de la taille de sortie est susceptible d'inclure dans le segment similaire des utilisateurs qui ne proviennent pas de la même distribution que les données de départ.
Les scores de pertinence sont normalisés au sein d'une même campagne et ne doivent pas être utilisés pour comparer les campagnes. Les scores de pertinence ne doivent pas être utilisés comme des preuves provenant d'une source unique pour un résultat commercial, car ils sont influencés par de multiples facteurs complexes en plus de la pertinence, tels que la qualité des stocks, le type d'inventaire, le calendrier des publicités, etc.
Les scores de pertinence ne doivent pas être utilisés pour juger de la qualité de la graine, mais plutôt pour déterminer si elle peut être augmentée ou diminuée. Considérez les exemples suivants :
+ Tous les scores sont positifs : cela indique que le nombre d'utilisateurs prédits comme similaires est supérieur au nombre d'utilisateurs inclus dans le segment similaire. Cela est courant pour les données sur les semences qui font partie d'un vaste marché, comme pour tous ceux qui ont acheté du dentifrice le mois dernier. Nous vous recommandons de consulter des données sur des semences plus petites, comme celles de tous ceux qui ont acheté du dentifrice plus d'une fois au cours du dernier mois.
+ Tous les scores sont négatifs ou négatifs pour la taille de segment de sosie souhaitée : cela indique que Clean Rooms ML prédit qu'il n'y a pas assez d'utilisateurs similaires dans la taille de segment de sosie souhaitée. Cela peut être dû au fait que les données sur les semences sont trop spécifiques ou que le marché est trop petit. Nous recommandons soit d'appliquer moins de filtres aux données sur les semences, soit d'élargir le marché. Par exemple, si les données initiales concernaient des clients ayant acheté une poussette et un siège auto, vous pourriez étendre le marché aux clients ayant acheté plusieurs produits pour bébés.
Les fournisseurs de données de formation déterminent si les scores de pertinence sont exposés et les compartiments dans lesquels les scores de pertinence sont calculés.
# Modèles personnalisés dans Clean Rooms ML
Avec Clean Rooms ML, les membres d'une collaboration peuvent utiliser un algorithme de modèle personnalisé dockerisé stocké dans Amazon ECR pour analyser conjointement leurs données. Pour ce faire, le *fournisseur de modèles* doit créer une image et la stocker dans Amazon ECR. Suivez les étapes décrites dans le [guide de l'utilisateur d'Amazon Elastic Container Registry](https://docs.aws.amazon.com/AmazonECR/latest/userguide/) pour créer un référentiel privé qui contiendra le modèle de ML personnalisé.
Tout membre d'une collaboration peut être le *fournisseur de modèles*, à condition de disposer des autorisations appropriées. Tous les membres d'une collaboration peuvent apporter des données au modèle. Aux fins du présent guide, les membres fournissant des données sont appelés *fournisseurs de données*. Le membre qui crée la collaboration est le *créateur de la collaboration*, et ce membre peut être le *fournisseur de modèles*, l'un des *fournisseurs de données* ou les deux.
Les rubriques suivantes décrivent les informations nécessaires pour créer un modèle de machine learning personnalisé.
**Topics**
+ [Prérequis pour la modélisation ML personnalisée](custom-model-prerequisites.md)
+ [Consignes de création de modèles pour le conteneur de formation](custom-model-guidelines.md)
+ [Directives de création de modèles pour le conteneur d'inférence](inference-model-guidelines.md)
+ [Réception des journaux et des métriques du modèle](custom-model-logs.md)
# Prérequis pour la modélisation ML personnalisée
Avant de pouvoir effectuer une modélisation ML personnalisée, vous devez prendre en compte les points suivants :
+ Déterminez si la formation du modèle et l'inférence sur le modèle entraîné seront effectuées dans le cadre de la collaboration.
+ Déterminez le rôle que chaque membre de la collaboration jouera et attribuez-lui les compétences appropriées.
+ Attribuez `CAN_QUERY` cette capacité au membre qui entraînera le modèle et exécutera l'inférence sur le modèle entraîné.
+ Attribuez le `CAN_RECEIVE_RESULTS` à au moins un membre de la collaboration.
+ `CAN_RECEIVE_MODEL_OUTPUT`Attribuez `CAN_RECEIVE_INFERENCE_OUTPUT` des capacités au membre qui recevra des exportations de modèles entraînés ou des sorties d'inférence, respectivement. Vous pouvez choisir d'utiliser les deux capacités si elles sont requises par votre cas d'utilisation.
+ Déterminez la taille maximale des artefacts du modèle entraîné ou des résultats d'inférence dont vous autoriserez l'exportation.
+ Nous recommandons que tous les utilisateurs aient les `CleanroomsMLFullAccess` politiques `CleanrooomsFullAccess` et associées à leur rôle. L'utilisation de modèles de ML personnalisés nécessite d'utiliser à la fois le ML AWS Clean Rooms et AWS Clean Rooms ML SDKs.
+ Tenez compte des informations suivantes concernant les rôles IAM.
+ Tous les fournisseurs de données doivent avoir un rôle d'accès aux services qui leur permet AWS Clean Rooms de lire les données de leurs AWS Glue catalogues et de leurs tables, ainsi que des emplacements Amazon S3 sous-jacents. Ces rôles sont similaires à ceux requis pour les requêtes SQL. Cela vous permet d'utiliser l'`CreateConfiguredTableAssociation`action. Pour de plus amples informations, veuillez consulter [Créez un rôle de service pour créer une association de tables configurée](ml-roles.md#ml-roles-custom-configure-table).
+ Tous les membres qui souhaitent recevoir des métriques doivent disposer d'un rôle d'accès au service qui leur permet de rédiger CloudWatch des métriques et des journaux. Ce rôle est utilisé par Clean Rooms ML pour écrire toutes les métriques et les journaux du modèle dans ceux des membres Compte AWS lors de l'entraînement et de l'inférence du modèle. Nous fournissons également des contrôles de confidentialité pour déterminer quels membres ont accès aux statistiques et aux journaux. Cela vous permet d'utiliser l'`CreateMLConfiguration`action. Pour plus d'informations, voir,[Création d'un rôle de service pour la modélisation ML personnalisée - Configuration ML](ml-roles.md#ml-roles-custom-configure).
Le membre recevant les résultats doit fournir un rôle d'accès au service avec l'autorisation d'écrire dans son compartiment Amazon S3. Ce rôle permet à Clean Rooms ML d'exporter les résultats (artefacts de modèles entraînés ou résultats d'inférence) vers un compartiment Amazon S3. Cela vous permet d'utiliser l'`CreateMLConfiguration`action. Pour de plus amples informations, veuillez consulter [Création d'un rôle de service pour la modélisation ML personnalisée - Configuration ML](ml-roles.md#ml-roles-custom-configure).
+ Le fournisseur de modèles doit fournir un rôle d'accès au service avec des autorisations pour lire son référentiel et son image Amazon ECR. Cela vous permet d'utiliser l'`CreateConfigureModelAlgorithm`action. Pour de plus amples informations, veuillez consulter [Créez un rôle de service pour fournir un modèle de machine learning personnalisé](ml-roles.md#ml-roles-custom-model-provider).
+ Le membre qui crée le pour générer des ensembles de données `MLInputChannel` à des fins d'entraînement ou d'inférence doit fournir un rôle d'accès au service qui permet à Clean Rooms ML d'exécuter une requête SQL dans. AWS Clean Rooms Cela vous permet d'utiliser les `StartTrainedModelInferenceJob` actions `CreateTrainedModel` et. Pour de plus amples informations, veuillez consulter [Création d'un rôle de service pour interroger un ensemble de données](ml-roles.md#ml-roles-custom-query-dataset).
+ Les auteurs du modèle doivent suivre les [Consignes de création de modèles pour le conteneur de formation](custom-model-guidelines.md) et s'[Directives de création de modèles pour le conteneur d'inférenceRéception des journaux et des métriques du modèle](inference-model-guidelines.md)assurer que les entrées et sorties du modèle sont configurées comme prévu par AWS Clean Rooms.
# Consignes de création de modèles pour le conteneur de formation
Cette section détaille les directives que les fournisseurs de modèles doivent suivre lors de la création d'un algorithme de modèle ML personnalisé pour Clean Rooms ML.
+ Utilisez l'image de base de conteneur appropriée prise en charge par la formation à l' SageMaker IA, comme décrit dans le guide du [développeur d'SageMaker IA](https://docs.aws.amazon.com/sagemaker/latest/dg-ecr-paths/sagemaker-algo-docker-registry-paths.html). Le code suivant vous permet d'extraire les images de base de conteneurs prises en charge à partir de points de terminaison d' SageMaker IA publics.
```
ecr_registry_endpoint='763104351884.dkr.ecr.$REGION.amazonaws.com'
base_image='pytorch-training:2.3.0-cpu-py311-ubuntu20.04-sagemaker'
aws ecr get-login-password --region $REGION | docker login --username AWS --password-stdin $ecr_registry_endpoint
docker pull $ecr_registry_endpoint/$base_image
```
+ Lorsque vous créez le modèle localement, assurez-vous de ce qui suit afin de pouvoir le tester localement, sur une instance de développement, sur SageMaker AI Training in your Compte AWS et sur Clean Rooms ML.
+ Nous vous recommandons d'écrire un script d'entraînement qui accède aux propriétés utiles de l'environnement d'entraînement par le biais de diverses variables d'environnement. Clean Rooms ML utilise les arguments suivants pour appeler l'entraînement sur le code de votre modèle : `SM_MODEL_DIR``SM_OUTPUT_DIR`,`SM_CHANNEL_TRAIN`, et`FILE_FORMAT`. Ces valeurs par défaut sont utilisées par Clean Rooms ML pour entraîner votre modèle ML dans son propre environnement d'exécution avec les données de toutes les parties.
+ Clean Rooms ML met à disposition vos canaux d'entrée d'entraînement via les `/opt/ml/input/data/channel-name` répertoires du conteneur docker. Chaque canal d'entrée ML est mappé en fonction du canal correspondant `channel_name` fourni dans la `CreateTrainedModel` demande.
```
parser = argparse.ArgumentParser()# Data, model, and output directories
parser.add_argument('--model_dir', type=str, default=os.environ.get('SM_MODEL_DIR', "/opt/ml/model"))
parser.add_argument('--output_dir', type=str, default=os.environ.get('SM_OUTPUT_DIR', "/opt/ml/output/data"))
parser.add_argument('--train_dir', type=str, default=os.environ.get('SM_CHANNEL_TRAIN', "/opt/ml/input/data/train"))
parser.add_argument('--train_file_format', type=str, default=os.environ.get('FILE_FORMAT', "csv"))
```
+ Assurez-vous de pouvoir générer un ensemble de données synthétique ou de test basé sur le schéma des collaborateurs qui sera utilisé dans le code de votre modèle.
+ Assurez-vous de pouvoir exécuter vous-même une tâche de formation à l' SageMaker IA Compte AWS avant d'associer l'algorithme du modèle à une AWS Clean Rooms collaboration.
Le code suivant contient un exemple de fichier Docker compatible avec les tests locaux, les tests de l'environnement SageMaker AI Training et Clean Rooms ML
```
FROM 763104351884.dkr.ecr.us-west-2.amazonaws.com/pytorch-training:2.3.0-cpu-py311-ubuntu20.04-sagemaker
MAINTAINER $author_name
ENV PYTHONDONTWRITEBYTECODE=1 \
PYTHONUNBUFFERED=1 \
LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:/usr/local/lib"
ENV PATH="/opt/ml/code:${PATH}"
# this environment variable is used by the SageMaker PyTorch container to determine our user code directory
ENV SAGEMAKER_SUBMIT_DIRECTORY /opt/ml/code
# copy the training script inside the container
COPY train.py /opt/ml/code/train.py
# define train.py as the script entry point
ENV SAGEMAKER_PROGRAM train.py
ENTRYPOINT ["python", "/opt/ml/code/train.py"]
```
+ Pour mieux surveiller les défaillances des conteneurs, nous vous recommandons d'exporter les journaux et de procéder au débogage en cas de défaillance. Dans une `GetTrainedModel` réponse, Clean Rooms ML renvoie les 1024 premiers caractères du fichier ci-dessous`StatusDetails`.
+ Une fois que vous avez effectué les modifications du modèle et que vous êtes prêt à le tester dans l'environnement d' SageMaker IA, exécutez les commandes suivantes dans l'ordre indiqué.
```
export ACCOUNT_ID=xxx
export REPO_NAME=xxx
export REPO_TAG=xxx
export REGION=xxx
docker build -t $ACCOUNT_ID.dkr.ecr.us-west-2.amazonaws.com/$REPO_NAME:$REPO_TAG
# Sign into AWS $ACCOUNT_ID/ Run aws configure
# Check the account and make sure it is the correct role/credentials
aws sts get-caller-identity
aws ecr create-repository --repository-name $REPO_NAME --region $REGION
aws ecr describe-repositories --repository-name $REPO_NAME --region $REGION
# Authenticate Doker
aws ecr get-login-password --region $REGION | docker login --username AWS --password-stdin $ACCOUNT_ID.dkr.ecr.$REGION.amazonaws.com
# Push To ECR Images
docker push $ACCOUNT_ID.dkr.ecr.$REGION.amazonaws.com$REPO_NAME:$REPO_TAG
# Create Sagemaker Training job
# Configure the training_job.json with
# 1. TrainingImage
# 2. Input DataConfig
# 3. Output DataConfig
aws sagemaker create-training-job --cli-input-json file://training_job.json --region $REGION
```
Une fois que le travail d' SageMaker intelligence artificielle est terminé et que vous êtes satisfait de l'algorithme de votre modèle, vous pouvez enregistrer le registre Amazon ECR auprès d'AWS Clean Rooms ML. Utilisez cette `CreateConfiguredModelAlgorithm` action pour enregistrer l'algorithme du modèle et `CreateConfiguredModelAlgorithmAssociation` pour l'associer à une collaboration.
# Directives de création de modèles pour le conteneur d'inférence
Cette section détaille les directives que les fournisseurs de modèles doivent suivre lors de la création d'un algorithme d'inférence pour Clean Rooms ML.
+ Utilisez l'image de base de conteneur compatible avec l'inférence SageMaker AI appropriée, comme décrit dans le Guide du [développeur SageMaker AI](https://docs.aws.amazon.com/sagemaker/latest/dg-ecr-paths/sagemaker-algo-docker-registry-paths.html). Le code suivant vous permet d'extraire les images de base de conteneurs prises en charge à partir de points de terminaison d' SageMaker IA publics.
```
ecr_registry_endpoint='763104351884.dkr.ecr.$REGION.amazonaws.com'
base_image='pytorch-inference:2.3.0-cpu-py311-ubuntu20.04-sagemaker'
aws ecr get-login-password --region $REGION | docker login --username AWS --password-stdin $ecr_registry_endpoint
docker pull $ecr_registry_endpoint/$base_image
```
+ Lorsque vous créez le modèle localement, assurez-vous de ce qui suit afin de pouvoir le tester localement, sur une instance de développement, sur SageMaker AI Batch Transform dans votre entreprise Compte AWS et sur Clean Rooms ML.
+ Clean Rooms ML met les artefacts de votre modèle issus de l'inférence à la disposition de votre code d'inférence via le `/opt/ml/model` répertoire du conteneur docker.
+ Clean Rooms ML divise les entrées par ligne, utilise une stratégie par `MultiRecord` lots et ajoute un caractère de nouvelle ligne à la fin de chaque enregistrement transformé.
+ Assurez-vous de pouvoir générer un jeu de données synthétique ou d'inférence de test basé sur le schéma des collaborateurs qui sera utilisé dans le code de votre modèle.
+ Assurez-vous de pouvoir exécuter vous-même une tâche de transformation par lots basée sur l' SageMaker IA Compte AWS avant d'associer l'algorithme du modèle à une AWS Clean Rooms collaboration.
Le code suivant contient un exemple de fichier Docker compatible avec les tests locaux, les tests d'environnement SageMaker AI Transform et Clean Rooms ML
```
FROM 763104351884.dkr.ecr.us-east-1.amazonaws.com/pytorch-inference:1.12.1-cpu-py38-ubuntu20.04-sagemaker
ENV PYTHONUNBUFFERED=1
COPY serve.py /opt/ml/code/serve.py
COPY inference_handler.py /opt/ml/code/inference_handler.py
COPY handler_service.py /opt/ml/code/handler_service.py
COPY model.py /opt/ml/code/model.py
RUN chmod +x /opt/ml/code/serve.py
ENTRYPOINT ["/opt/ml/code/serve.py"]
```
+ Une fois que vous avez effectué les modifications du modèle et que vous êtes prêt à le tester dans l'environnement d' SageMaker IA, exécutez les commandes suivantes dans l'ordre indiqué.
```
export ACCOUNT_ID=xxx
export REPO_NAME=xxx
export REPO_TAG=xxx
export REGION=xxx
docker build -t $ACCOUNT_ID.dkr.ecr.us-west-2.amazonaws.com/$REPO_NAME:$REPO_TAG
# Sign into AWS $ACCOUNT_ID/ Run aws configure
# Check the account and make sure it is the correct role/credentials
aws sts get-caller-identity
aws ecr create-repository --repository-name $REPO_NAME --region $REGION
aws ecr describe-repositories --repository-name $REPO_NAME --region $REGION
# Authenticate Docker
aws ecr get-login-password --region $REGION | docker login --username AWS --password-stdin $ACCOUNT_ID.dkr.ecr.$REGION.amazonaws.com
# Push To ECR Repository
docker push $ACCOUNT_ID.dkr.ecr.$REGION.amazonaws.com$REPO_NAME:$REPO_TAG
# Create Sagemaker Model
# Configure the create_model.json with
# 1. Primary container -
# a. ModelDataUrl - S3 Uri of the model.tar from your training job
aws sagemaker create-model --cli-input-json file://create_model.json --region $REGION
# Create Sagemaker Transform Job
# Configure the transform_job.json with
# 1. Model created in the step above
# 2. MultiRecord batch strategy
# 3. Line SplitType for TransformInput
# 4. AssembleWith Line for TransformOutput
aws sagemaker create-transform-job --cli-input-json file://transform_job.json --region $REGION
```
Une fois que le travail d' SageMaker intelligence artificielle est terminé et que vous êtes satisfait de votre transformation par lots, vous pouvez enregistrer le registre Amazon ECR auprès d'AWS Clean Rooms ML. Utilisez cette `CreateConfiguredModelAlgorithm` action pour enregistrer l'algorithme du modèle et `CreateConfiguredModelAlgorithmAssociation` pour l'associer à une collaboration.
# Réception des journaux et des métriques du modèle
Pour recevoir des journaux et des métriques issus de l'entraînement ou de l'inférence d'un modèle personnalisé, les membres doivent avoir [créé une configuration ML](https://docs.aws.amazon.com/clean-rooms/latest/userguide/create-custom-ml-collaboration.html) avec un rôle valide fournissant les CloudWatch autorisations nécessaires (voir [Création d'un rôle de service pour une modélisation ML personnalisée - Configuration ML](https://docs.aws.amazon.com/clean-rooms/latest/userguide/ml-roles.html#ml-roles-custom-configure)).
**Métrique du système**
Les métriques du système pour l'entraînement et l'inférence, telles que l'utilisation du processeur et de la mémoire, sont publiées à tous les membres en collaboration avec des configurations ML valides. Ces métriques peuvent être consultées au fur et à mesure de l'avancement de la tâche via CloudWatch Metrics in the `/aws/cleanroomsml/TrainedModels` or `/aws/cleanroomsml/TrainedModelInferenceJobs` namespaces, respectivement.
**Logs de modèles**
L'accès aux journaux du modèle est fourni par la politique de configuration de confidentialité de chaque algorithme de modèle configuré. L'auteur du modèle définit la politique de configuration de confidentialité lorsqu'il associe un algorithme de modèle configuré (via la console ou l'`CreateConfiguredModelAlgorithmAssociation`API) à une collaboration. La définition de la politique de configuration de confidentialité permet de contrôler quels membres peuvent recevoir les journaux du modèle.
En outre, l'auteur du modèle peut définir un modèle de filtre dans la politique de configuration de confidentialité pour filtrer les événements du journal. Tous les journaux qu'un conteneur modèle envoie vers `stdout` ou `stderr` qui correspondent au modèle de filtre (s'il est défini) sont envoyés à Amazon CloudWatch Logs. Les journaux des modèles sont disponibles dans des groupes de CloudWatch journaux `/aws/cleanroomsml/TrainedModels` ou`/aws/cleanroomsml/TrainedModelInferenceJobs`, respectivement.
**Métriques définies sur mesure**
Lorsque vous configurez un algorithme de modèle (via la console ou l'`CreateConfiguredModelAlgorithm`API), l'auteur du modèle peut fournir des noms de métriques spécifiques et des instructions regex à rechercher dans les journaux de sortie. Ils peuvent être consultés au fur et à mesure de l'avancement de la tâche via CloudWatch Metrics dans l'espace de `/aws/cleanroomsml/TrainedModels` noms. Lorsqu'il associe un algorithme de modèle configuré, l'auteur du modèle peut définir un niveau de bruit facultatif dans la configuration de confidentialité des métriques afin d'éviter de générer des données brutes tout en fournissant une visibilité sur les tendances des métriques personnalisées. Si un niveau de bruit est défini, les mesures sont publiées à la fin de la tâche plutôt qu'en temps réel.
# Informatique cryptographique pour Clean Rooms
Informatique cryptographique pour Clean Rooms (C3R) est une fonctionnalité AWS Clean Rooms qui peut être utilisée en plus des [règles d'analyse](analysis-rules.md). Avec C3R, les entreprises peuvent rassembler des données sensibles pour tirer de nouvelles informations de l'analyse des données tout en limitant cryptographiquement ce que les parties prenantes peuvent apprendre au cours du processus. Le C3R peut être utilisé par deux ou plusieurs parties qui souhaitent collaborer avec leurs données sensibles, mais doivent uniquement utiliser des données cryptées dans le cloud.
Le client de chiffrement C3R est un outil de chiffrement côté client que vous pouvez utiliser pour [chiffrer](glossary.md#glossary-encryption) vos données à utiliser. AWS Clean Rooms Lorsque vous utilisez le client de chiffrement C3R, les données restent protégées cryptographiquement pendant leur utilisation dans le cadre d'une AWS Clean Rooms collaboration. Comme dans le cas d'une AWS Clean Rooms collaboration normale, les données d'entrée sont des tables de base de données relationnelles, et le calcul est exprimé sous forme de requête SQL. Cependant, C3R ne prend en charge qu'un sous-ensemble limité de requêtes SQL sur des données chiffrées.
Plus précisément, C3R prend en charge le langage SQL JOIN and SELECT déclarations relatives aux données protégées par cryptographie. Chaque colonne de la table d'entrée peut être utilisée dans exactement l'un des types d'instructions SQL suivants :
+ Colonnes protégées par cryptographie pour une utilisation dans JOIN les déclarations sont appelées **fingerprint colonnes**.
+ Colonnes protégées par cryptographie pour une utilisation dans SELECT les déclarations sont appelées **sealed colonnes**.
+ Colonnes qui ne sont pas protégées par cryptographie pour être utilisées dans JOIN or SELECT les déclarations sont appelées **cleartext colonnes**.
Dans certains cas, GROUP BY les déclarations sont prises en charge sur fingerprint colonnes. Pour de plus amples informations, veuillez consulter [Fingerprintcolonnes](crypto-computing-column-types.md#fingerprint-columns). Actuellement, C3R ne prend pas en charge l'utilisation d'autres constructions SQL sur des données chiffrées, telles que WHERE des clauses ou des fonctions agrégées telles que SUM and AVERAGE, même s'ils seraient autrement autorisés par les règles d'analyse pertinentes.
Le C3R est conçu pour protéger les données contenues dans les cellules individuelles d'un tableau. En utilisant la configuration par défaut de C3R, les données sous-jacentes qu'un client met à la disposition de tiers dans le cadre d'une collaboration restent cryptées tant que le contenu est utilisé dans le cadre AWS Clean Rooms de cette collaboration. C3R utilise le cryptage AES-GCM standard pour tous sealed colonnes et une fonction pseudo-aléatoire standard, connue sous le nom de code d'authentification des messages basé sur le hachage (HMAC), pour protéger fingerprint colonnes.
Même si C3R chiffre les données de vos tables, les informations suivantes peuvent toujours être déduites :
+ Informations sur les tables elles-mêmes, notamment le nombre de colonnes, les noms des colonnes et le nombre de lignes de votre tableau.
+ Comme pour la plupart des formes de chiffrement standard, C3R n'essaie pas de masquer la longueur des valeurs chiffrées. C3R offre la possibilité de compléter des valeurs chiffrées pour masquer la longueur exacte des textes en clair. Cependant, une limite supérieure de la longueur des textes en clair dans chaque colonne pourrait tout de même être révélée à une autre partie.
+ Informations au niveau de la journalisation, telles que le moment où une ligne particulière a été ajoutée à une table C3R cryptée.
Pour plus d'informations sur le C3R, consultez les rubriques suivantes.
**Topics**
+ [Considérations relatives à l'utilisation de l'informatique cryptographique pour Clean Rooms](crypto-computing-considerations.md)
+ [Types de fichiers et de données pris en charge dans Cryptographic Computing pour Clean Rooms](crypto-computing-file-types.md)
+ [Noms de colonnes dans Cryptographic Computing pour Clean Rooms](crypto-computing-column-names.md)
+ [Types de colonnes dans le calcul cryptographique pour Clean Rooms](crypto-computing-column-types.md)
+ [Paramètres de calcul cryptographique](crypto-computing-parameters.md)
+ [Drapeaux facultatifs dans le calcul cryptographique pour Clean Rooms](crypto-computing-optional-flags.md)
+ [Requêtes avec informatique cryptographique pour Clean Rooms](crypto-computing-queries.md)
+ [Directives pour le client de chiffrement C3R](crypto-computing-guidelines.md)
# Considérations relatives à l'utilisation de l'informatique cryptographique pour Clean Rooms
Cryptographic Computing for Clean Rooms (C3R) vise à optimiser la protection des données. Toutefois, certains cas d'utilisation peuvent bénéficier de niveaux inférieurs de protection des données en échange de fonctionnalités supplémentaires. Vous pouvez faire ces compromis spécifiques en modifiant C3R à partir de sa configuration la plus sécurisée. En tant que client, vous devez être conscient de ces compromis et déterminer s'ils sont adaptés à votre cas d'utilisation. Les compromis à prendre en compte sont les suivants :
**Topics**
+ [Autoriser les données mixtes cleartext et cryptées dans vos tables](#allow-mixed-plaintext-and-encrypted-data)
+ [Autoriser les valeurs répétées dans les fingerprint colonnes](#allow-repeated-values)
+ [Assouplissement des restrictions relatives au fingerprint nom des colonnes](#loose-restrictions-on-join-column-names)
+ [Déterminer comment NULL les valeurs sont représentées](#determine-null-values)
Pour plus d'informations sur la façon de définir les paramètres de ces scénarios, consultez[Paramètres de calcul cryptographique](crypto-computing-parameters.md).
## Autoriser les données mixtes cleartext et cryptées dans vos tables
Le chiffrement de toutes les données côté client garantit une protection maximale des données. Cela limite toutefois certains types de requêtes (par exemple, la fonction d'SUMagrégation). Le risque lié à l'autorisation des cleartext données est qu'il est possible que toute personne ayant accès aux tables cryptées puisse déduire certaines informations sur les valeurs cryptées. Cela pourrait être fait en effectuant une analyse statistique des données cleartext et des données associées.
Par exemple, imaginez que vous disposiez des colonnes de `City` et`State`. La `City` colonne est chiffrée cleartext et `State` elle est cryptée. Lorsque vous voyez la valeur `Chicago` dans la `City` colonne, cela vous permet de déterminer avec une forte probabilité que `State` c'est le cas`Illinois`. En revanche, si une colonne l'est `City` et l'autre l'est`EmailAddress`, il cleartext `City` est peu probable que a révèle quoi que ce soit à propos d'un chiffré`EmailAddress`.
Pour plus d'informations sur le paramètre de ce scénario, consultez[Paramètre Autoriser cleartext les colonnes](crypto-computing-parameters.md#parameter-allowcleartext).
## Autoriser les valeurs répétées dans les fingerprint colonnes
Pour l'approche la plus sûre, nous supposons que chaque fingerprint colonne contient exactement une instance d'une variable. Aucun élément ne peut être répété dans une fingerprint colonne. Le client de chiffrement C3R mappe ces cleartext valeurs en valeurs uniques impossibles à distinguer des valeurs aléatoires. Il est donc impossible de déduire des informations les concernant à cleartext partir de ces valeurs aléatoires.
Le risque de valeurs répétées dans une fingerprint colonne est que les valeurs répétées se traduisent par des valeurs répétées d'apparence aléatoire. Ainsi, toute personne ayant accès aux tables cryptées pourrait, en théorie, effectuer une analyse statistique des fingerprint colonnes susceptible de révéler des informations sur cleartext les valeurs.
Encore une fois, supposons que la fingerprint colonne soit`State`, et que chaque ligne du tableau corresponde à un ménage américain. En effectuant une analyse de fréquence, on pourrait déduire quel état est `California` et lequel est `Wyoming` avec une probabilité élevée. Cette inférence est possible car il `California` compte beaucoup plus de résidents que. `Wyoming` En revanche, supposons que la fingerprint colonne porte sur un identifiant de ménage et que chaque ménage apparaisse dans la base de données entre 1 et 4 fois dans une base de données contenant des millions d'entrées. Il est peu probable qu'une analyse de fréquence révèle des informations utiles.
Pour plus d'informations sur le paramètre de ce scénario, consultez[Paramètre Autoriser les doublons](crypto-computing-parameters.md#parameter-allowduplicates).
## Assouplissement des restrictions relatives au fingerprint nom des colonnes
Par défaut, nous supposons que lorsque deux tables sont jointes à l'aide de fingerprint colonnes chiffrées, ces colonnes portent le même nom dans chaque table. La raison technique de ce résultat est que, par défaut, nous dérivons une clé cryptographique différente pour chiffrer chaque fingerprint colonne. Cette clé est dérivée d'une combinaison de la clé secrète partagée pour la collaboration et du nom de colonne. Si nous essayons de joindre deux colonnes portant des noms de colonne différents, nous dérivons des clés différentes et nous ne pouvons pas calculer une jointure valide.
Pour résoudre ce problème, vous pouvez désactiver la fonctionnalité qui déduit les clés du nom de chaque colonne. Le client de chiffrement C3R utilise ensuite une clé dérivée unique pour toutes les fingerprint colonnes. Le risque est qu'un autre type d'analyse de fréquence puisse être effectué qui pourrait révéler des informations.
Utilisons à nouveau l'`State`exemple `City` et. Si nous dérivons les mêmes valeurs aléatoires pour chaque fingerprint colonne (en n'incorporant pas le nom de la colonne). `New York`possède la même valeur aléatoire dans les `State` colonnes `City` et. New York est l'une des rares villes des États-Unis où le `City` nom est le même que le `State` nom. En revanche, si votre ensemble de données contient des valeurs complètement différentes dans chaque colonne, aucune information n'est divulguée.
Pour plus d'informations sur le paramètre de ce scénario, consultez[Paramètre JOIN d'autorisation des colonnes avec des noms différents](crypto-computing-parameters.md#parameter-allowjoin).
## Déterminer comment NULL les valeurs sont représentées
L'option qui s'offre à vous est de savoir s'il faut traiter les NULL valeurs de manière cryptographique (chiffrement et HMAC) comme toute autre valeur. Si vous ne traitez pas NULL les valeurs comme les autres valeurs, des informations peuvent être révélées.
Supposons, par exemple, que NULL la `Middle Name` colonne cleartext indique les personnes sans deuxième prénom. Si vous ne chiffrez pas ces valeurs, vous divulguez les lignes de la table cryptée qui sont utilisées pour les personnes sans deuxième prénom. Ces informations peuvent être un signal d'identification pour certaines personnes dans certaines populations. Mais si vous traitez des NULL valeurs de manière cryptographique, certaines requêtes SQL agissent différemment. Par exemple, les GROUP BY clauses ne regrouperont pas fingerprint NULL les valeurs dans fingerprint des colonnes.
Pour plus d'informations sur le paramètre de ce scénario, consultez[Paramètre de conservation NULL des valeurs](crypto-computing-parameters.md#parameter-preservenulls).
# Types de fichiers et de données pris en charge dans Cryptographic Computing pour Clean Rooms
Le client de chiffrement C3R reconnaît les types de fichiers suivants :
+ fichiers CSV
+ Parquetfichiers
Vous pouvez utiliser l'`--fileFormat`indicateur du client de chiffrement C3R pour spécifier un format de fichier de manière explicite. Lorsqu'il est explicitement spécifié, le format de fichier n'est pas déterminé par l'extension du fichier.
**Topics**
+ [fichiers CSV](#csv-file-type)
+ [Parquetfichiers](#parquet-file-type)
+ [Chiffrement de valeurs autres que des chaînes](#encrypt-non-string-values)
## fichiers CSV
Un fichier portant une extension .csv est supposé être au format CSV et contenir du texte codé en UTF-8. Le client de chiffrement C3R traite toutes les valeurs comme des chaînes.
### Propriétés prises en charge dans les fichiers .csv
Le client de chiffrement C3R nécessite que les fichiers .csv possèdent les propriétés suivantes :
+ Peut contenir ou non une ligne d'en-tête initiale qui nomme chaque colonne de manière unique.
+ Délimité par des virgules. (Actuellement, les délimiteurs personnalisés ne sont pas pris en charge.)
+ Texte codé en UTF-8.
#### Suppression des espaces blancs dans les entrées .csv
Les espaces blancs de début et de fin sont supprimés des entrées .csv.
#### NULLEncodage personnalisé pour un fichier .csv
Un fichier .csv peut utiliser un NULL encodage personnalisé.
Avec le client de chiffrement C3R, vous pouvez spécifier des codages personnalisés pour les NULL entrées dans les données d'entrée à l'aide de l'`--csvInputNULLValue=`indicateur. Le client de chiffrement C3R peut utiliser des encodages personnalisés dans le fichier de sortie généré pour les entrées NULL à l'aide de l'`--csvOutputNULLValue=`indicateur.
**Note**
Une NULL entrée est considérée comme *manquant* de contenu, en particulier dans le contexte d'un format tabulaire plus riche tel qu'un tableau SQL. Bien que le format .csv ne prenne pas explicitement en charge cette caractérisation pour des raisons historiques, il est courant de considérer qu'une entrée vide contenant uniquement des espaces blancs est considérée NULL comme telle. Il s'agit donc du comportement par défaut du client de chiffrement C3R et il peut être personnalisé selon les besoins.
### Comment les entrées .csv sont interprétées par C3R
Le tableau suivant fournit des exemples de la manière dont les entrées .csv sont rassemblées (cleartextcleartextpour plus de clarté) en fonction des valeurs (le cas échéant) fournies pour les indicateurs `--csvInputNULLValue=` et`--csvOutputNULLValue=`. Les espaces blancs de début et de fin situés en dehors des guillemets sont supprimés avant que C3R n'interprète le sens d'une valeur.
| `` | `` | Entrée d'entrée | Entrée de sortie |
| --- |--- |--- |--- |
| Aucune | Aucun | ,AnyProduct, | ,AnyProduct, |
| Aucun | Aucun | , AnyProduct , | ,AnyProduct, |
| Aucun | Aucun | ,"AnyProduct", | ,AnyProduct, |
| Aucun | Aucun | , "AnyProduct" , | ,AnyProduct, |
| Aucun | Aucun | ,, | ,, |
| Aucun | Aucun | , , | ,, |
| Aucun | Aucun | ,"", | ,, |
| Aucun | Aucun | ," ", | ," ", |
| Aucun | Aucun | , " " , | ," ", |
| "AnyProduct" | "NULL" | ,AnyProduct, | ,NULL, |
| "AnyProduct" | "NULL" | , AnyProduct , | ,NULL, |
| "AnyProduct" | "NULL" | ,"AnyProduct", | ,NULL, |
| "AnyProduct" | "NULL" | , "AnyProduct" , | ,NULL, |
| Aucun | "NULL" | ,, | ,NULL, |
| Aucun | "NULL" | , , | ,NULL, |
| Aucun | "NULL" | ,"", | ,NULL, |
| Aucun | "NULL" | ," ", | ," ", |
| Aucune | "NULL" | , " " , | ," ", |
| "" | "NULL" | ,, | ,NULL, |
| "" | "NULL" | , , | ,NULL, |
| "" | "NULL" | ,"", | ,"", |
| "" | "NULL" | ," ", | ," ", |
| "" | "NULL" | , " " , | ," ", |
| "\$1"\$1"" | "NULL" | ,, | ,, |
| "\$1"\$1"" | "NULL" | , , | ,, |
| "\$1"\$1"" | "NULL" | ,"", | ,NULL, |
| "\$1"\$1"" | "NULL" | ," ", | ," ", |
| "\$1"\$1"" | "NULL" | , " " , | ," ", |
### Fichier CSV sans en-têtes
Il n'est pas nécessaire que le fichier .csv source comporte des en-têtes dans la première ligne qui nomment chaque colonne de manière unique. Toutefois, un fichier .csv sans ligne d'en-tête nécessite un schéma de chiffrement positionnel. Le schéma de chiffrement positionnel est requis au lieu du schéma mappé classique utilisé à la fois pour les fichiers .csv avec une ligne d'en-tête et pour les fichiers. Parquet
Un schéma de chiffrement positionnel spécifie les colonnes de sortie par position plutôt que par nom. Un schéma de chiffrement mappé associe les noms des colonnes source aux noms des colonnes cibles. Pour plus d'informations, notamment une discussion détaillée et des exemples des deux formats de schéma, consultez[Schémas de tables cartographiées et positionnelles](create-schema.md#mapped-and-positional-schemas).
## Parquetfichiers
Un fichier avec une .parquet extension est supposé être au Apache Parquet format.
### Types de Parquet données pris en charge
Le client de chiffrement C3R peut traiter toutes les données non complexes (c'est-à-dire de type primitif) dans un Parquet fichier qui représente un type de données pris en charge par. AWS Clean Rooms
Toutefois, seules les colonnes de chaîne peuvent être utilisées pour les sealed colonnes.
Les types de données Parquet suivants sont pris en charge :
+ `Binary`type primitif avec les annotations logiques suivantes :
+ Aucun si le `--parquetBinaryAsString` est défini (type de `STRING` données)
+ `Decimal(scale, precision)`(type de `DECIMAL` données)
+ `String`(type de `STRING` données)
+ `Boolean`type de données primitif sans annotation logique (type de `BOOLEAN` données)
+ `Double`type de données primitif sans annotation logique (type de `DOUBLE` données)
+ `Fixed_Len_Binary_Array`type primitif avec annotation `Decimal(scale, precision)` logique (type de `DECIMAL` données)
+ `Float`type de données primitif sans annotation logique (type de `FLOAT` données)
+ `Int32`type primitif avec les annotations logiques suivantes :
+ Aucun (type de `INT` données)
+ `Date`(type de `DATE` données)
+ `Decimal(scale, precision)`(type de `DECIMAL` données)
+ `Int(16, true)`(type de `SMALLINT` données)
+ `Int(32, true)`(type de `INT` données)
+ `Int64`type de données primitif avec les annotations logiques suivantes :
+ Aucun (type de `BIGINT` données)
+ `Decimal(scale, precision)`(type de `DECIMAL` données)
+ `Int(64, true)`(type de `BIGINT` données)
+ `Timestamp(isUTCAdjusted, TimeUnit.MILLIS)`(type de `TIMESTAMP` données)
+ `Timestamp(isUTCAdjusted, TimeUnit.MICROS)`(type de `TIMESTAMP` données)
+ `Timestamp(isUTCAdjusted, TimeUnit.NANOS)`(type de `TIMESTAMP` données)
## Chiffrement de valeurs autres que des chaînes
Actuellement, seules les valeurs de chaîne sont prises en charge pour les sealed colonnes.
Pour les fichiers .csv, le client de chiffrement C3R traite toutes les valeurs comme du texte codé en UTF-8 et ne tente pas de les interpréter différemment avant le chiffrement.
Pour les colonnes d'empreintes digitales, les types sont regroupés en classes d'équivalence. Une classe d'équivalence est un ensemble de types de données dont l'égalité peut être comparée sans ambiguïté via un type de données représentatif.
Les classes d'équivalence permettent d'attribuer des empreintes identiques à la même valeur sémantique, quelle que soit la représentation d'origine. Cependant, la même valeur dans deux classes d'équivalence ne produira pas la même colonne d'empreintes digitales.
Par exemple, la même empreinte digitale `42` sera attribuée à la `INTEGRAL` valeur, qu'il s'agisse à l'origine d'un `SMALLINT``INT`, ou`BIGINT`. De plus, la `INTEGRAL` valeur ne `0` correspondra jamais à la `BOOLEAN` valeur `FALSE` (qui est représentée par la valeur`0`).
Les classes d'équivalence suivantes et les types de AWS Clean Rooms données correspondants sont pris en charge par les colonnes d'empreintes digitales :
| Classe d'équivalence | Type de AWS Clean Rooms données pris en charge |
| --- | --- |
| BOOLEAN | BOOLEAN |
| DATE | DATE |
| INTEGRAL | BIGINT, INT, SMALLINT |
| STRING | CHAR, STRING, VARCHAR |
# Noms de colonnes dans Cryptographic Computing pour Clean Rooms
Par défaut, les noms des colonnes sont importants dans Cryptographic Computing forClean Rooms.
Si la valeur du paramètre **Autoriser les colonnes avec JOIN des noms différents** est **fausse**, les noms des colonnes sont utilisés lors du chiffrement des fingerprint colonnes. C'est pourquoi, par défaut, les collaborateurs doivent se coordonner à l'avance et utiliser les mêmes noms de colonnes cibles pour les données qui utiliseront JOIN des instructions dans les requêtes. Par défaut, les colonnes chiffrées JOIN avec des noms différents ne fonctionnent avec succès JOIN sur aucune valeur.
Si la valeur du paramètre **Autoriser les colonnes avec JOIN des noms différents** est **vraie**, les JOIN instructions entre colonnes chiffrées en tant que fingerprint colonnes aboutissent. Le chiffrement des données avec ce paramètre peut permettre une certaine inférence des cleartext valeurs. Par exemple, si une ligne possède la même valeur de code d'authentification de message basé sur le hachage (HMAC) à la fois dans la `City` colonne et dans la `State` colonne, la valeur peut être. `New York`
## Normalisation des noms d'en-têtes de colonnes
Les noms des en-têtes de colonnes sont normalisés par le client de chiffrement C3R. Tous les espaces blancs de début et de fin sont supprimés et le nom de la colonne est mis en minuscules pour la sortie transformée.
La normalisation est appliquée avant tous les autres calculs, calculs ou autres opérations susceptibles d'être affectés par les noms de colonnes. Le fichier de sortie émis contient uniquement les noms normalisés.
# Types de colonnes dans le calcul cryptographique pour Clean Rooms
Cette rubrique fournit des informations sur les types de colonnes dans Cryptographic Computing forClean Rooms.
**Topics**
+ [Fingerprintcolonnes](#fingerprint-columns)
+ [Colonnes étanches](#sealed-columns)
+ [Cleartextcolonnes](#cleartext-columns)
## Fingerprintcolonnes
*Fingerprintles colonnes* sont des colonnes protégées cryptographiquement pour être utilisées dans JOIN des instructions.
Les données des fingerprint colonnes ne peuvent pas être déchiffrées. Seules les données provenant de colonnes scellées peuvent être déchiffrées.
Fingerprintles colonnes ne doivent être utilisées que dans les clauses et fonctions SQL suivantes :
+ JOIN (INNER, OUTER, LEFT, RIGHT, or FULL)par rapport aux autres fingerprint colonnes :
+ Si la valeur du `allowJoinsOnColumnsWithDifferentNames` paramètre est définie sur`false`, les deux fingerprint colonnes du JOIN doivent également porter le même nom.
+ `SELECT COUNT()`
+ `SELECT COUNT(DISTINCT )`
+ `GROUP BY`(À utiliser uniquement si la collaboration a défini la valeur du `preserveNulls` paramètre sur`true`.)
Les requêtes qui enfreignent ces contraintes peuvent donner des résultats incorrects.
## Colonnes étanches
Les *colonnes scellées* sont des colonnes protégées cryptographiquement pour être utilisées dans SELECT des instructions.
Les colonnes scellées ne doivent être utilisées que dans les clauses et fonctions SQL suivantes :
+ `SELECT`
+ `SELECT ... AS`
+ `SELECT COUNT()`
**Note**
`SELECT COUNT(DISTINCT )` n’est pas pris en charge.
Les requêtes qui enfreignent ces contraintes peuvent donner des résultats incorrects.
### Remplissage des données pour une sealed colonne avant le chiffrement
Lorsque vous spécifiez qu'une colonne doit être une sealed colonne, C3R vous demande quel type de *rembourrage choisir*. Le remplissage des données avant le chiffrement est facultatif. Sans rembourrage (type de pad`none`), la longueur des données cryptées indique la taille ducleartext. Dans certaines circonstances, la taille du cleartext peut exposer le texte en clair. Avec le rembourrage (un pad de type `fixed` ou`max`), toutes les valeurs sont d'abord rembourrées à une taille commune, puis cryptées. Avec le rembourrage, la longueur des données cryptées ne fournit aucune information sur la cleartext longueur d'origine, si ce n'est le fait de donner une limite supérieure à sa taille.
Si vous souhaitez un remplissage pour une colonne et que la longueur maximale en octets des données de cette colonne est connue, utilisez le `fixed` rembourrage. Utilisez une `length` valeur au moins égale à la longueur en octets de la valeur la plus longue de cette colonne.
**Note**
Une erreur se produit et le chiffrement échoue si une valeur est supérieure à la valeur fournie`length`.
Si vous souhaitez un remplissage pour une colonne et que la longueur maximale en octets des données de cette colonne n'est pas connue, utilisez le `max` rembourrage. Ce mode de remplissage rembourre toutes les données à la longueur de la valeur la plus longue plus des `length` octets supplémentaires.
**Note**
Vous souhaiterez peut-être chiffrer les données par lots ou mettre régulièrement à jour vos tables avec de nouvelles données. Sachez que le `max` remplissage remplira les entrées à la longueur (plus l'`length`octet) de l'entrée en texte brut la plus longue d'un lot donné. Cela signifie que la longueur du texte chiffré peut varier d'un lot à l'autre. Par conséquent, si vous connaissez la longueur maximale en octets d'une colonne, vous devez utiliser à la `fixed` place de. `max`
## Cleartextcolonnes
Cleartextles *colonnes* sont des colonnes qui ne sont pas protégées cryptographiquement pour être utilisées dans SELECT des instructions JOIN or.
Cleartextles colonnes peuvent être utilisées dans n'importe quelle partie de la requête SQL.
# Paramètres de calcul cryptographique
Les paramètres de calcul cryptographique sont disponibles pour les collaborations utilisant Cryptographic Computing for Clean Rooms (C3R) lors de la [création](create-collaboration.md) d'une collaboration. Vous pouvez créer une collaboration à l'aide de la AWS Clean Rooms console ou de l'`CreateCollaboration`API. Dans la console, vous pouvez définir des valeurs pour les paramètres dans Paramètres de **calcul cryptographique** après avoir activé l'option **Support de calcul cryptographique**. Pour plus d’informations, consultez les rubriques suivantes.
**Topics**
+ [Paramètre Autoriser cleartext les colonnes](#parameter-allowcleartext)
+ [Paramètre Autoriser les doublons](#parameter-allowduplicates)
+ [Paramètre JOIN d'autorisation des colonnes avec des noms différents](#parameter-allowjoin)
+ [Paramètre de conservation NULL des valeurs](#parameter-preservenulls)
## Paramètre Autoriser cleartext les colonnes
Dans la console, vous pouvez définir le paramètre **Autoriser les cleartext colonnes** lors de la [création d'une collaboration](create-collaboration.md) afin de spécifier si cleartext les données sont autorisées dans une table contenant des données chiffrées.
Le tableau suivant décrit les valeurs du paramètre **Autoriser cleartext les colonnes**.
| Valeur de paramètre | Description |
| --- | --- |
| Non | Cleartextles colonnes ne sont pas autorisées dans la table cryptée. Toutes les données sont protégées par cryptographie. |
| Oui | Cleartextles colonnes sont autorisées dans la table cryptée. Cleartextles colonnes ne sont pas protégées par cryptographie et sont incluses en tant quecleartext. Vous devez prendre note de ce que les cleartext données de vos lignes peuvent révéler à propos des autres données du tableau. Pour fonctionner SUM ou AVG sur des colonnes spécifiques, les colonnes doivent être inséréescleartext. |
À l'aide de l'opération `CreateCollaboration` API, pour le `dataEncryptionMetadata` paramètre, vous pouvez définir la valeur de `allowCleartext` to `true` ou`false`. Pour plus d'informations sur les opérations d'API, consultez la [référence des AWS Clean Rooms API](https://docs.aws.amazon.com/clean-rooms/latest/apireference/Welcome.html).
Cleartextles colonnes correspondent aux colonnes classées selon le schéma spécifique cleartext à la table. Les données de ces colonnes ne sont pas cryptées et peuvent être utilisées de quelque manière que ce soit. Cleartextles colonnes peuvent être utiles si les données ne sont pas sensibles and/or si une plus grande flexibilité est requise par rapport à ce que permet une sealed colonne ou une fingerprint colonne cryptée.
## Paramètre Autoriser les doublons
Dans la console, vous pouvez définir le paramètre **Autoriser les doublons** lors de la [création d'une collaboration](create-collaboration.md) afin de spécifier si les colonnes chiffrées pour les JOIN requêtes peuvent contenir des NULL non-valeurs dupliquées.
**Important**
Les paramètres **Autoriser les doublons**, [**Autoriser les colonnes portant JOIN des noms différents**](#parameter-allowjoin) et [**Préserver NULL les valeurs**](#parameter-preservenulls) ont des effets distincts mais connexes.
Le tableau suivant décrit les valeurs du paramètre **Autoriser les doublons**.
| Valeur de paramètre | Description |
| --- | --- |
| Non | Les valeurs répétées ne sont pas autorisées dans une fingerprint colonne. Toutes les valeurs d'une seule fingerprint colonne doivent être uniques. |
| Oui | Les valeurs répétées sont autorisées dans une fingerprint colonne. Si vous devez joindre des colonnes contenant des valeurs répétées, définissez cette valeur sur **Oui**. Lorsque cette option est définie sur **Oui**, les modèles de fréquence apparaissant dans les fingerprint colonnes de la table C3R ou des résultats peuvent impliquer des informations supplémentaires sur la structure des cleartext données. |
À l'aide de l'opération `CreateCollaboration` API, pour le `dataEncryptionMetadata` paramètre, vous pouvez définir la valeur de `allowDuplicates` to `true` ou`false`. Pour plus d'informations sur les opérations d'API, consultez la [référence des AWS Clean Rooms API](https://docs.aws.amazon.com/clean-rooms/latest/apireference/Welcome.html).
Par défaut, si des données chiffrées doivent être utilisées dans les JOIN requêtes, le client de chiffrement C3R exige que ces colonnes ne contiennent aucune valeur dupliquée. Cette exigence vise à renforcer la protection des données. Ce comportement permet de garantir que les modèles répétés dans les données ne sont pas observables. Toutefois, si vous souhaitez utiliser des données chiffrées dans des JOIN requêtes et que vous n'êtes pas préoccupé par les valeurs dupliquées, le paramètre **Autoriser les doublons** peut désactiver cette vérification conservatrice.
## Paramètre JOIN d'autorisation des colonnes avec des noms différents
Dans la console, vous pouvez définir le paramètre **Autoriser les colonnes JOIN portant des noms différents** lors de la [création d'une collaboration](create-collaboration.md) afin de spécifier si les JOIN instructions entre des colonnes portant des noms différents sont prises en charge.
Pour de plus amples informations, consultez [Normalisation des noms d'en-têtes de colonnes](crypto-computing-column-names.md#column-header-names-normalization).
Le tableau suivant décrit les valeurs du paramètre **Autoriser JOIN les colonnes portant des noms différents**.
| Valeur de paramètre | Description |
| --- | --- |
| Non | Les jointures de fingerprint colonnes portant des noms différents ne sont pas prises en charge. JOINles instructions ne fournissent des résultats précis que pour les colonnes portant le même nom. La valeur **Non** renforce la sécurité des informations mais oblige les participants à la collaboration à se mettre d'accord au préalable sur les noms des colonnes. Si deux colonnes portent des noms différents lorsqu'elles sont cryptées sous forme **JOINde fingerprint colonnes et que l'option Autoriser les colonnes portant des noms différents** est définie sur **Non**, les JOIN instructions sur ces colonnes ne produisent aucun résultat. Cela est dû au fait qu'aucune valeur n'est partagée entre eux après le chiffrement. |
| Oui | Les jointures de fingerprint colonnes portant des noms différents sont prises en charge. Pour plus de flexibilité, les utilisateurs peuvent définir cette valeur sur **Oui**, ce qui autorise les JOIN instructions sur les colonnes quel que soit le nom de la colonne. S'il est défini sur **Oui**, le client de chiffrement C3R ne prend pas en compte le nom de colonne lors de la protection des fingerprint colonnes. Par conséquent, les valeurs communes aux différentes fingerprint colonnes sont observables dans le tableau C3R. Par exemple, si une ligne possède la même JOIN valeur chiffrée à la fois dans une `City` colonne et dans une `State` colonne, il peut être raisonnable de déduire que cette valeur est `New York` la même. |
À l'aide de l'opération `CreateCollaboration` API, pour le `dataEncryptionMetadata` paramètre, vous pouvez définir la valeur de `allowJoinsOnColumnsWithDifferentNames` to `true` ou`false`. Pour plus d'informations sur les opérations d'API, consultez la [référence des AWS Clean Rooms API](https://docs.aws.amazon.com/clean-rooms/latest/apireference/Welcome.html).
Par défaut, le chiffrement des fingerprint colonnes est affecté par le `targetHeader` paramètre pour cette colonne, défini dans[Étape 4 : générer un schéma de chiffrement pour un fichier tabulaire](gen-encryption-schema-csv.md). Par conséquent, la même cleartext valeur possède des représentations cryptées différentes dans chaque fingerprint colonne pour laquelle elle est cryptée.
Ce paramètre peut être utile pour empêcher l'inférence de cleartext valeurs dans certains cas. Par exemple, le fait de voir la même valeur cryptée dans `City` des fingerprint colonnes `State` peut être utilisé pour déduire raisonnablement que la valeur est`New York`. Cependant, l'utilisation de ce paramètre nécessite une coordination supplémentaire à l'avance, de sorte que toutes les colonnes à joindre dans les requêtes portent des noms communs.
Vous pouvez utiliser le paramètre **Autoriser JOIN les colonnes portant des noms différents** pour assouplir cette restriction. Lorsque la valeur du paramètre est définie sur`Yes`, toutes les colonnes cryptées peuvent JOIN être utilisées ensemble, quel que soit leur nom.
## Paramètre de conservation NULL des valeurs
Dans la console, vous pouvez définir le paramètre **Conserver NULL les valeurs** lors de la [création d'une collaboration](create-collaboration.md) pour indiquer qu'aucune valeur n'est présente pour cette colonne.
Le tableau suivant décrit les valeurs du paramètre **Conserver NULL les valeurs**.
| Valeur de paramètre | Description |
| --- | --- |
| Non | NULLles valeurs ne sont pas préservées. NULLles valeurs n'apparaissent pas comme NULL dans une table cryptée. NULLles valeurs apparaissent sous forme de valeurs aléatoires uniques dans une table C3R. |
| Oui | NULLles valeurs sont préservées. NULLles valeurs apparaissent comme NULL dans une table cryptée. Si vous avez besoin d'une sémantique SQL pour les NULL valeurs, vous pouvez définir cette valeur sur Oui. Par conséquent, NULL les entrées apparaissent comme NULL dans la table C3R, que la colonne soit cryptée ou non et quel que soit le paramètre défini pour Autoriser les doublons. |
À l'aide de l'opération `CreateCollaboration` API, pour le `dataEncryptionMetadata` paramètre, vous pouvez définir la valeur de `preserveNulls` to `true` ou`false`. Pour plus d'informations sur les opérations d'API, consultez la [référence des AWS Clean Rooms API](https://docs.aws.amazon.com/clean-rooms/latest/apireference/Welcome.html).
Lorsque le paramètre **Conserver NULL les valeurs** est défini sur **Non** pour la collaboration :
1. NULLles entrées dans `cleartext` les colonnes restent inchangées.
1. NULLles entrées dans les `fingerprint` colonnes cryptées sont cryptées sous forme de valeurs aléatoires afin de masquer leur contenu. Le fait de rejoindre une colonne cryptée avec des NULL entrées dans la cleartext colonne ne produit aucune correspondance pour aucune des NULL entrées. Aucune correspondance n'est établie car ils reçoivent chacun leur propre contenu aléatoire unique.
1. NULLles entrées dans les `sealed` colonnes cryptées sont cryptées.
Lorsque la valeur du paramètre **Conserver les NULL valeurs** est définie sur **Oui** pour la collaboration, les NULL entrées de toutes les colonnes restent inchangées, que la colonne NULL soit cryptée ou non.
Le paramètre **Conserver NULL les valeurs** est utile dans des scénarios tels que l'enrichissement des données, dans lesquels vous souhaitez partager un manque d'informations exprimé sous la formeNULL. Le paramètre **Conserver NULL les valeurs** est également utile au fingerprint format HMAC si vous avez des NULL valeurs dans la colonne que vous souhaitez JOIN ouGROUP BY.
Si la valeur des paramètres **Autoriser les doublons** et **Préserver NULL les valeurs** est définie sur **Non**, la présence de plusieurs NULL entrées dans une fingerprint colonne génère une erreur et arrête le chiffrement. Si la valeur de l'un des paramètres est définie sur **Oui**, aucune erreur de ce type ne se produit.
# Drapeaux facultatifs dans le calcul cryptographique pour Clean Rooms
Les sections suivantes décrivent les indicateurs facultatifs que vous pouvez définir lorsque vous [cryptez des données](encrypt-data.md) à l'aide du client de chiffrement C3R pour personnaliser et tester des fichiers tabulaires.
**Topics**
+ [Indicateur `--csvInputNULLValue`](#optional-flags-CSVinputNullValue)
+ [Indicateur `--csvOutputNULLValue`](#optional-flags-CSVoutputNullValue)
+ [Indicateur `--enableStackTraces`](#optional-flags-enablestacktraces)
+ [Indicateur `--dryRun`](#optional-flags-dry-run)
+ [Indicateur `--tempDir`](#optional-flags-working-dir)
## Indicateur `--csvInputNULLValue`
Vous pouvez utiliser l'`--csvInputNULLValue`indicateur pour spécifier des codages personnalisés pour les NULL entrées dans les données d'entrée lorsque vous [cryptez des données à l'aide du client](encrypt-data.md) de chiffrement C3R.
Le tableau suivant récapitule l'utilisation et les paramètres de cet indicateur.
| Usage | Parameters |
| --- | --- |
| Facultatif. Les utilisateurs peuvent spécifier des codages personnalisés pour les NULL entrées dans les données d'entrée. | Encodage des NULL valeurs défini par l'utilisateur dans le fichier CSV d'entrée |
Une NULL entrée est une entrée considérée comme manquant de contenu, en particulier dans le contexte d'un format tabulaire plus riche tel qu'un tableau SQL. Bien que le format .csv ne prenne pas explicitement en charge cette caractérisation pour des raisons historiques, il est courant de considérer qu'une entrée vide contenant uniquement des espaces blancs l'est. NULL Il s'agit donc du comportement par défaut du client de chiffrement C3R et il peut être personnalisé selon les besoins.
## Indicateur `--csvOutputNULLValue`
Vous pouvez utiliser l'`--csvOutputNULLValue`indicateur pour spécifier des codages personnalisés pour les NULL entrées dans les données de sortie lorsque vous [cryptez des données à l'aide du client](encrypt-data.md) de chiffrement C3R.
Le tableau suivant récapitule l'utilisation et les paramètres de cet indicateur.
| Usage | Parameters |
| --- | --- |
| Facultatif. Les utilisateurs peuvent spécifier des codages personnalisés dans le fichier de sortie généré pour les NULL entrées. | Encodage des NULL valeurs défini par l'utilisateur dans le fichier CSV de sortie |
Une NULL entrée est une entrée considérée comme manquant de contenu, en particulier dans le contexte d'un format tabulaire plus riche tel qu'un tableau SQL. Bien que le format .csv ne prenne pas explicitement en charge cette caractérisation pour des raisons historiques, il est courant de considérer qu'une entrée vide contenant uniquement des espaces blancs l'est. NULL Il s'agit donc du comportement par défaut du client de chiffrement C3R et il peut être personnalisé selon les besoins.
## Indicateur `--enableStackTraces`
Lorsque vous [chiffrez des données](encrypt-data.md) à l'aide du client de chiffrement C3R, utilisez l'`--enableStackTraces`indicateur pour fournir des informations contextuelles supplémentaires afin de signaler les erreurs lorsque C3R rencontre une erreur.
AWS ne collecte pas les erreurs. Si vous rencontrez une erreur, utilisez le stack trace pour résoudre vous-même l'erreur ou envoyez le stack trace à Support pour obtenir de l'aide.
Le tableau suivant récapitule l'utilisation et les paramètres de cet indicateur.
| Usage | Parameters |
| --- | --- |
| Facultatif. Utilisé pour fournir des informations contextuelles supplémentaires afin de signaler les erreurs lorsque le client de chiffrement C3R rencontre une erreur. | Aucune |
## Indicateur `--dryRun`
[Les commandes du client de [chiffrement C3R crypter et déchiffrer](decrypt-data.md) incluent un indicateur facultatif.](encrypt-data.md) `--dryRun` L'indicateur prend tous les arguments fournis par l'utilisateur et vérifie leur validité et leur cohérence.
Vous pouvez utiliser l'`--dryRun`indicateur pour vérifier si votre fichier de schéma est valide et cohérent avec le fichier d'entrée correspondant.
Le tableau suivant récapitule l'utilisation et les paramètres de cet indicateur.
| Usage | Parameters |
| --- | --- |
| Facultatif. Demande au client de chiffrement C3R d'analyser les paramètres et de vérifier les fichiers, mais n'effectue aucun chiffrement ni déchiffrement. | Aucune |
## Indicateur `--tempDir`
Vous pouvez utiliser un répertoire temporaire car les fichiers chiffrés peuvent parfois être plus volumineux que les fichiers non chiffrés, en fonction de leurs paramètres. Les ensembles de données doivent également être chiffrés par collaboration pour fonctionner correctement.
Lorsque vous [chiffrez des données](encrypt-data.md) à l'aide de C3R, utilisez l'`--tempDir`indicateur pour spécifier l'emplacement où les fichiers temporaires peuvent être créés lors du traitement de l'entrée.
Le tableau suivant récapitule l'utilisation et les paramètres de cet indicateur.
| Usage | Parameters |
| --- | --- |
| Les utilisateurs peuvent spécifier l'emplacement où les fichiers temporaires peuvent être créés lors du traitement de l'entrée. | Par défaut, c'est le répertoire temporaire du système. |
# Requêtes avec informatique cryptographique pour Clean Rooms
Cette rubrique fournit des informations sur l'écriture de requêtes utilisant des tables de données chiffrées à l'aide de l'informatique cryptographique pourClean Rooms.
**Topics**
+ [Requêtes qui se rattachent à NULL](#queries-branch-on-null)
+ [Mappage d'une colonne source vers plusieurs colonnes cibles](#queries-mapping)
+ [Utiliser les mêmes données pour JOIN les deux SELECT requêtes](#queries-using-same-data)
## Requêtes qui se rattachent à NULL
Avoir une branche de requête sur une NULL instruction signifie utiliser une syntaxe similaire à`IF x IS NULL THEN 0 ELSE 1`.
Les requêtes peuvent toujours se baser sur NULL des instructions en cleartext colonnes.
Les requêtes peuvent se baser sur NULL des instructions en sealed fingerprint colonnes et en colonnes uniquement lorsque la valeur du paramètre **Conserver les valeurs NULL** (`preserveNulls`) est définie sur`true`.
Les requêtes qui enfreignent ces contraintes peuvent donner des résultats incorrects.
## Mappage d'une colonne source vers plusieurs colonnes cibles
Une colonne source peut être mappée à plusieurs colonnes cibles. Par exemple, vous pouvez vouloir les deux JOIN et SELECT sur une colonne.
Pour de plus amples informations, veuillez consulter [Utiliser les mêmes données pour JOIN les deux SELECT requêtes](#queries-using-same-data).
## Utiliser les mêmes données pour JOIN les deux SELECT requêtes
Si les données d'une colonne ne sont pas sensibles, elles peuvent apparaître dans une colonne cleartext cible, ce qui permet de les utiliser à n'importe quelle fin.
Si les données d'une colonne sont sensibles et doivent être utilisées à la fois pour les SELECT requêtes JOIN et, mappez cette colonne source à deux colonnes cibles dans le fichier de sortie. Une colonne est chiffrée avec la colonne `type` sous forme de fingerprint colonne, et une colonne est chiffrée avec la colonne `type` sous forme de colonne scellée. La génération de schéma interactive du client de chiffrement C3R suggère des suffixes d'en-tête de et. `_fingerprint` `_sealed` Ces suffixes d'en-tête peuvent constituer une convention utile pour différencier rapidement de telles colonnes.
# Directives pour le client de chiffrement C3R
Le client de chiffrement C3R est un outil qui permet aux entreprises de rassembler des données sensibles afin de tirer de nouvelles informations de l'analyse des données. L'outil limite cryptographiquement ce qui peut être appris par n'importe quelle partie et AWS au cours du processus. Bien que cela soit d'une importance vitale, le processus de sécurisation cryptographique des données peut entraîner une surcharge importante en termes de ressources de calcul et de stockage. Il est donc important de comprendre les inconvénients liés à l'utilisation de chaque paramètre et de savoir comment optimiser les paramètres tout en maintenant les garanties cryptographiques souhaitées. Cette rubrique se concentre sur les implications en termes de performances des différents paramètres du client et des schémas de chiffrement C3R.
Tous les paramètres de chiffrement du client de chiffrement C3R fournissent des garanties cryptographiques différentes. Les paramètres de collaboration sont les plus sécurisés par défaut. L'activation de fonctionnalités supplémentaires lors de la création d'une collaboration affaiblit les garanties de confidentialité, ce qui permet d'effectuer des activités telles que l'analyse des fréquences sur le texte chiffré. Pour plus d'informations sur la manière dont ces paramètres sont utilisés et sur leurs implications, consultez[Informatique cryptographique pour Clean Rooms](crypto-computing.md).
**Topics**
+ [Implications sur les performances pour les types de colonnes](#performance-implications)
+ [Résolution des problèmes liés aux augmentations imprévues de la taille du texte chiffré](#troubleshooting-ciphertext-size)
## Implications sur les performances pour les types de colonnes
C3R utilise trois types de colonnes : cleartextfingerprint, etsealed. Chacun de ces types de colonnes fournit des garanties cryptographiques différentes et a des utilisations prévues différentes. Dans les sections suivantes, les implications du type de colonne sur les performances sont abordées ainsi que l'impact de chaque paramètre sur les performances.
**Topics**
+ [Cleartextcolonnes](#cleartext-columns)
+ [Fingerprintcolonnes](#guidelines-fingerprint-columns)
+ [Sealedcolonnes](#guidelines-sealed-columns)
### Cleartextcolonnes
Cleartextles colonnes ne sont pas modifiées par rapport à leur format d'origine et ne sont en aucun cas traitées cryptographiquement. Ce type de colonne ne peut pas être configuré et n'a aucune incidence sur les performances de stockage ou de calcul.
### Fingerprintcolonnes
Fingerprintles colonnes sont destinées à être utilisées pour joindre des données sur plusieurs tables. À cette fin, la taille du texte chiffré obtenu doit toujours être la même. Toutefois, ces colonnes sont affectées par les paramètres de collaboration. Fingerprintles colonnes peuvent avoir différents degrés d'impact sur la taille du fichier de sortie en fonction du cleartext contenu de l'entrée.
**Topics**
+ [Frais généraux de base pour les fingerprint colonnes](#fingerprint-columns-base-overhead)
+ [Paramètres de collaboration pour les fingerprint colonnes](#fingerprint-columns-collab-settings)
+ [Exemple de données pour une fingerprint colonne](#collab-set-sample-data)
+ [fingerprintColonnes de dépannage](#fingerprint-columns-troubleshooting)
#### Frais généraux de base pour les fingerprint colonnes
Il existe un surcoût de base pour les fingerprint colonnes. Cette surcharge est constante et remplace la taille des cleartext octets.
Les données des fingerprint colonnes sont traitées cryptographiquement par le biais d'une fonction HMAC (Hash Based Message Authentication Code), qui transforme les données en un code d'authentification de message (MAC) de 32 octets. Ces données sont ensuite traitées via un encodeur base64, ce qui ajoute environ 33 % à la taille des octets. Il est précédé d'une désignation C3R à 8 octets pour désigner le type de colonne à laquelle appartiennent les données et la version du client qui les a produites. Le résultat final est de 52 octets. Ce résultat est ensuite multiplié par le nombre de lignes pour obtenir le surcoût total de base (utilisez le nombre total de `null` valeurs non égales s'il `preserveNulls` est défini sur true).
L'image suivante montre comment *`BASE_OVERHEAD = `*`C3R_DESIGNATION + `*`(MAC * 1.33)`***
![\[La surcharge de base de 52 octets pour une fingerprint colonne.\]](http://docs.aws.amazon.com/fr_fr/clean-rooms/latest/userguide/images/base-overhead-fingerprint.PNG)
Le texte chiffré de sortie dans les fingerprint colonnes sera toujours de 52 octets. Cela peut entraîner une diminution significative de la capacité de stockage si les cleartext données d'entrée dépassent en moyenne plus de 52 octets (par exemple, les adresses postales complètes). Cela peut représenter une augmentation significative du stockage si les cleartext données d'entrée sont en moyenne inférieures à 52 octets (par exemple, l'âge du client).
#### Paramètres de collaboration pour les fingerprint colonnes
##### Paramètre `preserveNulls`
Lorsque le paramètre au niveau de la collaboration `preserveNulls` est `false` (par défaut), chaque `null` valeur est remplacée par 32 octets uniques et aléatoires et traitée comme si ce n'était pas le cas. `null` Le résultat est que chaque `null` valeur est désormais de 52 octets. Cela peut ajouter des exigences de stockage importantes pour les tables contenant très peu de données par rapport à ce paramètre `true` et à ce que `null` les valeurs sont transmises sous forme `null` de.
Si vous n'avez pas besoin des garanties de confidentialité de ce paramètre et que vous préférez conserver `null` les valeurs de vos ensembles de données, activez le `preserveNulls` paramètre au moment de la création de la collaboration. Le `preserveNulls` paramètre ne peut pas être modifié une fois la collaboration créée.
#### Exemple de données pour une fingerprint colonne
Voici un exemple de jeu de données d'entrée et de sortie pour une fingerprint colonne avec des paramètres à reproduire. D'autres paramètres de collaboration n'ont `allowDuplicates` pas d'impact sur les résultats et peuvent être définis au fur `true` et à mesure que `allowCleartext` `false` vous essayez de reproduire localement.
**Exemple de secret partagé** : `wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY`
**Exemple d'identifiant de collaboration** : `a1b2c3d4-5678-90ab-cdef-EXAMPLE11111`
**allowJoinsOnColumnsWithDifferentNames**: `True` ce paramètre n'a aucune incidence sur les performances ou les exigences de stockage. Toutefois, ce paramètre rend le choix du nom de colonne non pertinent lors de la reproduction des valeurs indiquées dans les tableaux suivants.
**Exemple 1**
| | |
| --- |--- |
| Input | null |
| preserveNulls | TRUE |
| Output | null |
| Déterministe | Yes |
| Octets d'entrée | 0 |
| Octets de sortie | 0 |
**Exemple 2**
| | |
| --- |--- |
| Input | null |
| preserveNulls | FALSE |
| Output | 01:hmac:3lkFjthvV3IUu6mMvFc1a\$1XAHwgw/ElmOq4p3Yg25kk= |
| Déterministe | No |
| Octets d'entrée | 0 |
| Octets de sortie | 52 |
**Exemple 3**
| | |
| --- |--- |
| Input | empty string |
| preserveNulls | - |
| Output | 01:hmac:oKTgi3Gba\$1eUb3JteSz2EMgXUkF1WgM77UP0Ydw5kPQ= |
| Déterministe | Yes |
| Octets d'entrée | 0 |
| Octets de sortie | 52 |
**Exemple 4**
| | |
| --- |--- |
| Input | abcdefghijklmnopqrstuvwxyz |
| preserveNulls | - |
| Output | 01:hmac:kU/IqwG7FMmzzshr0B9scomE0UJUEE7j9keTctplGww= |
| Déterministe | Yes |
| Octets d'entrée | 26 |
| Octets de sortie | 52 |
**Exemple 5**
| | |
| --- |--- |
| Input | abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 |
| preserveNulls | - |
| Output | 01:hmac:ks3htnQbw2vdhCRFF6JNzW5LMndJaHG57uvE26mBtSs= |
| Déterministe | Yes |
| Octets d'entrée | 62 |
| Octets de sortie | 52 |
#### fingerprintColonnes de dépannage
**Pourquoi le texte chiffré de mes fingerprint colonnes est-il plusieurs fois supérieur à la taille du texte cleartext qui y est inscrit ?**
Le texte chiffré d'une fingerprint colonne a toujours une longueur de 52 octets. Si vos données d'entrée étaient petites (par exemple, l'âge des clients), elles indiqueront une augmentation significative de leur taille. Cela peut également se produire si le `preserveNulls` paramètre est réglé sur`false`.
**Pourquoi le texte chiffré de mes fingerprint colonnes est-il plusieurs fois plus petit que la taille du texte cleartext qui y figure ?**
Le texte chiffré d'une fingerprint colonne a toujours une longueur de 52 octets. Si vos données d'entrée sont volumineuses (par exemple, les adresses complètes des clients), leur taille diminuera considérablement.
**Comment savoir si j'ai besoin des garanties cryptographiques fournies par `preserveNulls` ?**
Malheureusement, la réponse est que cela dépend. Au minimum, [Paramètres de calcul cryptographique](crypto-computing-parameters.md) il convient de vérifier la manière dont le `preserveNulls` paramètre protège vos données. Cependant, nous vous recommandons de faire référence aux exigences de traitement des données de votre organisation et à tout contrat applicable à la collaboration correspondante.
**Pourquoi dois-je supporter la surcharge de base64 ?**
Pour garantir la compatibilité avec les formats de fichiers tabulaires tels que CSV, le codage base64 est nécessaire. Bien que certains formats de fichier Parquet puissent prendre en charge les représentations binaires des données, il est important que tous les participants à une collaboration représentent les données de la même manière afin de garantir des résultats de requête corrects.
### Sealedcolonnes
Sealedles colonnes sont destinées à être utilisées pour transférer des données entre les membres d'une collaboration. Le texte chiffré de ces colonnes n'est pas déterministe et a un impact significatif sur les performances et le stockage en fonction de la configuration des colonnes. Ces colonnes peuvent être configurées individuellement et ont souvent le plus grand impact sur les performances du client de chiffrement C3R et sur la taille du fichier de sortie qui en résulte.
**Topics**
+ [Frais généraux de base pour les sealed colonnes](#sealed-columns-base-overhead)
+ [Paramètres de collaboration pour les sealed colonnes](#sealed-columns-collab-settings)
+ [sealedColonnes des paramètres du schéma : types de rembourrage](#sealed-collab-pad-type)
+ [Exemple de données pour une sealed colonne](#sealed-collab-sample-data)
+ [sealedColonnes de dépannage](#troubleshooting-sealed-columns)
#### Frais généraux de base pour les sealed colonnes
Il existe un surcoût de base pour les sealed colonnes. Cette surcharge est constante et s'ajoute à la taille des octets cleartext et de remplissage (le cas échéant).
Avant tout chiffrement, les données des sealed colonnes sont précédées d'un caractère de 1 octet désignant le type de données contenues. Si le rembourrage est sélectionné, les données sont ensuite complétées et ajoutées avec 2 octets indiquant la taille du pad. Une fois ces octets ajoutés, les données sont traitées cryptographiquement à l'aide d'AES-GCM et stockées avec les IV (12 octets), nonce (32 octets) et Auth Tag (16 octets). Ces données sont ensuite traitées via un encodeur base64, ce qui ajoute environ 33 % à la taille des octets. Les données sont précédées d'une désignation C3R à 7 octets pour indiquer le type de colonne auquel elles appartiennent et la version du client utilisée pour les produire. Le résultat est un surdébit de base final de 91 octets. Ce résultat peut ensuite être multiplié par le nombre de lignes pour obtenir le surcoût total de base (utilisez le nombre total de valeurs non nulles s'il `preserveNulls` est défini sur true).
L'image suivante montre comment *`BASE_OVERHEAD = C3R_DESIGNATION + ((NONCE + IV + DATA_TYPE + PAD_SIZE + AUTH_TAG) * 1.33)`*
![\[La surcharge de base de 91 octets pour une sealed colonne.\]](http://docs.aws.amazon.com/fr_fr/clean-rooms/latest/userguide/images/base-overhead-sealed.PNG)
#### Paramètres de collaboration pour les sealed colonnes
##### Paramètre `preserveNulls`
Lorsque le paramètre au niveau de la collaboration `preserveNulls` est `false` (par défaut), chaque `null` valeur est unique, aléatoire de 32 octets et traitée comme si ce n'était pas le cas. `null` Le résultat est que chaque `null` valeur est désormais de 91 octets (plus si elle est complétée). Cela peut ajouter des exigences de stockage importantes pour les tables contenant très peu de données par rapport à ce paramètre `true` et à ce que `null` les valeurs sont transmises sous forme `null` de.
Si vous n'avez pas besoin des garanties de confidentialité de ce paramètre et que vous préférez conserver `null` les valeurs de vos ensembles de données, activez le `preserveNulls` paramètre au moment de la création de la collaboration. Le `preserveNulls` paramètre ne peut pas être modifié une fois la collaboration créée.
#### sealedColonnes des paramètres du schéma : types de rembourrage
**Topics**
+ [Type de pad `none`](#pad-type-none)
+ [Type de pad `fixed`](#pad-type-fixed)
+ [Type de pad `max`](#pad-type-max)
##### Type de pad `none`
La sélection d'un type de pad `none` n'ajoute aucun rembourrage à la surcharge de base décrite précédemment cleartext et n'ajoute aucune surcharge supplémentaire à la surcharge de base décrite précédemment. L'absence de rembourrage permet d'obtenir la taille de sortie la plus économe en espace. Cependant, il n'offre pas les mêmes garanties de confidentialité que les types de rembourrage `fixed` et de `max` rembourrage. Cela est dû au fait que la taille du sous-jacent cleartext est perceptible à partir de la taille du texte chiffré.
##### Type de pad `fixed`
La sélection d'un type de pad `fixed` est une mesure de protection de la vie privée qui permet de masquer la longueur des données contenues dans une colonne. Cela se fait en complétant le tout dans le champ cleartext fourni `pad_length` avant qu'il ne soit crypté. Toute donnée dépassant cette taille entraîne l'échec du client de chiffrement C3R.
Étant donné que le remplissage est ajouté cleartext avant d'être chiffré, AES-GCM dispose d'un mappage 1 à 1 entre les octets du texte chiffré. cleartext Le codage base64 ajoutera 33 %. La surcharge de stockage supplémentaire du rembourrage peut être calculée en soustrayant la longueur moyenne du de la valeur cleartext du `pad_length` et en la multipliant par 1,33. Le résultat est le surcoût moyen de remplissage par enregistrement. Ce résultat peut ensuite être multiplié par le nombre de lignes pour obtenir la surcharge de remplissage totale (utilisez le nombre total de `null` valeurs non égales si la valeur `preserveNulls` est définie sur`true`).
`PADDING_OVERHEAD = (PAD_LENGTH - AVG_CLEARTEXT_LENGTH) * 1.33 * ROW_COUNT`
Nous vous recommandons de sélectionner le minimum `pad_length` qui englobe la plus grande valeur d'une colonne. Par exemple, si la valeur la plus élevée est de 50 octets, une valeur `pad_length` de 50 est suffisante. Une valeur supérieure à cette valeur ne fera qu'augmenter la charge de stockage.
Le rembourrage fixe n'entraîne aucune surcharge de calcul significative.
##### Type de pad `max`
La sélection d'un type de pad `max` est une mesure de protection de la vie privée qui permet de masquer la longueur des données contenues dans une colonne. Cela se fait en ajoutant le tout cleartext à la plus grande valeur de la colonne, plus le montant supplémentaire, `pad_length` avant qu'il ne soit chiffré. En général, `max` le remplissage fournit les mêmes garanties que le remplissage `fixed` d'un seul ensemble de données, tout en permettant de ne pas connaître la plus grande cleartext valeur de la colonne. Cependant, le `max` remplissage peut ne pas fournir les mêmes garanties de confidentialité que le `fixed` remplissage entre les mises à jour, car la valeur la plus élevée des ensembles de données individuels peut être différente.
Nous vous recommandons de sélectionner une valeur supplémentaire `pad_length` de 0 lorsque vous utilisez le `max` rembourrage. Cette longueur permet à toutes les valeurs d'avoir la même taille que la plus grande valeur de la colonne. Une valeur supérieure à cette valeur ne fera qu'augmenter la charge de stockage.
Si la cleartext valeur la plus élevée est connue pour une colonne donnée, nous vous recommandons d'utiliser plutôt le type `fixed` pad. L'utilisation `fixed` du rembourrage assure la cohérence entre les ensembles de données mis à jour. L'`max`utilisation du remplissage permet de compléter chaque sous-ensemble de données à la valeur la plus élevée figurant dans le sous-ensemble.
#### Exemple de données pour une sealed colonne
Voici un exemple de jeu de données d'entrée et de sortie pour une sealed colonne avec des paramètres à reproduire. D'autres paramètres de collaboration tels que `allowCleartext``allowJoinsOnColumnsWithDifferentNames`, et `allowDuplicates` n'ont pas d'impact sur les résultats et peuvent être définis au fur `true` et à mesure que `false` vous essayez de reproduire localement. Bien qu'il s'agisse des paramètres de base à reproduire, la sealed colonne n'est pas déterministe et les valeurs changent à chaque fois. L'objectif est d'afficher les octets entrants par rapport aux octets sortants. Les `pad_length` valeurs d'exemple ont été choisies intentionnellement. Ils montrent que le `fixed` rembourrage donne les mêmes valeurs que le `max` rembourrage avec les `pad_length` paramètres minimaux recommandés ou lorsqu'un rembourrage supplémentaire est souhaité.
**Exemple de secret partagé** : `wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY`
**Exemple d'identifiant de collaboration** : `a1b2c3d4-5678-90ab-cdef-EXAMPLE11111`
**Topics**
+ [Type de pad `none`](#sealed-pad-type-none)
+ [Type de tampon `fixed` (exemple 1)](#sealed-pad-type-fixed)
+ [Type de tampon `fixed` (exemple 2)](#sealed-pad-type-fixed-2)
+ [Type de tampon `max` (exemple 1)](#sealed-pad-type-max)
+ [Type de tampon `max` (exemple 2)](#sealed-pad-type-max-2)
##### Type de pad `none`
**Exemple 1**
| | |
| --- |--- |
| Input | null |
| preserveNulls | TRUE |
| Output | null |
| Déterministe | Yes |
| Octets d'entrée | 0 |
| Octets de sortie | 0 |
**Exemple 2**
| | |
| --- |--- |
| Input | null |
| preserveNulls | FALSE |
| Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfssGSPbNIJfG3iXmu6cbCUrizuV |
| Déterministe | No |
| Octets d'entrée | 0 |
| Octets de sortie | 91 |
**Exemple 3**
| | |
| --- |--- |
| Input | empty string |
| preserveNulls | - |
| Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfstGSPEM6qR8DWC2PB2GMlX41YK |
| Déterministe | No |
| Octets d'entrée | 0 |
| Octets de sortie | 91 |
**Exemple 4**
| | |
| --- |--- |
| Input | abcdefghijklmnopqrstuvwxyz |
| preserveNulls | - |
| Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfsteEE1GKEPiRzyh0h7t6OmWMLTWCvO2ckr6pkx9sGL5VLDQeHzh6DmPpyWNuI= |
| Déterministe | No |
| Octets d'entrée | 26 |
| Octets de sortie | 127 |
**Exemple 5**
| | |
| --- |--- |
| Input | abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 |
| preserveNulls | - |
| Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfsteEE1GKEPiRzyh0h7t6OmWMLTWCvO2ckr6plwtH/8tRFnn2rF91bcB9G4\$1n8GiRfJNmqdP4/QOQ3cXb/pbvPcnnohrHIGSX54ua\$11/JfcVjc= |
| Déterministe | No |
| Octets d'entrée | 62 |
| Octets de sortie | 175 |
##### Type de tampon `fixed` (exemple 1)
Dans cet exemple, `pad_length` c'est 62 et la plus grande entrée est 62 octets.
**Exemple 1**
| | |
| --- |--- |
| Input | null |
| preserveNulls | TRUE |
| Output | null |
| Déterministe | Yes |
| Octets d'entrée | 0 |
| Octets de sortie | 0 |
**Exemple 2**
| | |
| --- |--- |
| Input | null |
| preserveNulls | FALSE |
| Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfssGSNWfMRp7nSb7SMX2s3JKLOhK1\$17r75Tk\$1Mx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcoNpATs0GzbnLkor4L\$1/aSuA= |
| Déterministe | No |
| Octets d'entrée | 0 |
| Octets de sortie | 175 |
**Exemple 3**
| | |
| --- |--- |
| Input | empty string |
| preserveNulls | - |
| Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfstGSNWfMRp7nSb7SMX2s3JKLOhK1\$17r75Tk\$1Mx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcoLB53l07VZpA6OwkuXu29CA= |
| Déterministe | No |
| Octets d'entrée | 0 |
| Octets de sortie | 175 |
**Exemple 4**
| | |
| --- |--- |
| Input | abcdefghijklmnopqrstuvwxyz |
| preserveNulls | - |
| Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfsteEE1GKEPiRzyh0h7t6OmWMLTWCvO2ckr6pkx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcutBAcO\$1Mb9tuU2KIHH31AWg= |
| Déterministe | No |
| Octets d'entrée | 26 |
| Octets de sortie | 175 |
**Exemple 5**
| | |
| --- |--- |
| Input | abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 |
| preserveNulls | - |
| Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfsteEE1GKEPiRzyh0h7t6OmWMLTWCvO2ckr6plwtH/8tRFnn2rF91bcB9G4\$1n8GiRfJNmqdP4/QOQ3cXb/pbvPcnnohrHIGSX54ua\$11/JfcVjc= |
| Déterministe | No |
| Octets d'entrée | 62 |
| Octets de sortie | 175 |
##### Type de tampon `fixed` (exemple 2)
Dans cet exemple, `pad_length` c'est 162 et la plus grande entrée est 62 octets.
**Exemple 1**
| | |
| --- |--- |
| Input | null |
| preserveNulls | TRUE |
| Output | null |
| Déterministe | Yes |
| Octets d'entrée | 0 |
| Octets de sortie | 0 |
**Exemple 2**
| | |
| --- |--- |
| Input | null |
| preserveNulls | FALSE |
| Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfssGSNWfMRp7nSb7SMX2s3JKLOhK1\$17r75Tk\$1Mx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcnkB0xbLWD7zNdAqQGR0rXoSESdW0I0vpNoGcBfv4cJbG0A3h1DvtkSSVc2B80OOGppzdDqhrUVN5wFNyn8vgfPMqDaeJk5bn\$18o4WtG/ClipNcjDXvXVtK4vfCohcCA6uwrmwv/xAySX\$1xcntotL703aBTBb |
| Déterministe | No |
| Octets d'entrée | 0 |
| Octets de sortie | 307 |
**Exemple 3**
| | |
| --- |--- |
| Input | empty string |
| preserveNulls | - |
| Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfstGSNWfMRp7nSb7SMX2s3JKLOhK1\$17r75Tk\$1Mx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcnkB0xbLWD7zNdAqQGR0rXoSESdW0I0vpNoGcBfv4cJbG0A3h1DvtkSSVc2B80OOGppzdDqhrUVN5wFNyn8vgfPMqDaeJk5bn\$18o4WtG/ClipNcjDXvXVtK4vfCohcCA6uwrmwv84lVaT9Yd\$16oQx65/\$1gdVT |
| Déterministe | No |
| Octets d'entrée | 0 |
| Octets de sortie | 307 |
**Exemple 4**
| | |
| --- |--- |
| Input | abcdefghijklmnopqrstuvwxyz |
| preserveNulls | - |
| Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfsteEE1GKEPiRzyh0h7t6OmWMLTWCvO2ckr6pkx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcnkB0xbLWD7zNdAqQGR0rXoSESdW0I0vpNoGcBfv4cJbG0A3h1DvtkSSVc2B80OOGppzdDqhrUVN5wFNyn8vgfPMqDaeJk5bn\$18o4WtG/ClipNcjDXvXVtK4vfCohcCA6uwrmwtX5Hnl\$1WyfO6ks3QMaRDGSf |
| Déterministe | No |
| Octets d'entrée | 26 |
| Octets de sortie | 307 |
**Exemple 5**
| | |
| --- |--- |
| Input | abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 |
| preserveNulls | - |
| Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfsteEE1GKEPiRzyh0h7t6OmWMLTWCvO2ckr6plwtH/8tRFnn2rF91bcB9G4\$1n8GiRfJNmqdP4/QOQ3cXb/pbvPcnkB0xbLWD7zNdAqQGR0rXoSESdW0I0vpNoGcBfv4cJbG0A3h1DvtkSSVc2B80OOGppzdDqhrUVN5wFNyn8vgfPMqDaeJk5bn\$18o4WtG/ClipNcjDXvXVtK4vfCohcCA6uwrmwjkJXQZOgPdeFX9Yr/8alV5i |
| Déterministe | No |
| Octets d'entrée | 62 |
| Octets de sortie | 307 |
##### Type de tampon `max` (exemple 1)
Dans cet exemple, la valeur `pad_length` est 0 et la plus grande entrée est de 62 octets.
**Exemple 1**
| | |
| --- |--- |
| Input | null |
| preserveNulls | TRUE |
| Output | null |
| Déterministe | Yes |
| Octets d'entrée | 0 |
| Octets de sortie | 0 |
**Exemple 2**
| | |
| --- |--- |
| Input | null |
| preserveNulls | FALSE |
| Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfssGSNWfMRp7nSb7SMX2s3JKLOhK1\$17r75Tk\$1Mx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcoNpATs0GzbnLkor4L\$1/aSuA= |
| Déterministe | No |
| Octets d'entrée | 0 |
| Octets de sortie | 175 |
**Exemple 3**
| | |
| --- |--- |
| Input | empty string |
| preserveNulls | - |
| Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfstGSNWfMRp7nSb7SMX2s3JKLOhK1\$17r75Tk\$1Mx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcoLB53l07VZpA6OwkuXu29CA= |
| Déterministe | No |
| Octets d'entrée | 0 |
| Octets de sortie | 175 |
**Exemple 4**
| | |
| --- |--- |
| Input | abcdefghijklmnopqrstuvwxyz |
| preserveNulls | - |
| Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfsteEE1GKEPiRzyh0h7t6OmWMLTWCvO2ckr6pkx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcutBAcO\$1Mb9tuU2KIHH31AWg= |
| Déterministe | No |
| Octets d'entrée | 26 |
| Octets de sortie | 175 |
**Exemple 5**
| | |
| --- |--- |
| Input | abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 |
| preserveNulls | - |
| Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfsteEE1GKEPiRzyh0h7t6OmWMLTWCvO2ckr6plwtH/8tRFnn2rF91bcB9G4\$1n8GiRfJNmqdP4/QOQ3cXb/pbvPcnnohrHIGSX54ua\$11/JfcVjc= |
| Déterministe | No |
| Octets d'entrée | 62 |
| Octets de sortie | 175 |
##### Type de tampon `max` (exemple 2)
Dans cet exemple, `pad_length` c'est 100 et la plus grande entrée est 62 octets.
**Exemple 1**
| | |
| --- |--- |
| Input | null |
| preserveNulls | TRUE |
| Output | null |
| Déterministe | Yes |
| Octets d'entrée | 0 |
| Octets de sortie | 0 |
**Exemple 2**
| | |
| --- |--- |
| Input | null |
| preserveNulls | FALSE |
| Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfssGSNWfMRp7nSb7SMX2s3JKLOhK1\$17r75Tk\$1Mx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcnkB0xbLWD7zNdAqQGR0rXoSESdW0I0vpNoGcBfv4cJbG0A3h1DvtkSSVc2B80OOGppzdDqhrUVN5wFNyn8vgfPMqDaeJk5bn\$18o4WtG/ClipNcjDXvXVtK4vfCohcCA6uwrmwv/xAySX\$1xcntotL703aBTBb |
| Déterministe | No |
| Octets d'entrée | 0 |
| Octets de sortie | 307 |
**Exemple 3**
| | |
| --- |--- |
| Input | empty string |
| preserveNulls | - |
| Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfstGSNWfMRp7nSb7SMX2s3JKLOhK1\$17r75Tk\$1Mx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcnkB0xbLWD7zNdAqQGR0rXoSESdW0I0vpNoGcBfv4cJbG0A3h1DvtkSSVc2B80OOGppzdDqhrUVN5wFNyn8vgfPMqDaeJk5bn\$18o4WtG/ClipNcjDXvXVtK4vfCohcCA6uwrmwv84lVaT9Yd\$16oQx65/\$1gdVT |
| Déterministe | No |
| Octets d'entrée | 0 |
| Octets de sortie | 307 |
**Exemple 4**
| | |
| --- |--- |
| Input | abcdefghijklmnopqrstuvwxyz |
| preserveNulls | - |
| Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfsteEE1GKEPiRzyh0h7t6OmWMLTWCvO2ckr6pkx9jy48Fcg1yOPvBqRSZ7oqy1V3UKfYTLEZb/hCz7oaIneVsrcnkB0xbLWD7zNdAqQGR0rXoSESdW0I0vpNoGcBfv4cJbG0A3h1DvtkSSVc2B80OOGppzdDqhrUVN5wFNyn8vgfPMqDaeJk5bn\$18o4WtG/ClipNcjDXvXVtK4vfCohcCA6uwrmwtX5Hnl\$1WyfO6ks3QMaRDGSf |
| Déterministe | No |
| Octets d'entrée | 26 |
| Octets de sortie | 307 |
**Exemple 5**
| | |
| --- |--- |
| Input | abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 |
| preserveNulls | - |
| Output | 01:enc:bm9uY2UwMTIzNDU2Nzg5MG5vbmNlMDEyMzQ1Njc4OTBqfRYZ98t5KU6aWfsteEE1GKEPiRzyh0h7t6OmWMLTWCvO2ckr6plwtH/8tRFnn2rF91bcB9G4\$1n8GiRfJNmqdP4/QOQ3cXb/pbvPcnkB0xbLWD7zNdAqQGR0rXoSESdW0I0vpNoGcBfv4cJbG0A3h1DvtkSSVc2B80OOGppzdDqhrUVN5wFNyn8vgfPMqDaeJk5bn\$18o4WtG/ClipNcjDXvXVtK4vfCohcCA6uwrmwjkJXQZOgPdeFX9Yr/8alV5i |
| Déterministe | No |
| Octets d'entrée | 62 |
| Octets de sortie | 307 |
#### sealedColonnes de dépannage
**Pourquoi le texte chiffré de mes sealed colonnes est-il plusieurs fois supérieur à la taille du texte cleartext qui y est inscrit ?**
Cela dépend de plusieurs facteurs. D'une part, le texte chiffré d'une Cleartext colonne a toujours une longueur d'au moins 91 octets. Si vos données d'entrée étaient petites (par exemple, l'âge des clients), elles indiqueront une augmentation significative de leur taille. Ensuite, si vous avez `preserveNulls` défini ce paramètre sur `false` et que vos données d'entrée contenaient un grand nombre de `null` valeurs, chacune de ces `null` valeurs aura été transformée en 91 octets de texte chiffré. Enfin, si vous utilisez le rembourrage, par définition, des octets sont ajoutés aux cleartext données avant qu'elles ne soient chiffrées.
**La plupart de mes données dans une sealed colonne sont très petites et je dois utiliser le rembourrage. Puis-je simplement supprimer les grandes valeurs et les traiter séparément pour économiser de l'espace ?**
Nous vous déconseillons de supprimer des valeurs importantes et de les traiter séparément. Cela modifie les garanties de confidentialité fournies par le client de chiffrement C3R. En tant que modèle de menace, supposons qu'un observateur puisse voir les deux ensembles de données chiffrés. Si l'observateur constate qu'une colonne d'un sous-ensemble de données est plus ou moins remplie qu'un autre sous-ensemble, il peut tirer des conclusions sur la taille des données de chaque sous-ensemble. Supposons, par exemple, qu'une `fullName` colonne soit complétée à un total de 40 octets dans un fichier et à 800 octets dans un autre fichier. Un observateur peut supposer qu'un ensemble de données contient le nom le plus long du monde (747 octets).
**Dois-je fournir un rembourrage supplémentaire lorsque j'utilise ce type de `max` rembourrage ?**
Non. Lorsque vous utilisez le `max` rembourrage, nous recommandons que le`pad_length`, également connu sous le nom de rembourrage supplémentaire *au-delà* de la plus grande valeur de la colonne, soit défini sur 0.
**Puis-je simplement en choisir une grande `pad_length` lorsque j'utilise un `fixed` rembourrage pour ne pas me demander si la plus grande valeur convient ?**
Oui, mais la grande longueur du pad est inefficace et utilise plus d'espace de stockage que nécessaire. Nous vous recommandons de vérifier la taille de la plus grande valeur et de la `pad_length` définir sur cette valeur.
**Comment savoir si j'ai besoin des garanties cryptographiques fournies par `preserveNulls` ?**
Malheureusement, la réponse est que cela dépend. Au minimum, [Informatique cryptographique pour Clean Rooms](crypto-computing.md) il convient de vérifier la manière dont le `preserveNulls` paramètre protège vos données. Cependant, nous vous recommandons de faire référence aux exigences de traitement des données de votre organisation et à tout contrat applicable à la collaboration correspondante.
**Pourquoi dois-je supporter la surcharge de base64 ?**
Pour garantir la compatibilité avec les formats de fichiers tabulaires tels que CSV, le codage base64 est nécessaire. Bien que certains formats de fichier Parquet puissent prendre en charge les représentations binaires des données, il est important que tous les participants à une collaboration représentent les données de la même manière afin de garantir des résultats de requête corrects.
## Résolution des problèmes liés aux augmentations imprévues de la taille du texte chiffré
Supposons que vous ayez chiffré vos données et que la taille des données obtenues soit étonnamment importante. Les étapes suivantes peuvent vous aider à identifier l'endroit où l'augmentation de taille s'est produite et les mesures que vous pouvez prendre, le cas échéant.
### Identification de l'endroit où l'augmentation de taille s'est produite
Avant de pouvoir déterminer pourquoi vos données chiffrées sont nettement plus volumineuses que vos cleartext données, vous devez d'abord identifier l'origine de l'augmentation de taille. Cleartextles colonnes peuvent être ignorées en toute sécurité car elles sont inchangées. Examinez le reste fingerprint des sealed colonnes et choisissez-en une qui semble significative.
### Identifier la raison pour laquelle l'augmentation de taille s'est produite
Une fingerprint colonne ou une sealed colonne peut contribuer à l'augmentation de la taille.
**Topics**
+ [L'augmentation de taille provient-elle d'une fingerprint colonne ?](#size-increase-from-fingerprint)
+ [L'augmentation de taille provient-elle d'une sealed colonne ?](#size-increase-from-sealed)
#### L'augmentation de taille provient-elle d'une fingerprint colonne ?
Si la colonne qui contribue le plus à l'augmentation du stockage est une fingerprint colonne, cela est probablement dû au fait que les cleartext données sont petites (par exemple, l'âge du client). Chaque fingerprint texte chiffré obtenu a une longueur de 52 octets. Malheureusement, rien ne peut être fait à ce sujet sur une column-by-column base solide. Pour plus d'informations, voir [Frais généraux de base pour les fingerprint colonnes](#fingerprint-columns-base-overhead) les détails de cette colonne, notamment son impact sur les exigences de stockage.
L'autre cause possible de l'augmentation de la taille d'une fingerprint colonne est le paramètre de collaboration,`preserveNulls`. Si le paramètre de collaboration pour `preserveNulls` est désactivé (paramètre par défaut), toutes les `null` valeurs des fingerprint colonnes seront devenues 52 octets de texte chiffré. Rien ne peut être fait pour cela dans le cadre de la collaboration actuelle. Le `preserveNulls` paramètre est défini au moment de la création d'une collaboration et tous les collaborateurs doivent utiliser le même paramètre pour garantir des résultats de requête corrects. Pour plus d'informations sur ce `preserveNulls` paramètre et sur l'impact de son activation sur les garanties de confidentialité de vos données, consultez[Informatique cryptographique pour Clean Rooms](crypto-computing.md).
#### L'augmentation de taille provient-elle d'une sealed colonne ?
Si la colonne qui contribue le plus à l'augmentation du stockage est une sealed colonne, certains détails peuvent contribuer à l'augmentation de la taille.
Si les cleartext données sont petites (par exemple, l'âge du client), chaque sealed texte chiffré obtenu a une longueur d'au moins 91 octets. Malheureusement, rien ne peut être fait à ce sujet. Pour plus d'informations, voir [Frais généraux de base pour les sealed colonnes](#sealed-columns-base-overhead) les détails de cette colonne, notamment son impact sur les exigences de stockage.
La deuxième cause principale de l'augmentation du stockage dans les sealed colonnes est le rembourrage. Le remplissage ajoute des octets supplémentaires cleartext avant le chiffrement afin de masquer la taille des valeurs individuelles d'un ensemble de données. Nous vous recommandons de définir le rembourrage à la valeur minimale possible pour votre ensemble de données. Au minimum, le `pad_length` `fixed` remplissage doit être défini de manière à inclure la plus grande valeur possible dans la colonne. Tout paramètre supérieur n'ajoute aucune garantie de confidentialité supplémentaire. Par exemple, si vous savez que la plus grande valeur possible d'une colonne peut être de 50 octets, nous vous recommandons de la `pad_length` définir sur 50 octets. Toutefois, si la sealed colonne utilise un `max` remplissage, nous vous recommandons de définir la `pad_length` valeur sur 0 octet. Cela est dû au fait que le `max` rembourrage fait référence au rembourrage *supplémentaire* au-delà de la plus grande valeur de la colonne.
La dernière cause possible de l'augmentation de la taille d'une sealed colonne est le paramètre de collaboration,`preserveNulls`. Si le paramètre de collaboration pour `preserveNulls` est désactivé (paramètre par défaut), toutes les `null` valeurs des sealed colonnes seront devenues 91 octets de texte chiffré. Rien ne peut être fait pour cela dans le cadre de la collaboration actuelle. Le `preserveNulls` paramètre est défini au moment de la création d'une collaboration, et tous les collaborateurs doivent utiliser le même paramètre pour garantir des résultats de requête corrects. Pour plus d'informations sur ce paramètre et sur l'impact de son activation sur les garanties de confidentialité de vos données, consultez[Informatique cryptographique pour Clean Rooms](crypto-computing.md).