1. 1. Vorbereitung
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. APIs für Datenschutz bei Werbung (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://settings/adPrivacy
auf und aktivieren Sie alle APIs zum Datenschutz bei Werbung.
Achten Sie außerdem darauf, dass Drittanbieter-Cookies aktiviert sind.
Achte darauf, dass Drittanbieter-Cookies ab dem chrome://settings/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
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. Im GitHub-Repository wird die Verwendung von IntelliJ oder Eclipse erwähnt, beide sind jedoch nicht erforderlich. Wenn Sie diese Tools nicht verwenden, laden Sie stattdessen die JAR-Datei in Ihre lokale Umgebung herunter.
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.
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.
Wichtige Schritte in der Bereitstellungsanleitung:
- „gcloud“ einrichten Befehlszeile und Terraform in Ihrer Umgebung
- Erstellen Sie einen Cloud Storage-Bucket zum Speichern des Terraform-Zustands.
- Laden Sie Abhängigkeiten herunter.
- Aktualisieren Sie
adtech_setup.auto.tfvars
und führen Sie das Terraform-Paketadtech_setup
aus. Im Anhang finden Sie eine Beispieldatei füradtech_setup.auto.tfvars
. Notieren Sie sich den Namen des hier erstellten Daten-Buckets. Er wird im Codelab zum Speichern der von uns erstellten Dateien verwendet. - 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ürdev.auto.tfvars
. - 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.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 können Sie 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, rufen Sie „Arbeitsbereiche“ auf. und wählen Sie „Arbeitsbereich erstellen“ aus.
Wählen Sie „Leerer Arbeitsbereich“ aus, klicken Sie auf „Weiter“ und nennen Sie ihn „GCP Privacy Sandbox“. Wähle "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.
Beide JSON-Dateien in „Mein Arbeitsbereich“ importieren über die Schaltfläche „Importieren“ Schaltfläche.
Dadurch wird die „GCP Privacy Sandbox“ erstellt zusammen mit den HTTP-Anfragen createJob
und getJob
an.
1.8.2. Autorisierung einrichten
Klicken Sie auf „GCP Privacy Sandbox“. und navigieren Sie zur Seite „Autorisierung“, .
Sie verwenden das Inhabertoken . Führen Sie in Ihrer Terminal-Umgebung diesen Befehl aus und kopieren Sie die Ausgabe.
gcloud auth print-identity-token
Fügen Sie diesen Tokenwert dann in das des Tabs „Autorisierung“ von Postman:
1.8.3. Umgebung einrichten
Rufen Sie „Kurzansicht der Umgebung“ auf. in der oberen rechten Ecke:
Klicken Sie auf „Bearbeiten“. und aktualisieren Sie den „aktuellen Wert“ von "environment", "region" und "cloud-function-id":
Sie können „request-id“ hinterlassen, fürs Erste leer sein, da wir es 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://
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 Zum Onboarding der Attestierung und Aggregationsdienst müssen Sie ein Chrome-Flag und einen CLI-Switch verwenden.
Für diese Demo verwenden wir die Privacy Sandbox-Demowebsite. Folgen Sie dem Link, um die Website aufzurufen. können Sie die Berichte dann unter chrome://private-aggregation-internals
aufrufen:
Der Bericht, der an den {reporting-origin}/.well-known/private-aggregation/debug/report-shared-storage
-Endpunkt gesendet wird, befindet sich auch im Berichtstext der Berichte, die auf der Seite "Chrome Internals" 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 diese URL: https://publickeyservice.msmt.gcp.privacysandboxservices.com.
2.2. Aggregierbaren Debug-Bericht erstellen
Kopieren Sie den Bericht im „Berichtstext“. von chrome://private-aggregation-internals
und erstellen Sie im Ordner privacy-sandbox-demos/tools/aggregatable_report_converter/out/artifacts/aggregatable_report_converter_jar
(innerhalb des in Prerequisite 1.5 heruntergeladenen Repositorys) 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 Debug-Modus befindet, können wir die debug_cleartext_payload
aus dem Berichttext verwenden um den Bucket-Schlüssel abzurufen.
Kopieren Sie die debug_cleartext_payload
aus dem Berichtstext.
Öffnen Sie goo.gle/ags-payload-decoder und fügen Sie 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
).
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 nun das lokale Testtool ausprobiert haben, können Sie dieselbe Übung mit einer Live-Bereitstellung des Zusammenfassungsdienstes in Ihrer eigenen Umgebung durchführen. Sehen Sie sich noch einmal die Voraussetzungen an, um sicherzugehen, dass alles für den Aggregationsdienst eingerichtet ist und fahren Sie dann mit Schritt 3 fort.
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
Folgen Sie dem Link, um die Website aufzurufen. können Sie die Berichte dann unter chrome://private-aggregation-internals
aufrufen:
Der Bericht, der an den {reporting-origin}/.well-known/private-aggregation/debug/report-shared-storage
-Endpunkt gesendet wird, befindet sich auch im Berichtstext der Berichte, die auf der Seite "Chrome Internals" 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 diese URL: https://publickeyservice.msmt.gcp.privacysandboxservices.com.
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 von chrome://private-aggregation-internals
.
In diesem Beispiel verwenden wir vim, da wir Linux verwenden. Sie können aber einen 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 Debug-Modus befindet, können wir die debug_cleartext_payload
aus dem Berichttext verwenden um den Bucket-Schlüssel abzurufen.
Kopieren Sie die debug_cleartext_payload
aus dem Berichtstext.
Öffnen Sie goo.gle/ags-payload-decoder und fügen Sie 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.
Jetzt haben wir den Bucket-Schlüssel und können die output_domain.avro
im selben Ordner erstellen, 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 die AVRO-Berichte und die Ausgabedomain erstellt wurden, können Sie die Berichte und die Ausgabedomain in den Bucket in Cloud Storage verschieben (was Sie unter „Voraussetzung 1.6“ notiert 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 dort die Datei output_domain.avro
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.
Wenn Ihr Job aufgrund eines Fehlers fehlschlägt, finden Sie in unserer Dokumentation zur Fehlerbehebung in GitHub weitere Informationen zum weiteren Vorgehen.
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.
{
"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>",
"reporting_site": "<domain of reporting origin(s) of report>", // Only one of attribution_report_to or reporting_site is required as of v2.7.0
"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.
Postman
Für den Endpunkt createJob
ist ein Anfragetext erforderlich, um dem Aggregationsdienst den Speicherort und die Dateinamen aggregierbarer Berichte, Ausgabedomains und Zusammenfassungsberichte bereitzustellen.
Zum „Body“ der createJob
-Anfrage gehen :
Ersetzen Sie die Platzhalter innerhalb 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>/<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>", // Only one of attribution_report_to or reporting_site is required as of v2.7.0
"report_error_threshold_percentage": "10",
"debug_run": "true"
}
}
„Senden“ 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“ die erforderlichen Informationen wie job_status
, return_message
und error_messages
(wenn bei dem Job ein Fehler aufgetreten ist) enthält.
Postman
Mit dem Endpunkt getJob
können Sie den Status der Jobanfrage prüfen. Wählen Sie im Bereich „Parameter“ der getJob
-Anfrage den Wert job_request_id
auf den job_request_id
, der in der createJob
-Anfrage gesendet wurde.
„Senden“ die getJob
-Anfrage:
Das Ergebnis sollte den Status Ihrer Jobanfrage mit dem HTTP-Status 200 zurückgeben. Die Anfrage „Body“ die erforderlichen Informationen wie job_status
, return_message
und error_messages
(wenn bei dem Job ein Fehler aufgetreten ist) enthält.
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.
Codelab abgeschlossen
Zusammenfassung:Sie haben den Zusammenfassungsdienst in Ihrer eigenen Cloud-Umgebung bereitgestellt, einen Debug-Bericht erstellt, eine Ausgabedomaindatei erstellt, diese Dateien in einem Cloud Storage-Bucket gespeichert und einen erfolgreichen Job ausgeführt.
Nächste Schritte:Verwenden Sie den Aggregationsdienst weiterhin in Ihrer Umgebung oder löschen Sie die soeben erstellten Cloud-Ressourcen gemäß der Anleitung zur Bereinigung in Schritt 4.
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: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