此页面由 Cloud Translation API 翻译。

接收和存储可汇总报告

本指南介绍了如何将加密的衡量报告传送给广告技术提供商。Chrome 浏览器和客户端会将这些报告发送到指定的报告端点，广告技术平台会在该端点接收和存储可汇总报告。这些端点位于提供商报告来源内的 .well-known 网址，由平台托管，可让广告技术提供商使用 Attribution Reporting API 或 Private Aggregation API 访问它们。

以下步骤详细介绍了汇总服务接收和存储可汇总报告的流程：

触发后，浏览器会发送可汇总的报告，其中包含有关跨网站数据和转化数据的详细信息。
浏览器将加密的报告提交到广告技术平台报告网域中的 .well-known 网址。
系统会将批量报告转发到汇总服务进行处理。
汇总服务会对报告进行统计汇总。
汇总服务会向汇总数据添加噪声，以加强用户隐私保护。
系统会将报告提供给广告技术公司，以便其进行分析和衡量。

下表介绍了 Private Aggregation API 和 Attribution Reporting API 的调试端点和正式版端点：

API	端点	说明
Private Aggregation API	调试端点： `[reporting-origin]/.well-known/private-aggregation/debug/report-shared-storage` 实时端点： `[reporting-origin]/.well-known/private-aggregation/report-shared-storage` `[reporting-origin]/.well-known/private-aggregation/report-protected-audience`	调试端点：适用于 Private Aggregation API 开发和测试。实时端点：在真实环境中接收和处理效果衡量报告
Attribution Reporting API	调试端点： `[reporting-origin]/.well-known/attribution-reporting/debug/report-aggregate-attribution` 实时端点： `[reporting-origin]/.well-known/attribution-reporting/report-aggregate-attribution`	调试端点：适用于 Attribution Reporting API 开发和测试。实时端点：用于汇总归因报告的正式版端点。在真实的生产环境中接收和处理汇总归因报告，以进行效果衡量。

报告来源通过 POST 调用接收 JSON 报告。然后，系统会将这些报告转换为 Avro 格式，并将其存储在云端存储空间中。批量处理后，系统会将 Avro 报告发送到汇总服务以进行汇总。

当一批 Avro 报告被视为可以处理时，广告技术平台会向汇总服务触发汇总作业请求。此服务托管在广告技术平台的云环境中，可从同一存储位置检索所需的 Avro 报告。出于安全考虑，汇总服务必须配置为使用已获批准的容器映像。如需了解可用的容器映像，请参阅隐私沙盒/汇总服务 GitHub 代码库。

以下是每个 API 返回的报告的代表性示例：

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 报告

为了进行批处理，可汇总的报告必须采用 Apache Avro 数据序列化格式。如需创建 Avro 报告，您必须使用 AVSC 架构。AVSC 架构文件定义了 Avro 记录结构和数据类型。如需查看 AVSC 架构示例，请参阅此 avrodoc/schemata GitHub 代码库中的 example.avsc 文件。

您可以在 privacysandbox/aggregation-service GitHub 代码库中，找到收集和批处理可汇总报告页面中的收集、转换和批处理报告部分中的 JavaScript 代码示例。

您可以灵活地将所有报告存储在单个 AVRO 文件中，也可以将其分布在多个文件中。虽然 AVRO 文件没有大小限制，但通常情况下，当文件数量介于云实例中的 CPU 数量与 1000 之间时，可获得最佳性能。

以下代码示例展示了可汇总报告的 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`	字节	对于实时报告或正式版报告，必须对 `payload` 进行 base64 解码并将其转换为字节数组。
`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 报告）和关联的网域文件。系统会从可汇总报告中提取预声明的键，并将其包含在输出网域中的摘要报告中。如需详细了解这些关键汇总键，请参阅了解归因报告的汇总键以及Private Aggregation API 基础知识的汇总键部分。输出网域还包含 bucket 字段，该字段表示存储分区键值。

网域文件必须采用 Avro 格式，并使用以下架构：

  {
    "type": "record",
    "name": "AggregationBucket",
    "fields": [
      {
        "name": "bucket",
        "type": "bytes",
        "doc": "A single bucket that appears in the aggregation service output. It is an 128-bit integer value encoded as a 16-byte big-endian bytestring."
      }
    ]
  }

存储分区键

输出网域中的存储分区键必须表示为十六进制字节字符串。

例如：

如果存储分区键是小数值 1369：

将 1369 转换为等效的十六进制数：559
将十六进制字符串“559”转换为字节字符串。

然后，应将存储分区键的此字节字符串表示法包含在输出网域 Avro 架构中。

重要注意事项：

数据类型：Avro 架构中的存储分区键应定义为字节类型，以适应十六进制字节字符串表示法。
转换：可以使用 Python 或 Java 实现从十进制到十六进制再到字节字符串的转换。

这种方法可确保存储分区键的格式正确无误，并且与输出网域的 Avro 架构中的预期数据类型兼容。

存储分区键应为十六进制字节字符串。例如，假设一个字节字符串的十进制值为 1369。转换为十六进制格式后，该值为 559，可添加到 Avro 输出网域中。 — **图 2**：该图展示了将存储分区键转换为十六进制表示法，然后再转换为字节字符串表示法，最终用于填充输出网域 AVRO 架构。

批量报告

如需详细了解隐私预算和批处理策略，请参阅批处理策略文档。请注意，可汇总的报告的 scheduled_report_time 和批量运行日期之间存在 MAX_REPORT_AGE 限制（目前为 90 天）。

摘要报告

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

作业完成后，摘要报告会存储在 output_data_bucket_name 存储分区中的 output_data_blob_prefix 中，如 createJob 请求中所述。

对于启用了 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` 示例

以下是 results.avsc 的 Avro 架构示例：

{
  "type": "record",
  "name": "AggregatedFact",
  "fields": [
    {
      "name": "bucket",
      "type": "bytes",
      "doc": "Histogram bucket used in aggregation. It is an 128-bit integer value encoded as a 16-byte big-endian bytestring. Leading 0-bits are left out."
    },
    {
      "name": "metric",
      "type": "long",
      "doc": "The metric associated with the bucket"
    }
  ]
}

示例 Avro 架构定义了一个名为 AggregatedFact 的记录。

`debug_results.avsc` 示例

以下是 debug_results.avsc 的 Avro 架构示例：

  {
  "type": "record",
  "name": "DebugAggregatedFact", Output domains include summary reports that contain pre-declared keys extracted from your aggregatable reports.
  "fields": [
      {
        "name": "bucket",
        "type": "bytes",
        "doc": "This represents the histogram bucket used in aggregation. It's a 128-bit integer, encoded as a 16-byte big-endian bytestring, with leading zero bytes omitted.."
      },
      {
        "name": "unnoised_metric",
        "type": "long",
        "doc": "The raw metric for 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 示例类似。

Avro 报告格式

从汇总服务收到的 Avro 报告通常采用一致的格式。Avro 报告格式包含以下字段：

存储分区：数据汇总的唯一标识符（例如“\u0005Y”）。
metric：相应存储分区的汇总值。此值通常包含添加的噪声，以加强隐私保护。

例如：

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

`debug_results.json` 示例

汇总服务中的调试 Avro 报告类似于以下 debug_results.json 示例。这些报告包含存储分区键、unnoised_metric（应用噪声之前存储分区键的摘要）以及添加到该指标的噪声。

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

注释还包含以下值：

in_reports：可汇总报告中提供的存储分区键
in_domain：output_domain Avro 文件中提供的存储分区键