Wdrażanie żądań i zarządzanie nimi za pomocą usługi agregacji

Po udanym wdrożeniu usługi agregacji możesz używać punktów końcowych createJob i getJob do interakcji z tą usługą. Na schemacie poniżej przedstawiono architekturę wdrożenia tych 2 punktów końcowych:

Omówienie interfejsu API usługi do agregacji
Rysunek 1.Omówienie interfejsu Aggregation Service API

Więcej informacji o punktach końcowych createJob i getJob znajdziesz w dokumentacji interfejsu Aggregation Service API.

Tworzenie zadania

Aby utworzyć zadanie, wyślij żądanie POST do punktu końcowego createJob. bash POST https://<api-gateway>/stage/v1alpha/createJob -+Przykład treści żądania createJob:

{
  "job_request_id": "<job_request_id>",
  "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
  "input_data_bucket_name": "<input_bucket_name>",
  "output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
  "output_data_bucket_name": "<output_bucket_name>",
  "job_parameters": {
    "output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
    "output_domain_bucket_name": "<output_domain_bucket_name>",
    "attribution_report_to": "<reporting origin of report>",
    "reporting_site": "<host name of reporting origin>"
  }
}

Pomyślne utworzenie zadania powoduje zwrócenie kodu stanu HTTP 202.

Pamiętaj, że atrybuty reporting_site i attribution_report_to wykluczają się nawzajem, więc wymagany jest tylko jeden z nich.

Możesz też poprosić o debugowanie, dodając debug_run do job_parameters. Więcej informacji o trybie debugowania znajdziesz w dokumentacji dotyczącej debugowania agregacji.

{
  "job_request_id": "<job_request_id>",
  "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
  "input_data_bucket_name": "<input_bucket_name>",
  "output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
  "output_data_bucket_name": "<output_bucket_name>",
  "job_parameters": {
    "output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
    "output_domain_bucket_name": "<output_domain_bucket_name>",
    "attribution_report_to": "<reporting origin of report>"
    "debug_run": "true"
  }
}

Pola żądania

Parametr Typ Opis
job_request_id Ciąg znaków Jest to unikalny identyfikator wygenerowany przez technologię reklamową. Powinien on składać się z liter ASCII o długości nieprzekraczającej 128 znaków. To pole identyfikuje żądanie zadania zbiorczego i pobiera wszystkie raporty AVRO nadające się do agregacji określone w polu „input_data_blob_prefix” z zasośnika wejściowego określonego w polu „input_data_bucket_name”, który jest hostowany w magazynie danych w chmurze usługi adtech.
Znaki: `a-z, A-Z, 0-9, !"#$%&'()*+,-./:;<=>?@[\]^_`{}~
input_data_blob_prefix Ciąg znaków To jest ścieżka do zasobnika. W przypadku pojedynczych plików możesz użyć ścieżki. W przypadku wielu plików możesz użyć prefiksu w ścieżce.
Przykład: folder/plik zbiera wszystkie raporty z folderu/plik1.avro, folderu/plik/plik1.avro i folderu/plik1/test/plik2.avro.
input_data_bucket_name Ciąg znaków To zasobnik danych wejściowych lub raportów możliwych do agregacji. Pliki te są przechowywane w chmurze dostawcy technologii reklamowej.
output_data_blob_prefix Ciąg znaków To jest ścieżka wyjściowa w zasośniku. Obsługiwany jest 1 plik wyjściowy.
output_data_bucket_name Ciąg znaków To miejsce na dane, do którego wysyłane są output_data. Pliki te znajdują się w chmurze dostawcy technologii reklamowej.
job_parameters Słownik Pole wymagane. To pole zawiera różne pola, takie jak:
  • output_domain_blob_prefix
  • output_domain_bucket_name
  • attribution_report_to
  • reporting_site
  • debug_privacy_epsilon
  • report_error_threshold_percentage
job_parameters.output_domain_blob_prefix Ciąg znaków Podobnie jak w przypadku parametru input_data_blob_prefix, jest to ścieżka w folderze output_domain_bucket_name, w którym znajduje się domena wyjściowa AVRO. W przypadku wielu plików możesz użyć prefiksu w ścieżce. Gdy usługa agregacji zakończy pracę nad zbiorem, zostanie utworzony raport podsumowania i przesłany do zasobnika wyjściowego output_data_bucket_name o nazwie output_data_blob_prefix.
job_parameters.output_domain_bucket_name Ciąg znaków To jest zasób danych dla pliku AVRO w domenie wyjściowej. Pliki te są przechowywane w chmurze dostawcy technologii reklamowej.
job_parameters.attribution_report_to Ciąg znaków Ta wartość jest wzajemnie wykluczająca się z wartością „reporting_site”. Jest to adres URL raportu lub źródło raportu, z którego raport został otrzymany. Miejsce pochodzenia witryny jest zarejestrowane w usłudze Aggregation Service Onboarding.
job_parameters.reporting_site Ciąg znaków Wzajemnie się wykluczają z opcją attribution_report_to. To nazwa hosta adresu URL raportu lub źródła raportu, z którego raport został otrzymany. Miejsce pochodzenia witryny jest zarejestrowane w usłudze Aggregation Service Onboarding. Uwaga: w ramach jednego żądania możesz przesłać wiele raportów pochodzących z różnych źródeł, pod warunkiem że wszystkie źródła należą do tej samej witryny raportowania określonej w tym parametrze.
job_parameters.debug_privacy_epsilon zmiennoprzecinkowa, podwójna, Pole opcjonalne. Jeśli nie podasz żadnej wartości, zostanie użyta wartość domyślna (10). Wartość może wynosić od 0 do 64.
job_parameters.report_error_threshold_percentage Podwójne Pole opcjonalne. Maksymalny odsetek nieudanych raportów, zanim zadanie zakończy się niepowodzeniem. Jeśli zostawisz to pole puste, wartość domyślna to 10%.
job_parameters.input_report_count wartość długości, Pole opcjonalne. Łączna liczba raportów podanych jako dane wejściowe zadania. Ta wartość w połączeniu z opcją report_error_threshold_percentage umożliwia wcześniejsze zakończenie zadania, gdy raporty są wykluczane z powodu błędów.
job_parameters.filtering_ids Ciąg znaków Pole opcjonalne. Lista niekwalifikowanych identyfikatorów filtrowania rozdzielonych przecinkami. Wszystkie wkłady inne niż pasujący identyfikator filtra są odfiltrowywane. (np. "filtering_ids": "12345,34455,12"). Wartością domyślną jest 0.
job_parameters.debug_run Wartość logiczna Pole opcjonalne. Podczas debugowania generowane są zafałszowane i niezafałszowane podsumowanie raportów i adnotacje, które wskazują, które klucze są obecne w danych wejściowych domeny lub w raportach. Ponadto nie jest wymagane, aby duplikaty w różnych partiach były unikalne. Pamiętaj, że debugowanie uwzględnia tylko raporty z oznaczeniem "debug_mode": "enabled". Od wersji 2.10.0 debugowanie nie zużywa budżetu na potrzeby prywatności.

Pobieranie zadania

Gdy specjalista ds. technologii reklamowych chce się dowiedzieć, jaki jest stan żądanego zbioru, może wywołać punkt końcowy getJob. Punkt końcowy getJob jest wywoływany za pomocą żądania HTTPS GET z parametrem job_request_id.

  GET https://<api-gateway>/stage/v1alpha/getJob?job_request_id=<job_request_id>

Powinieneś otrzymać odpowiedź z informacją o stanie zadania oraz ewentualnymi komunikatami o błędach:

{
    "job_status": "FINISHED",
    "request_received_at": "2023-07-17T19:15:13.926530Z",
    "request_updated_at": "2023-07-17T19:15:28.614942839Z",
    "job_request_id": "PSD_0003",
    "input_data_blob_prefix": "reports/output_reports_2023-07-17T19:11:27.315Z.avro",
    "input_data_bucket_name": "ags-report-bucket",
    "output_data_blob_prefix": "summary/summary.avro",
    "output_data_bucket_name": "ags-report-bucket",
    "postback_URL": "",
    "result_info": {
        "return_code": "SUCCESS",
        "return_message": "Aggregation job successfully processed",
        "error_summary": {
            "error_counts": [],
            "error_messages": []
        },
        "finished_at": "2023-07-17T19:15:28.607802354Z"
    },
    "job_parameters": {
        "debug_run": "true",
        "output_domain_bucket_name": "ags-report-bucket",
        "output_domain_blob_prefix": "output_domain/output_domain.avro",
        "attribution_report_to": "https://privacy-sandcastle-dev-dsp.web.app"
    },
    "request_processing_started_at": "2023-07-17T19:15:21.583759622Z"
}

Pola odpowiedzi

Parametr Typ Opis
job_request_id Ciąg znaków To unikalny identyfikator zadania lub partii określony w żądaniu createJob.
job_status Ciąg znaków To jest stan żądania zadania.
request_received_at Ciąg znaków Czas otrzymania żądania.
request_updated_at Ciąg znaków Czas ostatniej aktualizacji zadania.
input_data_blob_prefix Ciąg znaków To jest prefiks danych wejściowych ustawiony w polu createJob.
input_data_bucket_name Ciąg znaków To zasobnik danych wejściowych platformy reklamowej, w którym są przechowywane raporty podlegające agregacji. To pole ma wartość createJob.
output_data_blob_prefix Ciąg znaków To prefiks danych wyjściowych ustawiony w pozycji createJob.
output_data_bucket_name Ciąg znaków To zasobnik danych wyjściowych usługi reklamowej, w którym są przechowywane wygenerowane raporty podsumowujące. To pole ma wartość createJob.
request_processing_started_at Ciąg znaków Czas rozpoczęcia ostatniej próby przetwarzania. Nie uwzględnia czasu oczekiwania w kolejce zadań. (Całkowity czas przetwarzania = request_updated_at – request_processing_started_at)
result_info Słownik Jest to wynik createJob żądania i zawiera wszystkie dostępne informacje. Pokazuje wartości return_code, return_message, finished_at i error_summary.
result_info.return_code Ciąg znaków Kod zwracany przez zadanie. Te informacje są potrzebne do rozwiązania problemu, jeśli wystąpi problem z usługą agregacji.
result_info.return_message Ciąg znaków Zwracany jest komunikat o powodzeniu lub niepowodzeniu zadania. Te informacje są też potrzebne do rozwiązania problemów z usługą agregacji.
result_info.error_summary Słownik Błędy zwracane przez zadanie. Zawiera on liczbę raportów wraz z typami napotkanych błędów.
result_info.finished_at Sygnatura czasowa Sygnatura czasowa wskazująca ukończenie zadania.
result_info.error_summary.error_counts Lista Zwraca listę komunikatów o błędach wraz z liczbą raportów, które nie zostały przesłane z powodu tego samego komunikatu o błędzie. Każda liczba błędów zawiera kategorię error_count i description.
result_info.error_summary.error_messages Lista Zwraca listę komunikatów o błędach z raportów, których nie udało się przetworzyć.
job_parameters Słownik Zawiera parametry zadania podane w żądaniu createJob. Właściwości takie jak `output_domain_blob_prefix` i `output_domain_bucket_name`.
job_parameters.attribution_report_to Ciąg znaków Wzajemnie się wykluczają z opcją reporting_site. To adres URL raportu lub źródło, z którego raport został otrzymany. Źródło należy do witryny zarejestrowanej w ramach procesu wdrażania usługi agregacji. Jest to określone w żądaniu createJob.
job_parameters.reporting_site Ciąg znaków Wzajemnie się wykluczają z opcją attribution_report_to. To nazwa hosta adresu URL raportu lub źródło, z którego raport został otrzymany. Źródło należy do witryny zarejestrowanej w ramach procesu wdrażania usługi agregacji. Pamiętaj, że w jednym żądaniu możesz przesyłać raporty z wielu źródeł, o ile wszystkie źródła należą do tej samej witryny wymienionej w tym parametrze. Jest to określone w żądaniu createJob. Upewnij się też, że grupa zawiera tylko te raporty, które chcesz agregować w momencie tworzenia zadania. Przetwarzane są wszystkie raporty dodane do zasobnika danych wejściowych, których źródła danych pasują do witryny raportowania określonej w parametrze zadania. Usługa agregacji uwzględnia tylko raporty w zasośniku danych, które pasują do zarejestrowanego źródła raportowania zadania. Jeśli na przykład zarejestrowane źródło to https://exampleabc.com, uwzględniane są tylko raporty z https://exampleabc.com, nawet jeśli grupa zawiera raporty z subdomen (https://1.exampleabc.com itp.) lub z zupełnie innych domen (https://3.examplexyz.com).
job_parameters.debug_privacy_epsilon zmiennoprzecinkowa, podwójna, Pole opcjonalne. Jeśli nie podasz żadnej wartości, zostanie użyta wartość domyślna 10. Wartości mogą wynosić od 0 do 64. Ta wartość jest określona w żądaniu createJob.
job_parameters.report_error_threshold_percentage Podwójne Pole opcjonalne. To jest próg procentowy raportów, które mogą się nie udać przed niepowodzeniem zadania. Jeśli nie przypiszesz żadnej wartości, zostanie użyta wartość domyślna 10%. Jest to określone w żądaniu createJob.
job_parameters.input_report_count Długa wartość Pole opcjonalne. Łączna liczba raportów dostarczonych jako dane wejściowe do tego zadania. Wartość parametru report_error_threshold_percentage w połączeniu z tą wartością powoduje przedwczesne zakończenie zadania, jeśli znaczna liczba raportów została wykluczona z powodu błędów. To ustawienie jest określone w żądaniu createJob.
job_parameters.filtering_ids Ciąg znaków Pole opcjonalne. Lista niekwalifikowanych identyfikatorów filtrowania rozdzielonych przecinkami. Wszystkie wkłady inne niż pasujący identyfikator filtra są odfiltrowywane. Jest to określone w żądaniu createJob. (np. "filtering_ids":"12345,34455,12". Wartość domyślna to „0”.