1. Conditions préalables
Pour suivre cet atelier de programmation, vous devez remplir quelques prérequis. Chaque exigence est indiquée en conséquence, qu'elle soit requise pour le "Test en local" ou le "Service d'agrégation".
1.1. Télécharger l'outil de test en local (test en local)
Pour effectuer des tests en local, vous devrez télécharger l'outil de test en local. L'outil génère des rapports récapitulatifs à partir des rapports de débogage non chiffrés.
Vous pouvez télécharger l'outil de test en local depuis les archives JAR Lambda dans GitHub. Il doit être nommé LocalTestingTool_{version}.jar.
1.2. Assurez-vous que JAVA JRE est installé (service de tests et d'agrégation en local)
Ouvrez le terminal et utilisez java --version pour vérifier si Java ou openJDK est installé sur votre ordinateur.
Si ce n'est pas le cas, 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 rapport Aggregatable (Local Testing and Aggregation Service)
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 Ad Privacy (service de tests et d'agrégation en local)
Dans votre navigateur, accédez à chrome://settings/adPrivacy et activez toutes les API Ad Privacy.
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 terminé l'enregistrement et l'attestation pour Chrome et Android.
Pour les tests en local, vous pouvez désactiver l'enregistrement à 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 modifiez le forçage en fonction de 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 qu'ils puissent l'utiliser. Remplissez le formulaire d'intégration du service d'agrégation en fournissant l'adresse du site de reporting, l'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é qui utilise 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 à 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 votre 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 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 d'API createJob et getJob créés sur AWS.
1.7.3. Autorisations des utilisateurs et des groupes AWS
Pour déployer le service d'agrégation sur AWS, vous devez fournir certaines autorisations à l'utilisateur utilisé pour le déploiement. Pour cet atelier de programmation, assurez-vous que l'utilisateur dispose d'un accès administrateur pour 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 fichier binaire Terraform est installé dans votre environnement local.
Téléchargez le fichier 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
Assurez-vous que Terraform est disponible sur "classpath".
terraform -v
1,9. Postman (pour le service d'agrégation AWS)
Dans 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 "Suivant" et nommez-le Privacy Sandbox. Sélectionnez Personal (Personnel), puis cliquez sur Create (Créer).
Téléchargez les fichiers préconfigurés de configuration JSON et d'environnement global de l'espace de travail.
Importez les fichiers JSON dans My Workspace à l'aide du bouton Import (Importer).
La collection Privacy Sandbox sera créée 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 l'aperçu rapide 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-east1. 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 auto-compilation à l'aide des scripts fournis.
2. Atelier de programmation pour les tests en local
Vous pouvez utiliser l'outil de test en local de votre ordinateur pour effectuer des agrégations et générer des rapports récapitulatifs à l'aide des rapports de débogage non chiffrés.
Étapes de l'atelier de programmation
Étape 2.1. Générer un rapport: permet de déclencher la création de rapports Private Aggregation afin de 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 l'API et convertissent les rapports JSON en rapports au format AVRO.
Étape 2.3 : Analysez 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, étant donné que les buckets sont prédéfinis, récupérez les clés de bucket telles qu'elles vous ont été fournies.
Étape 2.4 : Créez l'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éer des rapports récapitulatifs à l'aide de l'outil de test local: utilisez cet outil pour générer des rapports de synthèse dans l'environnement local.
Étape 2.6 : Consulter le rapport récapitulatif: consultez le rapport récapitulatif créé par l'outil de test en local.
2.1. Rapport sur les déclencheurs
Accédez au site de démonstration de la Privacy Sandbox. Un rapport d'agrégation privé est alors généré. Vous pouvez consulter le rapport à l'adresse chrome://private-aggregation-internals.
Si votre rapport affiche l'état 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 dans le 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 qu'il s'agit d'un rapport agrégable AWS.
Placez le corps du rapport JSON dans un fichier JSON. 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 à votre dossier de rapports et utilisez aggregatable_report_converter.jar pour créer le rapport de débogage agrégable. Un rapport agrégable appelé report.avro est alors créé dans votre répertoire actuel.
java -jar aggregatable_report_converter.jar \
--request_type convertToAvro \
--input_file report.json \
--debug
2.3. Analyser la clé du 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 sortie des domaines 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 extraites des rapports.
Les clés de bucket sont conçues par l'appelant de l'API, et la ressource demo contient des exemples de clés de bucket préconstruites. Étant donné que 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 corps du rapport pour récupérer la clé du bucket. Toutefois, dans ce cas, la démonstration de la Privacy Sandbox crée les clés de bucket. L'agrégation privée de ce site étant en mode débogage, vous pouvez utiliser l'debug_cleartext_payload du corps du rapport pour obtenir la clé du bucket.
Copiez debug_cleartext_payload à partir du corps du rapport.
Ouvrez l'outil de débogage de la charge utile pour l'agrégation privée et collez votre debug_cleartext_payload dans la zone INPUT, puis cliquez sur INPUT.
La page renvoie la valeur décimale de la clé du bucket. Voici un exemple de clé de bucket.
2.4. Créer l'AVRO du domaine de sortie
Maintenant que nous avons la clé de bucket, copiez la valeur décimale de la clé de bucket. Créez le output_domain.avro à l'aide de la clé du 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 récapitulatifs à l'aide de l'outil de test en local
Nous allons utiliser LocalTestingTool_{version}.jar, qui a été téléchargé à la section 1.1, pour créer les rapports récapitulatifs. Exécutez la commande suivante : Vous devez remplacer LocalTestingTool_{version}.jar par la version téléchargée pour 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, un message semblable à l'image suivante doit s'afficher. Un rapport output.avro est créé une fois l'opération terminée.
2.6. Examiner le rapport récapitulatif
Le rapport récapitulatif créé est au format AVRO. Pour qu'il soit lisible, vous devez convertir le fichier AVRO au format JSON. Idéalement, la technologie publicitaire doit coder pour reconvertir les rapports AVRO au format JSON.
Pour notre atelier de programmation, nous utiliserons 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 s'affiche. En plus du rapport output.json créé dans le même répertoire
Ouvrez le fichier JSON dans l'é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 que vous avez cloné le dépôt du service d'agrégation, accédez au dossier Terraform du dépôt et au dossier cloud correspondant. Si cloud_provider est AWS, vous pouvez passer à la section
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-les dans votre dossier dev.
cd dev
Mettez à jour votre fichier main.tf et appuyez sur i pour input afin de le modifier.
vim main.tf
Annulez la mise en commentaire du code dans le cadre rouge en supprimant le signe #, puis en mettant à jour les noms du bucket et de la 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 sont enregistrées sur main.tf.
Renommez ensuite example.auto.tfvars en 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'encadré rouge qui suit l'image avec les paramètres ARN AWS 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 doit ressembler à l'image suivante.
3.4. Déployer le service d'agrégation
Pour déployer le service d'agrégation, dans le même dossier
terraform init
Vous devriez obtenir un résultat semblable à celui-ci:
Une fois Terraform initialisé, créez le plan d'exécution Terraform. Elle renvoie le nombre de ressources à ajouter et d'autres informations supplémentaires semblables à l'image ci-dessous.
terraform plan
Vous pouvez consulter le récapitulatif "Plan" ci-dessous. S'il s'agit d'un nouveau déploiement, vous devriez voir le nombre de ressources qui seront ajoutées : 0 pour modifier et 0 pour détruire.
Une fois ces opérations effectuées, vous pouvez appliquer Terraform.
terraform apply
Lorsque vous êtes invité à confirmer l'exécution des actions par Terraform, saisissez un 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 d'une entrée pour le service d'agrégation
Créez ensuite 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 sur les déclencheurs
Étape 4.2 : Collectez des rapports agrégables
Étape 4.3 : Convertissez les rapports au format AVRO
Étape 4.4. Créer l'AVRO du domaine de sortie
4.1. Rapport sur les déclencheurs
Accédez au site de démonstration de la Privacy Sandbox. Un rapport d'agrégation privé est alors généré. Vous pouvez consulter le rapport à l'adresse chrome://private-aggregation-internals.
Si votre rapport affiche l'état 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 l'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
Dans cet atelier de programmation, vous allez collecter des rapports manuellement. En production, les technologies publicitaires doivent collecter et convertir les rapports de manière programmatique.
Dans chrome://private-aggregation-internals, copiez le corps du rapport reçu dans le 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 qu'il s'agit d'un rapport agrégable AWS.
Placez le corps du rapport JSON dans un fichier JSON. 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 des rapports au format AVRO
Les rapports provenant des points de terminaison .well-known sont au format JSON et doivent être convertis au format de rapport AVRO. Une fois que vous disposez du rapport JSON, accédez à votre dossier de rapports et utilisez aggregatable_report_converter.jar pour créer le rapport de débogage agrégable. Un rapport agrégable appelé report.avro est alors créé dans votre répertoire actuel.
java -jar aggregatable_report_converter.jar \
--request_type convertToAvro \
--input_file report.json
4.4. Créer l'AVRO du domaine de sortie
Pour créer le fichier output_domain.avro, vous avez besoin des clés de bucket pouvant être extraites des rapports.
Les clés de bucket sont conçues par la technologie publicitaire. Toutefois, dans le cas présent, les clés de bucket sont créées sur le site Démonstration de la Privacy Sandbox. L'agrégation privée de ce site étant en mode débogage, vous pouvez utiliser l'debug_cleartext_payload du corps du rapport pour obtenir la clé du bucket.
Copiez debug_cleartext_payload à partir du corps du rapport.
Ouvrez goo.gle/ags-payload-decoder, 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é du bucket, créez le 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 les rapports AVRO (section 3.2.3) et le domaine de sortie (section 3.2.4) créés, transférez ces rapports et le domaine de sortie vers les buckets de création de rapports S3.
Si la CLI AWS est configurée dans votre environnement local, utilisez les commandes suivantes pour copier les rapports dans le bucket S3 et le dossier de rapports 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
terraform apply vous renvoie create_job_endpoint, get_job_endpoint et frontend_api_id. Copiez frontend_api_id et placez-le dans la variable globale Postman frontend_api_id que vous avez configurée dans la section 1.9 de la condition 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. Utilisation du point de terminaison createJob pour effectuer des lots
Étape 5.2 : Utilisez le point de terminaison getJob pour récupérer l'état du lot
Étape 5.3. Examiner le rapport récapitulatif
5.1. Utiliser le point de terminaison createJob pour effectuer des lots
Dans Postman, ouvrez la collection Privacy Sandbox et sélectionnez createJob.
Sélectionnez Body (Corps), puis raw pour placer la charge utile de votre requête.
Le schéma de charge utile createJob est disponible dans 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), la tâche est créée avec le job_request_id. Vous devriez recevoir une réponse HTTP 202 une fois la requête acceptée par le service d'agrégation. Vous trouverez d'autres codes de retour possibles dans Codes de réponse HTTP
5.2. Utiliser le point de terminaison getJob pour récupérer l'état d'un 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 la valeur job_request_id envoyée dans la requête createJob.
Le résultat de getJob doit renvoyer l'état de votre requête de tâche avec un état HTTP de 200. La requête "Body" contient les informations nécessaires telles que job_status, return_message et error_messages (si la tâche comporte une erreur).
Étant donné que le site de création de rapports du rapport de démonstration généré est différent du site intégré sur votre ID AWS, vous pouvez recevoir une réponse avec un return_code PRIVACY_BUDGET_AUTHORIZATION_ERROR. Cela est normal, car le site de l'origine de création des rapports des rapports ne correspond pas au site de création de rapports intégré à 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-dsp.dev"
},
"request_processing_started_at": "2023-12-07T22:51:06.034472697Z"
}
5.3. Examiner le rapport récapitulatif
Une fois que vous avez reçu votre rapport de synthèse dans votre bucket S3 de sortie, vous pouvez le télécharger dans votre environnement local. Les rapports récapitulatifs 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 de valeurs agrégées pour chaque clé de bucket, semblable à l'image suivante.
Si votre requête createJob inclut debug_run en tant que 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é du bucket, la métrique sans bruit et le bruit ajouté à la métrique sans bruit pour former le rapport récapitulatif. Le rapport est semblable à l'image suivante.
Les annotations contiennent également in_reports et in_domain, ce qui signifie que:
- in_reports - La clé du bucket est disponible dans les rapports agrégables.
- in_domain : la clé du bucket est disponible dans le fichier AVRO "output_domain".