Cette page a été traduite par l'API Cloud Translation.

Recevoir et stocker des rapports agrégables

Lorsque les technologies publicitaires déclenchent des API de mesure (API Attribution Reporting ou API Private Aggregation), les rapports chiffrés sont envoyés du côté client / navigateur Chrome au point de terminaison de reporting de la technologie publicitaire, qui est une URL .well-known avec l'origine des rapports de la technologie publicitaire. Le point de terminaison de création de rapports est hébergé par la technologie publicitaire pour collecter les rapports chiffrés.

Voici les points de terminaison par API:

Private Aggregation
- Débogage [reporting-origin]/.well-known/private-aggregation/debug/report-shared-storage
- [reporting-origin]/.well-known/private-aggregation/report-shared-storage ou /.well-known/private-aggregation/report-protected-audience en direct
Rapports sur l'attribution
- Débogage [reporting-origin]/.well-known/attribution-reporting/debug/report-aggregate-attribution
- [reporting-origin]/.well-known/attribution-reporting/report-aggregate-attribution en direct

Les technologies publicitaires recevront les rapports au format JSON via un appel POST. Les technologies publicitaires collecteront ces rapports JSON, puis les convertiront au format AVRO, qui est utilisé dans le service d'agrégation. Une fois convertis, les rapports AVRO sont stockés dans l'espace de stockage cloud de la technologie publicitaire pour être regroupés ultérieurement.

Une fois que la technologie publicitaire est prête à effectuer le traitement par lot, elle déclenche une requête de tâche d'agrégation via le service d'agrégation, où les rapports sont récupérés à partir du stockage cloud de la technologie publicitaire. Le service d'agrégation est hébergé sur le stockage cloud de la technologie publicitaire et doit comporter une image de la liste d'autorisation.

Les rapports reçus se présentent comme suit:

API Private Aggregation

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

API Attribution Reporting

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

Convertir des rapports JSON en AVRO

Lors du traitement par lot, les rapports agrégables doivent être au format AVRO. Pour créer un rapport AVRO, vous avez besoin du schéma AVRO (AVSC) du rapport.

Un exemple de code JavaScript est disponible dans le dépôt GitHub du service d'agrégation.

Vous trouverez ci-dessous le schéma AVRO pour les rapports agrégables. Les différents champs des rapports sont payload, key_id et shared_info.

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

Paramètre	Type	Description
`payload`	Octets	La charge utile doit être décodée en base64 et convertie en tableau d'octets à partir de `payload` pour les rapports en direct / en production.
`debug_cleartext_payload`	Octets	La charge utile doit être décodée en base64 et convertie en tableau d'octets à partir de `debug_cleartext_payload` pour les rapports de débogage.
`key_id`	Chaîne	Il s'agit de la chaîne key_id trouvée dans le rapport. Le key_id est un identifiant universel unique de 128 bits semblable.
`shared_info`	Chaîne	Il s'agit de la chaîne non falsifiée trouvée dans le champ shared_info du rapport.

Voici un exemple de fichier JSON de rapport:

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

Domaine de sortie AVRO

Pour générer des rapports récapitulatifs à l'aide du service d'agrégation, la technologie publicitaire nécessite les rapports agrégables et le fichier de domaine. Les rapports agrégables sont les rapports JSON reçus dans l'origine des rapports et convertis au format AVRO. Les domaines de sortie contiennent les clés prédéclarées qui seront collectées à partir de vos rapports agrégables et qui seront écrites dans les rapports récapitulatifs. En savoir plus sur ces clés dans les rapports sur l'attribution et les clés dans l'agrégation privée Le domaine de sortie contiendra le bucket de champ, et la valeur du bucket sera votre clé de bucket.

Le fichier de domaine doit également être au format AVRO et utiliser le schéma suivant:

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

Clé de bucket

La clé de bucket doit être une chaîne d'octets hexadécimale de la clé de bucket. Par exemple, si la clé est 1369 au format décimal. Converti en hexadécimal, il devient 559. Vous devrez ensuite convertir 559 en chaîne d'octets à ajouter au domaine de sortie AVRO.

Rapports par lot

Pour en savoir plus sur les budgets de confidentialité et le traitement par lot, consultez le document sur les stratégies de traitement par lot. N'oubliez pas non plus qu'un rapport agrégable ne peut être traité par lot que pendant une certaine période. Un rapport ne doit pas dépasser la valeur MAX_REPORT_AGE entre la date de création de l'scheduled_report_time et la date d'exécution du lot (actuellement 90 jours).

Rapports récapitulatifs

Après le traitement par lot, le service d'agrégation crée le rapport récapitulatif au format AVRO. Le rapport récapitulatif utilise le schéma results.avsc.

Le rapport récapitulatif se trouve dans le output_data_blob_prefix du bucket output_data_bucket_name indiqué dans la requête createJob.

Pour les lots du service d'agrégation où debug_run est activé, il crée deux rapports. Le rapport récapitulatif et le rapport récapitulatif de débogage. Le rapport récapitulatif de débogage se trouve dans le dossier output_data_blob_prefix/debug.

Le rapport de débogage généré utilise le schéma debug_results.avsc.

Le rapport récapitulatif et le rapport de débogage seront nommés [output_data_blob_prefix]-1-of-1.avro. Si votre préfixe output_data_blob_prefix est summary/summary.avro, le rapport se trouvera dans le dossier "summary" avec le nom summary-1-of-1.avro.

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

Une fois converti, votre rapport récapitulatif ressemblera à l'exemple results.json. Lorsque debug_run est activé, le rapport récapitulatif de débogage renvoie un résultat semblable à l'exemple debug_results.json.

results.json (exemple)

Les rapports AVRO provenant du service d'agrégation peuvent se ressembler, avec la clé de bucket et la valeur récapitulative / agrégée, avec un bruit supplémentaire sur les valeurs du bucket.

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

debug_results.json (exemple)

Les rapports de débogage AVRO provenant du service d'agrégation doivent ressembler à ce qui suit. Vous recevez vos clés de bucket, unnoised_metric (résumé des clés de bucket sans bruit) et le bruit ajouté à unnoised_metric.

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

Les annotations contiennent également in_reports et / ou in_domain, ce qui signifie:

in_reports: la clé du bucket est disponible dans les rapports agrégables.
in_domain: la clé de bucket est disponible dans le fichier AVRO output_domain