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.

reporting_site i attribution_report_to się wzajemnie wykluczają, 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 zasobinu danych określonego w polu „input_data_bucket_name”, który jest hostowany w przechowywaniu 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 jest zasób danych, do którego wysyłane są output_data. Dane 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 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 wykluczona 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 procesie wdrażania usługi agregacji.
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 procesie wdrażania usługi agregacji. 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 wartością 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 rozdzielona 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 podsumowania raportów i adnotacje, które wskazują, które klucze są obecne w danych wejściowych domeny lub w raportach. Ponadto nie jest też 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 dostawca technologii reklamowej chce sprawdzić 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 Jest 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 jest ustawione na 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 platformy reklamowej, w którym są przechowywane wygenerowane raporty podsumowania. To pole jest ustawione na 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łędzie 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 przetworzenie się nie udało.
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ła, 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ć, zanim zadanie zakończy się niepowodzeniem. 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 podanych jako dane wejściowe do tego zadania. Parametr „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”.