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 do agregacji wymaga pełnego wdrożenia usługi do 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, musisz ukończyć proces rejestracji i atrybucji w przypadku zarówno Chrome, jak i Androida.

1.2. Włącz interfejsy API dotyczące ochrony prywatności w reklamach (usługa lokalnego 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

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 zainstalowana jest JAVA JRE (usługa lokalnego testowania i zbiorczości)

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

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 (usługa do testowania lokalnego i agregacji)

Plik aggregatable_report_converter możesz pobrać z repozytorium GitHub Privacy Sandbox Demos. 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 GCP (usługi do agregacji)

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

Aby skonfigurować interfejs wiersza poleceń gcloud, pobrać binarne i moduły Terraform oraz utworzyć zasoby GCP dla usługi agregacji, wykonaj instrukcje wdrażania na GitHubie.

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 zbierz frontend_service_cloudfunction_url z wyjścia Terraform, którego będziesz potrzebować do wysyłania żądań do usługi agregacji w kolejnych krokach.

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

Aby korzystać z usługi agregacji, należy najpierw wdrożyć ją w grupie koordynowanej. 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 GCP. (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)

Ten warsztat programistyczny 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 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. Aggregation Service Usage, znajdziesz szczegółowe instrukcje dotyczące korzystania z obu opcji. Możesz je teraz wyświetlić, aby określić, 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.

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.

Zaimportuj oba pliki JSON do „Mojego Workspace” za pomocą przycisku „Importuj”.

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

1.8.2. Autoryzacja konfiguracji

Kliknij kolekcję „Piaskownia prywatności GCP”, a potem przejdź do karty „Autoryzacja”.

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:

1.8.3. Konfigurowanie środowiska

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

Kliknij „Edytuj” i zaktualizuj „Wartość bieżąca” w przypadku „environment”, „region” i „cloud-function-id”:

Pole „request-id” możesz na razie pozostawić puste, ponieważ wypełnimy je później. W przypadku pozostałych pól użyj wartości z frontend_service_cloudfunction_url, które zostały zwrócone po pomyślnym wdrożeniu Terraform w sekcji Wymagania wstępne 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

Za pomocą lokalnego narzędzia do testowania na komputerze możesz wykonać agregację i wygenerować podsumowanie raportów za pomocą niezaszyfrowanych raportów debugowania. Zanim zaczniesz, upewnij się, że spełniasz wszystkie wymagania wstępne oznaczone etykietą „Testowanie lokalne”.

Etapy ćwiczenia z Codelabs

Krok 2.1. Wyzwalanie raportu: aby móc zebrać raport, wygeneruj raport prywatny.

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 usługi adtech zbierają 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 zasobników: klucze zasobników są tworzone przez firmy technologiczne. 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 podsumowania: sprawdź raport podsumowania 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 przejść do witryny, w której możesz wyświetlać raporty: chrome://private-aggregation-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 zbiorczego, który jest specyficzny dla GCP 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.

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.

Następnie 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 zsumować.

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 firmę adTech. W tym przypadku jednak klucze zbiorów tworzy witryna Demo Piaskownicy prywatności. Ponieważ prywatne agregacje na tej stronie są 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.

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

Strona zwraca wartość dziesiętną klucza puli. Poniżej znajduje się 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ś. Pamiętaj, aby zastąpić klucz zasobnika wyodzyskanym 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

Do utworzenia raportów podsumowujących użyjemy pliku LocalTestingTool_{version}.jar pobranego w sekcji Wymagania wstępne 1.3. Aby to zrobić, użyj podanego niżej 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 poniżej. Gdy to nastąpi, zostanie utworzony raport output.avro.

2.6. Sprawdzanie raportu podsumowującego

Utworzony raport podsumowujący jest w formacie AVRO. Aby móc je odczytać, musisz przekonwertować je z formatu AVRO na format JSON. W idealnej sytuacji firma adTech powinna napisać kod, który konwertuje raporty AVRO z powrotem na format JSON.

Do konwertowania raportu AVRO na format JSON użyjemy narzędzia aggregatable_report_converter.jar.

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

Zwraca to raport podobny do tego poniżej. oraz raport output.json utworzony w tym samym katalogu.

Ć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 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, upewnij się, że 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: tworzenie raportów usługi do agregacji, które są grupowane w pakiety na potrzeby usługi do agregacji.

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

Krok 3.2. Korzystanie z usługi do agregacji: za pomocą interfejsu API usługi do agregacji możesz tworzyć raporty podsumowujące i je przeglądać.

• 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 do grupowania w usłudze agregacji. Polecenia powłoki w tych instrukcjach można wykonywać w Cloud Shell w GCP (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 aktywatorach

Kliknij link, aby przejść do witryny, w której możesz wyświetlać raporty: chrome://private-aggregation-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 zbiorczego, który jest specyficzny dla GCP 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.

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 odbywa się ręcznie. W środowisku produkcyjnym systemy adTech powinny zbierać i konwertować raporty za pomocą programów komputerowych.

Skopiuj raport w formacie JSON w sekcji „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.

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 raport JSON jest już dostępny, 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 zsumować.

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

3.1.4. Tworzenie wyjściowego typu danych AVRO

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

Klucze zbiorów są projektowane przez firmę adTech. W tym przypadku jednak klucze zbiorów tworzy witryna Demo Piaskownicy prywatności. Ponieważ prywatne agregacje na tej stronie są 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.

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

Strona zwraca wartość dziesiętną klucza puli. Poniżej znajduje się 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ś. Pamiętaj, aby zastąpić klucz zasobnika wyodzyskanym 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ł utworzony w warunku wstępnym 1.6).

Jeśli masz skonfigurowany interfejs wiersza poleceń gcloud w środowisku lokalnym, użyj podanych niżej 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 agregacji

Pamiętaj, że w sekcji Wstępny wymóg 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 GitHub, aby dowiedzieć się, jak postępować dalej.

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

Aby utworzyć zadanie, wykonaj instrukcje dotyczące cURL lub Postmana podane poniżej.

cURL

W programie „Terminal” utwórz plik z treścią żądania (body.json) i wklej go poniżej. Pamiętaj, aby zaktualizować 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_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"
  }
}

Wykonaj poniższe żądanie. Zastąp zmienne zastępcze w adresie URL żądania cURL wartościami z wartości frontend_service_cloudfunction_url, która jest wyświetlana 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:

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

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

Kod odpowiedzi znajdziesz w dolnej części strony:

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, postępuj zgodnie z instrukcjami cURL lub Postmana podanymi poniżej.

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. Sekcja „Body” żądania zawiera niezbędne informacje, takie jak job_status, return_message i error_messages (jeśli wystąpił błąd).

Postman

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

„Wyślij” prośbę getJob:

Wynik powinien zwracać stan żądania zadania z kodem stanu HTTP 200. Sekcja „Body” żądania zawiera niezbędne informacje, takie jak job_status, return_message i error_messages (jeśli wystąpił błąd).

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:

Jeśli żądanie createJob zawiera wartość debug_run równą „true”, raport podsumowania możesz otrzymać w folderze debugowania w folderze output_data_blob_prefix. Raport jest w formacie AVRO i można go przekonwertować na format JSON za pomocą podanego powyżej polecenia.

Raport zawiera klucz zbioru, dane bez szumu oraz szum dodany do danych bez szumu, aby utworzyć raport podsumowujący. Raport wygląda podobnie do tego poniżej.

Zawierają one też atrybuty „in_reports” lub „in_domain”, które oznaczają:

• in_reports – klucz zbiornika 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ś/wdrożyłaś w własnym środowisku chmurowym, zebrałeś/zebrałaś raport debugowania, utworzyłeś/utworzyłaś plik domeny wyjściowej, przechowywałeś/przechowywałaś te pliki w zasobniku Cloud Storage i uruchomiłeś/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 podsumowania:

$ 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