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

1. 1. Wymagania wstępne

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

Ten przewodnik możesz przejść w 2 trybach: testowania lokalnego lub usługi agregacji. Tryb testowania lokalnego wymaga komputera lokalnego i przeglądarki Chrome (nie wymaga tworzenia ani używania 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. Dokończ rejestrację i potwierdzenie (usługa do agregacji)

Aby korzystać z interfejsów API Piaskownicy prywatności, sprawdź, czy masz ukończony proces rejestracji i atestowania zarówno w Chrome, jak i na Androidzie.

1.2. Włącz interfejsy API ochrony prywatności w reklamach (testowanie lokalne i usługa agregacji)

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

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

Sprawdź też, czy masz włączoną obsługę plików cookie innych firm.

W sekcji 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 akceptowane konfiguracje to:

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

  Włączanie plików cookie

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

Testy lokalne wymagają pobrania narzędzia do testów lokalnych. Narzędzie wygeneruje raporty podsumowujące na podstawie niezaszyfrowanych raportów debugowania.

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

1.4. Sprawdź, czy jest zainstalowane środowisko JAVA JRE (usługa testowania lokalnego i usługa agregacji)

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

Sprawdź wersję Javy.

Jeśli nie jest zainstalowana, możesz ją pobrać i zainstalować ze strony Javy lub strony openJDK.

1.5. Pobieranie narzędzia aggregatable_report_converter (testowanie lokalne i usługa do agregacji)

Kopię narzędzia aggregatable_report_converter możesz pobrać z repozytorium GitHub z Wersjami demonstracyjnymi Piaskownicy prywatności. W repozytorium GitHub jest mowa o używaniu IntelliJ lub Eclipse, ale nie jest to wymagane. Jeśli nie korzystasz z tych narzędzi, pobierz plik JAR do środowiska lokalnego.

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

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

Aby skonfigurować gcloud CLI, pobrać pliki binarne i moduły Terraform oraz utworzyć zasoby Google Cloud na potrzeby usługi agregacji, postępuj zgodnie z instrukcjami wdrażania w 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ład pliku adtech_setup.auto.tfvars znajdziesz w Dodatku. Zanotuj nazwę utworzonego tutaj zasobnika danych – będzie ona używana w tym laboratorium do przechowywania tworzonych przez nas plików.
5. Zaktualizuj dev.auto.tfvars, podaj się za konto usługi wdrażania i uruchom Terraform dev. Przykład pliku dev.auto.tfvars znajdziesz w Dodatku.
6. Po zakończeniu wdrażania zarejestruj frontend_service_cloudfunction_url z danych wyjściowych Terraform. Będzie on potrzebny do wysyłania żądań do usługi do agregacji w dalszych krokach.

1.7. Dokończ rejestrację w usłudze do agregacji (usługa do agregacji)

Aby korzystać z usługi agregacji, musisz przejść proces wprowadzania koordynatorów. Wypełnij formularz rejestracji w usłudze agregacji, podając witrynę raportującą 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. konfigurowanie środowiska Google Cloud, (Wskazówka: jeśli używasz domyślnych nazw, to konto usługi będzie zaczynać się od „worker-sa@”).

Proces dołączania do programu może potrwać do 2 tygodni.

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

Ten przewodnik zawiera 2 opcje wywoływania punktów końcowych interfejsu API usługi agregacji: cURL i Postman. cURL to szybszy i łatwiejszy sposób wywoływania punktów końcowych interfejsu API z terminala, ponieważ wymaga minimalnej konfiguracji i nie wymaga dodatkowego oprogramowania. Jeśli jednak nie chcesz używać cURL, możesz zamiast tego użyć Postmana do wykonywania i zapisywania żądań interfejsu API do wykorzystania w przyszłości.

W sekcji 3.2. Wykorzystanie usługi agregacji, znajdziesz szczegółowe instrukcje korzystania z obu opcji. Możesz teraz wyświetlić podgląd tych metod, aby zdecydować, której z nich użyjesz. Jeśli wybierzesz Postman, wykonaj te czynności wstępne.

1.8.1. Skonfiguruj obszar roboczy

Załóż konto Postman. Po zarejestrowaniu się automatycznie utworzymy dla Ciebie przestrzeń roboczą.

Obszar roboczy Postman.

Jeśli obszar roboczy nie zostanie utworzony, kliknij „Obszary robocze” na górnym pasku nawigacyjnym i wybierz „Utwórz obszar roboczy”.

Wybierz „Pusty obszar roboczy”, kliknij Dalej i nadaj mu nazwę „GCP Piaskownica prywatności”. Wybierz „Osobiste” i kliknij „Utwórz”.

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

Zaimportuj oba pliki JSON do sekcji „Mój obszar roboczy” za pomocą przycisku „Importuj”.

Przycisk Importuj.

Spowoduje to utworzenie kolekcji „GCP Piaskownica prywatności” wraz z żądaniami HTTP createJob i getJob.

1.8.2. Autoryzacja konfiguracji

Kliknij kolekcję „Piaskownica prywatności GCP” i otwórz kartę „Authorization” (Autoryzacja).

Przycisk autoryzacji.

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

gcloud auth print-identity-token

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

Pole „Token”.

1.8.3. Konfigurowanie środowiska

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

Przycisk szybkiego podglądu środowiska.

Kliknij „Edytuj” i zaktualizuj „Bieżącą wartość” parametrów „environment”, „region” i „cloud-function-id”:

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 pliku frontend_service_cloudfunction_url, który został zwrócony po pomyślnym zakończeniu wdrażania Terraform w ramach wymagania wstępnego 1.6. Adres URL ma ten format: https://--frontend-service--uc.a.run.app

2. 2. Ćwiczenie z programowania dotyczące testowania lokalnego

Szacowany czas potrzebny na ukończenie samouczka: <1 godzina

Możesz użyć narzędzia do testowania lokalnego na swoim urządzeniu, 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 oznaczone jako „Testowanie lokalne”.

Kroki ćwiczeń

Krok 2.1. Raport wyzwalający: wyzwala raportowanie Private Aggregation, aby umożliwić zbieranie raportu.

Krok 2.2. Utwórz raport debugowania AVRO: przekonwertuj zebrany raport JSON na raport w formacie AVRO. Ten krok będzie podobny do sytuacji, w której dostawcy technologii reklamowych pobierają raporty z punktów końcowych interfejsu API do raportowania i konwertują raporty w formacie JSON na raporty w formacie AVRO.

Krok 2.3. Pobieranie kluczy segmentów: klucze segmentów są projektowane przez dostawców technologii reklamowych. W tym laboratorium, ponieważ zasobniki są wstępnie zdefiniowane, pobierz klucze zasobników zgodnie z podanymi informacjami.

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

Krok 2.5. Utwórz raport podsumowujący: użyj narzędzia do testowania lokalnego, aby utworzyć raporty podsumowujące w środowisku lokalnym.

Krok 2.6. Sprawdź raporty podsumowujące: zapoznaj się z raportem podsumowującym utworzonym przez narzędzie do testowania lokalnego.

2.1. Raport aktywatora

Aby wywołać raport prywatnej 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 ukończonej rejestracji i atestowania oraz wdrożenia usługi agregacji, musisz użyć flagi Chrome i przełącznika wiersza poleceń.

W tym przykładzie użyjemy witryny demonstracyjnej Piaskownicy prywatności. Kliknij link, aby przejść do witryny, a potem wyświetlić raporty na stronie chrome://private-aggregation-internals:

Strona wewnętrzna Chrome.

Raport wysyłany do punktu końcowego {reporting-origin}/.well-known/private-aggregation/debug/report-shared-storage znajduje się też w sekcji „Treść raportu” w raportach wyświetlanych na stronie Wewnętrzne informacje o Chrome.

Możesz tu zobaczyć wiele raportów, ale w tym laboratorium użyj raportu z możliwością 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 „treści raportu” będą zawierać ten adres URL: https://publickeyservice.msmt.gcp.privacysandboxservices.com.

Raport debugowania Google Cloud.

2.2. Tworzenie raportu z możliwością agregacji do debugowania

Skopiuj raport z sekcji „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 sekcji Wymagania wstępne 1.5).

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

vim report.json

Wklej raport do report.json i zapisz plik.

Kod JSON raportu.

Gdy to zrobisz, użyj aggregatable_report_converter.jar, aby utworzyć raport z możliwością debugowania. Spowoduje to utworzenie w bieżącym katalogu raportu z możliwością agregacji o nazwie report.avro.

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

2.3. Pobieranie klucza zasobnika z raportu

Aby utworzyć plik output_domain.avro, potrzebujesz kluczy zasobnika, które można pobrać z raportów.

Klucze segmentów są projektowane przez technologię reklamową. W tym przypadku klucze segmentów tworzy jednak witryna Privacy Sandbox Demo. Prywatna agregacja w przypadku tej witryny jest w trybie debugowania, więc możemy użyć debug_cleartext_payload z sekcji „Treść raportu”, aby uzyskać klucz segmentu.

Skopiuj debug_cleartext_payload z treści raportu.

Debuguj ładunek w formie tekstu nieszyfrowanego.

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

Przycisk dekodowania.

Strona zwraca wartość dziesiętną klucza segmentu. Oto przykładowy klucz do kosza.

Przykładowy klucz zasobnika.

2.4. Tworzenie domeny wyjściowej AVRO

Mamy już klucz zasobnika, więc utwórzmy plik output_domain.avro w tym samym folderze, w którym pracowaliśmy. Sprawdź, czy zastępujesz klucz zasobnika pobranym kluczem zasobnika.

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

Aby utworzyć raporty podsumowujące, użyjemy pobranego w sekcji Wymagania wstępne 1.3 pliku LocalTestingTool_{version}.jar. Wpisz to polecenie: Zastąp {version} pobraną wersją. Pamiętaj, aby przenieść LocalTestingTool_{version}.jar do bieżącego katalogu lub dodać ścieżkę względną, aby odwołać się do jego bieżącej lokalizacji.

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

Po uruchomieniu polecenia zobaczysz coś podobnego do tego. Po zakończeniu tego procesu zostanie utworzony raportoutput.avro.

Dane wyjściowe AVRO

2.6. Sprawdzanie raportu podsumowującego

Utworzony raport podsumowujący jest w formacie AVRO. Aby to zrobić, musisz przekonwertować plik z formatu AVRO na format JSON. Najlepiej, aby dostawca technologii reklamowej napisał kod, który przekonwertuje raporty AVRO z powrotem na format JSON.

Użyjemy aggregatable_report_converter.jar, aby przekonwertować raport AVRO z powrotem na format JSON.

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

Zwróci to raport podobny do tego poniżej. wraz z raportem output.json utworzonym w tym samym katalogu.

Wyjściowy plik JSON

Ćwiczenia z programowania ukończone

Podsumowanie: zebrano raport debugowania, utworzono plik domeny wyjściowej i wygenerowano raport podsumowujący za pomocą lokalnego narzędzia testowego, które symuluje zachowanie agregacji usługi do agregacji.

Dalsze kroki: po przeprowadzeniu eksperymentu z narzędziem do testowania lokalnego możesz spróbować wykonać to samo ćwiczenie z wdrożoną na żywo usługą Aggregation Service w swoim środowisku. Sprawdź jeszcze raz wymagania wstępne, aby upewnić się, że wszystko zostało skonfigurowane w trybie „Usługa agregacji”, a potem przejdź do kroku 3.

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

Szacowany czas potrzebny na ukończenie samouczka: 1 godzina

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

Kroki ćwiczeń

Krok 3.1. Tworzenie danych wejściowych usługi do agregacji: tworzenie raportów usługi do agregacji, które są przesyłane do usługi do agregacji w partiach.

• Krok 3.1.1. Raport o aktywatorach
• Krok 3.1.2. Zbieranie raportów zbiorczych
• Krok 3.1.3. Konwertowanie raportów na format AVRO
• Krok 3.1.4. Tworzenie pliku AVRO output_domain
• Krok 3.1.5. Przenoszenie raportów do zasobnika Cloud Storage

Krok 3.2. Wykorzystanie usługi agregacji: używaj interfejsu Aggregation Service API do tworzenia raportów podsumowujących i ich przeglądania.

• Krok 3.2.1. Używanie punktu końcowego createJob do przetwarzania wsadowego
• Krok 3.2.2. Używanie punktu końcowego getJob do pobierania stanu pakietu
• Krok 3.2.3. Sprawdzanie raportu podsumowującego

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

Następnie utwórz raporty AVRO do przetwarzania wsadowego w usłudze do agregacji. Polecenia powłoki w tych krokach można uruchamiać w Cloud Shell Google Cloud (o ile zależności z sekcji Wymagania wstępne zostaną sklonowane do środowiska Cloud Shell) lub w lokalnym środowisku wykonawczym.

3.1.1. Raport o aktywatorach

Kliknij link, aby przejść do witryny, a potem wyświetlić raporty na stronie chrome://private-aggregation-internals:

Strona wewnętrzna Chrome

Raport wysyłany do punktu końcowego {reporting-origin}/.well-known/private-aggregation/debug/report-shared-storage znajduje się też w sekcji „Treść raportu” w raportach wyświetlanych na stronie Wewnętrzne informacje o Chrome.

Możesz tu zobaczyć wiele raportów, ale w tym laboratorium użyj raportu z możliwością 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 „treści raportu” będą zawierać ten adres URL: https://publickeyservice.msmt.gcp.privacysandboxservices.com.

Raport debugowania Google Cloud.

3.1.2. Zbieranie raportów zbiorczych

Zbierz raporty, które można agregować, z punktów końcowych .well-known odpowiedniego interfejsu API.

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

W tym samouczku zbieramy raporty ręcznie. W środowisku produkcyjnym firmy zajmujące się technologiami reklamowymi będą programowo zbierać i konwertować raporty.

Skopiujmy raport JSON w sekcji „Treść raportu” z chrome://private-aggregation-internals.

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

vim report.json

Wklej raport do report.json i zapisz plik.

 Raport 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 na format raportu AVRO. Gdy uzyskasz raport JSON, przejdź do miejsca, w którym jest przechowywany plik report.json, i użyj aggregatable_report_converter.jar, aby utworzyć raport z możliwością agregacji do debugowania. Spowoduje to utworzenie w bieżącym katalogu raportu z możliwością agregacji o nazwie report.avro.

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

3.1.4. Tworzenie pliku AVRO output_domain

Aby utworzyć plik output_domain.avro, potrzebujesz kluczy zasobnika, które można pobrać z raportów.

Klucze segmentów są projektowane przez technologię reklamową. W tym przypadku klucze segmentów tworzy jednak witryna Privacy Sandbox Demo. Prywatna agregacja w przypadku tej witryny jest w trybie debugowania, więc możemy użyć debug_cleartext_payload z sekcji „Treść raportu”, aby uzyskać klucz segmentu.

Skopiuj debug_cleartext_payload z treści raportu.

Debuguj ładunek w formie tekstu nieszyfrowanego.

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

Przycisk dekodowania.

Strona zwraca wartość dziesiętną klucza segmentu. Oto przykładowy klucz do kosza.

Przykładowy klucz zasobnika.

Mamy już klucz zasobnika, więc utwórzmy plik output_domain.avro w tym samym folderze, w którym pracowaliśmy. Sprawdź, czy zastępujesz klucz zasobnika pobranym kluczem zasobnika.

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ł zapisany w punkcie 1.6 w sekcji Wymagania wstępne).

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

Przypomnij sobie, że w sekcji Wymagania wstępne 1.8 wybrano narzędzie curl lub Postman do wysyłania żądań interfejsu API do punktów końcowych usługi agregacji. Instrukcje dotyczące obu opcji znajdziesz poniżej.

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

3.2.1. Używanie punktu końcowego createJob do przetwarzania wsadowego

Aby utworzyć zadanie, skorzystaj z jednej z tych instrukcji dotyczących curl lub Postmana.

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 oznacza każde pole, znajdziesz w tej 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 symbole zastępcze w adresie URL żądania curl wartościami z frontend_service_cloudfunction_url, które są wyświetlane po pomyślnym zakończeniu wdrażania 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 zwrócić odpowiedź HTTP 202. Inne możliwe kody odpowiedzi są udokumentowane w specyfikacjach interfejsu API.

Postman

W przypadku punktu końcowego createJob wymagany jest tekst żądania, aby przekazać Usłudze agregacji lokalizację i nazwy plików raportów podlegających agregacji, domeny wyjściowe i raporty podsumowujące.

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

Karta Treść

Zastąp zmienne w podanym 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 do interfejsu API createJob:

Przycisk wysyłania

Kod odpowiedzi znajdziesz w dolnej części strony:

Kod odpowiedzi

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

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

Aby uzyskać zadanie, skorzystaj z jednej z tych instrukcji dotyczących curl lub Postmana.

curl

Wykonaj to żądanie w terminalu. Zastąp symbole zastępcze w adresie URL wartościami z frontend_service_cloudfunction_url, czyli tego samego adresu URL, którego używasz w przypadku żądania createJob. W przypadku parametru „job_request_id” użyj wartości 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 zwrócić stan żądania zadania z kodem stanu HTTP 200. Żądanie „Body” zawiera 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 prośby o wykonanie zadania, możesz użyć punktu końcowego getJob. W sekcji „Params” w żądaniu getJob zmień wartość job_request_id na wartość job_request_id, która została wysłana w żądaniu createJob.

Identyfikator żądania zadania

„Wyślij” prośbę getJob:

Przycisk wysyłania

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

Odpowiedź JSON

3.2.3. Sprawdzanie raportu podsumowującego

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

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

Zwraca plik JSON z zagregowanymi wartościami każdego klucza zasobnika, który wygląda podobnie do tego poniżej.

Raport zbiorczy.

Jeśli w Twoim createJobżądaniu parametr debug_run ma wartość „true”, raport podsumowujący otrzymasz w folderze debugowania znajdującym się w 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 segmentu, dane bez szumu i szum dodany do danych bez szumu w celu utworzenia raportu zbiorczego. Raport jest podobny do tego poniżej.

Raport z szumem

Adnotacje zawierają też wartość „in_reports” lub „in_domain” (albo obie te wartości), co oznacza:

• in_reports – klucz segmentu jest dostępny w raportach zbiorczych.
• in_domain – klucz zasobnika jest dostępny w pliku AVRO output_domain.

Ćwiczenia z programowania ukończone

Podsumowanie: usługa agregacji została wdrożona we własnym środowisku chmurowym, zebrano raport debugowania, utworzono plik domeny wyjściowej, zapisano te pliki w zasobniku Cloud Storage i uruchomiono zadanie.

Dalsze kroki: nadal korzystaj z usługi agregacji w swoim środowisku lub usuń utworzone zasoby w chmurze, postępując zgodnie z instrukcjami czyszczenia w kroku 4.

4. 4. Porządkowanie roszczeń

Aby usunąć zasoby utworzone na potrzeby usługi Aggregation Service za pomocą Terraform, użyj polecenia destroy w folderach adtech_setup i dev (lub w 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 możliwe do agregowania i raporty podsumowujące:

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

Możesz też przywrócić poprzedni stan ustawień plików cookie w Chrome, które zostały zmienione w ramach wymagania 1.2.

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