1. Vorbereitung
Für dieses Codelab sind einige Voraussetzungen erforderlich. Jede Anforderung ist entsprechend gekennzeichnet, je nachdem, ob sie für „Lokale Tests“ oder den „Aggregationsdienst“ erforderlich ist.
1.1 Lokales Testtool herunterladen (Lokales Testen)
Für das lokale Testen ist der Download des Local Testing Tool erforderlich. Das Tool generiert Zusammenfassungsberichte aus den unverschlüsselten Fehlerbehebungsberichten.
Das Tool für lokale Tests kann im GitHub-Repository für Lambda-JAR-Archive heruntergeladen werden. Er sollte LocalTestingTool_{version}.jar heißen.
1.2. Prüfen, ob JAVA JRE installiert ist (lokaler Test und Aggregation Service)
Öffnen Sie das Terminal und prüfen Sie mit java --version, ob auf Ihrem Computer Java oder OpenJDK installiert ist.
Java-JRE-Version mit `java --version` prüfen.
Wenn es nicht installiert ist, können Sie es von der Java-Website oder der openJDK-Website herunterladen und installieren.
1.3. Aggregatable Report Converter herunterladen (lokale Tests und Aggregationsdienst)
Sie können eine Kopie des Konverters für aggregierbare Berichte aus dem GitHub-Repository für Privacy Sandbox-Demos herunterladen.
1.4 Datenschutz-APIs für Werbung aktivieren (lokale Tests und Aggregation Service)
Rufen Sie in Ihrem Browser chrome://settings/adPrivacy auf und aktivieren Sie alle APIs für den Datenschutz bei Werbung.
Prüfen Sie, ob Drittanbieter-Cookies aktiviert sind.
Rufen Sie in Ihrem Browser chrome://settings/cookies auf und wählen Sie Drittanbieter-Cookies im Inkognitomodus blockieren aus.
Chrome-Einstellung für Drittanbieter-Cookies.
1.5 Web- und Android-Registrierung (Aggregationsdienst)
Wenn Sie Privacy Sandbox-APIs in einer Produktionsumgebung verwenden möchten, müssen Sie die Registrierung und Attestierung sowohl für Chrome als auch für Android abgeschlossen haben.
Für lokale Tests kann die Registrierung mit einem Chrome-Flag und einem CLI-Schalter deaktiviert werden.
Wenn Sie das Chrome-Flag für unsere Demo verwenden möchten, rufen Sie chrome://flags/#privacy-sandbox-enrollment-overrides auf und aktualisieren Sie die Überschreibung mit Ihrer Website. Wenn Sie unsere Demowebsite verwenden, ist keine Aktualisierung erforderlich.
Chrome-Flag zum Überschreiben der Privacy Sandbox-Registrierung.
1.6 Einrichtung des Aggregationsdienstes (Aggregation Service)
Für die Verwendung des Aggregation Service ist ein Onboarding bei Koordinatoren erforderlich. Füllen Sie das Onboarding-Formular für den Aggregationsdienst aus. Geben Sie dazu die Adresse Ihrer Berichtswebsite, die AWS-Konto-ID und weitere Informationen an.
1.7. Cloud-Anbieter (Aggregationsdienst)
Für den Aggregation Service ist eine vertrauenswürdige Ausführungsumgebung erforderlich, die eine Cloud-Umgebung verwendet. Der Aggregationsdienst wird auf Amazon Web Services (AWS) und Google Cloud (GCP) unterstützt. In diesem Codelab wird nur die AWS-Integration behandelt.
AWS bietet eine vertrauenswürdige Ausführungsumgebung namens Nitro Enclaves. Prüfen Sie, ob Sie ein AWS-Konto haben, und folgen Sie der Installations- und Updateanleitung für die AWS-Befehlszeile, um Ihre AWS-Befehlszeilenumgebung einzurichten.
Wenn Ihre AWS-Befehlszeile neu ist, können Sie sie anhand der CLI-Konfigurationsanleitung konfigurieren.
1.7.1. AWS S3-Bucket erstellen
Erstellen Sie einen AWS S3-Bucket zum Speichern des Terraform-Zustands und einen weiteren S3-Bucket zum Speichern Ihrer Berichte und Zusammenfassungsberichte. Sie können den angegebenen CLI-Befehl verwenden. Ersetzen Sie das Feld in <> durch die entsprechenden Variablen.
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. Nutzerzugriffsschlüssel erstellen
Erstellen Sie Nutzerzugriffsschlüssel mithilfe der AWS-Anleitung. Damit werden die auf AWS erstellten API-Endpunkte createJob und getJob aufgerufen.
1.7.3. AWS-Nutzer- und ‑Gruppenberechtigungen
Wenn Sie den Aggregation Service auf AWS bereitstellen möchten, müssen Sie dem Nutzer, der für die Bereitstellung des Dienstes verwendet wird, bestimmte Berechtigungen erteilen. Prüfen Sie für dieses Codelab, ob der Nutzer Administratorzugriff hat, um sicherzugehen, dass er bei der Bereitstellung über alle Berechtigungen verfügt.
1.8. Terraform (Aggregationsdienst)
In diesem Codelab wird Terraform zum Bereitstellen des Aggregationsdienstes verwendet. Prüfen Sie, ob die Terraform-Binärdatei in Ihrer lokalen Umgebung installiert ist.
Laden Sie die Terraform-Binärdatei in Ihre lokale Umgebung herunter.
Nachdem die Terraform-Binärdatei heruntergeladen wurde, extrahieren Sie die Datei und verschieben Sie die Terraform-Binärdatei in /usr/local/bin.
cp <directory>/terraform /usr/local/bin
Prüfen Sie, ob Terraform im Klassenpfad verfügbar ist.
terraform -v
1.9. Postman (für Aggregation Service AWS)
In diesem Codelab verwenden Sie Postman für die Anfragenverwaltung.
Erstellen Sie einen Arbeitsbereich, indem Sie oben in der Navigationsleiste auf Arbeitsbereiche klicken und dann Arbeitsbereich erstellen auswählen.
Postman-Arbeitsbereich
Wählen Sie Leerer Arbeitsbereich aus, klicken Sie auf „Weiter“ und geben Sie den Namen Privacy Sandbox ein. Wählen Sie Privat aus und klicken Sie auf Erstellen.
Laden Sie die vorkonfigurierten Dateien JSON-Konfiguration und Globale Umgebung für den Arbeitsbereich herunter.
Importieren Sie die JSON-Dateien mit der Schaltfläche Importieren in Mein Arbeitsbereich.
Postman-JSON-Dateien importieren
Dadurch wird die Privacy Sandbox-Sammlung zusammen mit den HTTP-Anfragen createJob und getJob erstellt.
In Postman importierte Sammlung.
Aktualisieren Sie den AWS-Zugriffsschlüssel und den geheimen Schlüssel über Umgebungsübersicht.
Postman-Umgebung im Überblick.
Klicken Sie auf Bearbeiten und aktualisieren Sie den „Aktuellen Wert“ von access_key und secret_key. frontend_api_id wird in diesem Dokument im Abschnitt 3.1.4 beschrieben. Wir empfehlen, die Region „us-east-1“ zu verwenden. Wenn Sie jedoch in einer anderen Region bereitstellen möchten, müssen Sie das veröffentlichte AMI in Ihr Konto kopieren oder einen Self-Build mit den bereitgestellten Skripts durchführen.
Globale Postman-Variablen. 
Globale Variablen in Postman bearbeiten.
2. Codelab zum lokalen Testen
Mit dem Tool für lokale Tests auf Ihrem Computer können Sie die Aggregation durchführen und Zusammenfassungsberichte mit den unverschlüsselten Debug-Berichten erstellen.
Codelab-Schritte
Schritt 2.1: Trigger-Bericht: Löst die Berichterstellung für die private Aggregation aus, damit der Bericht abgerufen werden kann.
Schritt 2.2: Aggregierbaren Debug-Bericht erstellen: Konvertieren Sie den erfassten JSON-Bericht in einen AVRO-formatierten Bericht.
Dieser Schritt ähnelt dem Erfassen der Berichte von den API-Berichtsendpunkten durch Ad-Tech-Unternehmen und dem Konvertieren der JSON-Berichte in Berichte im AVRO-Format.
Schritt 2.3: Bucket-Schlüssel aus dem Debug-Bericht parsen: Bucket-Schlüssel werden von Ad-Tech-Unternehmen entwickelt. Da die Buckets in diesem Codelab vordefiniert sind, rufen Sie die Bucket-Schlüssel wie angegeben ab.
Schritt 2.4: AVRO für Ausgabedomäne erstellen: Nachdem die Bucket-Schlüssel abgerufen wurden, erstellen Sie die AVRO-Datei für die Ausgabedomäne.
Schritt 2.5: Zusammenfassungsberichte mit dem Local Testing Tool erstellen: Mit dem Local Testing Tool können Sie Zusammenfassungsberichte in der lokalen Umgebung erstellen.
Schritt 2.6: Zusammenfassungsbericht ansehen: Sehen Sie sich den Zusammenfassungsbericht an, der vom Local Testing Tool erstellt wird.
2.1. Trigger-Bericht
Rufen Sie die Privacy Sandbox-Demowebsite auf. Dadurch wird ein Bericht zur privaten Aggregation ausgelöst. Sie können den Bericht unter chrome://private-aggregation-internals aufrufen.
Interne Informationen zur privaten Aggregation in Chrome.
Wenn sich Ihr Bericht im Status Ausstehend befindet, können Sie ihn auswählen und auf Ausgewählte Berichte senden klicken.
Bericht zur privaten Aggregation senden.
2.2. Aggregierbaren Debug-Bericht erstellen
Kopieren Sie in chrome://private-aggregation-internals den Berichtstext, der am [reporting-origin]/.well-known/private-aggregation/report-shared-storage-Endpunkt empfangen wurde.
Prüfen Sie, ob im Berichtstext das aggregation_coordinator_origin das https://publickeyservice.msmt.aws.privacysandboxservices.com enthält. Das bedeutet, dass der Bericht ein aggregierbarer AWS-Bericht ist.
Bericht zur privaten Aggregation.
Fügen Sie den JSON-Berichtstext in eine JSON-Datei ein. In diesem Beispiel können Sie vim verwenden. Sie können aber auch einen beliebigen anderen Texteditor verwenden.
vim report.json
Fügen Sie den Bericht in report.json ein und speichern Sie die Datei.
JSON-Datei für den Bericht.
Rufen Sie dann Ihren Berichtsordner auf und verwenden Sie aggregatable_report_converter.jar, um den aggregierbaren Debug-Bericht zu erstellen. Dadurch wird im aktuellen Verzeichnis ein aggregierbarer Bericht mit dem Namen report.avro erstellt.
java -jar aggregatable_report_converter.jar \
--request_type convertToAvro \
--input_file report.json \
--debug
2.3. Bucket-Schlüssel aus dem Debug-Bericht parsen
Für den Aggregationsdienst sind beim Batching zwei Dateien erforderlich. Der aggregierbare Bericht und die Ausgabedatei für die Domain. Die Ausgabedatei für die Domain enthält die Schlüssel, die Sie aus den aggregierbaren Berichten abrufen möchten. Zum Erstellen der Datei output_domain.avro benötigen Sie die Bucket-Schlüssel, die aus den Berichten abgerufen werden können.
Bucket-Schlüssel werden vom Aufrufer der API entworfen. Die Demo enthält vorgefertigte Beispiel-Bucket-Schlüssel. Da in der Demo der Debug-Modus für die private Aggregation aktiviert ist, können Sie die Debug-Klartextnutzlast aus dem Berichtstext parsen, um den Bucket-Schlüssel abzurufen. In diesem Fall werden die Bucket-Schlüssel jedoch von der Website Privacy Sandbox-Demo erstellt. Da die private Aggregation für diese Website im Debug-Modus ist, können Sie den Bucket-Schlüssel mit debug_cleartext_payload aus dem Berichtstext abrufen.
Kopieren Sie die debug_cleartext_payload aus dem Berichtstext.
Debuggen der Klartext-Nutzlast aus dem Berichtstext.
Öffnen Sie das Tool Debug payload decoder for Private Aggregation, fügen Sie Ihre debug_cleartext_payloadin das Feld INPUT ein und klicken Sie auf Decode.
Nutzlast-Decoder.
Auf der Seite wird der Dezimalwert des Bucket-Schlüssels zurückgegeben. Im Folgenden sehen Sie ein Beispiel für einen Bucket-Schlüssel.
Ergebnis des Nutzlastdecoders.
2.4 AVRO-Ausgabedomain erstellen
Kopieren Sie nun den Dezimalwert des Bucket-Schlüssels. Erstellen Sie dann die output_domain.avro mit dem Bucket-Schlüssel. Achten Sie darauf, dass Sie
java -jar aggregatable_report_converter.jar \
--request_type createDomainAvro \
--bucket_key <bucket key>
Das Script erstellt die Datei output_domain.avro in Ihrem aktuellen Ordner.
2.5 Zusammenfassungsberichte mit dem Local Testing Tool erstellen
Wir verwenden LocalTestingTool_{version}.jar, das in Abschnitt 1.1 heruntergeladen wurde, um die Zusammenfassungsberichte zu erstellen. Verwenden Sie den folgenden Befehl. Ersetzen Sie LocalTestingTool_{version}.jar durch die Version, die für LocalTestingTool heruntergeladen wurde.
Führen Sie den folgenden Befehl aus, um einen Zusammenfassungsbericht in Ihrer lokalen Entwicklungsumgebung zu generieren:
java -jar LocalTestingTool_{version}.jar \
--input_data_avro_file report.avro \
--domain_avro_file output_domain.avro \
--output_directory .
Nachdem der Befehl ausgeführt wurde, sollte die Ausgabe in etwa so aussehen: Nach Abschluss des Vorgangs wird ein Bericht output.avro erstellt.
Avro-Datei mit dem zusammenfassenden Bericht zu lokalen Tests.
2.6. Zusammenfassenden Bericht ansehen
Der erstellte Zusammenfassungsbericht liegt im AVRO-Format vor. Dazu müssen Sie die Daten von AVRO in ein JSON-Format konvertieren. Im Idealfall sollte die Ad-Tech-Lösung so programmiert sein, dass AVRO-Berichte wieder in JSON konvertiert werden.
In diesem Codelab verwenden wir das bereitgestellte aggregatable_report_converter.jar-Tool, um den AVRO-Bericht wieder in JSON zu konvertieren.
java -jar aggregatable_report_converter.jar \
--request_type convertToJson \
--input_file output.avro
Daraufhin wird ein Bericht wie im folgenden Bild angezeigt. Zusammen mit einem Bericht output.json, der im selben Verzeichnis erstellt wurde.
Zusammenfassungs-Avro-Datei, die in JSON konvertiert wurde.
Öffnen Sie die JSON-Datei in einem Editor Ihrer Wahl, um den Zusammenfassungsbericht anzusehen.
3. Bereitstellung des Aggregationsdienstes
So stellen Sie den Aggregation Service bereit:
Schritt 3: Aggregation Service Deployment: Deploy Aggregation Service on AWS
Step 3.1. Repository des Aggregationsdienstes klonen
Schritt 3.2 Vorgefertigte Abhängigkeiten herunterladen
Schritt 3.3 Entwicklungsumgebung erstellen
Schritt 3.4 Aggregationsdienst bereitstellen
3.1. Repository des Aggregationsdienstes klonen
Klonen Sie in Ihrer lokalen Umgebung das GitHub-Repository für den Aggregationsdienst.
git clone https://github.com/privacysandbox/aggregation-service.git
3.2 Vorkonfigurierte Abhängigkeiten herunterladen
Nachdem Sie das Aggregation Service-Repository geklont haben, rufen Sie den Terraform-Ordner des Repositorys und den entsprechenden Cloud-Ordner auf. Wenn Ihr cloud_provider AWS ist, können Sie mit
cd <repository_root>/terraform/aws
Führen Sie in download_prebuilt_dependencies.sh aus.
bash download_prebuilt_dependencies.sh
3.3 Entwicklungsumgebung erstellen
Erstellen Sie eine Entwicklungsumgebung in dev.
mkdir dev
Kopieren Sie den Inhalt des Ordners demo in den Ordner dev.
cp -R demo/* dev
Verschieben Sie sie in den Ordner dev.
cd dev
Aktualisieren Sie die Datei main.tf und drücken Sie i für input, um die Datei zu bearbeiten.
vim main.tf
Entfernen Sie das Kommentarzeichen (#) aus dem rot umrandeten Code und aktualisieren Sie die Bucket- und Schlüsselnamen.
Für AWS-main.tf:
AWS-Haupt-TF-Datei.
Der Code, bei dem das Kommentarzeichen entfernt wurde, sollte so aussehen:
backend "s3" {
bucket = "<tf_state_bucket_name>"
key = "<environment_name>.tfstate"
region = "us-east-1"
}
Wenn die Aktualisierungen abgeschlossen sind, speichern Sie sie und beenden Sie den Editor, indem Sie esc -> :wq! drücken. Dadurch werden die Änderungen auf main.tf gespeichert.
Benennen Sie dann example.auto.tfvars in dev.auto.tfvars um.
mv example.auto.tfvars dev.auto.tfvars
Aktualisieren Sie dev.auto.tfvars und drücken Sie i für input, um die Datei zu bearbeiten.
vim dev.auto.tfvars
Aktualisieren Sie die Felder im roten Kästchen im folgenden Bild mit den richtigen AWS-ARN-Parametern, die während des Onboardings für den Aggregationsdienst, die Umgebung und die Benachrichtigungs-E-Mail angegeben werden.
Bearbeiten Sie die automatische TFVARS-Datei für die Entwicklung.
Wenn die Aktualisierungen abgeschlossen sind, drücke esc -> :wq!. Dadurch wird die Datei dev.auto.tfvars gespeichert. Sie sollte in etwa wie im folgenden Bild aussehen.
Aktualisierte TFVARS-Datei für die automatische Entwicklung.
3.4. Aggregationsdienst bereitstellen
Um den Aggregationsdienst bereitzustellen, initialisieren Sie Terraform im selben Ordner
terraform init
Die Ausgabe sollte in etwa so aussehen:
Terraform initialisieren.
Nachdem Terraform initialisiert wurde, erstellen Sie den Terraform-Ausführungsplan. Dabei wird die Anzahl der hinzuzufügenden Ressourcen und andere zusätzliche Informationen zurückgegeben, wie im folgenden Bild zu sehen ist.
terraform plan
Im Folgenden sehen Sie die Zusammenfassung des Abos. Wenn es sich um eine neue Bereitstellung handelt, sollten Sie die Anzahl der Ressourcen sehen, die hinzugefügt werden, mit 0 zu ändernden und 0 zu löschenden Ressourcen.
Terraform-Plan.
Danach können Sie Terraform anwenden.
terraform apply
Wenn Sie von Terraform aufgefordert werden, die Ausführung der Aktionen zu bestätigen, geben Sie yes ein.
Terraform-Aufforderung zum Anwenden.
Sobald terraform apply abgeschlossen ist, werden die folgenden Endpunkte für createJob und getJob zurückgegeben. Die frontend_api_id, die Sie in Postman in Abschnitt 1.9 aktualisieren müssen, wird ebenfalls zurückgegeben.
Terraform apply complete.
4. Eingabe für den Aggregationsdienst erstellen
Erstellen Sie nun die AVRO-Berichte für das Batching im Aggregationsdienst.
Schritt 4: Eingabe für den Aggregationsdienst erstellen: Erstellen Sie die Berichte für den Aggregationsdienst, die für den Aggregationsdienst gebatcht werden.
Schritt 4.1 Trigger-Bericht
Schritt 4.2 Zusammenfassbare Berichte erstellen
Schritt 4.3 Berichte in AVRO konvertieren
Schritt 4.4 AVRO-Ausgabedomain erstellen
4.1. Trigger-Bericht
Rufen Sie die Privacy Sandbox-Demowebsite auf. Dadurch wird ein Bericht zur privaten Aggregation ausgelöst. Sie können den Bericht unter chrome://private-aggregation-internals aufrufen.
Interne Informationen zur privaten Aggregation in Chrome.
Wenn sich Ihr Bericht im Status Ausstehend befindet, können Sie ihn auswählen und auf Ausgewählte Berichte senden klicken. '
Bericht zur privaten Aggregation senden.
4.2. Zusammenfassbare Berichte erfassen
Rufen Sie Ihre aggregierbaren Berichte über die .well-known-Endpunkte der entsprechenden API ab.
- Private Aggregation
[reporting-origin] /.well-known/private-aggregation/report-shared-storage - Attribution Reporting – Zusammenfassungsbericht
[reporting-origin] /.well-known/attribution-reporting/report-aggregate-attribution
In diesem Codelab führen Sie die Berichtserstellung manuell durch. In der Produktion wird von Anbietern von Anzeigentechnologien erwartet, dass sie die Berichte programmatisch erheben und konvertieren.
Kopieren Sie in chrome://private-aggregation-internals den Berichtstext, der am [reporting-origin]/.well-known/private-aggregation/report-shared-storage-Endpunkt empfangen wurde.
Prüfen Sie, ob im Berichtstext das aggregation_coordinator_origin das https://publickeyservice.msmt.aws.privacysandboxservices.com enthält. Das bedeutet, dass der Bericht ein aggregierbarer AWS-Bericht ist.
Bericht zur privaten Aggregation.
Fügen Sie den JSON-Berichtstext in eine JSON-Datei ein. In diesem Beispiel können Sie vim verwenden. Sie können aber auch einen beliebigen anderen Texteditor verwenden.
vim report.json
Fügen Sie den Bericht in report.json ein und speichern Sie die Datei.
JSON-Datei für den Bericht.
4.3. Berichte in AVRO konvertieren
Berichte, die von den .well-known-Endpunkten empfangen werden, liegen im JSON-Format vor und müssen in das AVRO-Berichtsformat konvertiert werden. Sobald Sie den JSON-Bericht haben, rufen Sie den Berichtsordner auf und verwenden Sie aggregatable_report_converter.jar, um den aggregierbaren Debug-Bericht zu erstellen. Dadurch wird im aktuellen Verzeichnis ein aggregierbarer Bericht mit dem Namen report.avro erstellt.
java -jar aggregatable_report_converter.jar \
--request_type convertToAvro \
--input_file report.json
4.4. AVRO-Ausgabedomain erstellen
Zum Erstellen der Datei output_domain.avro benötigen Sie die Bucket-Schlüssel, die aus den Berichten abgerufen werden können.
Bucket-Schlüssel werden vom Anbieter von Anzeigentechnologien erstellt. In diesem Fall werden sie jedoch von der Privacy Sandbox-Demowebsite erstellt. Da die private Aggregation für diese Website im Debug-Modus ist, können Sie den Bucket-Schlüssel mit debug_cleartext_payload aus dem Berichtstext abrufen.
Kopieren Sie die debug_cleartext_payload aus dem Berichtstext.
Debuggen der Klartext-Nutzlast aus dem Berichtstext.
Öffnen Sie goo.gle/ags-payload-decoder, fügen Sie Ihr debug_cleartext_payloadin das Feld INPUT ein und klicken Sie auf Decode.
Nutzlast-Decoder.
Auf der Seite wird der Dezimalwert des Bucket-Schlüssels zurückgegeben. Im Folgenden sehen Sie ein Beispiel für einen Bucket-Schlüssel.
Ergebnis des Nutzlastdecoders.
Nachdem Sie den Bucket-Schlüssel haben, können Sie output_domain.avro erstellen. Achten Sie darauf, dass Sie
java -jar aggregatable_report_converter.jar \
--request_type createDomainAvro \
--bucket_key <bucket key>
Das Script erstellt die Datei output_domain.avro in Ihrem aktuellen Ordner.
4.5. Berichte in einen AWS-Bucket verschieben
Nachdem die AVRO-Berichte (aus Abschnitt 3.2.3) und die Ausgabedomain (aus Abschnitt 3.2.4) erstellt wurden, verschieben Sie die Berichte und die Ausgabedomain in die S3-Buckets für Berichte.
Wenn Sie die AWS CLI in Ihrer lokalen Umgebung eingerichtet haben, verwenden Sie die folgenden Befehle, um die Berichte in den entsprechenden S3-Bucket und Berichtsordner zu kopieren.
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. Nutzung des Aggregationsdienstes
Aus der terraform apply werden die create_job_endpoint, get_job_endpoint und die frontend_api_id zurückgegeben. Kopieren Sie frontend_api_id und fügen Sie es in die globale Postman-Variable frontend_api_id ein, die Sie im Abschnitt 1.9 der Voraussetzungen eingerichtet haben.
Schritt 5: Aggregationsdienst verwenden: Verwenden Sie die Aggregation Service API, um Zusammenfassungsberichte zu erstellen und zu prüfen.
Schritt 5.1 createJob-Endpunkt zum Batch-
verwendenSchritt 5.2 Batchstatus mit dem getJob-Endpunkt abrufen
Schritt 5.3 Zusammenfassenden Bericht ansehen
5.1. createJob-Endpunkt für Batch verwenden
Öffnen Sie in Postman die Sammlung Privacy Sandbox und wählen Sie createJob aus.
Wählen Sie Body und dann raw aus, um die Nutzlast Ihrer Anfrage einzufügen.
Postman-Anfragetext für „createJob“
Das Nutzlastschema für createJob ist auf github verfügbar und sieht in etwa so aus: Ersetzen Sie <> durch die entsprechenden Felder.
{
"job_request_id": "<job_request_id>",
"input_data_blob_prefix": "<report_folder>/<report_name>.avro",
"input_data_blob_prefixes": [
"<report_folder>/<report_name-1>/",
"<report_folder>/<report_name-2>/",
"<report_folder>/<report_name>.avro"
], // Mutually exclusive to input_data_blob_prefix as of v2.11.0
"input_data_bucket_name": "<bucket_name>",
"output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
"output_data_bucket_name": "<bucket_name>",
"job_parameters": {
"output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
"output_domain_bucket_name": "<bucket_name>",
"attribution_report_to": "<reporting origin of report>",
"reporting_site": "<domain of reporting origin(s) of report>", // Mutually exclusive to attribution_report_to as of v2.7.0
"report_error_threshold_percentage": "10",
"debug_run": "true"
}
}
Wenn Sie auf Senden klicken, wird der Job mit der job_request_id erstellt. Sie sollten eine HTTP 202-Antwort erhalten, sobald die Anfrage vom Aggregationsdienst akzeptiert wurde. Andere mögliche Rückgabecodes finden Sie unter HTTP-Antwortcodes.
Status der Postman-Anfrage „createJob“
5.2. Batchstatus mit dem Endpunkt „getJob“ abrufen
Mit dem Endpunkt getJob können Sie den Status der Jobanfrage prüfen. Wählen Sie in der Sammlung Privacy Sandbox die Option getJob aus.
Aktualisieren Sie unter Params den Wert von „job_request_id“ auf job_request_id, der in der createJob-Anfrage gesendet wurde.
Postman-Anfrage für „getJob“
Das Ergebnis von getJob sollte den Status Ihrer Jobanfrage mit dem HTTP-Statuscode 200 zurückgeben. Die Anfrage Body enthält die erforderlichen Informationen wie job_status, return_message und error_messages (falls beim Job ein Fehler aufgetreten ist).
Postman-Anfragestatus für „getJob“
Da sich die Berichtswebsite des generierten Demoberichts von der Website unterscheidet, die Sie mit Ihrer AWS-ID eingerichtet haben, erhalten Sie möglicherweise eine Antwort mit dem PRIVACY_BUDGET_AUTHORIZATION_ERROR-Rückgabecode. Das ist normal, da die Website des Berichterstellungsursprungs der Berichte nicht mit der Website übereinstimmt, die für die AWS-ID registriert wurde.
{
"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_blob_prefixes": [ // Mutually exclusive to input_data_blob_prefix as of v2.11.0
"<report_folder>/<report_name-1>/",
"<report_folder>/<report_name-2>/",
"<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",
"reporting_site": "<domain of reporting origin(s) of report>", // Mutually exclusive to attribution_report_to as of v2.7.0
},
"request_processing_started_at": "2023-12-07T22:51:06.034472697Z"
}
5.3. Zusammenfassenden Bericht ansehen
Sobald Sie den Zusammenfassungsbericht in Ihrem Ausgabe-S3-Bucket erhalten haben, können Sie ihn in Ihre lokale Umgebung herunterladen. Zusammenfassungsberichte sind im AVRO-Format und können wieder in ein JSON-Format konvertiert werden. Mit dem folgenden Befehl können Sie Ihren Bericht mit aggregatable_report_converter.jar lesen.
java -jar aggregatable_report_converter.jar \
--request_type convertToJson \
--input_file <summary_report_avro>
Dadurch wird ein JSON-Objekt mit aggregierten Werten für jeden Bucket-Schlüssel zurückgegeben, das dem folgenden Bild ähnelt.
Zusammenfassungsbericht
Wenn Ihr createJob-Antrag debug_run als true enthält, können Sie den Zusammenfassungsbericht im Debug-Ordner in output_data_blob_prefix abrufen. Der Bericht liegt im AVRO-Format vor und kann mit dem vorherigen Befehl in eine JSON-Datei konvertiert werden.
Der Bericht enthält den Bucket-Schlüssel, den Messwert ohne Rauschen und das Rauschen, das dem Messwert ohne Rauschen hinzugefügt wird, um den Zusammenfassungsbericht zu erstellen. Der Bericht sieht etwa so aus:
Zusammenfassender Bericht zur Fehlerbehebung.
Die Anmerkungen enthalten auch in_reports und in_domain, was Folgendes bedeutet:
- in_reports: Der Bucket-Schlüssel ist in den aggregierbaren Berichten verfügbar.
- in_domain: Der Bucket-Schlüssel ist in der AVRO-Datei „output_domain“ verfügbar.