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

1. 1. Vorbereitung

Geschätzte Dauer: 1–2 Stunden

Für dieses Codelab gibt es zwei Modi: Lokale Tests und Aggregationsdienst. Für den lokalen Testmodus sind ein lokaler Computer und der Chrome-Browser erforderlich. Es müssen keine Google Cloud-Ressourcen erstellt oder verwendet werden. Für den Aggregationsdienstmodus ist eine vollständige Bereitstellung des Aggregationsdienstes in Google Cloud erforderlich.

Für dieses Codelab sind in beiden Modi einige Voraussetzungen erforderlich. Jede Anforderung ist entsprechend gekennzeichnet, je nachdem, ob sie für den lokalen Test oder den Aggregationsdienst erforderlich ist.

1.1 Registrierung und Bestätigung abschließen (Aggregationsdienst)

Wenn Sie Privacy Sandbox-APIs verwenden möchten, müssen Sie die Registrierung und Attestierung für Chrome und Android abgeschlossen haben.

1.2. APIs zum Schutz der Privatsphäre von Nutzern aktivieren (lokale Tests und Aggregation Service)

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

Rufen Sie in Ihrem Browser chrome://settings/adPrivacy auf und aktivieren Sie alle APIs zum Datenschutz bei Werbung.

Prüfen Sie außerdem, ob Drittanbieter-Cookies aktiviert sind.

Prüfen Sie in chrome://settings/cookies, ob Drittanbieter-Cookies NICHT blockiert werden. Je nach Chrome-Version werden in diesem Einstellungsmenü möglicherweise unterschiedliche Optionen angezeigt. Akzeptable Konfigurationen sind unter anderem:

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

Cookies aktivieren

1.3. 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 Cloud Functions-JAR-Archive heruntergeladen werden. Er sollte LocalTestingTool_{version}.jar heißen.

1.4 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-Version prüfen.

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 herunterladen (lokale Tests und Aggregationsdienst)

Sie können eine Kopie von „aggregatable_report_converter“ aus dem GitHub-Repository für Privacy Sandbox-Demos herunterladen. Im GitHub-Repository wird die Verwendung von IntelliJ oder Eclipse erwähnt, aber keines der beiden ist erforderlich. Wenn Sie diese Tools nicht verwenden, laden Sie die JAR-Datei stattdessen in Ihre lokale Umgebung herunter.

1.6 Cloud Platform-Umgebung einrichten (Aggregationsdienst)

Für den Aggregationsdienst ist eine Trusted Execution Environment erforderlich, die einen Cloud-Anbieter verwendet. In diesem Codelab wird der Aggregation Service in Google Cloud bereitgestellt. AWS wird aber auch unterstützt.

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

Wichtige Schritte in der Bereitstellungsanleitung:

1. Richten Sie die gcloud CLI und Terraform in Ihrer Umgebung ein.
2. Cloud Storage-Bucket zum Speichern des Terraform-Zustands erstellen
3. Abhängigkeiten herunterladen
4. Aktualisieren Sie adtech_setup.auto.tfvars und führen Sie das adtech_setup-Terraform aus. Ein Beispiel für eine adtech_setup.auto.tfvars-Datei finden Sie im Anhang. Notieren Sie sich den Namen des hier erstellten Daten-Buckets. Er wird im Codelab zum Speichern der von uns erstellten Dateien verwendet.
5. Aktualisieren Sie dev.auto.tfvars, übernehmen Sie die Identität des Bereitstellungsdienstkontos und führen Sie dev Terraform aus. Ein Beispiel für eine dev.auto.tfvars-Datei finden Sie im Anhang.
6. Erfassen Sie nach Abschluss der Bereitstellung die frontend_service_cloudfunction_url aus der Terraform-Ausgabe, die für Anfragen an den Aggregationsdienst in späteren Schritten benötigt wird.

1.7. Onboarding für den Aggregationsdienst abschließen (Aggregationsdienst)

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 Ihre Reporting-Website und andere Informationen an, wählen Sie „Google Cloud“ aus und geben Sie die Adresse Ihres Dienstkontos ein. Dieses Dienstkonto wird im vorherigen Schritt (1.6. Google Cloud-Umgebung einrichten). Hinweis: Wenn Sie die bereitgestellten Standardnamen verwenden, beginnt dieses Dienstkonto mit „worker-sa@“.

Die Einrichtung kann bis zu zwei Wochen dauern.

1.8. Methode zum Aufrufen der API-Endpunkte (Aggregation Service) festlegen

In diesem Codelab werden zwei Optionen zum Aufrufen der Aggregation Service API-Endpunkte vorgestellt: cURL und Postman. cURL ist die schnellere und einfachere Methode, um die API-Endpunkte über das Terminal aufzurufen, da nur eine minimale Einrichtung und keine zusätzliche Software erforderlich ist. Wenn Sie cURL nicht verwenden möchten, können Sie stattdessen Postman verwenden, um API-Anfragen auszuführen und für die zukünftige Verwendung zu speichern.

Abschnitt 3.2 Unter „Aggregation Service Usage“ (Aggregation Service-Nutzung) finden Sie eine detaillierte Anleitung zur Verwendung beider Optionen. Sie können sich jetzt eine Vorschau ansehen, um zu entscheiden, welche Methode Sie verwenden möchten. Wenn Sie Postman auswählen, führen Sie die folgenden Schritte zur Ersteinrichtung aus.

1.8.1. Arbeitsbereich einrichten

Registrieren Sie sich für ein Postman. Nach der Registrierung wird automatisch ein Arbeitsbereich für Sie erstellt.

Einen Postman-Arbeitsbereich.

Wenn kein Arbeitsbereich für Sie erstellt wird, wählen Sie oben in der Navigationsleiste „Arbeitsbereiche“ und dann „Arbeitsbereich erstellen“ aus.

Wählen Sie „Leerer Arbeitsbereich“ aus, klicken Sie auf „Weiter“ und geben Sie „GCP Privacy Sandbox“ als Namen ein. Wählen Sie „Privat“ aus und klicken Sie auf „Erstellen“.

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

Importieren Sie beide JSON-Dateien mit der Schaltfläche „Importieren“ in „Mein Arbeitsbereich“.

Die Schaltfläche „Importieren“.

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 rufen Sie den Tab „Autorisierung“ auf.

  Schaltfläche „Autorisierung“

Sie verwenden die Methode „Bearer Token“. Führen Sie in Ihrer Terminalumgebung diesen Befehl aus und kopieren Sie die Ausgabe.

gcloud auth print-identity-token

Fügen Sie diesen Tokenwert dann in das Feld „Token“ auf dem Postman-Tab „Authorization“ ein:

Das Feld „Token“.

1.8.3. Umgebung einrichten

Gehen Sie oben rechts zu „Umgebung – Kurzübersicht“:

Die Schaltfläche „Umgebung – Kurzübersicht“.

Klicken Sie auf „Bearbeiten“ und aktualisieren Sie den „Aktuellen Wert“ von „environment“, „region“ und „cloud-function-id“:

  Aktuelle Werte festlegen.

Sie können „request-id“ vorerst leer lassen, da wir das Feld später ausfüllen. Verwenden Sie für die anderen Felder die Werte aus frontend_service_cloudfunction_url, die bei erfolgreichem 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 zum lokalen Testen

Geschätzte Dauer: weniger als 1 Stunde

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. Bevor Sie beginnen, prüfen Sie, ob Sie alle Voraussetzungen erfüllt haben, die mit „Lokale Tests“ gekennzeichnet sind.

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: „Debug-AVRO-Bericht erstellen“: Konvertiert den erfassten JSON-Bericht in einen AVRO-formatierten Bericht. Dieser Schritt ähnelt dem Vorgang, wenn Ad-Tech-Unternehmen die Berichte von den API-Berichtsendpunkten abrufen und die JSON-Berichte in AVRO-formatierte Berichte konvertieren.

Schritt 2.3: Bucket-Schlüssel abrufen: 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: Output Domain AVRO erstellen: Nachdem die Bucket-Schlüssel abgerufen wurden, erstellen Sie die AVRO-Datei für die Ausgabedomäne.

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

Schritt 2.6: Zusammenfassungsberichte ansehen: Sehen Sie sich den Zusammenfassungsbericht an, der vom Tool für lokale Tests erstellt wird.

2.1. Trigger-Bericht

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 Attestierung sowie das Onboarding für den Aggregationsdienst 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. Die Berichte finden Sie dann unter chrome://private-aggregation-internals:

Chrome-Interna-Seite.

Der Bericht, der an den {reporting-origin}/.well-known/private-aggregation/debug/report-shared-storage-Endpunkt gesendet wird, ist auch im „Berichtstext“ der Berichte auf der Seite „Chrome Internals“ zu finden.

Hier werden möglicherweise viele Berichte angezeigt. Verwenden Sie für dieses Codelab den aggregierbaren Bericht, der Google Cloud-spezifisch ist und vom Debug-Endpunkt generiert wird. Die „Berichts-URL“ enthält „/debug/“ und der aggregation_coordinator_origin field des „Berichtstexts“ enthält diese URL: https://publickeyservice.msmt.gcp.privacysandboxservices.com.

Google Cloud Debug-Bericht.

2.2. Aggregierbaren Debug-Bericht erstellen

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

In diesem Beispiel verwenden wir vim, da wir Linux 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.

: Der JSON-Code des Berichts.

Verwenden Sie dann 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 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 vom Anbieter von Anzeigentechnologien erstellt. In diesem Fall werden sie jedoch von der Privacy Sandbox-Demowebsite erstellt. Da sich die private Aggregation für diese Website im Debug-Modus befindet, können wir den Bucket-Schlüssel aus dem debug_cleartext_payload im „Berichtstext“ abrufen.

Kopieren Sie die debug_cleartext_payload aus dem Berichtstext.

  Klartextnutzlast debuggen.

Öffnen Sie goo.gle/ags-payload-decoder, fügen Sie Ihren debug_cleartext_payload in das Feld „INPUT“ ein und klicken Sie auf „Decode“.

Die Schaltfläche zum Decodieren.

Auf der Seite wird der Dezimalwert des Bucket-Schlüssels zurückgegeben. Im Folgenden sehen Sie ein Beispiel für einen Bucket-Schlüssel.

Ein Beispiel für einen Bucket-Schlüssel.

2.4 AVRO-Ausgabedomain erstellen

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

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 Voraussetzung 1.3 heruntergeladen wurde, um mit dem folgenden Befehl die Zusammenfassungsberichte 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, um auf den aktuellen Speicherort zu verweisen.

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 ausgeben

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 das Ad-Tech-Unternehmen Code schreiben, um AVRO-Berichte wieder 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

Es wird ein Bericht ähnlich dem folgenden zurückgegeben. Zusammen mit einem Bericht output.json, der im selben Verzeichnis erstellt wurde.

JSON ausgeben

Codelab abgeschlossen!

Zusammenfassung:Sie haben einen Debug-Bericht erstellt, eine Ausgabedomaindatei erstellt und mit dem lokalen Testtool einen Zusammenfassungsbericht generiert, der das Aggregationsverhalten des Aggregationsdienstes simuliert.

Nächste Schritte:Nachdem Sie das Tool für lokale Tests ausprobiert haben, können Sie dasselbe in Ihrer eigenen Umgebung mit einer Livebereitstellung des Aggregationsdienstes durchführen. Prüfen Sie noch einmal die Voraussetzungen, um sicherzugehen, dass Sie alles für den Aggregationsdienstmodus eingerichtet haben, und fahren Sie dann mit Schritt 3 fort.

3. 3. Codelab zum Aggregationsdienst

Geschätzte Dauer: 1 Stunde

Bevor Sie beginnen, prüfen Sie, ob Sie alle Voraussetzungen erfüllt haben, die mit „Aggregation Service“ gekennzeichnet sind.

Codelab-Schritte

Schritt 3.1: Eingabe für den Aggregationsdienst erstellen: Erstellen Sie die Berichte für den Aggregationsdienst, die für den Aggregationsdienst gebatcht werden.

• Schritt 3.1.1: Triggerbericht
• Schritt 3.1.2: Zusammenfassbare Berichte erfassen
• Schritt 3.1.3: Berichte in AVRO konvertieren
• Schritt 3.1.4: AVRO für output_domain erstellen
• Schritt 3.1.5: Berichte in einen Cloud Storage-Bucket verschieben

Schritt 3.2: Nutzung des Aggregationsdienstes: Mit der Aggregation Service API können Sie Zusammenfassungsberichte erstellen und prüfen.

• Schritt 3.2.1: createJob-Endpunkt für Batch verwenden
• Schritt 3.2.2: getJob-Endpunkt zum Abrufen des Batchstatus verwenden
• Schritt 3.2.3: Zusammenfassenden Bericht ansehen

3.1. Eingabeerstellung für den Aggregationsdienst

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

3.1.1. Triggerbericht

Klicken Sie auf den Link, um die Website aufzurufen. Die Berichte finden Sie dann unter chrome://private-aggregation-internals:

Chrome-Interna-Seite

Der Bericht, der an den {reporting-origin}/.well-known/private-aggregation/debug/report-shared-storage-Endpunkt gesendet wird, ist auch im „Berichtstext“ der Berichte auf der Seite „Chrome Internals“ zu finden.

Hier werden möglicherweise viele Berichte angezeigt. Verwenden Sie für dieses Codelab den aggregierbaren Bericht, der Google Cloud-spezifisch ist und vom Debug-Endpunkt generiert wird. Die „Berichts-URL“ enthält „/debug/“ und der aggregation_coordinator_origin field des „Berichtstexts“ enthält diese URL: https://publickeyservice.msmt.gcp.privacysandboxservices.com.

Google Cloud Debug-Bericht.

3.1.2. Zusammenfassbare Berichte erfassen

Rufen Sie Ihre zusammenfassbaren 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 wir die Berichtserstellung manuell durch. In der Produktion wird von Anbietern von Anzeigentechnologien erwartet, dass sie die Berichte programmatisch erheben und konvertieren.

Kopieren wir den JSON-Bericht im „Berichtstext“ aus chrome://private-aggregation-internals.

In diesem Beispiel verwenden wir vim, da wir Linux 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.

Berichts-JSON

3.1.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 Speicherort von report.json 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

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 vom Anbieter von Anzeigentechnologien erstellt. In diesem Fall werden sie jedoch von der Privacy Sandbox-Demowebsite erstellt. Da sich die private Aggregation für diese Website im Debug-Modus befindet, können wir den Bucket-Schlüssel aus dem debug_cleartext_payload im „Berichtstext“ abrufen.

Kopieren Sie die debug_cleartext_payload aus dem Berichtstext.

  Klartextnutzlast debuggen.

Öffnen Sie goo.gle/ags-payload-decoder, fügen Sie Ihren debug_cleartext_payload in das Feld „INPUT“ ein und klicken Sie auf „Decode“.

Die Schaltfläche zum Decodieren.

Auf der Seite wird der Dezimalwert des Bucket-Schlüssels zurückgegeben. Im Folgenden sehen Sie ein Beispiel für einen Bucket-Schlüssel.

Ein Beispiel für einen Bucket-Schlüssel.

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

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.

3.1.5. Berichte in einen Cloud Storage-Bucket verschieben

Nachdem die AVRO-Berichte und die Ausgabedomain erstellt wurden, verschieben Sie die Berichte und die Ausgabedomain in den Bucket in Cloud Storage, den Sie in Voraussetzung 1.6 notiert haben.

Wenn Sie die gcloud CLI in Ihrer lokalen Umgebung eingerichtet haben, verwenden Sie die folgenden Befehle, um die Dateien in die entsprechenden Ordner zu kopieren.

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 Ihren Bucket hoch. Erstellen Sie einen Ordner mit dem Namen „reports“ und laden Sie die Datei report.avro dort 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

In Voraussetzung 1.8 haben Sie entweder „curl“ oder Postman für API-Anfragen an Aggregation Service-Endpunkte ausgewählt. Anleitungen für beide Optionen finden Sie unten.

Wenn Ihr Job mit einem Fehler fehlschlägt, finden Sie in unserer Dokumentation zur Fehlerbehebung auf GitHub weitere Informationen dazu, wie Sie vorgehen müssen.

3.2.1. createJob-Endpunkt für Batch verwenden

Verwenden Sie eine der folgenden Anleitungen für curl oder Postman, um einen Job zu erstellen.

curl

Erstellen Sie im Terminal eine Datei für den Anfragetext (body.json) und fügen Sie das folgende JSON-Objekt ein. Achten Sie darauf, dass Sie die Platzhalterwerte aktualisieren. Weitere Informationen dazu, wofür die einzelnen Felder stehen, finden Sie in dieser API-Dokumentation.

{
    "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": "<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"
    }
}

Führe die folgende Anfrage aus. Ersetzen Sie die Platzhalter in der URL der curl-Anfrage durch die Werte aus frontend_service_cloudfunction_url, die nach erfolgreichem Abschluss der 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 Aggregationsdienst akzeptiert wurde. Andere mögliche Antwortcodes sind in den API-Spezifikationen dokumentiert.

Postman

Für den createJob-Endpunkt ist ein Anfragetext erforderlich, um dem Aggregation Service den Speicherort und die Dateinamen von aggregierbaren Berichten, Ausgabedomains und Zusammenfassungsberichten bereitzustellen.

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

Tab „Body“

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

{
    "job_request_id": "<job_request_id>",
    "input_data_blob_prefix": "<report_folder>/",
    "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": "<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"
    }
}

Senden Sie die createJob-API-Anfrage:

Schaltfläche „Senden“

Der Antwortcode befindet sich in der unteren Hälfte der Seite:

Antwortcode

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

3.2.2. getJob-Endpunkt zum Abrufen des Batchstatus verwenden

Verwenden Sie eine der folgenden Anleitungen für curl oder Postman, um einen Job abzurufen.

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. Das ist 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 createJob-Endpunkt 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-Statuscode 200 zurückgeben. Der Anfragetext enthält die erforderlichen Informationen wie job_status, return_message und error_messages (wenn beim Job ein Fehler aufgetreten ist).

Postman

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

ID der Jobanfrage

Senden Sie die getJob-Anfrage:

Schaltfläche „Senden“

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

Antwort (JSON)

3.2.3. Zusammenfassenden Bericht ansehen

Sobald Sie den Zusammenfassungsbericht in Ihrem Cloud Storage-Ausgabe-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 diesem 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 in etwa so aussieht:

Zusammenfassungsbericht

Wenn Ihre createJob-Anfrage debug_run als „true“ enthält, können Sie den Zusammenfassungsbericht im Debug-Ordner im output_data_blob_prefix abrufen. Der Bericht liegt im AVRO-Format vor und kann mit dem vorherigen Befehl in JSON 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:

Bericht mit Rauschen

Die Annotationen enthalten auch „in_reports“ oder „in_domain“ (oder beides). Das 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.

Codelab abgeschlossen!

Zusammenfassung:Sie haben den Aggregationsdienst in Ihrer eigenen Cloud-Umgebung bereitgestellt, einen Debug-Bericht erstellt, eine Ausgabedomänendatei erstellt, diese Dateien in einem Cloud Storage-Bucket gespeichert und einen erfolgreichen Job ausgeführt.

Nächste Schritte:Verwenden Sie den Aggregation Service weiterhin in Ihrer Umgebung oder löschen Sie die Cloud-Ressourcen, die Sie gerade erstellt haben, indem Sie der Anleitung zum Bereinigen in Schritt 4 folgen.

4. 4. Klären

Wenn Sie die für den Aggregation Service mit Terraform erstellten Ressourcen löschen möchten, verwenden Sie den Befehl „destroy“ in den Ordnern adtech_setup und dev (oder einem anderen Ordner für die 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 aggregierbaren Berichten und Übersichtsberichten:

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

Sie können die Chrome-Cookie-Einstellungen aus Voraussetzung 1.2 auch auf den vorherigen Zustand 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:me@email.com"]

# 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 = "worker-sa@my-project-id.iam.gserviceaccount.com"

min_worker_instances = 1
max_worker_instances = 20