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 des rapports est hébergé par la technologie publicitaire pour collecter les rapports chiffrés.

Diagramme du rapport AgS

Voici les points de terminaison par API :

Private Aggregation
- Déboguer [reporting-origin]/.well-known/private-aggregation/debug/report-shared-storage
- En direct [reporting-origin]/.well-known/private-aggregation/report-shared-storage ou /.well-known/private-aggregation/report-protected-audience
Rapports sur l'attribution
- Déboguer [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 collectent ces rapports JSON, puis les convertissent au format AVRO, qui est utilisé dans le service d'agrégation. Une fois convertis, les rapports AVRO sont stockés dans le stockage cloud de la technologie publicitaire pour un traitement ultérieur par lot.

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é dans le stockage cloud de la technologie publicitaire et doit comporter une image ajoutée à 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 rapports 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 pouvez avoir un seul fichier AVRO pour tous vos rapports ou diviser les rapports en plusieurs fichiers AVRO. La taille d'AVRO n'est pas limitée. Pour des raisons de performances, il est recommandé de limiter le nombre de fichiers AVRO à un nombre compris entre le nombre de processeurs disponibles pour votre instance Cloud et 1 000.

Voici 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 un tableau d'octets à partir de `payload` pour les rapports en ligne / de production.
`debug_cleartext_payload`	Octets	La charge utile doit être décodée en base64 et convertie en un tableau d'octets à partir de `debug_cleartext_payload` pour les rapports de débogage.
`key_id`	Chaîne	Il s'agira de la chaîne key_id trouvée dans le rapport. La clé key_id sera un identifiant unique universel de 128 bits similaire.
`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 a besoin des rapports agrégables et du 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 avec 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, avoir une clé de 1369 en décimales. Une fois converti en hexadécimal, il sera 559. Vous devrez ensuite convertir 559 en une chaîne d'octets qui sera ajoutée au domaine de sortie AVRO

Schéma de clé de bucket AgS

Rapports groupés

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. La durée d'un rapport ne doit pas dépasser MAX_REPORT_AGE entre la date de 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 récapitulatif et le rapport de débogage seront nommés comme [output_data_blob_prefix]-1-of-1.avro. Si le préfixe "output_data_blob_prefix" est summary/summary.avro, le rapport sera placé dans le dossier "summary" sous 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 du 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 se présenter comme suit, où 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é du bucket est disponible dans le fichier AVRO output_domain.