本指南說明如何將經過加密的評估報表傳送給廣告技術供應商。Chrome 瀏覽器和用戶端會將這些報表傳送至指定的回報端點,廣告技術平台會在該端點接收及儲存可匯總報表。這些端點位於供應商報表來源中的 .well-known
網址,由平台代管,讓廣告技術供應商使用 Attribution Reporting API 或 Private Aggregation API 存取這些端點。

下列步驟詳細說明匯總服務接收及儲存可匯總報表的程序:
- 觸發後,瀏覽器會傳送可匯總的報表,其中包含跨網站和轉換資料的詳細資料。
- 瀏覽器會將經過加密的報表傳送至廣告技術報表網域中的
.well-known
網址。 - 系統會將批次報表轉送至匯總服務進行處理。
- 匯總服務會統計並匯總報表。
- 匯總服務會在匯總資料中加入雜訊,以強化使用者隱私。
- 系統會將報表提供給廣告技術公司,以利分析和評估。
下表說明 Private Aggregation API 和 Attribution Reporting API 的偵錯和實際端點:
API | 端點 | 說明 |
---|---|---|
私密匯總 API |
|
|
Attribution Reporting API |
|
|
報表來源會透過 POST 呼叫接收 JSON 報表。系統會將這些報表轉換為 Avro 格式,並將報表儲存在雲端儲存空間中。在批次處理完成後,系統會將 Avro 報表傳送至匯總服務進行匯總。
當一批 Avro 報表已準備好供處理時,廣告技術平台會向匯總服務觸發匯總工作要求。這項服務會在廣告技術平台的雲端環境中代管,並從相同的儲存位置擷取所需的 Avro 報表。基於安全考量,匯集服務必須設定為使用核准的容器映像檔。如要查看可用的容器映像檔,請參閱 Privacy Sandbox/Aggregation-Service 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 存放區的「Collecting and Batching Aggregatable Reports」頁面「Collect, transform and batch reports」部分,找到 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 報表) 和相關聯的網域檔案。系統會從可匯總報表中擷取先前宣告的鍵,並將這些鍵納入輸出網域中的摘要報表。如要進一步瞭解這些重要的匯總鍵,請參閱「瞭解歸因報表的匯總鍵」和「私人匯總 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 結構定義中預期的資料類型相容。

批次報表
如要進一步瞭解隱私預算和批次處理策略,請參閱批次處理策略說明文件。請注意,可匯總的報表在 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 報表格式包含下列欄位:
bucket:資料匯總的專屬 ID (例如「\u0005Y」)。
指標:對應值區的加總值。這個值通常會加入雜訊,以提升隱私性。
例如:
{
"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 檔案中可用的 bucket 鍵