Ta strona została przetłumaczona przez Cloud Translation API.

Otrzymywanie raportów zbiorczych do sklepu

Gdy technologie reklamowe wywołują interfejsy API do pomiarów (Attribution Reporting API lub Private Aggregation API), zaszyfrowane raporty są wysyłane z przeglądarki Chrome lub klienta do punktu końcowego raportowania danej technologii reklamowej, czyli adresu URL .well-known z pochodzącym z niej źródłem raportowania. Punkt końcowy raportowania jest hostowany przez firmę zajmującą się technologiami reklamowymi, aby zbierać zaszyfrowane raporty.

Schemat raportu AgS

Oto punkty końcowe dla każdego interfejsu API:

Agregacja prywatna
- Debugowanie [reporting-origin]/.well-known/private-aggregation/debug/report-shared-storage
- Na żywo [reporting-origin]/.well-known/private-aggregation/report-shared-storage lub /.well-known/private-aggregation/report-protected-audience
Attribution Reporting
- Debugowanie [reporting-origin]/.well-known/attribution-reporting/debug/report-aggregate-attribution
- Na żywo [reporting-origin]/.well-known/attribution-reporting/report-aggregate-attribution

Firmy z branży technologii reklamowych będą otrzymywać raporty w formacie JSON za pomocą wywołania POST. Technologie reklamowe będą zbierać te raporty JSON, a następnie konwertować je na format AVRO, który jest używany w usłudze agregacji. Po przekonwertowaniu raporty AVRO są przechowywane w chmurze dostawcy technologii reklamowej na potrzeby późniejszego zbiorczego przetwarzania.

Gdy usługa adtech będzie gotowa do zbiorczego przetwarzania danych, wyśle żądanie zadania agregacji za pomocą usługi agregacji, w której raporty są pobierane z miejsca w chmurze usługi adtech. Usługa agregacji jest hostowana w chmurze w chmurze technologii reklamowej i powinna zawierać obraz z listy dozwolonych.

Otrzymane zgłoszenia wyglądają mniej więcej tak:

Private Aggregation API

  {
    "aggregation_coordinator_origin": "https://publickeyservice.msmt.aws.privacysandboxservices.com",
    "aggregation_service_payloads": [ {
        "key_id": "1a2baa3f-5d48-46cf-91f0-772633c12640",
        "payload": "8Cjr1s3FVkCYkjzBvyzJn14yardVjd5N4vLCA69LQAPbIkJ0B58hAqUGBCNXpvTjW9ZpIoZbCSiUOsUDuoA/S+tqVolLMkame6sWC07cfUmZcVsbU+La3pzTMtCgdtNc8MIWgD3C63CMw7rWroRlechewVUajvAYVK/0HJq0YyGrTiFZZm36zi0jjyHLAXKV8p1Lvy1d0o/wnBxC5oVo5BV6LPkxqQEcoYS2GyixUuht6wD0RzuH+BxxuH6vY/ynp2xDrnwftjvqwDUAxUWLFTunthM6BXZVxlrvOBim1h2dvPqWSyKZ5gafo+MgW9EM4SraavNM3XzZSCjdtAfSMJMrynSu2j0opyAq+9e1jq1xeYN00yZrJ0Y/GTI45IGjgCnVmvmuoI9ucW2SnXP31CQBwHqk4gtUgMsYGFSUYfhtnAQ/8TSbaXyS2LX+cQW87LqkvIraWw6o37O24VFBreFoFFXpu3IUeCZfji+Sr4/ykfZuHeMzQbBavyNnHKzPZlbLSXMiucx4/vWzYyOzHeIlbtupXVvbi40V2PieDShaSbjI266kGgFkeCk6z51AaAGebDPtRT1lhBpcoQ6JdF0Yp5VWSnyFARKFtCZ1aEBrlUlrEHLUQY/pFtmDxJQiicRz1YPjR8jRr3C7hlRhWwov0dMocqnMz5209hHGVZWSsaGc9kWjtxREW2ULXfoIwOGbX+WZsyFW2RhXksQPJ5fhyNc4ROkAzUthLb68gC5e0yZHvmLIAU4hcWe0UanJv+jRljn8PAPaJHKFUxQNJyBA7mTbn5mkpycxGrX6T3ZYdPHqvckqt9llJZWjr8NneizzZFRuJk423BDs38fXkvcTAsAckd2Zu0u2KC45WR93sN2/CWrqB7/QU9BsgNdonl/ehAWhU1LbcRRvBTcR9+0wL7vRL7cv5LG3+gRYRKsWI6U2nDSWp0cNpo9+HU0JNiifa5X0cguihqU2bSk6ABozgRtCZ7m+7eqWXMLSzBdmc1CPUoQppo6Wmf6ujdNqI6v2S6pDH781lph8Z2v7ZpxGdhVVPEL51cVn"
    } ],
    "debug_key": "1234",
    "shared_info": "{\"api\":\"shared-storage\",\"report_id\":\"05e3b948-cb8d-4404-be29-bfeac7ad9710\",\"reporting_origin\":\"https://privacy-sandbox-demos-dsp.dev\",\"scheduled_report_time\":\"1707784729\",\"version\":\"0.1\"}"
  }

Attribution Reporting API.

  {
    "aggregation_coordinator_origin": "https://publickeyservice.msmt.aws.privacysandboxservices.com",
    "aggregation_service_payloads": [ {
        "key_id": "2dee0f3f-2aee-4a4a-8238-9154ed3d6f72",
        "payload": "pHvTHhcxvNKaCmnLpvYQsXlJpiNRuFO5Zj1QqUlqgWPOfuoHLfiXiFjmpvY8a53/OYnS4bKwHwJReFcofldsu8E9BzTTJ3CEk+B7vbEjnDPaljhpIBMTuQXy3QHGK4slWR/yNZVm2uXRWR/DVVzXziBoTDjN7qaPstRoLKUUMdfY2u8oq4tnLY00Y+NDZttZ4wJvC7hPmvY3lqHjdl14JPD2ytZZ4NViYzno3WKdH/oZc0jhGK4zI38lAM0qpahF/B9yb4zOu7IRIjQpNx73P8naDyddxLldoVlW/qHpO04FguWymscvI/8i6NwUR6Kj8seRlWS0iIUhETt/ai3lilKUHUb+uz0YG2kxjoXq7Ldk+MP56nNl67ZRNi2YZ7bOGI/okYWoT/wt2uWPe/5xAEMmadxl0hQQrG7YXHRSD8rDnaVPXo+AKIxdg727yJeB1ZENZvovl/kIevdRAmdBe2h1U3J6Uz6psly/46fvjgkj5QD+kO2uaYirzvmwS19luJsN/Qvh/R3ZO4qlJIQI0nDJPWwUJ4ODpyVmj4a0xQp3t2ESEnf4EmY7+khn3xpF5+MwEWKES2ZeDf7SHalR99pvZA8G3Fr8M0PWFmT00cmKCBwpQgZyd3Eay70UlqdkbFEedxiCVWKNNOUz41m5KG/7K3aR+dYx57l57Wct4gOFQg3jiUEBJWrFIVCXf12BT5iz5rBQh1N1CUt2oCOhYL/sPuBl6OV5GWHSIj8FUdpoDolqKXWINXfE88MUijE2ghNRpJN25BXIErUQtO9wFQv7zotC6d2BIaF0x8AkKg/7yzBQRySX/FZP3H3lMkpOz9rQMV8DjZ2lz7nV4k6CFo8qhT6cpYJD7GpYl81xJbglNqcJt5Pe5YUHrdBMyAFsTh3yoJvYnhQib/0xVN/a93lbYccxsd0yi375n4Xz0i1HUoe2ps+WlU8XysAUA1agG936eshaY1anTtbJbrcoaH+BNSacKiq4saprgUGl4eDjaR/uBhvUnO52WkmAGon8De3EFMZ/kwpPBNSXi7/MIAMjotsSKBc19bfg"
    } ],
    "shared_info": "{\"api\":\"attribution-reporting\",\"attribution_destination\":\"https://privacy-sandbox-demos-shop.dev\",\"report_id\":\"5b052748-f5fb-4f14-b291-de03484ed59e\",\"reporting_origin\":\"https://privacy-sandbox-demos-dsp.dev\",\"scheduled_report_time\":\"1707786751\",\"source_registration_time\":\"0\",\"version\":\"0.1\"}",
    "source_debug_key": "123456789",
    "trigger_debug_key": "123456789"
  }

Konwertowanie danych w formacie JSON na raporty AVRO

W przypadku zbiorczego przetwarzania raporty podlegające agregacji muszą być w formacie AVRO. Aby utworzyć raport AVRO, musisz mieć schemat AVSC (AVRO) raportu.

Przykładowy kod JavaScript jest dostępny w repozytorium usługi agregacji na GitHubie.

Możesz utworzyć 1 plik AVRO dla wszystkich raportów lub podzielić raporty na wiele plików AVRO. Rozmiar pliku AVRO nie jest ograniczony. Ze względu na wydajność zalecamy, aby liczba plików AVRO nie przekraczała 1000 – liczba procesorów dostępnych dla instancji Cloud.

Poniżej znajduje się schemat AVRO dla raportów agregowanych. Poszczególne pola raportów to payload, key_id i shared_info.

  {
    "type": "record",
    "name": "AggregatableReport",
    "fields": [
      {
        "name": "payload",
        "type": "bytes"
      },
      {
        "name": "key_id",
        "type": "string"
      },
      {
        "name": "shared_info",
        "type": "string"
      }
    ]
  }

Parametr	Typ	Opis
`payload`	Bajty	Na potrzeby raportów bieżących / produkcyjnych ładunek musi być zdekodowany w base64 i przekonwertowany na tablicę bajtów z `payload`.
`debug_cleartext_payload`	Bajty	Na potrzeby raportów na temat debugowania ładunek musi być zdekodowany w base64 i przekonwertowany na tablicę bajtów z `debug_cleartext_payload`.
`key_id`	Ciąg znaków	Będzie to ciąg znaków key_id znaleziony w raporcie. key_id będzie 128-bitowym identyfikatorem uniwersalnym podobnym do UUID.
`shared_info`	Ciąg znaków	Będzie to nienaruszony ciąg znaków znaleziony w polu shared_info raportu.

Oto przykładowy plik JSON raportu:

{ 
   "aggregation_coordinator_identifier": "aws-cloud",      
   "aggregation_service_payloads": [{ 
      "debug_cleartext_payload": "omRkYXhgaJldmFsdWVEAAAAgGZidWNrZXRQAAAAAAAAAAAAAAAAAAAFWW1vcGVyYX", 
      "key_id": "3c6e2850-edf6-4886-eb70-eb3f2a7a7596",
      "payload": "oapYz92Mb1yam9YQ2AnK8dduTt2RwFUSApGcKqXnG1q+aGXfJ5DGpSxMj0NxdZgp7Cq" 
   }],
   "debug_key": "1234", 
   "shared_info":
"{\"api\":\"shared-storage\",\"debug_mode\":\"enabled\",\"report_id\":\"b029b922-93e9-4d66-a8c6-8cdeec762aed\",\"reporting_origin\":\"https://privacy-sandbox-demos-dsp.dev\",\"scheduled_report_time\":\"1719251997\",\"version\":\"0.1\"}"
}

AVRO domeny wyjściowej

Aby generować raporty podsumowujące za pomocą usługi agregacji, technologie reklamowe wymagają raportów agregowanych i pliku domeny. Raporty agregowane będą pochodzić z raportów JSON otrzymanych w źródle raportowania i przekonwertowanych na format AVRO. Domeny wyjściowe będą zawierać zadeklarowane wcześniej klucze, które zostaną zebrane z raportów podlegających agregacji i zapisane w raportach podsumowań. Dowiedz się więcej o tych kluczach w raportach atrybucji i kluczach w przypadku agregacji prywatnej. Domena wyjściowa będzie zawierać pole zbioru, a wartość zbioru będzie kluczem zbioru.

Plik domeny musi też być w formacie AVRO z użyciem tego schematu:

  {
    "type": "record",
    "name": "AggregationBucket",
    "fields": [
      {
        "name": "bucket",
        "type": "bytes",
        "doc": "A single bucket that appears in the aggregation service output. 128-bit integer encoded as a 16-byte big-endian bytestring."
      }
    ]
  }

Klucz zasobnika

Klucz zasobnika powinien być szesnastkowym ciągiem bajtów klucza zasobnika. Przykładem może być klucz 1369 w systemie dziesiętnym. Po przekonwertowaniu na szesnastki otrzymasz 559. Następnie musisz przekonwertować wartość 559 na ciąg bajtów, który zostanie dodany do domeny wyjściowej AVRO.

Schemat kluczy zasobnika AgS

Raporty zbiorcze

Więcej informacji o budżetach na potrzeby ochrony prywatności i grupowaniu znajdziesz w dokumencie na temat strategii grupowania. Pamiętaj też, że raport agregowany można grupować tylko w określonym przedziale czasu. Raport nie może przekraczać wartości MAX_REPORT_AGE w okresie od scheduled_report_time do daty uruchomienia partii (obecnie 90 dni).

Raporty zbiorcze

Po zakończeniu grupowania usługa agregacji tworzy raport podsumowujący w formacie AVRO. Raport podsumowujący korzysta ze schematu results.avsc.

Raport podsumowujący będzie się znajdował w folderze output_data_blob_prefix w zasobniku output_data_bucket_name wskazanym w żądaniu createJob.

W przypadku zbiorów danych usługi agregacji, w których włączono debug_run, tworzy 2 raporty. Raport Podsumowanie i raport Podsumowanie debugowania. Raport z podsumowaniem debugowania będzie się znajdował w folderze output_data_blob_prefix/debug.

Wygenerowany raport debugowania używa schematu debug_results.avsc.

Zarówno podsumowanie, jak i raport debugowania będą miały nazwę [output_data_blob_prefix]-1-of-1.avro. Jeśli prefiks wyjściowe_data_blob_prefix to summary/summary.avro, raport będzie się znajdował w folderze podsumowania o nazwie summary-1-of-1.avro.

results.avsc

{
  "type": "record",
  "name": "AggregatedFact",
  "fields": [
    {
      "name": "bucket",
      "type": "bytes",
      "doc": "Histogram bucket used in aggregation. 128-bit integer encoded as a 16-byte big-endian bytestring. Leading 0-bits will be left out."
    },
    {
      "name": "metric",
      "type": "long",
      "doc": "Metric associated with the bucket"
    }
  ]
}

debug_results.avsc

  {
  "type": "record",
  "name": "DebugAggregatedFact",
  "fields": [
      {
        "name": "bucket",
        "type": "bytes",
        "doc": "Histogram bucket used in aggregation. 128-bit integer encoded as a 16-byte big-endian bytestring. Leading 0-bits will be left out."
      },
      {
        "name": "unnoised_metric",
        "type": "long",
        "doc": "Unnoised metric associated with the bucket."
      },
      {
        "name": "noise",
        "type": "long",
        "doc": "The noise applied to the metric in the regular result."
      }
      {
        "name":"annotations",
        "type": {
          "type": "array",
          "items": {
            "type":"enum",
            "name":"bucket_tags",
            "symbols":["in_domain","in_reports"]
          }
       }
    ]
  }

Po przekonwertowaniu raport podsumowania będzie wyglądać jak przykładowy results.json. Gdy debug_run jest włączony, raport z debugowaniem zwraca dane podobne do przykładu debug_results.json.

results.json (przykład)

Raporty AVRO pochodzące z usługi agregacji mogą wyglądać podobnie tam, gdzie jest klucz zasobnika oraz wartość podsumowania / dane zbiorcze z dodanym szumem wartości zasobników.

  {
    "bucket": "\u0005Y",
    "metric": 26308
  }

debug_results.json (przykład)

Raporty debugowania AVRO pochodzące z usługi agregacji powinny wyglądać podobnie do tego, w którym otrzymujesz klucze zbiorów unnoised_metric (podsumowanie kluczy zbiorów bez szumu) i szum dodawany do unnoised_metric.

  {
    "bucket": "\u0005Y",
    "unnoised_metric": 128,
    "noise": -17948,
    "annotations": [
      "in_reports",
      "in_domain"
    ]
  }

Oprócz tego adnotacje będą zawierać in_reports lub in_domain, co oznacza:

in_reports: klucz zasobnika jest dostępny w raportach agregowanych.
in_domain: klucz zasobnika jest dostępny w pliku output_domain AVRO