Aggregierte Berichte empfangen und speichern

Wenn Anbieter von Anzeigentechnologien Analyse-APIs (Attribution Reporting API oder Private Aggregation API) auslösen, werden die verschlüsselten Berichte vom Chrome-Browser / Client an den Berichts-Endpunkt der Anzeigentechnologie gesendet. Dieser ist eine .well-known-URL mit dem Berichts-Ursprung der Anzeigentechnologie. Der Berichtsendpunkt wird von AdTech gehostet, um die verschlüsselten Berichte zu erfassen.

Die folgenden Endpunkte sind für jede API verfügbar:

• Private Aggregation

  • Debuggen [reporting-origin]/.well-known/private-aggregation/debug/report-shared-storage
  • Live [reporting-origin]/.well-known/private-aggregation/report-shared-storage oder /.well-known/private-aggregation/report-protected-audience

• Attributionsberichte

  • Debuggen [reporting-origin]/.well-known/attribution-reporting/debug/report-aggregate-attribution
  • Live [reporting-origin]/.well-known/attribution-reporting/report-aggregate-attribution

Anbieter von Anzeigentechnologien erhalten die Berichte im JSON-Format über einen POST-Aufruf. Anbieter von Anzeigentechnologien erfassen diese JSON-Berichte und konvertieren sie später in das AVRO-Format, das im Aggregationsdienst verwendet wird. Nach der Umwandlung werden die AVRO-Berichte im Cloud-Speicher der Anzeigentechnologie für die spätere Batchverarbeitung gespeichert.

Sobald die AdTech-Technologie für die Batchverarbeitung bereit ist, löst sie über den Aggregationsdienst eine Aggregationsjobanfrage aus, bei der die Berichte aus dem Cloud-Speicher der AdTech-Technologie abgerufen werden. Der Aggregationsdienst wird im Cloud-Speicher der Anzeigentechnologie gehostet und sollte ein auf der Zulassungsliste stehendes Bild haben.

Die erhaltenen Berichte sehen in etwa so aus:

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

JSON-Berichte in AVRO-Berichte konvertieren

Bei der Batchverarbeitung müssen aggregierbare Berichte im AVRO-Format vorliegen. Zum Erstellen eines AVRO-Berichts benötigen Sie das AVRO-Schema (AVSC) des Berichts.

Im GitHub-Repository des Aggregationsdiensts ist ein Beispiel für JavaScript-Code verfügbar.

Empfohlen
Sie können eine AVRO-Datei für alle Berichte verwenden oder Berichte in mehrere AVRO-Dateien aufteilen. Die Größe von AVRO-Dateien ist nicht begrenzt. Aus Leistungsgründen wird empfohlen, die Anzahl der AVRO-Dateien auf eine Zahl zwischen der Anzahl der für Ihre Cloud-Instanz verfügbaren CPUs und 1.000 zu beschränken.

Im Folgenden finden Sie das AVRO-Schema für aggregierbare Berichte. Die verschiedenen Felder für die Berichte sind payload, key_id und shared_info.

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

Parameter	Typ	Beschreibung
payload	Byte	Die Nutzlast muss für Live-/Produktionsberichte base64-decodiert und von payload in ein Byte-Array umgewandelt werden.
debug_cleartext_payload	Byte	Die Nutzlast muss für Debugberichte aus debug_cleartext_payload base64-decodiert und in ein Byte-Array umgewandelt werden.
key_id	String	Das ist der im Bericht enthaltene String „key_id“. Die „key_id“ ist eine 128-Bit-eindeutige Kennung.
shared_info	String	Das ist der unveränderte String im Feld „shared_info“ des Berichts.

Hier ein Beispiel für einen Bericht in 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\"}"
}

Ausgabedomain AVRO

Um Zusammenfassungsberichte mit dem Aggregationsdienst zu erstellen, benötigt die Anzeigentechnologie die aggregierbaren Berichte und die Domaindatei. Die aggregierbaren Berichte sind die JSON-Berichte, die am Ursprung der Berichterstellung empfangen und in das AVRO-Format konvertiert wurden. Ausgabedomains enthalten die vorab deklarierten Schlüssel, die aus Ihren aggregierbaren Berichten erfasst und in die Zusammenfassungsberichte geschrieben werden. Weitere Informationen zu diesen Schlüsseln in Attributionsberichten und Schlüsseln in der privaten Aggregation Die Ausgabedomain enthält den Feld-Bucket und der Bucket-Wert ist der Bucket-Schlüssel.

Die Domaindatei muss außerdem im AVRO-Format mit dem folgenden Schema vorliegen:

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

Bucket-Schlüssel

Der Bucket-Schlüssel sollte ein Hexadezimal-Bytestring des Bucket-Schlüssels sein. Ein Beispiel hierfür wäre der Dezimalschlüssel 1369. In Hexadezimalschreibweise entspricht das 559. Dann müssen Sie 559 in einen Bytestring konvertieren, der der Ausgabedomain AVRO hinzugefügt wird.

Batchberichte

Weitere Informationen zu Datenschutzbudgets und Batchverarbeitung finden Sie im Dokument Batchverarbeitungsstrategien. Beachten Sie außerdem, dass ein aggregierbarer Bericht nur innerhalb eines bestimmten Zeitraums gebatcht werden kann. Ein Bericht darf zwischen dem scheduled_report_time und dem Datum der Batchausführung den Wert MAX_REPORT_AGE nicht überschreiten (aktuell 90 Tage).

Zusammenfassende Berichte

Nach dem Batching erstellt der Aggregationsdienst den Zusammenfassungsbericht im AVRO-Format. Im Übersichtsbericht wird das results.avsc-Schema verwendet.

Der zusammenfassende Bericht befindet sich im output_data_blob_prefix-Bucket output_data_bucket_name, der in der createJob-Anfrage angegeben ist.

Für Aggregationsdienst-Batches, bei denen „debug_run“ aktiviert ist, werden zwei Berichte erstellt. Der Zusammenfassungsbericht und der Bericht zur Fehlerbehebung. Der Bericht zur Fehlerbehebung befindet sich im Ordner output_data_blob_prefix/debug.

Der generierte Debugbericht verwendet das debug_results.avsc-Schema.

Sowohl der Zusammenfassungsbericht als auch der Debug-Bericht werden [output_data_blob_prefix]-1-of-1.avro genannt. Wenn Ihr output_data_blob_prefix summary/summary.avro ist, wird der Bericht im Ordner „summary“ mit dem Namen summary-1-of-1.avro gespeichert.

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

Nach der Umwandlung sieht Ihr Zusammenfassungsbericht in etwa so aus wie im Beispiel results.json. Wenn „debug_run“ aktiviert ist, gibt der Bericht zur Fehlerbehebung in etwa Folgendes zurück: debug_results.json.

results.json (Beispiel)

AVRO-Berichte aus dem Aggregationsdienst können ähnlich aussehen, wenn Sie den Bucket-Schlüssel und den zusammengefassten / aggregierten Wert mit zusätzlichen Schwankungen der Bucket-Werte haben.

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

debug_results.json (Beispiel)

Debug-AVRO-Berichte vom Aggregationsdienst sollten in etwa so aussehen: Sie enthalten Ihre Bucket-Schlüssel, unnoised_metric (Zusammenfassung der Bucket-Schlüssel ohne Rauschen) und das Rauschen, das der unnoised_metric hinzugefügt wird.

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

Die Anmerkungen enthalten außerdem in_reports und / oder in_domain, was Folgendes bedeutet:

• in_reports: Der Bucket-Schlüssel ist in den aggregierten Berichten verfügbar.
• in_domain: Der Bucket-Schlüssel ist in der output_domain-AVRO-Datei verfügbar.