接收和存储可汇总报告

当广告技术平台触发效果衡量 API（Attribution Reporting API 或 Private Aggregation API）时，加密报告会从 Chrome 浏览器 / 客户端发送到广告技术平台的报告端点，该端点是包含广告技术平台报告来源的 .well-known 网址。报告端点由广告技术平台托管，用于收集加密报告。

AgS 报告示意图。

以下是每个 API 的端点：

  • 不公开汇总

    • 调试 [reporting-origin]/.well-known/private-aggregation/debug/report-shared-storage
    • 实时 [reporting-origin]/.well-known/private-aggregation/report-shared-storage 或 /.well-known/private-aggregation/report-protected-audience

  • Attribution Reporting

    • 调试 [reporting-origin]/.well-known/attribution-reporting/debug/report-aggregate-attribution
    • 直播 [reporting-origin]/.well-known/attribution-reporting/report-aggregate-attribution

广告技术平台将通过 POST 调用接收 JSON 格式的报告。广告技术平台会收集这些 JSON 报告，稍后将其转换为汇总服务中使用的 AVRO 格式。转换后，AVRO 报告会存储在广告技术平台的云端存储空间中，以供日后批量处理。

广告技术平台准备好进行批处理后，会通过汇总服务触发汇总作业请求，系统会从广告技术平台的云端存储空间检索报告。汇总服务托管在广告技术平台的云端存储空间中，并且应包含列入许可名单的图片。

收到的报告类似于以下内容：

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 报告转换为 Avro 报告

进行批处理时，可汇总的报告需要采用 AVRO 格式。如需创建 AVRO 报告，您需要报告 AVRO 架构 (AVSC)。

汇总服务 GitHub 代码库中提供了JavaScript 代码示例。

以下是可汇总报告的 Avro 架构。报告的不同字段分别为 payload、key_id 和 shared_info。

  {
    "type": "record",
    "name": "AggregatableReport",
    "fields": [
      {
        "name": "payload",
        "type": "bytes"
      },
      {
        "name": "key_id",
        "type": "string"
      },
      {
        "name": "shared_info",
        "type": "string"
      }
    ]
  }
参数 类型 说明
payload 字节 如需生成实时 / 正式版报告，需要对载荷进行 base64 解码，并将其转换为 payload 中的字节数组。
debug_cleartext_payload 字节 为了生成调试报告，需要对载荷进行 base64 解码，并将其转换为 debug_cleartext_payload 中的字节数组。
key_id 字符串 这是报告中找到的 key_id 字符串。key_id 将是一个类似的 128 位通用唯一标识符。
shared_info 字符串 这是报告 shared_info 字段中找到的未经篡改的字符串。

以下是报告 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\"}"
}

输出网域 AVRO

若要使用汇总服务生成摘要报告，广告技术平台需要汇总报告和域名文件。可汇总的报告将是报告来源收到的 JSON 报告，并已转换为 AVRO 格式。输出网域将包含从可汇总报告收集并写入摘要报告的预声明键。详细了解归因报告中的键和不公开汇总中的键。输出网域将包含字段存储分区，存储分区值将是您的存储分区键。

域名文件还需要采用 AVRO 格式，并使用以下架构：

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

存储分区键

存储分区键应为存储分区键的十六进制字节字符串。例如，将键设置为十进制 1369。转换为十六进制后，它将为 559。然后，您需要将 559 转换为字节字符串，以添加到输出网域 AVRO

AgS 存储分区密钥示意图。

批量报告

如需详细了解隐私预算和批处理，请参阅批处理策略文档。另请注意，可汇总的报告只能在特定时间段内批处理。报告的 scheduled_report_time 和批量运行日期之间的时间不得超过 MAX_REPORT_AGE（目前为 90 天）。

摘要报告

批处理后，汇总服务会以 AVRO 格式创建摘要报告。摘要报告使用 results.avsc 架构。

摘要报告将位于 createJob 请求中所述的 output_data_bucket_name 存储分区中的 output_data_blob_prefix 中。

对于启用了 debug_run 的汇总服务批次，它会创建两个报告。摘要报告和调试摘要报告。调试摘要报告将位于 output_data_blob_prefix/debug 文件夹中。

生成的调试报告使用 debug_results.avsc 架构。

摘要报告和调试报告都将命名为 [output_data_blob_prefix]-1-of-1.avro。如果您的 output_data_blob_prefix 为 summary/summary.avro，报告将位于名称为 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"]
          }
       }
    ]
  }

转换后，您的摘要报告将如下例 results.json 所示。启用 debug_run 后，调试摘要报告会返回类似于示例 debug_results.json 的内容。

results.json（示例）

来自汇总服务的 AVRO 报告可能看起来很相似，其中包含存储分区键和摘要 / 汇总值，以及添加的存储分区值噪声。

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

debug_results.json（示例）

来自汇总服务的调试 AVRO 报告应如下所示，您会收到分桶键 unnoised_metric（不含噪声的分桶键摘要）以及添加到 unnoised_metric 的噪声。

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

注解还将包含 in_reports 和 / 或 in_domain，这表示：

  • in_reports：存储分区键可在可汇总报告中使用
  • in_domain：存储分区密钥位于 output_domain AVRO 文件中