Menerima dan menyimpan laporan agregat

Panduan ini menjelaskan cara laporan pengukuran terenkripsi dikirim ke penyedia teknologi iklan. Browser dan klien Chrome mengirimkan laporan ini ke endpoint pelaporan yang ditetapkan, tempat platform teknologi iklan menerima dan menyimpan laporan agregat. Endpoint ini, yang terletak di URL .well-known dalam origin pelaporan penyedia, dihosting oleh platform, sehingga penyedia teknologi iklan yang menggunakan Attribution Reporting API atau Private Aggregation API dapat mengaksesnya.

Langkah-langkah berikut menjelaskan proses Layanan Agregasi untuk menerima dan menyimpan laporan agregat:

1. Saat dipicu, browser akan mengirimkan laporan gabungan yang berisi detail tentang data lintas situs dan konversi.
2. Browser mengirimkan laporan terenkripsi ke URL .well-known dalam domain pelaporan teknologi iklan.
3. Sistem meneruskan batch laporan ke Layanan Agregasi untuk diproses.
4. Layanan Agregasi merangkum laporan secara statistik.
5. Layanan Agregasi menambahkan derau ke data ringkasan untuk meningkatkan privasi pengguna.
6. Sistem ini menyediakan laporan kepada perusahaan teknologi iklan untuk tujuan analisis dan pengukuran.

Tabel berikut menjelaskan endpoint debug dan live untuk Private Aggregation API dan Attribution Reporting API:

Asal pelaporan menerima laporan JSON melalui panggilan POST. Sistem kemudian mengubah laporan ini menjadi format Avro dan menyimpannya di cloud storage. Setelah pemrosesan batch, sistem akan mengirimkan laporan Avro ke Layanan Agregasi untuk dibuat ringkasannya.

Platform teknologi iklan memicu permintaan tugas agregasi ke Layanan Agregasi saat sekumpulan laporan Avro dianggap siap diproses. Layanan ini, yang dihosting dalam lingkungan cloud platform teknologi iklan, mengambil laporan Avro yang diperlukan dari lokasi penyimpanan yang sama. Untuk tujuan keamanan, Layanan Agregasi harus dikonfigurasi untuk menggunakan image container yang disetujui. Lihat repositori GitHub sandbox privasi/layanan agregasi untuk mengetahui image container yang tersedia.

Berikut adalah contoh perwakilan laporan yang ditampilkan oleh setiap API:

• Contoh laporan 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\"}"
  }

• Contoh laporan 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"
  }

Mengonversi laporan JSON ke Avro

Laporan agregat harus dalam format serialisasi data Apache Avro untuk tujuan pengelompokan. Untuk membuat laporan Avro, Anda harus menggunakan skema AVSC. File skema AVSC menentukan struktur data dan jenis data Avro. Untuk contoh skema AVSC, lihat file example.avsc di repositori GitHub avrodoc/schemata ini.

Anda dapat menemukan contoh kode JavaScript di bagian Mengumpulkan, mengubah, dan mengelompokkan laporan di halaman Mengumpulkan dan Mengelompokkan Laporan yang Dapat Digabung yang terletak di repositori GitHub privacysandbox/aggregation-service.

Anda memiliki fleksibilitas untuk menyimpan semua laporan dalam satu file AVRO atau mendistribusikannya di beberapa file. Meskipun file AVRO tidak memiliki batas ukuran, performa optimal biasanya dicapai jika jumlah file berkisar dari jumlah CPU di instance cloud Anda hingga 1.000.

Contoh kode berikut menunjukkan skema Avro untuk laporan agregat. Kolom laporan mencakup payload, key_id, dan shared_info.

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

Berikut adalah contoh laporan 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\"}"
}

Spesifikasi file domain

Untuk membuat laporan ringkasan dengan Layanan Agregasi, Anda memerlukan laporan agregat (laporan JSON yang dikonversi ke Avro) dan file domain terkait. Sistem mengekstrak kunci yang telah dideklarasikan sebelumnya dari laporan gabungan Anda dan menyertakannya dalam laporan ringkasan dalam domain output. Anda akan menemukan detail tentang kunci agregasi penting ini di Memahami kunci agregasi untuk Pelaporan Atribusi dan bagian Kunci agregasi di Dasar-dasar Private Aggregation API. Domain output juga menyertakan kolom bucket yang mewakili nilai kunci bucket Anda.

File domain harus dalam format Avro menggunakan skema berikut:

  {
    "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."
      }
    ]
  }

Kunci bucket

Kunci bucket dalam domain output harus direpresentasikan sebagai string byte heksadesimal.

Contoh:

Jika kunci bucket adalah nilai desimal 1369:

1. Mengonversi 1369 ke nilai heksadesimal yang setara: 559

2. Konversikan string heksadesimal "559" menjadi string byte.

Representasi string byte dari kunci bucket ini kemudian harus disertakan dalam skema Avro domain output.

Pertimbangan penting:

• Jenis data: Kunci bucket dalam skema Avro harus ditentukan sebagai jenis byte untuk mengakomodasi representasi string byte hex.

• Konversi: Konversi dari desimal ke heksadesimal, lalu ke string byte dapat diterapkan menggunakan Python atau Java.

Pendekatan ini memastikan bahwa kunci bucket diformat dengan benar dan kompatibel dengan jenis data yang diharapkan dalam skema Avro untuk domain output.

Laporan batch

Untuk mengetahui detail tentang anggaran privasi dan strategi pengelompokan, lihat dokumentasi strategi pengelompokan. Perhatikan bahwa laporan gabungan memiliki batas MAX_REPORT_AGE (saat ini 90 hari) antara scheduled_report_time dan tanggal pengoperasian batch.

Laporan ringkasan

Setelah pengelompokan, Layanan Agregasi akan membuat laporan ringkasan dalam format Avro menggunakan skema results.avsc.

Setelah tugas selesai, laporan ringkasan disimpan di output_data_blob_prefix dalam bucket output_data_bucket_name seperti yang dinyatakan dalam permintaan createJob.

Untuk batch Layanan Agregasi dengan debug_run diaktifkan, batch ini akan membuat dua laporan, yaitu laporan ringkasan dan laporan ringkasan debug. Laporan ringkasan debug berada di folder output_data_blob_prefix/debug. Laporan ringkasan debug menggunakan skema debug_results.avsc.

Laporan ringkasan dan debug diberi nama [output_data_blob_prefix]-1-of-1.avro. Jika output_data_blob_prefix Anda adalah summary/summary.avro, laporan akan berada di folder ringkasan dengan nama summary-1-of-1.avro.

Contoh results.avsc

Berikut adalah contoh skema Avro untuk 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"
    }
  ]
}

Contoh skema Avro menentukan data bernama AggregatedFact.

Contoh debug_results.avsc

Berikut adalah contoh skema Avro untuk 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"]
          }
       }
    ]
  }

Setelah dikonversi, laporan ringkasan Anda akan menyerupai contoh results.json. Jika debug_run diaktifkan, laporan ringkasan debug yang ditampilkan akan mirip dengan contoh debug_results.json.

Format laporan Avro

Laporan Avro yang diterima dari Layanan Agregasi biasanya mengikuti format yang konsisten. Format laporan Avro mencakup kolom berikut:

• bucket: ID unik untuk agregasi data (Misalnya, "\u0005Y").

• metric: Nilai gabungan untuk bucket yang sesuai. Nilai ini sering kali menyertakan derau tambahan untuk meningkatkan privasi.

  Contoh:

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

Contoh debug_results.json

Laporan Avro debug dari Layanan Agregasi akan menyerupai contoh debug_results.json berikut. Laporan ini mencakup kunci bucket, unnoised_metric (ringkasan kunci bucket sebelum penerapan derau), dan derau yang ditambahkan ke metrik tersebut.

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

Anotasi juga berisi nilai berikut:

• in_reports: kunci bucket yang tersedia di dalam laporan gabungan

• in_domain: kunci bucket yang tersedia di dalam file Avro output_domain