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.
W dalszych krokach opisujemy proces odbierania i przechowywania przez usługę agregacji raportów, które można agregować:
- 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.
- Przeglądarka dostarcza zaszyfrowane raporty do adresu URL
.well-knownw domenie raportowania dostawcy technologii reklamowej. - System przekazuje zbiory raportów do usługi agregującej w celu ich przetworzenia.
- Usługa agregująca podsumowuje statystycznie raporty.
- Usługa agregacji dodaje szum do danych podsumowanych, aby zwiększyć prywatność użytkowników.
- 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 |
|
|
| Interfejs Attribution Reporting API |
|
|
Ź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_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 |
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:
Konwertowanie liczby 1369 na jej odpowiednik szesnastkowy: 559
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.
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 zbiorczychin_domain: klucz zasobnika dostępny w pliku Avrooutput_domain