Praca z usługą agregacji w Google Cloud Platform (GCP)

1. 1. Wymagania wstępne

Szacowany czas potrzebny na ukończenie: 1–2 godziny

W tym ćwiczeniu możesz korzystać z 2 trybów: testowania lokalnego lub usługi agregacji. Tryb testowania lokalnego wymaga lokalnego komputera i przeglądarki Chrome (nie trzeba tworzyć ani używać zasobów Google Cloud). Tryb usługi agregacji wymaga pełnego wdrożenia usługi agregacji w Google Cloud.

Aby wykonać to ćwiczenie w dowolnym trybie, musisz spełnić kilka wymagań wstępnych. Każde wymaganie jest odpowiednio oznaczone, aby wskazać, czy jest wymagane w przypadku testów lokalnych czy usługi agregacji.

1.1. Ukończenie rejestracji i atestacjowania (usługa do agregacji)

Aby korzystać z interfejsów API Piaskownicy prywatności, sprawdź, czy masz ukończone rejestrację i atesta w przypadku zarówno Chrome, jak i Androida.

1.2. Włączanie interfejsów API ochrony prywatności w reklamach (lokalna usługa testowania i zbiorczości)

Ponieważ będziemy korzystać z Piaskownicy prywatności, zachęcamy do włączenia interfejsów API reklam w Piaskownicy prywatności.

W przeglądarce otwórz chrome://settings/adPrivacy i włącz wszystkie interfejsy API dotyczące prywatności w reklamach.

Sprawdź też, czy pliki cookie innych firm są włączone.

W witrynie chrome://settings/cookies sprawdź, czy pliki cookie innych firm NIE są blokowane. W zależności od wersji Chrome w tym menu ustawień mogą być widoczne różne opcje, ale dopuszczalne konfiguracje to:

  • „Blokuj wszystkie pliki cookie innych firm” = WYŁĄCZONY
  • „Blokuj pliki cookie innych firm” = WYŁĄCZONY
  • „Blokuj pliki cookie innych firm w trybie incognito” = WŁĄCZONY

Włączanie obsługi plików cookie Włączanie plików cookie

1.3. Pobieranie narzędzia do testowania lokalnego (testowanie lokalne)

Testowanie lokalne wymaga pobrania narzędzia do testowania lokalnego. Na podstawie niezaszyfrowanych raportów debugowania narzędzie wygeneruje raporty podsumowujące.

Narzędzie do testowania lokalnego można pobrać z archiwów JAR funkcji w Cloud na GitHubie. Powinien nazywać się LocalTestingTool_{version}.jar.

1.4. Sprawdź, czy zainstalowano środowisko wykonawcze JAVA JRE (usługa lokalna do testowania i zbiorczości)

Otwórz terminal i użyj polecenia java --version, aby sprawdzić, czy na komputerze jest zainstalowana Java lub openJDK.

Sprawdź wersję Javy. Sprawdź wersję Javy.

Jeśli nie jest zainstalowana, możesz ją pobrać i zainstalować z witryny Java lub witryny openJDK.

1.5. Pobierz narzędzie aggregatable_report_converter (lokalna usługa testowania i agregacji)

Kopie narzędzia aggregatable_report_converter możesz pobrać z repozytorium GitHub z przykładami dotyczącymi Piaskownicy prywatności. Repozytorium GitHuba wspomina o używaniu IntelliJ lub Eclipse, ale żadne z tych narzędzi nie jest wymagane. Jeśli nie używasz tych narzędzi, pobierz plik JAR do środowiska lokalnego.

1.6. Konfigurowanie środowiska Cloud Platform (usługi agregacji)

Usługa agregacji wymaga użycia zaufanego środowiska wykonawczego, które korzysta z usług dostawcy chmury. W tym laboratorium kodu usługa agregacji zostanie wdrożona w Google Cloud, ale obsługiwana jest też usługa AWS.

Aby skonfigurować interfejs wiersza poleceń gcloud, pobrać pliki binarne i moduły Terraform oraz utworzyć zasoby Google Cloud dla usługi agregacji, postępuj zgodnie z instrukcjami wdrożenia na GitHub.

Najważniejsze kroki w instrukcjach wdrażania:

  1. Skonfiguruj interfejs wiersza poleceń „gcloud” i Terraform w swoim środowisku.
  2. Utwórz zasobnik Cloud Storage, w którym będzie przechowywany stan Terraform.
  3. Pobierz zależności.
  4. Zaktualizuj adtech_setup.auto.tfvars i uruchom adtech_setup Terraform. Przykładowy plik adtech_setup.auto.tfvars znajdziesz w Dodatku. Zanotuj nazwę zasobnika danych, który został tutaj utworzony – będzie on używany w codelab do przechowywania tworzonych przez nas plików.
  5. Zaktualizuj dev.auto.tfvars, podaj się za konto usługi wdrożeniowej i uruchom dev Terraform. Przykładowy plik dev.auto.tfvars znajdziesz w Dodatku.
  6. Po zakończeniu wdrażania zapisz frontend_service_cloudfunction_url z danych wyjściowych Terraform. Dane te będą potrzebne do wysyłania żądań do usługi do agregacji w kolejnych krokach.

1.7. Ukończenie rejestracji usługi do agregacji (usługa do agregacji)

Usługa agregacji wymaga wdrożenia dla koordynatorów, aby można było z niej korzystać. Wypełnij formularz wstępnej konfiguracji usługi agregacji, podając witrynę raportowania i inne informacje, wybierając „Google Cloud” i wpisując adres konta usługi. To konto usługi jest tworzone w ramach poprzedniego wymagania wstępnego (1.6. Skonfiguruj środowisko Google Cloud. (Wskazówka: jeśli użyjesz podanych domyślnych nazw, to konto usługi zacznie się od „worker-sa@”).

Proces wprowadzenia może potrwać do 2 tygodni.

1.8. Określ metodę wywoływania punktów końcowych interfejsu API (usługi agregacji)

W tym laboratorium programistycznym znajdziesz 2 opcje wywoływania punktów końcowych interfejsu Aggregation Service API: cURL i Postman. cURL to szybszy i prostszy sposób wywoływania punktów końcowych interfejsu API z terminala, ponieważ wymaga minimalnej konfiguracji i nie wymaga instalowania dodatkowego oprogramowania. Jeśli jednak nie chcesz używać cURL, możesz zamiast tego użyć Postmana do wykonywania i zapisywania żądań interfejsu API na przyszłość.

W sekcji 3.2. Korzystanie z usługi agregacji, w której znajdziesz szczegółowe instrukcje korzystania z obu opcji. Możesz je teraz wyświetlić, aby zdecydować, której metody użyjesz. Jeśli wybierzesz Postman, wykonaj tę początkową konfigurację.

1.8.1. Skonfiguruj obszar roboczy

Załóż konto Postman. Po zarejestrowaniu automatycznie utworzymy dla Ciebie środowisko pracy.

Obszar roboczy Postmana Obszar roboczy Postmana.

Jeśli nie masz utworzonego obszaru roboczego, w górnej części menu kliknij „Obszary robocze” i wybierz „Utwórz obszar roboczy”.

Wybierz „Pusty obszar roboczy”, kliknij Dalej i nadaj mu nazwę „GCP Privacy Sandbox”. Wybierz „Osobiście” i kliknij „Utwórz”.

Pobierz wstępnie skonfigurowany plik konfiguracji JSON i pliki środowiska globalnego.

Za pomocą przycisku „Importuj” zaimportuj oba pliki JSON do „Mojego środowiska pracy”.

Przycisk Importuj. Przycisk Importuj.

Spowoduje to utworzenie kolekcji „GCP Privacy Sandbox” wraz z żądaniami HTTP createJob i getJob.

1.8.2. Autoryzacja konfiguracji

Kliknij kolekcję „GCP Privacy Sandbox” i otwórz kartę „Autoryzacja”.

Przycisk autoryzacji. Przycisk autoryzacji.

Użyjesz metody „Bearer Token”. W środowisku terminala uruchom to polecenie i skopiuj wynik.

gcloud auth print-identity-token

Następnie wklej tę wartość tokena w polu „Token” na karcie autoryzacji w Postman:

Jej Pole „Token”.

1.8.3. Konfigurowanie środowiska

W prawym górnym rogu kliknij „Szybki podgląd środowiska”:

przycisk Szybki przegląd środowiska. Przycisk szybkiego przeglądu środowiska.

Kliknij „Edytuj” i zaktualizuj „Obecną wartość” w przypadku „environment”, „region” i „cloud-function-id”:

Ustaw bieżące wartości. Ustaw bieżące wartości.

Na razie możesz pozostawić pole „request-id” puste, ponieważ wypełnimy je później. W pozostałych polach użyj wartości z frontend_service_cloudfunction_url, które zostały zwrócone po pomyślnym wdrożeniu Terraform w warunku wstępnym 1.6. Adres URL ma taki format: https://--frontend-service--uc.a.run.app

2. 2. Testowanie lokalne – Codelab

Szacowany czas potrzebny na ukończenie: <1 godzina

Możesz użyć lokalnego narzędzia do testowania na swoim komputerze, aby przeprowadzić agregację i wygenerować raporty podsumowujące na podstawie niezaszyfrowanych raportów debugowania. Zanim zaczniesz, sprawdź, czy zostały spełnione wszystkie wymagania wstępne opisane jako „Testowanie lokalne”.

Etapy ćwiczenia z Codelabs

Krok 2.1. Wyzwalanie raportu: wyzwala raport Private Aggregation, aby można było go zebrać.

Krok 2.2. Utwórz raport debugowania AVRO: przekształcaj zebrany raport w formacie JSON w raport w formacie AVRO. Ten krok będzie podobny do tego, gdy specjaliści ds. technologii reklam zbierają raporty z punktów końcowych interfejsu API do raportowania i przekształcają raporty w formacie JSON w raporty w formacie AVRO.

Krok 2.3. Pobieranie kluczy zbiorów: klucze zbiorów są projektowane przez specjalistów ds. technologii reklam. W tym ćwiczeniu zasobniki są zdefiniowane wstępnie, więc pobierz klucze zasobników zgodnie z ich nazwami.

Krok 2.4. Utwórz plik wyjściowy AVRO: po pobraniu kluczy zasobów utwórz plik wyjściowy AVRO.

Krok 2.5. Tworzenie raportu podsumowania: korzystając z narzędzia do testowania lokalnego, możesz tworzyć raporty podsumowania w środowisku lokalnym.

Krok 2.6. Sprawdzanie raportów podsumowujących: sprawdź raport podsumowujący utworzony przez narzędzie do testowania lokalnego.

2.1. Raport o aktywatorach

Aby wywołać raport prywatnego agregacji, możesz użyć witryny demonstracyjnej Piaskownicy prywatności (https://privacy-sandbox-demos-news.dev/?env=gcp) lub własnej witryny (np. https://adtechexample.com). Jeśli używasz własnej witryny i nie masz jeszcze ukończonego procesu rejestracji i atestacji oraz wdrażania usługi agregacji, musisz użyć flagi Chrome i przełącznika w wierszu poleceń.

W tym pokazie użyjemy witryny demonstracyjnej Piaskownicy prywatności. Kliknij link, aby otworzyć stronę, na której możesz wyświetlić raporty: chrome://private-aggregation-internals

Strona Chrome Internals Strona Chrome Internals.

Raport wysłany do punktu końcowego {reporting-origin}/.well-known/private-aggregation/debug/report-shared-storage znajdziesz też w sekcji „Treść raportu” w raportach wyświetlanych na stronie Chrome Internals.

Możesz tu zobaczyć wiele raportów, ale w tym przypadku użyj raportu podlegającego agregacji, który jest specyficzny dla Google Cloud i generowany przez punkt końcowy debugowania. „Adres URL raportu” będzie zawierać „/debug/”, a aggregation_coordinator_origin field w „Tekście raportu” będzie zawierać ten adres URL: https://publickeyservice.msmt.gcp.privacysandboxservices.com.

Raport debugowania Google Cloud. Raport Google Cloud Debug.

2.2. Tworzenie raportu zbiorczego debugowania

Skopiuj raport znaleziony w sekcji „Report Body” (Treść raportu) w chrome://private-aggregation-internals i utwórz plik JSON w folderze privacy-sandbox-demos/tools/aggregatable_report_converter/out/artifacts/aggregatable_report_converter_jar (w repozytorium pobranym w wymaganiach wstępnych 1.5).

W tym przykładzie używamy vim, ponieważ pracujemy w systemie Linux. Możesz jednak użyć dowolnego edytora tekstu.

vim report.json

Wklej raport w miejscu report.json i zapisz plik.

Kod JSON raportu. Kod JSON raportu.

Następnie użyj aggregatable_report_converter.jar, aby utworzyć agregowany raport debugowania. Spowoduje to utworzenie w bieżącym katalogu raportu o nazwie report.avro, który można agregować.

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

2.3. Pobieranie klucza zbioru z raportu

Aby utworzyć plik output_domain.avro, musisz mieć klucze zasobników, które można pobrać z raportów.

Klucze zbiorów są tworzone przez technologię reklamową. W tym przypadku klucze zbiorów tworzy witryna Demo Piaskownicy prywatności. Ponieważ prywatna agregacja danych z tej witryny jest w trybie debugowania, możemy użyć wartości debug_cleartext_payload z sekcji „Treść raportu”, aby uzyskać klucz zbioru.

Skopiuj debug_cleartext_payload z treści raportu.

Debugowanie ładunku w postaci tekstu nieszyfrowanego. Debugowanie ładunku danych w formie tekstu nieszyfrowanego.

Otwórz stronę goo.gle/ags-payload-decoder, wklej dane debug_cleartext_payload w polu „INPUT” (Wejście) i kliknij „Decode” (Odkoduj).

Przycisk dekodowania. Przycisk dekodowania.

Strona zwraca wartość dziesiętną klucza puli. Poniżej znajduje się przykładowy klucz zasobnika.

Przykładowy klucz zasobnika Przykładowy klucz zasobnika.

2.4. Tworzenie domeny wyjściowej AVRO

Gdy mamy już klucz zasobnika, utwórzmy output_domain.avro w tym samym folderze, w którym do tej pory pracowałeś/pracowałaś. Sprawdź, czy klucz zasobnika został zastąpiony przez klucz zasobnika, który został pobrany.

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

Skrypt utworzy plik output_domain.avro w bieżącym folderze.

2,5. Tworzenie raportów podsumowujących za pomocą narzędzia do testów lokalnych

Do utworzenia raportów podsumowania użyjemy pliku LocalTestingTool_{version}.jar pobranego w sekcji Wymagania wstępne 1.3 za pomocą tego polecenia. Zastąp {version} pobraną wersją. Pamiętaj, aby przenieść plik LocalTestingTool_{version}.jar do bieżącego katalogu lub dodać ścieżkę względną, która odwołuje się do bieżącej lokalizacji.

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

Po wykonaniu polecenia powinien pojawić się komunikat podobny do tego. Gdy to nastąpi, zostanie utworzony raport output.avro.

Dane wyjściowe AVRO Dane wyjściowe AVRO

2.6. Sprawdzanie raportu podsumowującego

Utworzony raport podsumowania jest w formacie AVRO. Aby móc je odczytać, musisz przekonwertować je z formatu AVRO na format JSON. W idealnej sytuacji firma zajmująca się technologiami reklamowymi powinna napisać kod, który konwertuje raporty AVRO z powrotem na format JSON.

Do konwertowania raportu AVRO na format JSON użyjemy funkcji aggregatable_report_converter.jar.

java -jar aggregatable_report_converter.jar \
  --request_type convertToJson \
  --input_file output.avro

Zwraca on raport podobny do tego: oraz raport output.json utworzony w tym samym katalogu.

Dane wyjściowe w formacie JSON Dane wyjściowe w formacie JSON

Ćwiczenia z programowania zostały ukończone

Podsumowanie: zebrałeś raport debugowania, utworzył plik domeny wyjściowej i wygenerował raport podsumowujący za pomocą lokalnego narzędzia do testowania, które symuluje zachowanie usługi do agregacji.

Dalsze czynności: po eksperymentowaniu z narzędziem do testowania lokalnego możesz wykonać to samo ćwiczenie z użyciem wdrożenia usługi agregacji w swoim środowisku. Sprawdź wymagania wstępne, aby upewnić się, że wszystko jest skonfigurowane pod kątem trybu „Aggregation Service”, a potem przejdź do kroku 3.

3. 3. Ćwiczenie z programowania dotyczące usługi agregacji

Szacowany czas potrzebny na ukończenie: 1 godzina

Zanim zaczniesz, sprawdź, czy zostały spełnione wszystkie wymagania wstępne opisane jako „Usługa agregacji”.

Etapy ćwiczenia z Codelabs

Krok 3.1. Tworzenie danych wejściowych usługi do agregacji: twórz raporty usługi do agregacji, które są grupowane w partie na potrzeby usługi do agregacji.

  • Krok 3.1.1. Raport o wyzwalaczu
  • Krok 3.1.2. Gromadzenie raportów zbiorczych
  • Krok 3.1.3. Konwertowanie raportów na format AVRO
  • Krok 3.1.4. Tworzenie wyjścia typu AVRO
  • Krok 3.1.5. Przenoszenie raportów do zasobnika Cloud Storage

Krok 3.2. Korzystanie z usługi agregacji: możesz używać interfejsu API usługi agregacji do tworzenia i sprawdzania raportów podsumowujących.

  • Krok 3.2.1. Używanie punktu końcowego createJob do grupowania
  • Krok 3.2.2. Używanie punktu końcowego getJob do pobierania stanu zbiorczego
  • Krok 3.2.3. Sprawdzanie raportu zbiorczego

3.1. Tworzenie danych wejściowych usługi do agregacji

Utwórz raporty AVRO na potrzeby grupowania w usłudze do agregacji. Polecenia powłoki w tych krokach można uruchamiać w Cloud Shell w Google Cloud (o ile zależności z warunków wstępnych są skopiowane do środowiska Cloud Shell) lub w lokalnym środowisku wykonania.

3.1.1. Raport o wyzwalaczu

Kliknij link, aby otworzyć stronę, na której możesz wyświetlić raporty: chrome://private-aggregation-internals

Strona Chrome Internals Strona Chrome Internals

Raport wysłany do punktu końcowego {reporting-origin}/.well-known/private-aggregation/debug/report-shared-storage znajdziesz też w sekcji „Treść raportu” w raportach wyświetlanych na stronie Chrome Internals.

Możesz tu zobaczyć wiele raportów, ale w tym przypadku użyj raportu podlegającego agregacji, który jest specyficzny dla Google Cloud i generowany przez punkt końcowy debugowania. „Adres URL raportu” będzie zawierać „/debug/”, a aggregation_coordinator_origin field w „Tekście raportu” będzie zawierać ten adres URL: https://publickeyservice.msmt.gcp.privacysandboxservices.com.

Raport debugowania Google Cloud. Raport Google Cloud Debug.

3.1.2. Gromadzenie raportów zbiorczych

Zbieraj raporty podlegające agregacji z punktów końcowych .well-known odpowiedniego interfejsu API.

  • Prywatna agregacja: {reporting-origin}/.well-known/private-aggregation/report-shared-storage
  • Attribution Reporting - Summary Report: {reporting-origin}/.well-known/attribution-reporting/report-aggregate-attribution

W tym przypadku zbieranie raportów wykonujemy ręcznie. W środowisku produkcyjnym firmy zajmujące się technologiami reklamowymi powinny zbierać i konwertować raporty programowo.

Skopiuj raport w formacie JSON w polu „Treść raportu” z chrome://private-aggregation-internals.

W tym przykładzie używamy vim, ponieważ korzystamy z Linuksa. Możesz jednak użyć dowolnego edytora tekstu.

vim report.json

Wklej raport w miejscu report.json i zapisz plik.

Raport JSON Raport w formacie JSON

3.1.3. Konwertowanie raportów na format AVRO

Raporty otrzymywane z punktów końcowych .well-known są w formacie JSON i muszą zostać przekonwertowane do formatu raportu AVRO. Gdy masz już raport w formacie JSON, przejdź do miejsca, w którym jest przechowywany plik report.json, i użyj narzędzia aggregatable_report_converter.jar, aby utworzyć agregowany raport debugowania. Spowoduje to utworzenie w bieżącym katalogu raportu o nazwie report.avro, który można agregować.

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

3.1.4. Tworzenie wyjścia typu AVRO

Aby utworzyć plik output_domain.avro, musisz mieć klucze zasobników, które można pobrać z raportów.

Klucze zbiorów są tworzone przez technologię reklamową. W tym przypadku klucze zbiorów tworzy witryna Demo Piaskownicy prywatności. Ponieważ prywatna agregacja danych z tej witryny jest w trybie debugowania, możemy użyć wartości debug_cleartext_payload z sekcji „Treść raportu”, aby uzyskać klucz zbioru.

Skopiuj debug_cleartext_payload z treści raportu.

Debugowanie ładunku w postaci tekstu nieszyfrowanego. Debugowanie ładunku danych w formie tekstu nieszyfrowanego.

Otwórz stronę goo.gle/ags-payload-decoder, wklej dane debug_cleartext_payload w polu „INPUT” (Wejście) i kliknij „Decode” (Odkoduj).

Przycisk dekodowania. Przycisk dekodowania.

Strona zwraca wartość dziesiętną klucza puli. Poniżej znajduje się przykładowy klucz zasobnika.

Przykładowy klucz zasobnika Przykładowy klucz zasobnika.

Gdy mamy już klucz zasobnika, utwórzmy output_domain.avro w tym samym folderze, w którym do tej pory pracowałeś/pracowałaś. Sprawdź, czy klucz zasobnika został zastąpiony przez klucz zasobnika, który został pobrany.

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

Skrypt utworzy plik output_domain.avro w bieżącym folderze.

3.1.5. Przenoszenie raportów do zasobnika Cloud Storage

Po utworzeniu raportów AVRO i domeny wyjściowej przenieś raporty i domenę wyjściową do zasobnika w Cloud Storage (który został utworzony w warunku wstępnym 1.6).

Jeśli masz skonfigurowany interfejs wiersza poleceń gcloud w środowisku lokalnym, użyj tych poleceń, aby skopiować pliki do odpowiednich folderów.

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

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

W przeciwnym razie prześlij pliki ręcznie do zasobnika. Utwórz folder o nazwie „reports” i prześlij do niego plik report.avro. Utwórz folder o nazwie „output_domains” i prześlij do niego plik output_domain.avro.

3.2. Wykorzystanie usługi do agregacji

Pamiętaj, że w sekcji Wstępne wymagania 1.8 wybrano curl lub Postman do wysyłania żądań interfejsu API do punktów końcowych usługi agregacji. Poniżej znajdziesz instrukcje dotyczące obu opcji.

Jeśli zadanie nie zostanie wykonane z powodu błędu, zapoznaj się z naszą dokumentacją na temat rozwiązywania problemów na GitHubie, aby dowiedzieć się, co zrobić dalej.

3.2.1. Używanie punktu końcowego createJob do grupowania

Aby utworzyć zadanie, użyj jednej z tych instrukcji dotyczących curl lub Postman.

curl

W „Terminalu” utwórz plik treści żądania (body.json) i wklej do niego ten obiekt JSON. Pamiętaj o zaktualizowaniu wartości zmiennych. Więcej informacji o tym, co oznaczają poszczególne pola, znajdziesz w dokumentacji interfejsu API.

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

Wykonaj to żądanie. Zastąp zmienne zastępcze w adresie URL żądania curl wartościami z frontend_service_cloudfunction_url, który jest wyświetlany po pomyślnym wdrożeniu Terraform w sekcji Wymagania wstępne 1.6.

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

Gdy usługa agregacji zaakceptuje żądanie, powinna zostać zwrócona odpowiedź HTTP 202. Inne możliwe kody odpowiedzi są opisane w specyfikacji interfejsu API.

Postman

W przypadku punktu końcowego createJob wymagane jest ciało żądania, aby udostępnić usłudze agregacji lokalizację i nazwy plików raportów podlegających agregacji, docelowych domen i raportów zbiorczych.

Otwórz kartę „Body” (Treść) żądania createJob:

Karta Treść Karta Body

Zastąp zmienne w pliku JSON. Więcej informacji o tych polach i ich znaczeniu znajdziesz w dokumentacji interfejsu API.

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

„Wyślij” żądanie interfejsu API createJob:

Przycisk Wyślij Przycisk wysyłania

Kod odpowiedzi znajdziesz w dolnej części strony:

Kod odpowiedzi Kod odpowiedzi

Gdy usługa agregacji zaakceptuje żądanie, powinna zostać zwrócona odpowiedź HTTP 202. Inne możliwe kody odpowiedzi są opisane w specyfikacji interfejsu API.

3.2.2. Używanie punktu końcowego getJob do pobierania stanu zbiorczego

Aby uzyskać zadanie, użyj jednej z tych instrukcji dotyczących curl lub Postman.

curl

Wykonaj w terminalu to żądanie. Zastąp zmienne w adresie URL wartościami z adresu frontend_service_cloudfunction_url, który jest taki sam jak adres URL użyty w żądaniu createJob. W polu „job_request_id” użyj wartości z zadania utworzonego za pomocą punktu końcowego createJob.

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>

Wynik powinien zwracać stan żądania zadania z kodem stanu HTTP 200. W polu „Body” żądania znajdują się niezbędne informacje, takie jak job_status, return_message i error_messages (jeśli zadanie zakończyło się błędem).

Postman

Aby sprawdzić stan żądania zadania, możesz użyć punktu końcowego getJob. W sekcji „Parametres” żądania getJob zaktualizuj wartość job_request_id na job_request_id, która została wysłana w żądaniu createJob.

Identyfikator żądania zadania Identyfikator żądania zadania

„Wyślij” prośbę getJob:

Przycisk Wyślij Przycisk wysyłania

Wynik powinien zwracać stan żądania zadania z kodem stanu HTTP 200. W polu „Body” żądania znajdują się niezbędne informacje, takie jak job_status, return_message i error_messages (jeśli zadanie zakończyło się błędem).

Odpowiedź w formacie JSON Odpowiedź w formacie JSON

3.2.3. Sprawdzanie raportu zbiorczego

Gdy otrzymasz raport podsumowujący w zasobniku Cloud Storage, możesz go pobrać do środowiska lokalnego. Raporty podsumowania są w formacie AVRO i można je przekonwertować z powrotem do formatu JSON. Aby odczytać raport, możesz użyć polecenia aggregatable_report_converter.jar.

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

Zwraca to obiekt JSON z wartościami zbiorczymi każdego klucza zasobnika, który wygląda podobnie do tego:

Raport zbiorczy. Raport zbiorczy.

Jeśli w prośbie createJob uwzględnisz parametr debug_run o wartości true, raport podsumowania znajdziesz w folderze debugowania w folderze output_data_blob_prefix. Raport jest w formacie AVRO i można go przekonwertować na format JSON za pomocą powyższego polecenia.

Raport zawiera klucz zbioru, dane bez szumu oraz szum, który został dodany do danych bez szumu, aby utworzyć raport podsumowujący. Raport wygląda podobnie do tego:

Raport o szumach Raport o szumieniu

Oprócz tego zawierają one również ciągi „in_reports” lub „in_domain” (lub oba), które oznaczają:

  • in_reports – klucz zbioru jest dostępny w raportach podlegających agregacji.
  • in_domain – klucz zasobnika jest dostępny w pliku AVRO domeny wyjściowej.

Ćwiczenia z programowania zostały ukończone

Podsumowanie: usługę Aggregation Service wdrożyłeś(-aś) w własnym środowisku chmurowym, zebrał(-aś) raport debugowania, utworzył(-aś) plik domeny wyjściowej, przechowywał(-aś) te pliki w zasobniku Cloud Storage i uruchomił(-aś) zadanie.

Dalsze kroki: możesz nadal używać usługi agregacji w swoim środowisku lub usunąć utworzone przez siebie zasoby w chmurze, wykonując instrukcje czyszczenia podane w kroku 4.

4. 4. Porządkowanie roszczeń

Aby usunąć zasoby utworzone dla usługi agregacji za pomocą Terraform, użyj polecenia destroy w folderach adtech_setup i dev (lub innym środowisku):

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

Aby usunąć zasobnik Cloud Storage zawierający raporty podlegające agregacji i raporty podsumowujące:

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

Możesz też przywrócić ustawienia plików cookie Chrome z warunku wstępnego 1.2 do poprzedniego stanu.

5. 5. Dodatek

Przykładowy plik adtech_setup.auto.tfvars

/**
 * 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>"

Przykładowy plik dev.auto.tfvars

/**
 * 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