Mit dem Aggregationsdienst auf der Google Cloud Platform (GCP) arbeiten

1. 1. Voraussetzungen

Geschätzte Dauer: ein bis zwei Stunden

Es gibt zwei Modi, dieses Codelab auszuführen: Lokaler Test oder Aggregationsdienst. Für den lokalen Testmodus sind ein lokaler Computer und ein Chrome-Browser erforderlich. Es dürfen keine Google Cloud-Ressourcen erstellt oder verwendet werden. Der Modus „Aggregationsdienst“ erfordert eine vollständige Bereitstellung des Aggregationsdienstes in Google Cloud.

Damit Sie dieses Codelab in beiden Modi ausführen können, müssen einige Voraussetzungen erfüllt sein. Jede Anforderung wird entsprechend gekennzeichnet, unabhängig davon, ob sie für lokale Tests oder den Aggregationsdienst erforderlich ist.

1.1. Vollständige Registrierung und Bestätigung (Aggregationsdienst)

Wenn Sie Privacy Sandbox APIs verwenden möchten, müssen Sie sowohl für Chrome als auch für Android die Registrierung und Bestätigung abgeschlossen haben.

1.2. Privacy Sandbox APIs (lokaler Test- und Aggregationsdienst) aktivieren

Da wir die Privacy Sandbox verwenden werden, empfehlen wir Ihnen, die Privacy Sandbox Ads APIs zu aktivieren.

Rufen Sie in Ihrem Browser chrome://flags/#privacy-sandbox-ads-apis auf und aktivieren Sie die Privacy Sandbox APIs.

Achten Sie außerdem darauf, dass Cookies von Drittanbietern aktiviert sind.

Rufen Sie in Ihrem Browser chrome://settings/cookies auf. Achte darauf, dass Drittanbieter-Cookies NICHT blockiert werden. Je nach Chrome-Version werden in diesem Einstellungsmenü möglicherweise unterschiedliche Optionen angezeigt. Zulässige Konfigurationen sind jedoch:

• „Alle Drittanbieter-Cookies blockieren“ = DEAKTIVIERT
• „Drittanbieter-Cookies blockieren“ = DEAKTIVIERT
• „Cookies von Drittanbietern im Inkognitomodus blockieren“ = AKTIVIERT

Starten Sie Chrome neu, damit die Änderungen wirksam werden.

1.3. Lokales Testtool herunterladen (lokaler Test)

Für lokale Tests muss das lokale Testtool heruntergeladen werden. Das Tool erstellt zusammenfassende Berichte aus den unverschlüsselten Debug-Berichten.

Das lokale Testtool kann in den JAR-Archiven für Cloud Functions-Funktionen in GitHub heruntergeladen werden. Sie sollte den Namen LocalTestingTool_{version}.jar haben.

1.4 Achten Sie darauf, dass JAVA JRE installiert ist (lokaler Test- und Aggregationsdienst)

Öffnen Sie das Terminal und prüfen Sie mit java --version, ob auf Ihrem Computer Java oder openJDK installiert ist.

Wenn es nicht installiert ist, können Sie es von der Java-Website oder der openJDK-Website herunterladen und installieren.

1.5 aggregatable_report_converter (lokaler Test- und Aggregationsdienst) herunterladen

Sie können eine Kopie von „aggregatable_report_converter“ aus dem GitHub-Repository zu Privacy Sandbox-Demos herunterladen.

1.6 GCP-Umgebung (Aggregationsdienst) einrichten

Für den Aggregationsdienst ist eine vertrauenswürdige Ausführungsumgebung erforderlich, die einen Cloud-Anbieter verwendet. In diesem Codelab wird der Aggregationsdienst in der GCP bereitgestellt. AWS wird aber auch unterstützt.

1.6.1. Bereitstellung

Folgen Sie der Bereitstellungsanleitung in GitHub, um die gcloud CLI einzurichten, Terraform-Binärdateien und -Module herunterzuladen und GCP-Ressourcen für den Aggregationsdienst zu erstellen.

Wichtiger Hinweis: Sie benötigen bestimmte Berechtigungen, um den Dienst bereitzustellen. Für dieses Codelab muss der Nutzer die Berechtigung „Administratorzugriff“ oder „Inhaber“ für das GCP-Projekt haben.

Wichtige Schritte in der Bereitstellungsanleitung:

1. Richten Sie die „gcloud“-Befehlszeile und Terraform in Ihrer Umgebung ein.
2. Erstellen Sie einen Cloud Storage-Bucket zum Speichern des Terraform-Zustands.
3. Laden Sie Abhängigkeiten herunter.
4. Aktualisieren Sie adtech_setup.auto.tfvars und führen Sie das Terraform-Paket adtech_setup aus. Im Anhang finden Sie eine Beispieldatei für adtech_setup.auto.tfvars.
5. Aktualisieren Sie dev.auto.tfvars, übernehmen Sie die Identität des Bereitstellungsdienstkontos und führen Sie das Terraform-dev aus. Im Anhang finden Sie eine Beispieldatei für dev.auto.tfvars.
6. Sobald die Bereitstellung abgeschlossen ist, erfassen Sie die frontend_service_cloudfunction_url aus der Terraform-Ausgabe, die erforderlich ist, um in späteren Schritten Anfragen an den Aggregationsdienst zu senden.

1.6.2. Bucket für Berichte

Sobald das Projekt eingerichtet ist, erstellen Sie einen Bucket in Cloud Storage, um Ihre aggregierten Berichte und Zusammenfassungsberichte aus diesem Codelab zu speichern. Dies ist ein gcloud-Beispielbefehl zum Erstellen eines Buckets. Ersetzen Sie die Platzhalter durch einen Namen und Ort Ihrer Wahl.

gcloud storage buckets create gs://<bucket-name> --location=<location>

1.7 Onboarding des Aggregationsdienstes abschließen (Aggregationsdienst)

Für den Aggregationsdienst ist ein Onboarding für Koordinatoren erforderlich, um den Dienst nutzen zu können. Füllen Sie das Onboarding-Formular für Aggregationsdienst aus. Geben Sie dazu Ihre Berichtswebsite und andere Informationen an, wählen Sie „Google Cloud“ aus und geben Sie die Adresse Ihres Dienstkontos ein. Dieses Dienstkonto wird in der vorherigen Voraussetzung (1.6. GCP-Umgebung einrichten). Hinweis: Wenn Sie die bereitgestellten Standardnamen verwenden, beginnt dieses Dienstkonto mit „worker-sa@“.

Es kann bis zu zwei Wochen dauern, bis das Onboarding abgeschlossen ist.

1.8 Methode zum Aufrufen der API-Endpunkte (Aggregationsdienst) festlegen

Dieses Codelab bietet zwei Optionen zum Aufrufen der Aggregation Service API-Endpunkte: cURL und Postman. Mit cURL lassen sich die API-Endpunkte über Ihr Terminal schneller und einfacher aufrufen, da nur minimale Einrichtung und keine zusätzliche Software erforderlich sind. Wenn Sie cURL nicht verwenden möchten, können Sie stattdessen Postman verwenden, um API-Anfragen für die zukünftige Verwendung auszuführen und zu speichern.

In Abschnitt 3.2. Aggregationsdienstnutzung finden Sie eine detaillierte Anleitung für beide Optionen. Sie können sich jetzt eine Vorschau ansehen, um zu entscheiden, welche Methode Sie verwenden sollten. Wenn Sie Postman auswählen, führen Sie die folgende Ersteinrichtung durch.

1.8.1. Arbeitsbereich einrichten

Sie müssen sich für ein Postman-Konto registrieren. Nach der Registrierung wird automatisch ein Arbeitsbereich für Sie erstellt.

Wenn kein Arbeitsbereich für Sie erstellt wurde, wählen Sie im oberen Navigationselement „Arbeitsbereiche“ die Option „Arbeitsbereich erstellen“ aus.

Wählen Sie „Leerer Arbeitsbereich“ aus, klicken Sie auf „Weiter“ und nennen Sie ihn „GCP Privacy Sandbox“. Wählen Sie "Persönlich" aus und klicken Sie auf "Erstellen".

Laden Sie die vorkonfigurierte JSON-Konfiguration und die Dateien für die globale Umgebung des Arbeitsbereichs herunter.

Importieren Sie beide JSON-Dateien über die Schaltfläche „Importieren“ in „Mein Arbeitsbereich“.

Dadurch wird die Sammlung „GCP Privacy Sandbox“ zusammen mit den HTTP-Anfragen createJob und getJob erstellt.

1.8.2. Autorisierung einrichten

Klicken Sie auf die Sammlung „GCP Privacy Sandbox“ und gehen Sie zum Tab „Autorisierung“.

Sie verwenden die Methode "Bearer Token" (Inhabertoken). Führen Sie in Ihrer Terminal-Umgebung diesen Befehl aus und kopieren Sie die Ausgabe.

gcloud auth print-identity-token

Fügen Sie dann diesen Tokenwert in das Feld "Token" des Postman-Autorisierungs-Tabs ein:

1.8.3. Umgebung einrichten

Gehen Sie oben rechts zur „Kurzübersicht ‚Umgebung‘“:

Klicken Sie auf „Bearbeiten“ und aktualisieren Sie den aktuellen Wert von „Umgebung“, „Region“ und „Cloud-Funktions-ID“:

Sie können das Feld „request-id“ vorerst leer lassen, da wir dies später ergänzen werden. Verwenden Sie für die anderen Felder die Werte aus frontend_service_cloudfunction_url, die nach Abschluss der Terraform-Bereitstellung in Voraussetzung 1.6 zurückgegeben wurden. Die URL hat folgendes Format: https://--frontend-service--uc.a.run.app

2. 2. Codelab für lokale Tests

Geschätzte Dauer: weniger als 1 Stunde

Sie können das lokale Testtool auf Ihrem Computer verwenden, um mithilfe der unverschlüsselten Fehlerbehebungsberichte Aggregationen durchzuführen und zusammenfassende Berichte zu generieren. Bevor du beginnst, stelle sicher, dass du alle mit „Lokale Tests“ gekennzeichneten Voraussetzungen erfüllt hast.

Codelab-Schritte

Schritt 2.1: Triggerbericht: Lösen Sie Berichte zur privaten Aggregation aus, damit der Bericht erfasst werden kann.

Schritt 2.2: AVRO-Fehlerbehebungsbericht erstellen: Konvertieren Sie den erfassten JSON-Bericht in einen AVRO-formatierten Bericht. Dieser Schritt ähnelt dem, wenn adTechs die Berichte von den API-Endpunkten für die Berichterstellung erfassen und die JSON-Berichte in Berichte im AVRO-Format umwandeln.

Schritt 2.3: Bucket-Schlüssel abrufen: Bucket-Schlüssel werden von adTechs entwickelt. Da die Buckets in diesem Codelab vordefiniert sind, sollten Sie die Bucket-Schlüssel wie angegeben abrufen.

Schritt 2.4: AVRO der Ausgabedomain erstellen: Sobald die Bucket-Schlüssel abgerufen sind, erstellen Sie die AVRO-Datei der Ausgabedomain.

Schritt 2.5: Zusammenfassungsbericht erstellen: Mit dem lokalen Testtool können Sie Zusammenfassungsberichte in der lokalen Umgebung erstellen.

Schritt 2.6: Zusammenfassungsberichte überprüfen: Überprüfen Sie den Zusammenfassungsbericht, der vom lokalen Testtool erstellt wird.

2.1. Triggerbericht

Wenn Sie einen privaten Aggregationsbericht auslösen möchten, können Sie die Privacy Sandbox-Demowebsite (https://privacy-sandbox-demos-news.dev/?env=gcp) oder Ihre eigene Website (z.B. https://adtechexample.com) verwenden. Wenn Sie Ihre eigene Website verwenden und die Registrierung und Bestätigung und das Onboarding des Aggregationsdienstes noch nicht abgeschlossen haben, müssen Sie ein Chrome-Flag und einen CLI-Switch verwenden.

Für diese Demo verwenden wir die Privacy Sandbox-Demowebsite. Klicken Sie auf den Link, um die Website aufzurufen. Anschließend können Sie die Berichte unter chrome://private-aggregation-internals aufrufen:

Der an den {reporting-origin}/.well-known/private-aggregation/debug/report-shared-storage-Endpunkt gesendete Bericht befindet sich auch im „Berichtstext“ der Berichte, die auf der Seite „Interne Daten“ von Chrome angezeigt werden.

Möglicherweise sehen Sie hier viele Berichte. Verwenden Sie für dieses Codelab jedoch den aggregierbaren Bericht, der GCP-spezifisch ist und vom Endpunkt der Fehlerbehebung generiert wird. Die Berichts-URL enthält „/debug/“ und die aggregation_coordinator_origin field des Berichtstexts enthält die folgende URL: https://publickeyservice.msmt.gcp.privacysandboxservices.com.

Hinweis: Wenn du keinen Debug-Bericht wie oben siehst, aktualisiere die Privacy Sandbox-Demoseite und dann die Seite mit den internen Chrome-Inhalten. Sie sollten mehr Berichte sehen, einschließlich eines Berichts, der vom Endpunkt der Fehlerbehebung generiert wurde. Ist dies nicht der Fall, überprüfen Sie, ob Drittanbieter-Cookies aktiviert sind.

2.2. Aggregierbaren Debug-Bericht erstellen

Kopieren Sie den Bericht aus dem „Report Body“ (Berichtstext) von chrome://private-aggregation-internals und erstellen Sie im Ordner privacy-sandbox-demos/tools/aggregatable_report_converter/out/artifacts/aggregatable_report_converter_jar (im Repository, das in Voraussetzung 1.5 heruntergeladen wurde) eine JSON-Datei.

In diesem Beispiel verwenden wir vim, da wir Linux verwenden. Sie können aber jeden beliebigen Texteditor verwenden.

vim report.json

Fügen Sie den Bericht in report.json ein und speichern Sie die Datei.

Anschließend erstellen Sie mit aggregatable_report_converter.jar den aggregierten Debug-Bericht. Dadurch wird ein aggregierter Bericht mit dem Namen report.avro in Ihrem aktuellen Verzeichnis erstellt.

java -jar aggregatable_report_converter.jar \
  --request_type convertToAvro \
  --input_file report.json \
  --debug

2.3. Bucket-Schlüssel aus Bericht abrufen

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 von der Anzeigentechnologie (adTech) entworfen. In diesem Fall werden die Bucket-Schlüssel jedoch von der Website Privacy Sandbox Demo erstellt. Da sich die private Aggregation für diese Website im Fehlerbehebungsmodus befindet, können wir den debug_cleartext_payload aus dem „Report Body“ (Berichtstext) verwenden, um den Bucket-Schlüssel abzurufen.

Kopieren Sie die debug_cleartext_payload aus dem Berichtstext.

Öffne goo.gle/ags-payload-decoder, füge deinen debug_cleartext_payload in das Feld „INPUT“ ein und klicke auf „Decodieren“.

Die Seite gibt den Dezimalwert des Bucket-Schlüssels zurück. Unten sehen Sie ein Beispiel für einen Bucket-Schlüssel.

2.4 AVRO der Ausgabedomain erstellen

Nachdem Sie nun den Bucket-Schlüssel haben, erstellen wir die output_domain.avro im selben Ordner, in dem wir gearbeitet haben. Achten Sie darauf, den Bucket-Schlüssel durch den abgerufenen Bucket-Schlüssel zu ersetzen.

java -jar aggregatable_report_converter.jar \
  --request_type createDomainAvro \
  --bucket_key <bucket key>

Das Skript erstellt die Datei output_domain.avro im aktuellen Ordner.

2.5 Zusammenfassende Berichte mit dem lokalen Test-Tool erstellen

Wir verwenden LocalTestingTool_{version}.jar, das in Voraussetzung 1.3 heruntergeladen wurde, um die zusammenfassenden Berichte mit dem folgenden Befehl zu erstellen. Ersetzen Sie {version} durch die heruntergeladene Version. Denken Sie daran, LocalTestingTool_{version}.jar in das aktuelle Verzeichnis zu verschieben oder einen relativen Pfad hinzuzufügen, der auf seinen aktuellen Speicherort verweist.

java -jar LocalTestingTool_{version}.jar \
  --input_data_avro_file report.avro \
  --domain_avro_file output_domain.avro \
  --output_directory .

Sobald der Befehl ausgeführt wurde, sollte Folgendes angezeigt werden: Der Bericht output.avro wird erstellt, sobald dieser Vorgang abgeschlossen ist.

2.6 Zusammenfassungsbericht überprüfen

Der erstellte zusammenfassende Bericht ist im AVRO-Format erstellt. Um dies lesen zu können, müssen Sie es von AVRO in ein JSON-Format konvertieren. Idealerweise sollte adTech Code schreiben, um AVRO-Berichte zurück in JSON zu konvertieren.

Wir verwenden aggregatable_report_converter.jar, 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 der unten zurückgegeben. Mit einem Bericht, der im selben Verzeichnis erstellt wurde (output.json).

3. 3. Codelab zum Aggregationsdienst

Geschätzte Dauer: 1 Stunde

Bevor Sie beginnen, müssen Sie alle Voraussetzungen erfüllen, die mit „Aggregationsdienst“ gekennzeichnet sind.

Codelab-Schritte

Schritt 3.1: Eingabeerstellung für Aggregationsdienst: Erstellen Sie die Aggregationsdienstberichte, die für den Aggregationsdienst in Batches zusammengefasst werden.

• Schritt 3.1.1: Triggerbericht
• Schritt 3.1.2: Aggregierbare Berichte erstellen
• Schritt 3.1.3: Berichte in AVRO konvertieren
• Schritt 3.1.4: AVRO für „output_domain“ erstellen
• Schritt 3.1.5: Berichte in Cloud Storage-Bucket verschieben

Schritt 3.2: Nutzung des Aggregationsdienstes: Verwenden Sie die Aggregation Service API, um Zusammenfassungsberichte zu erstellen und die Zusammenfassungsberichte zu überprüfen.

• Schritt 3.2.1: Endpunkt createJob für Batch verwenden
• Schritt 3.2.2: Endpunkt getJob zum Abrufen des Batchstatus verwenden
• Schritt 3.2.3: Überprüfen des Zusammenfassungsberichts

3.1. Eingabeerstellung für Aggregationsdienst

Erstellen Sie nun die AVRO-Berichte für die Batchverarbeitung an den Aggregationsdienst. Die Shell-Befehle in diesen Schritten können in Cloud Shell der GCP oder in einer lokalen Ausführungsumgebung ausgeführt werden, sofern die Abhängigkeiten aus den Voraussetzungen in Ihrer Cloud Shell-Umgebung geklont werden.

3.1.1. Triggerbericht

Klicken Sie auf den Link, um die Website aufzurufen. Anschließend können Sie die Berichte unter chrome://private-aggregation-internals aufrufen:

Der an den {reporting-origin}/.well-known/private-aggregation/debug/report-shared-storage-Endpunkt gesendete Bericht befindet sich auch im „Berichtstext“ der Berichte, die auf der Seite „Interne Daten“ von Chrome angezeigt werden.

Möglicherweise sehen Sie hier viele Berichte. Verwenden Sie für dieses Codelab jedoch den aggregierbaren Bericht, der GCP-spezifisch ist und vom Endpunkt der Fehlerbehebung generiert wird. Die Berichts-URL enthält „/debug/“ und die aggregation_coordinator_origin field des Berichtstexts enthält die folgende URL: https://publickeyservice.msmt.gcp.privacysandboxservices.com.

Hinweis: Wenn du keinen Debug-Bericht wie oben siehst, aktualisiere die Privacy Sandbox-Demoseite und dann die Seite mit den internen Chrome-Inhalten. Sie sollten mehr Berichte sehen, einschließlich eines Berichts, der vom Endpunkt der Fehlerbehebung generiert wurde. Ist dies nicht der Fall, überprüfen Sie, ob Drittanbieter-Cookies aktiviert sind.

3.1.2. Aggregierbare Berichte erstellen

Erfassen Sie die aggregierbaren Berichte aus den .well-known-Endpunkten der entsprechenden API.

• Private Zusammenfassung: {reporting-origin}/.well-known/private-aggregation/report-shared-storage
• Attributionsberichte – Zusammenfassungsbericht: {reporting-origin}/.well-known/attribution-reporting/report-aggregate-attribution

In diesem Codelab führen wir die Berichtserfassung manuell durch. In der Produktion werden die Berichte von den AdTechs programmatisch erfasst und konvertiert.

Jetzt kopieren wir den JSON-Bericht aus chrome://private-aggregation-internals in den „Report Body“ (Berichtstext).

In diesem Beispiel verwenden wir vim, da wir Linux verwenden. Sie können aber jeden beliebigen Texteditor verwenden.

vim report.json

Fügen Sie den Bericht in report.json ein und speichern Sie die Datei.

3.1.3. Berichte in AVRO konvertieren

Von den .well-known-Endpunkten empfangene Berichte haben das JSON-Format und müssen in das AVRO-Berichtsformat konvertiert werden. Nachdem Sie den JSON-Bericht erhalten haben, gehen Sie zum Speicherort von report.json und verwenden Sie aggregatable_report_converter.jar, um den aggregierten Fehlerbehebungsbericht zu erstellen. Dadurch wird ein aggregierter Bericht mit dem Namen report.avro in Ihrem aktuellen Verzeichnis erstellt.

java -jar aggregatable_report_converter.jar \
  --request_type convertToAvro \
  --input_file report.json

3.1.4. AVRO für „output_domain“ 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 von der Anzeigentechnologie (adTech) entworfen. In diesem Fall werden die Bucket-Schlüssel jedoch von der Website Privacy Sandbox Demo erstellt. Da sich die private Aggregation für diese Website im Fehlerbehebungsmodus befindet, können wir den debug_cleartext_payload aus dem „Report Body“ (Berichtstext) verwenden, um den Bucket-Schlüssel abzurufen.

Kopieren Sie die debug_cleartext_payload aus dem Berichtstext.

Öffne goo.gle/ags-payload-decoder, füge deinen debug_cleartext_payload in das Feld „INPUT“ ein und klicke auf „Decodieren“.

Die Seite gibt den Dezimalwert des Bucket-Schlüssels zurück. Unten sehen Sie ein Beispiel für einen Bucket-Schlüssel.

Nachdem Sie nun den Bucket-Schlüssel haben, erstellen wir die output_domain.avro im selben Ordner, in dem wir gearbeitet haben. Achten Sie darauf, den Bucket-Schlüssel durch den abgerufenen Bucket-Schlüssel zu ersetzen.

java -jar aggregatable_report_converter.jar \
  --request_type createDomainAvro \
  --bucket_key <bucket key>

Das Skript erstellt die Datei output_domain.avro im aktuellen Ordner.

3.1.5. Berichte in Cloud Storage-Bucket verschieben

Nachdem Sie die AVRO-Berichte und die Ausgabedomain erstellt haben, verschieben Sie die Berichte und die Ausgabedomain in den Bucket in Cloud Storage, den Sie im letzten Schritt in „Voraussetzung 1.6“ erstellt haben.

Wenn Sie die gcloud CLI in Ihrer lokalen Umgebung eingerichtet haben, kopieren Sie die Dateien mit den folgenden Befehlen in die entsprechenden Ordner.

gcloud storage cp report.avro gs://<bucket_name>/reports/

gcloud storage cp output_domain.avro gs://<bucket_name>/output_domain/

Andernfalls laden Sie die Dateien manuell in den Bucket hoch. Erstellen Sie einen Ordner namens „Berichte“ und laden Sie dort die Datei report.avro hoch. Erstellen Sie einen Ordner mit dem Namen „output_domains“ und laden Sie die Datei output_domain.avro dort hoch.

3.2. Nutzung des Aggregationsdienstes

Denken Sie daran, dass Sie in der Voraussetzung 1.8 entweder cURL oder Postman ausgewählt haben, um API-Anfragen an Aggregationsdienst-Endpunkte zu senden. Nachfolgend finden Sie Anleitungen für beide Optionen.

3.2.1. Endpunkt createJob für Batch verwenden

Verwenden Sie die folgenden cURL- oder Postman-Anweisungen, um einen Job zu erstellen.

cURL

Erstellen Sie in Ihrem „Terminal“ eine Anfragetextdatei (body.json) und fügen Sie den folgenden Text ein. Aktualisieren Sie unbedingt die Platzhalterwerte. Weitere Informationen zu den Werten der einzelnen Felder finden Sie in dieser API-Dokumentation.

Hinweis: attribution_report_to ist der Ursprung, der auch als „Website für AdTech-Berichte“ bezeichnet wird und während der Einrichtung des Aggregationsdienstes eingerichtet wurde (Voraussetzung 1.7).

{
  "job_request_id": "<job_request_id>",
  "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
  "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>",
    "report_error_threshold_percentage": "10",
    "debug_run": "true"
  }
}

Führen Sie die folgende Anfrage aus. Ersetzen Sie die Platzhalter in der URL der cURL-Anfrage durch die Werte aus frontend_service_cloudfunction_url, die nach erfolgreicher Terraform-Bereitstellung in Voraussetzung 1.6 ausgegeben werden.

curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  -d @body.json \
  https://<environment>-<region>-frontend-service-<cloud-function-id>-uc.a.run.app/v1alpha/createJob

Sie sollten eine HTTP 202-Antwort erhalten, sobald die Anfrage vom Zusammenfassungsdienst akzeptiert wurde. Andere mögliche Antwortcodes sind in den API-Spezifikationen dokumentiert.

Postbote

Für den Endpunkt createJob ist ein Anfragetext erforderlich, um dem Aggregationsdienst den Speicherort und die Dateinamen aggregierbarer Berichte, Ausgabedomains und Zusammenfassungsberichte bereitzustellen.

Rufen Sie den Tab „Body“ der createJob-Anfrage auf:

Ersetzen Sie die Platzhalter innerhalb der bereitgestellten JSON-Datei. Weitere Informationen zu diesen Feldern und ihrer Bedeutung finden Sie in der API-Dokumentation.

Hinweis: attribution_report_to ist der Ursprung, der auch als „Website für AdTech-Berichte“ bezeichnet wird und während der Einrichtung des Aggregationsdienstes eingerichtet wurde (Voraussetzung 1.7).

{
  "job_request_id": "<job_request_id>",
  "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
  "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>",
    "report_error_threshold_percentage": "10",
    "debug_run": "true"
  }
}

Senden Sie die API-Anfrage createJob:

Den Antwortcode finden Sie in der unteren Hälfte der Seite:

Sie sollten eine HTTP 202-Antwort erhalten, sobald die Anfrage vom Zusammenfassungsdienst akzeptiert wurde. Andere mögliche Antwortcodes sind in den API-Spezifikationen dokumentiert.

3.2.2. Endpunkt getJob zum Abrufen des Batchstatus verwenden

Folgen Sie der Anleitung unten für cURL oder Postman, um einen Job zu erhalten.

cURL

Führen Sie die folgende Anfrage in Ihrem Terminal aus. Ersetzen Sie die Platzhalter in der URL durch die Werte aus frontend_service_cloudfunction_url. Dabei handelt es sich um dieselbe URL, die Sie für die createJob-Anfrage verwendet haben. Verwenden Sie für „job_request_id“ den Wert aus dem Job, den Sie mit dem Endpunkt createJob erstellt haben.

curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  https://<environment>-<region>-frontend-service-<cloud-function-id>-uc.a.run.app/v1alpha/getJob?job_request_id=<job_request_id>

Das Ergebnis sollte den Status Ihrer Jobanfrage mit dem HTTP-Status 200 zurückgeben. Die Anfrage „Body“ enthält die erforderlichen Informationen wie job_status, return_message und error_messages (wenn beim Job ein Fehler aufgetreten ist).

Hinweis: Der Bericht, den wir für dieses Codelab verwenden, hängt mit der Berichtsquelle der Privacy Sandbox-Demowebsite zusammen. Bei der Einrichtung des Aggregationsdienstes in Ihrer GCP-Umgebung haben Sie jedoch Ihre eigene Berichtsquelle angegeben. Da der Bericht von einer anderen Website stammt als die, auf der Sie angemeldet waren, erhalten Sie möglicherweise eine Antwort mit dem Rückgabecode PRIVACY_BUDGET_AUTHORIZATION_ERROR. Das ist normal und kann ignoriert werden.

Postbote

Mit dem Endpunkt getJob können Sie den Status der Jobanfrage prüfen. Aktualisieren Sie im Abschnitt „Parameter“ der getJob-Anfrage den job_request_id-Wert in den job_request_id, der in der createJob-Anfrage gesendet wurde.

Senden Sie die getJob-Anfrage:

Das Ergebnis sollte den Status Ihrer Jobanfrage mit dem HTTP-Status 200 zurückgeben. Die Anfrage „Body“ enthält die erforderlichen Informationen wie job_status, return_message und error_messages (wenn beim Job ein Fehler aufgetreten ist).

Hinweis: Der Bericht, den wir für dieses Codelab verwenden, hängt mit der Berichtsquelle der Privacy Sandbox-Demowebsite zusammen. Bei der Einrichtung des Aggregationsdienstes in Ihrer GCP-Umgebung haben Sie jedoch Ihre eigene Berichtsquelle angegeben. Da der Bericht von einer anderen Website stammt als die, auf der Sie angemeldet waren, erhalten Sie möglicherweise eine Antwort mit dem Rückgabecode PRIVACY_BUDGET_AUTHORIZATION_ERROR. Das ist normal und kann ignoriert werden.

3.2.3. Überprüfen des Zusammenfassungsberichts

Sobald Sie den Zusammenfassungsbericht im Cloud Storage-Ausgabe-Bucket erhalten haben, können Sie ihn in Ihre lokale Umgebung herunterladen. Zusammenfassungsberichte liegen im AVRO-Format vor und können wieder in das JSON-Format konvertiert werden. Mit dem folgenden Befehl können Sie aggregatable_report_converter.jar verwenden, um Ihren Bericht zu lesen.

java -jar aggregatable_report_converter.jar \
  --request_type convertToJson \
  --input_file <summary_report_avro>

Dadurch wird eine JSON-Datei mit aggregierten Werten jedes Bucket-Schlüssels zurückgegeben, die in etwa so aussieht:

Wenn in deiner createJob-Anfrage debug_run auf „true“ gesetzt ist, erhältst du den zusammenfassenden Bericht im Fehlerbehebungsordner, der sich im output_data_blob_prefix befindet. Der Bericht ist im AVRO-Format und kann mit dem obigen Befehl in ein JSON-Format konvertiert werden.

Der Bericht enthält den Bucket-Schlüssel, den nicht verrauschten Messwert und das Rauschen, das dem nicht verrauschten Messwert hinzugefügt wird, um den zusammenfassenden Bericht zu erstellen. Der Bericht sieht in etwa so aus:

Die Anmerkungen enthalten auch „in_reports“ und/oder „in_domain“. Das bedeutet:

• in_reports: Der Bucket-Schlüssel ist in den aggregierten Berichten verfügbar.
• in_domain: Der Bucket-Schlüssel ist in der AVRO-Datei "output_domain" verfügbar.

4. 4. Klären

Wenn Sie die Ressourcen löschen möchten, die über Terraform für den Aggregationsdienst erstellt wurden, verwenden Sie den Befehl zum Löschen in den Ordnern adtech_setup und dev (oder einer anderen Umgebung):

$ cd <repository_root>/terraform/gcp/environments/adtech_setup
$ terraform destroy
$ cd <repository_root>/terraform/gcp/environments/dev
$ terraform destroy

So löschen Sie den Cloud Storage-Bucket mit Ihren aggregierten Berichten und Zusammenfassungsberichten:

$ gcloud storage buckets delete gs://my-bucket

Sie können auch Ihre Chrome-Cookie-Einstellungen von Voraussetzung 1.2 auf ihren vorherigen Status zurücksetzen.

5. 5. Anhang

adtech_setup.auto.tfvars-Beispieldatei

/**
 * Copyright 2023 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

project = "my-project-id"

# Required to generate identity token for access of Adtech Services API endpoints
service_account_token_creator_list = ["user:[e-mail]"]

# Uncomment the below line if you like Terraform to create an Artifact registry repository
# for self-build container artifacts. "artifact_repo_location" defaults to "us".
artifact_repo_name     = "my-ags-artifacts"

# Note: Either one of [1] or [2] must be uncommented.

# [1] Uncomment below lines if you like Terraform grant needed permissions to
# pre-existing service accounts
# deploy_service_account_email = "<YourDeployServiceAccountName>@<ProjectID>.iam.gserviceaccount.com"
# worker_service_account_email = "<YourWorkerServiceAccountName>@<ProjectID>.iam.gserviceaccount.com"

# [2] Uncomment below lines if you like Terraform to create service accounts
# and needed permissions granted e.g "deploy-sa" or "worker-sa"
deploy_service_account_name = "deploy-sa"
worker_service_account_name = "worker-sa"
# Uncomment the below line if you want Terraform to create the
# below bucket. "data_bucket_location" defaults to "us".
data_bucket_name     = "my-ags-data"

# Uncomment the below lines if you want to specify service account customer role names
# deploy_sa_role_name = "<YourDeploySACustomRole>"
# worker_sa_role_name = "<YourWorkerSACustomRole>"

dev.auto.tfvars-Beispieldatei

/**
 * Copyright 2022 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

# Example values required by job_service.tf
#
# These values should be modified for each of your environments.
region      = "us-central1"
region_zone = "us-central1-c"

project_id  = "my-project-id"
environment = "operator-demo-env"

# Co-locate your Cloud Spanner instance configuration with the region above.
# https://cloud.google.com/spanner/docs/instance-configurations#regional-configurations
spanner_instance_config = "regional-us-central1"

# Adjust this based on the job load you expect for your deployment.
# Monitor the spanner instance utilization to decide on scale out / scale in.
# https://console.cloud.google.com/spanner/instances
spanner_processing_units = 100

# Uncomment the line below at your own risk to disable Spanner database protection.
# This needs to be set to false and applied before destroying all resources is possible.
spanner_database_deletion_protection = false

instance_type = "n2d-standard-8" # 8 cores, 32GiB

# Container image location that packages the job service application
# If not set otherwise, uncomment and edit the line below:
#worker_image = "<location>/<project>/<repository>/<image>:<tag or digest>"

# Service account created and onboarded for worker
user_provided_worker_sa_email = "[e-mail]"

min_worker_instances = 1
max_worker_instances = 20