1. Prérequis
Pour suivre cet atelier de programmation, vous devez remplir quelques conditions préalables. Chaque exigence est marquée en conséquence, qu'elle soit obligatoire pour "Test local" ou "Service d'agrégation".
1.1. Télécharger l'outil de test en local (tests en local)
Pour effectuer des tests en local, vous devez télécharger l'outil de test local. L'outil génère des rapports récapitulatifs à partir des rapports de débogage non chiffrés.
L'outil de test en local peut être téléchargé dans les archives JAR Lambda de GitHub. Il doit être nommé LocalTestingTool_{version}.jar.
1.2. Assurez-vous que JAVA JRE est installé (service de test et d'agrégation local)
Ouvrez Terminal et utilisez java --version pour vérifier si Java ou OpenJDK est installé sur votre ordinateur.
S'il n'est pas installé, vous pouvez le télécharger et l'installer à partir du site Java ou du site openJDK.
1.3. Télécharger le convertisseur de rapports agrégables (service de test et d'agrégation local)
Vous pouvez télécharger une copie du convertisseur de rapports agrégables à partir du dépôt GitHub des démonstrations de la Privacy Sandbox.
1.4. Activer les API Privacy Sandbox (service de test et d'agrégation local)
Dans votre navigateur, accédez à chrome://flags/#privacy-sandbox-ads-apis et activez les API Privacy Sandbox.
Assurez-vous que les cookies tiers sont activés.
Dans votre navigateur, accédez à chrome://settings/cookies, puis sélectionnez Bloquer les cookies tiers en mode navigation privée.
1.5. Inscription sur le Web et Android (service d'agrégation)
Pour utiliser les API Privacy Sandbox dans un environnement de production, assurez-vous d'avoir suivi l'inscription et l'attestation pour Chrome et Android.
Pour les tests en local, l'enregistrement peut être désactivé à l'aide d'un indicateur Chrome et d'un commutateur CLI.
Pour utiliser l'indicateur Chrome pour notre démonstration, accédez à chrome://flags/#privacy-sandbox-enrollment-overrides et mettez à jour le forçage sur votre site. Si vous utilisez notre site de démonstration, aucune mise à jour n'est requise.
1.6. Intégration du service d'agrégation (service d'agrégation)
Le service d'agrégation nécessite l'intégration des coordinateurs pour pouvoir l'utiliser. Remplissez le formulaire d'intégration du service d'agrégation en fournissant l'adresse du site pour le reporting, votre ID de compte AWS et d'autres informations.
1.7. Fournisseur cloud (service d'agrégation)
Le service d'agrégation nécessite l'utilisation d'un environnement d'exécution sécurisé reposant sur un environnement cloud. Le service d'agrégation est compatible avec Amazon Web Services (AWS) et Google Cloud (GCP). Cet atelier de programmation ne traite que de l'intégration d'AWS.
AWS fournit un environnement d'exécution sécurisé appelé Nitro Enclaves. Assurez-vous de disposer d'un compte AWS et suivez les instructions d'installation et de mise à jour de la CLI AWS pour configurer votre environnement de CLI AWS.
Si la CLI AWS est nouvelle, vous pouvez la configurer à l'aide des instructions de configuration de la CLI.
1.7.1. Créer un bucket AWS S3
Créez un bucket AWS S3 pour stocker l'état Terraform, et un autre bucket S3 pour stocker vos rapports et vos rapports récapitulatifs. Vous pouvez utiliser la commande CLI fournie. Remplacez le champ dans <> par les variables appropriées.
aws s3api create-bucket --bucket <tf_bucket_name> --region us-east-1
aws s3api create-bucket --bucket <report_bucket_name> --region us-east-1
1.7.2. Créer une clé d'accès utilisateur
Créez des clés d'accès utilisateur à l'aide du guide AWS. Cela permettra d'appeler les points de terminaison des API createJob et getJob créés sur AWS.
1.7.3. Autorisations d'utilisateur et de groupe AWS
Pour déployer le service d'agrégation sur AWS, vous devez fournir certaines autorisations à l'utilisateur utilisé pour déployer le service. Pour cet atelier de programmation, assurez-vous que l'utilisateur dispose d'un accès administrateur afin de disposer de toutes les autorisations nécessaires au déploiement.
1.8. Terraform (service d'agrégation)
Cet atelier de programmation utilise Terraform pour déployer le service d'agrégation. Assurez-vous que le binaire Terraform est installé dans votre environnement local.
Téléchargez le binaire Terraform dans votre environnement local.
Une fois le fichier binaire Terraform téléchargé, extrayez le fichier et déplacez-le dans /usr/local/bin.
cp <directory>/terraform /usr/local/bin
Vérifiez que Terraform est disponible sur le chemin de classe.
terraform -v
1.9. Postman (pour le service d'agrégation AWS)
Pour cet atelier de programmation, utilisez Postman pour gérer les requêtes.
Pour créer un espace de travail, accédez à l'élément de navigation supérieur Espaces de travail, puis sélectionnez Créer un espace de travail.
Sélectionnez Espace de travail vide, cliquez sur le bouton suivant et nommez-le Privacy Sandbox. Sélectionnez Personal (Personnel), puis cliquez sur Create (Créer).
Téléchargez les fichiers de configuration JSON et d'environnement global de l'espace de travail préconfigurés.
Importez les fichiers JSON dans Mon espace de travail à l'aide du bouton Import (Importer).
Cette opération crée la collection Privacy Sandbox pour vous, ainsi que les requêtes HTTP createJob et getJob.
Mettez à jour la clé d'accès et la clé secrète AWS via Aperçu de l'environnement.
Cliquez sur Modifier, puis mettez à jour la valeur actuelle de access_key et secret_key. Notez que frontend_api_id sera indiqué dans la section 3.1.4 de ce document. Nous vous conseillons également d'utiliser la région "us-east-1". Toutefois, si vous souhaitez effectuer un déploiement dans une autre région, veillez à copier l'AMI publiée dans votre compte ou à effectuer une création automatique à l'aide des scripts fournis.
2. Atelier de programmation sur les tests en local
Vous pouvez utiliser l'outil de test en local de votre ordinateur pour effectuer une agrégation et générer des rapports de synthèse à l'aide des rapports de débogage non chiffrés.
Étapes de l'atelier de programmation
Étape 2.1. Déclencher un rapport: déclenchez un rapport d'agrégation privée pour pouvoir collecter le rapport.
Étape 2.2 : Créer un rapport de débogage agrégable: convertissez le rapport JSON collecté en rapport au format AVRO.
Cette étape est semblable à celle où les technologies publicitaires collectent les rapports à partir des points de terminaison de création de rapports de l'API et convertissent les rapports JSON en rapports au format AVRO.
Étape 2.3 : Analyser la clé de bucket à partir du rapport de débogage: les clés de bucket sont conçues par des technologies publicitaires. Dans cet atelier de programmation, les buckets étant prédéfinis, vous pouvez récupérer les clés de bucket telles qu'elles sont fournies.
Étape 2.4 : Créez le fichier AVRO du domaine de sortie: une fois les clés de bucket récupérées, créez le fichier AVRO du domaine de sortie.
Étape 2.5 : Créez des rapports de synthèse à l'aide de l'outil de test local: utilisez l'outil de test local pour être en mesure de créer des rapports de synthèse dans l'environnement local.
Étape 2.6 : Examinez le rapport récapitulatif: examinez le rapport récapitulatif créé par l'outil de test local.
2.1. Rapport sur les déclencheurs
Accédez au site de démonstration de la Privacy Sandbox. Cela déclenche un rapport d'agrégation privé. Vous pouvez consulter le rapport à l'adresse chrome://private-aggregation-internals.
Si l'état de votre rapport est En attente, vous pouvez le sélectionner, puis cliquer sur Envoyer les rapports sélectionnés.
2.2. Créer un rapport de débogage agrégable
Dans chrome://private-aggregation-internals, copiez le corps du rapport reçu au point de terminaison [reporting-origin]/.well-known/private-aggregation/report-shared-storage.
Assurez-vous que dans Report Body (Corps du rapport), aggregation_coordinator_origin contient https://publickeyservice.msmt.aws.privacysandboxservices.com, ce qui signifie que le rapport est un rapport agrégable AWS.
Placez le corps du rapport JSON dans un fichier JSON Report Body. Dans cet exemple, vous pouvez utiliser Vim. Mais vous pouvez utiliser n’importe quel éditeur de texte.
vim report.json
Collez le rapport dans report.json et enregistrez votre fichier.
Ensuite, accédez au dossier de votre rapport et utilisez aggregatable_report_converter.jar pour créer le rapport de débogage agrégable. Cette opération crée un rapport agrégable appelé report.avro dans votre répertoire actuel.
java -jar aggregatable_report_converter.jar \
--request_type convertToAvro \
--input_file report.json \
--debug
2.3. Analyser la clé de bucket à partir du rapport de débogage
Le service d'agrégation nécessite deux fichiers lors du traitement par lot. Rapport agrégable et fichier de domaine de sortie. Le fichier de domaine de sortie contient les clés que vous souhaitez récupérer à partir des rapports agrégables. Pour créer le fichier output_domain.avro, vous avez besoin des clés de bucket pouvant être récupérées à partir des rapports.
Les clés de bucket sont conçues par l'appelant de l'API, et la démonstration contient des exemples de clés de bucket prédéfinis. Comme la démonstration a activé le mode débogage pour Private Aggregation, vous pouvez analyser la charge utile de débogage en texte clair à partir du Report Body (Corps du rapport) pour récupérer la clé de bucket. Toutefois, dans ce cas, la démonstration de la Privacy Sandbox sur le site crée les clés de bucket. Étant donné que l'agrégation privée pour ce site est en mode débogage, vous pouvez utiliser l'debug_cleartext_payload du corps du rapport pour obtenir la clé de bucket.
Copiez l'élément debug_cleartext_payload à partir du corps du rapport.
Ouvrez l'outil Debug payload decoder for Private Aggregation (Décodeur de charge utile de débogage pour Private Aggregation) et collez votre debug_cleartext_payload dans la zone INPUT (ENTRÉE), puis cliquez sur "Decode" (Décoder).
La page renvoie la valeur décimale de la clé du bucket. Voici un exemple de clé de bucket.
2.4. Créer le domaine AVRO de sortie
Maintenant que nous disposons de la clé de bucket, copiez la valeur décimale de la clé. Créez le output_domain.avro à l'aide de la clé de bucket. Veillez à remplacer
java -jar aggregatable_report_converter.jar \
--request_type createDomainAvro \
--bucket_key <bucket key>
Le script crée le fichier output_domain.avro dans votre dossier actuel.
2.5. Créer des rapports de synthèse à l'aide de l'outil de test local
Nous utiliserons le fichier LocalTestingTool_{version}.jar téléchargé dans la section 1.1 pour créer les rapports de synthèse. Exécutez la commande ci-dessous. Vous devez remplacer LocalTestingTool_{version}.jar par la version téléchargée de LocalTestingTool.
Exécutez la commande suivante pour générer un rapport récapitulatif dans votre environnement de développement local:
java -jar LocalTestingTool_{version}.jar \
--input_data_avro_file report.avro \
--domain_avro_file output_domain.avro \
--output_directory .
Une fois la commande exécutée, une image semblable à l'image suivante doit s'afficher. Un rapport output.avro est créé une fois cette opération terminée.
2.6. Consulter le rapport récapitulatif
Le rapport de synthèse créé est au format AVRO. Pour être en mesure de lire ce texte, vous devez le convertir d'AVRO au format JSON. Idéalement, la technologie publicitaire devrait coder pour reconvertir les rapports AVRO au format JSON.
Pour notre atelier de programmation, nous allons utiliser l'outil aggregatable_report_converter.jar fourni pour reconvertir le rapport AVRO au format JSON.
java -jar aggregatable_report_converter.jar \
--request_type convertToJson \
--input_file output.avro
Un rapport semblable à l'image ci-dessous est renvoyé. ainsi qu'un rapport output.json créé dans le même répertoire.
Ouvrez le fichier JSON dans un éditeur de votre choix pour consulter le rapport récapitulatif.
3. Déploiement du service d'agrégation
Pour déployer le service d'agrégation, procédez comme suit:
Étape 3 : Déploiement du service d'agrégation: déployez le service d'agrégation sur AWS
Étape 3.1 Clonez le dépôt du service d'agrégation.
Étape 3.2 Téléchargez les dépendances prédéfinies
Étape 3.3. Créez un environnement de développement.
Étape 3.4 : Déployer le service d'agrégation
3.1. Cloner le dépôt du service d'agrégation
Dans votre environnement local, clonez le dépôt GitHub du service d'agrégation.
git clone https://github.com/privacysandbox/aggregation-service.git
3.2. Télécharger les dépendances prédéfinies
Une fois le dépôt du service d'agrégation cloné, accédez au dossier Terraform du dépôt et au dossier cloud correspondant. Si votre fournisseur cloud_provider est AWS, vous pouvez passer à
cd <repository_root>/terraform/aws
Dans download_prebuilt_dependencies.sh.
bash download_prebuilt_dependencies.sh
3.3. Créer un environnement de développement
Créez un environnement de développement dans dev.
mkdir dev
Copiez le contenu du dossier demo dans le dossier dev.
cp -R demo/* dev
Déplacez-vous dans le dossier dev.
cd dev
Mettez à jour votre fichier main.tf, puis appuyez sur i pour input afin de le modifier.
vim main.tf
Pour annuler la mise en commentaire du code dans le cadre rouge, supprimez le signe # et mettez à jour les noms de bucket et de clé.
Pour AWS main.tf:
Le code sans commentaire doit se présenter comme suit.
backend "s3" {
bucket = "<tf_state_bucket_name>"
key = "<environment_name>.tfstate"
region = "us-east-1"
}
Une fois les mises à jour terminées, enregistrez-les et quittez l'éditeur en appuyant sur esc -> :wq!. Les mises à jour seront enregistrées sur main.tf.
Remplacez example.auto.tfvars par dev.auto.tfvars.
mv example.auto.tfvars dev.auto.tfvars
Mettez à jour dev.auto.tfvars et appuyez sur i pour input afin de modifier le fichier.
vim dev.auto.tfvars
Mettez à jour les champs de l'image suivante dans l'encadré rouge avec les paramètres AWS ARN appropriés fournis lors de l'intégration du service d'agrégation, de l'environnement et de l'e-mail de notification.
Une fois les mises à jour effectuées, appuyez sur esc -> :wq!. Le fichier dev.auto.tfvars est alors enregistré. Il devrait ressembler à l'image suivante.
3.4. Déployer le service d'agrégation
Pour déployer le service d'agrégation, initialisez Terraform dans le même dossier
terraform init
Un résultat semblable aux lignes suivantes doit s'afficher:
Une fois Terraform initialisé, créez le plan d'exécution Terraform. Où renvoie le nombre de ressources à ajouter et d'autres informations supplémentaires semblables à l'image suivante.
terraform plan
Vous pouvez le consulter dans le récapitulatif Plan qui s'affiche. S'il s'agit d'un nouveau déploiement, vous devriez voir le nombre de ressources qui seront ajoutées, avec 0 pour la modifier et 0 pour la détruire.
Une fois cette opération effectuée, vous pouvez appliquer Terraform.
terraform apply
Lorsque Terraform vous demande de confirmer l'exécution des actions, saisissez yes dans la valeur.
Une fois l'opération terraform apply terminée, les points de terminaison suivants pour createJob et getJob sont renvoyés. Le frontend_api_id que vous devez mettre à jour dans Postman à la section 1.9 est également renvoyé.
4. Création des entrées du service d'agrégation
Créez les rapports AVRO pour le traitement par lot dans le service d'agrégation.
Étape 4 : Création des entrées du service d'agrégation: créez les rapports du service d'agrégation qui sont regroupés pour le service d'agrégation.
Étape 4.1 Rapport du déclencheur
Étape 4.2. Collectez des rapports agrégables
Étape 4.3. Convertissez les rapports au format AVRO
Étape 4.4. Créer le domaine AVRO de sortie
4.1. Rapport sur les déclencheurs
Accédez au site de démonstration de la Privacy Sandbox. Cela déclenche un rapport d'agrégation privé. Vous pouvez consulter le rapport à l'adresse chrome://private-aggregation-internals.
Si l'état de votre rapport est En attente, vous pouvez le sélectionner, puis cliquer sur Envoyer les rapports sélectionnés.
4.2. Collecter des rapports agrégables
Collectez vos rapports agrégables à partir des points de terminaison .well-known de votre API correspondante.
- Agrégation privée
[reporting-origin] /.well-known/private-aggregation/report-shared-storage - Attribution Reporting - Rapport récapitulatif
[reporting-origin] /.well-known/attribution-reporting/report-aggregate-attribution
Pour cet atelier de programmation, vous allez collecter des rapports manuellement. En production, les technologies publicitaires sont censées collecter et convertir les rapports de manière programmatique.
Dans chrome://private-aggregation-internals, copiez le corps du rapport reçu au point de terminaison [reporting-origin]/.well-known/private-aggregation/report-shared-storage.
Assurez-vous que dans Report Body (Corps du rapport), aggregation_coordinator_origin contient https://publickeyservice.msmt.aws.privacysandboxservices.com, ce qui signifie que le rapport est un rapport agrégable AWS.
Placez le corps du rapport JSON dans un fichier JSON Report Body. Dans cet exemple, vous pouvez utiliser Vim. Mais vous pouvez utiliser n’importe quel éditeur de texte.
vim report.json
Collez le rapport dans report.json et enregistrez votre fichier.
4.3. Convertir les rapports au format AVRO
Les rapports envoyés par les points de terminaison .well-known sont au format JSON et doivent être convertis au format AVRO. Une fois que vous disposez du rapport JSON, accédez au dossier de votre rapport et utilisez aggregatable_report_converter.jar pour créer le rapport de débogage agrégable. Cette opération crée un rapport agrégable appelé report.avro dans votre répertoire actuel.
java -jar aggregatable_report_converter.jar \
--request_type convertToAvro \
--input_file report.json
4.4. Créer le domaine AVRO de sortie
Pour créer le fichier output_domain.avro, vous avez besoin des clés de bucket pouvant être récupérées à partir des rapports.
Les clés de bucket sont conçues par la technologie publicitaire. Toutefois, dans le cas présent, la démonstration de la Privacy Sandbox sur le site les crée. Étant donné que l'agrégation privée pour ce site est en mode débogage, vous pouvez utiliser l'debug_cleartext_payload du corps du rapport pour obtenir la clé de bucket.
Copiez l'élément debug_cleartext_payload à partir du corps du rapport.
Ouvrez goo.gle/ags-payload-decoder et collez votre debug_cleartext_payload dans le champ INPUT, puis cliquez sur INPUT.
La page renvoie la valeur décimale de la clé du bucket. Voici un exemple de clé de bucket.
Maintenant que nous disposons de la clé de bucket, vous pouvez créer output_domain.avro. Veillez à remplacer
java -jar aggregatable_report_converter.jar \
--request_type createDomainAvro \
--bucket_key <bucket key>
Le script crée le fichier output_domain.avro dans votre dossier actuel.
4.5. Déplacer des rapports vers un bucket AWS
Une fois que les rapports AVRO (de la section 3.2.3) et le domaine de sortie (de la section 3.2.4) sont créés, déplacez les rapports et le domaine de sortie vers les buckets S3 de création de rapports.
Si la CLI AWS est configurée dans votre environnement local, exécutez les commandes suivantes pour copier les rapports dans le bucket et le dossier de rapports S3 correspondants.
aws s3 cp report.avro s3://<report_bucket_name>/<report_folder>/
aws s3 cp output_domain.avro s3://<report_bucket_name>/<output_domain_folder>/
5. Utilisation du service d'agrégation
À partir de terraform apply, les éléments create_job_endpoint, get_job_endpoint et frontend_api_id vous sont renvoyés. Copiez frontend_api_id et placez-le dans la variable globale postman frontend_api_id que vous avez configurée à la section 1.9 préalable.
Étape 5 : Utilisation du service d'agrégation: utilisez l'API Aggregation Service pour créer des rapports récapitulatifs et les examiner.
Étape 5.1 Utilisez le point de terminaison createJob pour effectuer un traitement par lot.
Étape 5.2. Utilisez le point de terminaison getJob pour récupérer l'état du lot.
Étape 5.3 Examen du rapport récapitulatif
5.1. Utiliser le point de terminaison createJob pour le traitement par lot
Dans Postman, ouvrez la collection Privacy Sandbox, puis sélectionnez createJob.
Sélectionnez Body (Corps), puis raw pour placer la charge utile de la requête.
Le schéma de charge utile createJob est disponible sur github. Il se présente comme suit. Remplacez <> par les champs appropriés.
{
"job_request_id": "<job_request_id>",
"input_data_blob_prefix": "<report_folder>/<report_name>.avro",
"input_data_bucket_name": "<input_bucket_name>",
"output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
"output_data_bucket_name": "<output_bucket_name>",
"job_parameters": {
"output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
"output_domain_bucket_name": "<output_domain_bucket_name>",
"attribution_report_to": "<reporting origin of report>",
"report_error_threshold_percentage": "10",
"debug_run": "true"
}
}
Une fois que vous avez cliqué sur Send (Envoyer), le job est créé avec l'job_request_id. Vous devriez recevoir une réponse HTTP 202 une fois la requête acceptée par le service d'agrégation. Un autre code de retour possible est disponible dans les codes de réponse HTTP
5.2. Utiliser le point de terminaison getJob pour récupérer l'état du lot
Pour vérifier l'état de la requête de tâche, vous pouvez utiliser le point de terminaison getJob. Sélectionnez getJob dans la collection Privacy Sandbox.
Dans Params (Paramètres), remplacez la valeur job_request_id par le job_request_id envoyé dans la requête createJob.
Le résultat de getJob doit renvoyer l'état de votre requête de tâche avec l'état HTTP 200. La requête "Body" contient les informations nécessaires telles que job_status, return_message et error_messages (si la tâche a généré une erreur).
Étant donné que le site de reporting du rapport de démonstration généré est différent de votre site intégré sur votre ID AWS, vous pouvez recevoir une réponse avec l'en-tête return_code PRIVACY_BUDGET_AUTHORIZATION_ERROR. Ce comportement est normal, car le site de l'origine des rapports dans les rapports ne correspond pas au site de création de rapports intégré pour l'ID AWS.
{
"job_status": "FINISHED",
"request_received_at": "2023-12-07T22:50:58.830956Z",
"request_updated_at": "2023-12-07T22:51:10.526326456Z",
"job_request_id": "<job_request_id>",
"input_data_blob_prefix": "<report_folder>/<report_name>.avro",
"input_data_bucket_name": "<input_bucket_name>",
"output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
"output_data_bucket_name": "<output_bucket_name>",
"postback_url": "",
"result_info": {
"return_code": "PRIVACY_BUDGET_AUTHORIZATION_ERROR",
"return_message": "Aggregation job successfully processed",
"error_summary": {
"error_counts": [],
"error_messages": []
},
"finished_at": "2023-12-07T22:51:10.517730898Z"
},
"job_parameters": {
"debug_run": "true",
"output_domain_bucket_name": "<output_domain_bucket_name>",
"output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
"attribution_report_to": "https://privacy-sandbox-demos-news.dev"
},
"request_processing_started_at": "2023-12-07T22:51:06.034472697Z"
}
5.3. Examen du rapport récapitulatif
Une fois que vous avez reçu le rapport de synthèse dans votre bucket S3 de sortie, vous pouvez le télécharger dans votre environnement local. Les rapports de synthèse sont au format AVRO et peuvent être reconvertis au format JSON. Vous pouvez utiliser aggregatable_report_converter.jar pour lire votre rapport à l'aide de la commande suivante.
java -jar aggregatable_report_converter.jar \
--request_type convertToJson \
--input_file <summary_report_avro>
Cette commande renvoie un fichier JSON des valeurs agrégées pour chaque clé de bucket, semblable à l'image suivante.
Si votre requête createJob inclut debug_run comme true, vous pouvez recevoir votre rapport récapitulatif dans le dossier de débogage situé dans output_data_blob_prefix. Le rapport est au format AVRO et peut être converti au format JSON à l'aide de la commande précédente.
Le rapport contient la clé de l'ensemble, la métrique sans bruit et le bruit ajouté à la métrique sans bruit pour former le rapport récapitulatif. Le rapport ressemble à l'image suivante.
Les annotations contiennent également in_reports et in_domain, ce qui signifie:
- in_reports : la clé de bucket est disponible dans les rapports agrégables.
- in_domain : la clé de bucket est disponible dans le fichier AVRO "output_domain".