otrzymywać i przechowywać raporty podlegające agregacji;

Z tego przewodnika dowiesz się, jak szyfrowane raporty z danymi o pomiarach są dostarczane dostawcom technologii reklamowych. Przeglądarki i klienci Chrome wysyłają te raporty do wyznaczonych punktów końcowych raportowania, gdzie platforma reklamowa otrzymuje i przechowuje raporty z możliwością agregacji. Te punkty końcowe, które znajdują się pod adresami URL .well-known w ramach origin raportowania dostawcy, są hostowane przez platformę, co umożliwia dostawcom technologii reklamowych korzystanie z nich za pomocą interfejsu Attribution Reporting API lub interfejsu Private Aggregation API.

Proces odbierania i przechowywania raportów zbiorczych w ramach usługi agregacji Piaskownicy prywatności.
Rysunek 1. Usługa do agregacji: przetwarzanie raportów zbiorczych.

W dalszych krokach opisujemy proces odbierania i przechowywania przez usługę agregacji raportów, które można agregować:

  1. Gdy zostanie wywołany, przeglądarka wysyła raporty, które można agregować, zawierające szczegóły dotyczące danych dotyczących konwersji i danych z wielu witryn.
  2. Przeglądarka dostarcza zaszyfrowane raporty do adresu URL .well-known w domenie raportowania dostawcy technologii reklamowej.
  3. System przekazuje zbiory raportów do usługi agregującej w celu ich przetworzenia.
  4. Usługa agregująca podsumowuje statystycznie raporty.
  5. Usługa agregacji dodaje szum do danych podsumowanych, aby zwiększyć prywatność użytkowników.
  6. System udostępnia raporty firmie zajmującej się technologiami reklamowymi na potrzeby analizy i pomiarów.

Tabela poniżej zawiera opis punktów końcowych do debugowania i produkcyjnych interfejsu Private Aggregation API oraz interfejsu Attribution Reporting API:

Interfejs API Punkt końcowy Opis
Interfejs Private Aggregation API
Punkt końcowy debugowania:
[reporting-origin]/.well-known/private-aggregation/debug/report-shared-storage
Punkty końcowe w czasie rzeczywistym:
  • [reporting-origin]/.well-known/private-aggregation/report-shared-storage
  • [reporting-origin]/.well-known/private-aggregation/report-protected-audience
Punkt końcowy debugowania:
Do tworzenia i testowania interfejsu Private Aggregation API.
Punkty końcowe w czasie rzeczywistym:
Otrzymuje i przetwarza raporty pomiarowe w środowiskach produkcyjnych
Interfejs Attribution Reporting API
Punkt końcowy debugowania:
[reporting-origin]/.well-known/attribution-reporting/debug/report-aggregate-attribution
Punkt końcowy w produkcji:
[reporting-origin]/.well-known/attribution-reporting/report-aggregate-attribution
Punkt końcowy debugowania:
Do tworzenia i testowania interfejsu Attribution Reporting API.
Punkty końcowe w czasie rzeczywistym:
  • Punkt końcowy w wersji produkcyjnej służący do generowania raportów atrybucji zbiorczych.
  • Odbiera i przetwarza raporty zbiorcze o przypisaniu w środowiskach produkcyjnych na potrzeby pomiarów.

Źródła danych do raportowania otrzymują raporty w formacie JSON za pomocą wywołań POST. Następnie system przekształca te raporty w format Avro i przechowuje je w chmurze. Po przetworzeniu zbiorczym system wysyła raporty Avro do usługi agregującej w celu ich podsumowania.

Gdy partia raportów Avro jest gotowa do przetwarzania, platformy adtech wysyłają do usługi agregującej żądanie wykonania zadania agregacji. Ta usługa hostowana w środowisku chmury platformy technologicznej reklam pobiera wymagane raporty Avro z tego samego miejsca w usłudze magazynu. Ze względów bezpieczeństwa usługa agregacji musi być skonfigurowana tak, aby używać zatwierdzonego obrazu kontenera. Dostępne obrazy kontenera znajdziesz w repozytorium GitHub piaskownicy prywatności/usługi agregacji.

Poniżej znajdziesz przykłady raportów zwróconych przez poszczególne interfejsy API:

  • Przykład raportu 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\"}"
  }
  • Przykład raportu 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 JSON na raporty Avro

Raporty podlegające agregacji muszą być w formacie serializacji danych Apache Avro, aby można je było grupować. Aby utworzyć raport Avro, musisz użyć schematu AVSC. Plik schematu AVSC definiuje strukturę rekordu Avro i typ danych. Przykład schematu AVSC znajdziesz w pliku example.avsc w tym repozytorium GitHub avrodoc/schemata.

Przykładowy kod JavaScript znajdziesz w sekcji Zbieranie, przekształcanie i zbiorcze raportów na stronie Zbieranie i zbiorcze zbiorczych raportów w repozytorium GitHub privacysandbox/aggregation-service.

Możesz przechowywać wszystkie raporty w jednym pliku AVRO lub rozdzielić je na kilka plików. Pliki AVRO nie mają limitu rozmiaru, ale optymalną wydajność osiąga się zwykle wtedy, gdy liczba plików mieści się w zakresie od liczby procesorów w Twoim wystąpieniu w chmurze do 1000.

Poniższy przykład kodu pokazuje schemat Avro dla raportów możliwych do zgrupowania. Pola raportu to payload, key_idshared_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 Wartość payload musi zostać zdekodowana z formatu Base64 i przekształcona w tablicę bajtów w przypadku raportów na żywo lub produkcyjnych.
debug_cleartext_payload Bajty Dane muszą być zdekodowane z formatu Base64 i przekształcone w tablicę bajtów z debug_cleartext_payload na potrzeby raportów debugowania.
key_id Ciąg znaków To jest ciąg znaków key_id znaleziony w raporcie. key_id to 128-bitowy uniwersalny identyfikator.
shared_info Ciąg znaków To niezmieniony, nienaruszony ciąg znaków znaleziony w polu shared_info raportu.

Oto przykładowy raport w formacie JSON:

{
   "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\"}"
}

Specyfikacja pliku domeny

Generowanie raportów zbiorczych za pomocą usługi agregacji wymaga raportów możliwych do zsumowania (raportów w formacie JSON przekonwertowanym na Avro) oraz powiązanego pliku domeny. System wyodrębnia z raportów podlegających agregacji zadeklarowane wcześniej klucze i włącza je do raportów podsumowania w domenach danych wyjściowych. Szczegółowe informacje o tych kluczowych kluczach agregacji znajdziesz w artykule Kluczowe informacje o kluczach agregacji w raportowaniu atrybucji oraz w sekcji Klucz agregacji w artykule Podstawy interfejsu Private Aggregation API. Domena wyjściowa zawiera też pole bucket, które reprezentuje wartość klucza zasobnika.

Plik domeny musi 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. It is an 128-bit integer value encoded as a 16-byte big-endian bytestring."
      }
    ]
  }

Klucz zasobnika

Klucz zasobnika w domenie wyjściowej musi być reprezentowany jako ciąg bajtów szesnastkowych.

Na przykład:

Jeśli klucz zbioru to wartość dziesiętna 1369:

  1. Konwertowanie liczby 1369 na jej odpowiednik szesnastkowy: 559

  2. Konwertuje ciąg szesnastkowy „559” na ciąg bajtów.

Ten ciąg bajtów reprezentujący klucz zasobnika powinien zostać uwzględniony w schemacie Avro domeny wyjściowej.

Ważne kwestie:

  • Typ danych: klucz zasobnika w schemacie Avro powinien być zdefiniowany jako typ bajtowy, aby uwzględnić reprezentację ciągu bajtów szesnastkowych.

  • Konwersja: konwersję z dziesiętkowego na szesnastkowy, a potem na ciąg bajtów można zaimplementować w języku Python lub Java.

Dzięki temu klucz puli ma prawidłowy format i jest zgodny z oczekiwanym typem danych w schemacie Avro dla domeny wyjściowej.

Klucz zasobnika powinien być szesnastkowym ciągiem bajtów. Weźmy na przykład ciąg bajtów o wartości dziesiętnej 1369. Po przekonwertowaniu na format szesnastkowy wartość ta wynosi 559 i jest dodawana do domeny wyjściowej Avro.
Rysunek 2. Diagram ilustrujący przekształcenie klucza puli w reprezentację szesnastkową, a następnie w postaci ciągu bajtów, która jest ostatecznie używana do wypełniania schematu AVRO domeny wyjściowej.

Raporty zbiorcze

Szczegółowe informacje o budżetach na prywatność i strategiach zbiorczego przetwarzania znajdziesz w dokumentacji dotyczącej strategii zbiorczego przetwarzania. Pamiętaj, że raporty, które można agregować, mają limit MAX_REPORT_AGE (obecnie 90 dni) między wartością scheduled_report_time a datą uruchomienia partii.

Raporty podsumowujące

Po zgrupowaniu danych usługa Aggregation Service tworzy raport podsumowujący w formacie Avro, korzystając ze schematu results.avsc.

Po zakończeniu zadania raport podsumowania jest przechowywany w zasośniku output_data_blob_prefix w zasośniku output_data_bucket_name zgodnie z żądaniem createJob.

W przypadku partii usługi agregującej, w których włączono opcję debug_run, tworzy 2 raporty: raport z podsumowaniem i raport z podsumowaniem debugowania. Raport Podsumowanie debugowania znajduje się w folderze output_data_blob_prefix/debug. Raport Podsumowanie debugowania używa schematu debug_results.avsc.

Zarówno raport z podsumowaniem, jak i raport debugowania mają nazwę [output_data_blob_prefix]-1-of-1.avro. Jeśli output_data_blob_prefix to summary/summary.avro, raport znajduje się w folderze podsumowania o nazwie summary-1-of-1.avro.

results.avsc – przykład

Oto przykładowy schemat Avro dla results.avsc:

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

Przykładowy schemat Avro definiuje rekord o nazwie AggregatedFact.

debug_results.avsc – przykład

Poniżej znajdziesz przykład schematu Avro dla debug_results.avsc:

  {
  "type": "record",
  "name": "DebugAggregatedFact", Output domains include summary reports that contain pre-declared keys extracted from your aggregatable reports.
  "fields": [
      {
        "name": "bucket",
        "type": "bytes",
        "doc": "This represents the histogram bucket used in aggregation. It's a 128-bit integer, encoded as a 16-byte big-endian bytestring, with leading zero bytes omitted.."
      },
      {
        "name": "unnoised_metric",
        "type": "long",
        "doc": "The raw metric for 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 raportu podsumowania będzie on wyglądał podobnie do przykładu results.json. Gdy włączona jest opcja debug_run, raport podsumowania debugowania zwraca dane podobne do tych w przykładzie debug_results.json.

Format raportów Avro

Raporty Avro otrzymywane z usługi agregującej zwykle są zgodne z określonym formatem. Format raportu Avro zawiera te pola:

  • bucket: niepowtarzalny identyfikator agregacji danych (np. „\u0005Y”).

  • metric: zsumowana wartość dla odpowiedniego zbioru. Ta wartość często zawiera dodany szum, aby zwiększyć prywatność.

    Na przykład:

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

debug_results.json – przykład

Debugowanie raportów Avro z usługi agregacji będzie wyglądać podobnie do tego przykładu debug_results.json. Te raporty zawierają klucze zakresów, wartość unnoised_metric (podsumowanie wartości kluczy zakresów przed zastosowaniem szumu) oraz wartość szumu dodana do tego rodzaju danych.

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

Oprócz tego adnotacje zawierają te wartości:

  • in_reports: klucz zbioru dostępny w raportach zbiorczych

  • in_domain: klucz zasobnika dostępny w pliku Avro output_domain