Diese Seite wurde von der Cloud Translation API übersetzt.

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 des Anbieters von Anzeigentechnologien gesendet. Dieser Endpunkt ist eine .well-known-URL mit dem Berichts-Ursprung des Anbieters von Anzeigentechnologien. Der Berichtsendpunkt wird von der Anzeigentechnologie gehostet, um die verschlüsselten Berichte zu erfassen.

AggS-Berichtdiagramm

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

Private Aggregation
- Debuggen [reporting-origin]/.well-known/private-aggregation/debug/report-shared-storage
- [reporting-origin]/.well-known/private-aggregation/report-shared-storage oder /.well-known/private-aggregation/report-protected-audience live
Attributionsberichte
- Debuggen [reporting-origin]/.well-known/attribution-reporting/debug/report-aggregate-attribution
- Aktuell: [reporting-origin]/.well-known/attribution-reporting/report-aggregate-attribution

AdTechs 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 Umstellung werden die AVRO-Berichte zur späteren Batchverarbeitung im Cloud-Speicher der Anzeigentechnologie gespeichert.

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

Die eingegangenen 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

Für die Batchverarbeitung müssen aggregierte Berichte im AVRO-Format vorliegen. Zum Erstellen eines AVRO-Berichts benötigen Sie das AVRO-Schema (AVSC) des Berichts.

Im GitHub-Repository des Aggregation Service finden Sie Beispielcode für JavaScript.

Sie können eine AVRO-Datei für alle Berichte erstellen 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 sehen Sie das AVRO-Schema für aggregierte Berichte. Die unterschiedlichen 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 in ein Byte-Array von `payload` konvertiert werden.
`debug_cleartext_payload`	Byte	Die Nutzlast muss für Fehlerbehebungsberichte mit Base64 decodiert und in ein Byte-Array von `debug_cleartext_payload` konvertiert werden.
`key_id`	String	Das ist der String „key_id“ aus dem Bericht. Die "key_id" ist eine universell eindeutige 128-Bit-Kennung.
`shared_info`	String	Das ist der unveränderte String im Feld „shared_info“ des Berichts.

Hier sehen Sie ein JSON-Beispiel für einen Bericht:

{ 
   "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 der Ausgabedomain

Zum Generieren von Zusammenfassungsberichten mit dem Zusammenfassungsdienst sind für die Anzeigentechnologie die aggregierbaren Berichte und die Domaindatei erforderlich. Die aggregierten Berichte sind die JSON-Berichte, die am Ursprung der Berichte empfangen und in das AVRO-Format konvertiert werden. 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 ist der Schlüssel 1369 in Dezimalzahlen. Bei der Konvertierung in den Hexadezimalwert ist der Wert 559. Anschließend müssen Sie 559 in einen Bytestring umwandeln, der der Ausgabedomain AVRO hinzugefügt wird.

AgS-Bucket-Schlüsseldiagramm

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 Ausführungsdatum des Batches (derzeit 90 Tage) nicht überschreiten. MAX_REPORT_AGE

Zusammenfassende Berichte

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

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

Für Aggregation Service-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.

Im generierten Fehlerbehebungsbericht wird das Schema debug_results.avsc verwendet.

Sowohl der Zusammenfassungs- als auch der Debug-Bericht werden als [output_data_blob_prefix]-1-of-1.avro bezeichnet. 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 zusammenfassende Bericht zur Fehlerbehebung etwas aus dem Beispiel debug_results.json zurück.

results.json (Beispiel)

AVRO-Berichte, die aus dem Zusammenfassungsdienst stammen, können ähnlich aussehen, wenn Sie den Bucket-Schlüssel und den Zusammenfassungs-/Gesamtwert mit zusätzlichem Rauschen der Bucket-Werte haben.

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

debug_results.json (Beispiel)

Die Fehlerbehebung für AVRO-Berichte, die aus dem Zusammenfassungsdienst stammen, sollte in etwa so aussehen, wenn Sie Ihre Bucket-Schlüssel, unnoised_metric (Zusammenfassung der Bucket-Schlüssel ohne Rauschen) und das Rauschen, das dem unnoised_metric hinzugefügt wird, erhalten.

  {
    "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 aggregierbaren Berichten verfügbar.
in_domain: Der Bucket-Schlüssel ist in der output_domain-AVRO-Datei verfügbar.