Hướng dẫn này mô tả cách phân phối báo cáo đo lường đã mã hoá cho các nhà cung cấp công nghệ quảng cáo. Trình duyệt và ứng dụng Chrome gửi các báo cáo này đến các điểm cuối báo cáo được chỉ định, nơi nền tảng công nghệ quảng cáo nhận và lưu trữ các báo cáo tổng hợp. Các điểm cuối này, nằm ở URL .well-known trong nguồn gốc báo cáo của nhà cung cấp, do nền tảng lưu trữ, cho phép nhà cung cấp công nghệ quảng cáo sử dụng Attribution Reporting API hoặc Private Aggregation API để truy cập vào các điểm cuối đó.
Các bước sau đây trình bày chi tiết quy trình của Dịch vụ tổng hợp để nhận và lưu trữ các báo cáo tổng hợp:
- Khi được kích hoạt, trình duyệt sẽ gửi các báo cáo tổng hợp chứa thông tin chi tiết về cả dữ liệu chuyển đổi và dữ liệu trên nhiều trang web.
- Trình duyệt phân phối các báo cáo đã mã hoá đến URL
.well-knowntrong miền báo cáo công nghệ quảng cáo. - Hệ thống sẽ chuyển tiếp các lô báo cáo đến Dịch vụ tổng hợp để xử lý.
- Dịch vụ tổng hợp tóm tắt các báo cáo theo số liệu thống kê.
- Dịch vụ tổng hợp thêm nhiễu vào dữ liệu tóm tắt để tăng cường quyền riêng tư của người dùng.
- Hệ thống cung cấp báo cáo cho công ty công nghệ quảng cáo để phân tích và đo lường.
Bảng sau đây mô tả các điểm cuối gỡ lỗi và trực tiếp cho API Tổng hợp riêng tư và API Báo cáo phân bổ:
| API | Điểm cuối | Mô tả |
|---|---|---|
| Private Aggregation API |
|
|
| Attribution Reporting API |
|
|
Nguồn gốc báo cáo nhận báo cáo JSON thông qua lệnh gọi POST. Sau đó, hệ thống sẽ chuyển đổi các báo cáo này thành định dạng Avro và đưa vào bộ nhớ trên đám mây. Sau khi xử lý hàng loạt, hệ thống sẽ gửi báo cáo Avro đến Dịch vụ tổng hợp để tóm tắt.
Các nền tảng công nghệ quảng cáo sẽ kích hoạt yêu cầu công việc tổng hợp cho Dịch vụ tổng hợp khi một lô báo cáo Avro được coi là đã sẵn sàng để xử lý. Dịch vụ này, được lưu trữ trong môi trường đám mây của nền tảng công nghệ quảng cáo, truy xuất các báo cáo Avro bắt buộc từ cùng một vị trí bộ nhớ. Vì mục đích bảo mật, bạn phải định cấu hình Dịch vụ tổng hợp để sử dụng hình ảnh vùng chứa đã phê duyệt. Hãy tham khảo kho lưu trữ GitHub về hộp cát về quyền riêng tư/dịch vụ tổng hợp để biết các hình ảnh vùng chứa hiện có.
Sau đây là ví dụ minh hoạ các báo cáo do từng API trả về:
- Ví dụ về báo cáo 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\"}"
}
- Ví dụ về báo cáo 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"
}
Chuyển đổi báo cáo JSON sang Avro
Báo cáo tổng hợp phải ở định dạng chuyển đổi tuần tự dữ liệu Apache Avro cho mục đích xử lý hàng loạt. Để tạo báo cáo Avro, bạn phải sử dụng giản đồ AVSC. Tệp giản đồ AVSC xác định cấu trúc bản ghi và loại dữ liệu Avro. Để biết ví dụ về giản đồ AVSC, hãy xem tệp example.avsc trong kho lưu trữ GitHub avrodoc/schemata này.
Bạn có thể tìm thấy mã JavaScript mẫu trong phần Thu thập, chuyển đổi và báo cáo theo lô của trang Thu thập và báo cáo tổng hợp theo lô trong kho lưu trữ GitHub privacysandbox/aggregation-service.
Bạn có thể linh hoạt lưu trữ tất cả báo cáo trong một tệp AVRO hoặc phân phối các báo cáo đó trên nhiều tệp. Mặc dù tệp AVRO không có giới hạn về kích thước, nhưng hiệu suất tối ưu thường đạt được khi số lượng tệp nằm trong khoảng từ số lượng CPU trong phiên bản đám mây của bạn đến 1000.
Ví dụ về mã sau đây cho thấy giản đồ Avro cho các báo cáo tổng hợp. Các trường báo cáo bao gồm payload, key_id và shared_info.
{
"type": "record",
"name": "AggregatableReport",
"fields": [
{
"name": "payload",
"type": "bytes"
},
{
"name": "key_id",
"type": "string"
},
{
"name": "shared_info",
"type": "string"
}
]
}
| Thông số | Loại | Mô tả |
|---|---|---|
payload |
Byte |
payload phải được giải mã base64 và chuyển đổi thành một mảng byte cho báo cáo trực tiếp hoặc báo cáo chính thức.
|
debug_cleartext_payload |
Byte |
Trọng tải phải được giải mã base64 và chuyển đổi thành một mảng byte từ debug_cleartext_payload cho báo cáo gỡ lỗi.
|
key_id |
Chuỗi | Đây là chuỗi key_id tìm thấy trong báo cáo. key_id là giá trị nhận dạng duy nhất chung 128 bit. |
shared_info |
Chuỗi | Đây là chuỗi không bị thay đổi, không bị can thiệp tìm thấy trong trường shared_info của báo cáo. |
Dưới đây là ví dụ về báo cáo 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\"}"
}
Thông số kỹ thuật của tệp miền
Để tạo báo cáo tóm tắt bằng Dịch vụ tổng hợp, bạn cần có báo cáo tổng hợp (báo cáo JSON được chuyển đổi sang Avro) và tệp miền được liên kết. Hệ thống sẽ trích xuất các khoá đã khai báo trước từ báo cáo tổng hợp của bạn và đưa các khoá đó vào báo cáo tóm tắt trong các miền đầu ra. Bạn sẽ tìm thấy thông tin chi tiết về các khoá tổng hợp quan trọng này trong bài viết Tìm hiểu về khoá tổng hợp cho Báo cáo phân bổ và phần Khoá tổng hợp trong bài viết Kiến thức cơ bản về API Tổng hợp riêng tư. Miền đầu ra cũng bao gồm trường bucket đại diện cho giá trị khoá bộ chứa.
Tệp miền phải ở định dạng Avro bằng cách sử dụng giản đồ sau:
{
"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."
}
]
}
Khoá bộ chứa
Khoá bộ chứa trong miền đầu ra phải được biểu thị dưới dạng chuỗi byte thập lục phân.
Ví dụ:
Nếu khoá bộ chứa là giá trị thập phân 1369:
Chuyển đổi 1369 sang giá trị thập lục phân tương đương: 559
Chuyển đổi chuỗi thập lục phân "559" thành chuỗi byte.
Sau đó, chuỗi byte đại diện cho khoá bộ chứa này sẽ được đưa vào giản đồ Avro của miền đầu ra.
Những điều quan trọng cần cân nhắc:
Loại dữ liệu: Khoá bộ chứa trong giản đồ Avro phải được xác định là loại byte để phù hợp với cách biểu thị chuỗi byte hex.
Chuyển đổi: Bạn có thể triển khai việc chuyển đổi từ thập phân sang hệ thập lục phân rồi sang chuỗi byte bằng Python hoặc Java.
Phương pháp này đảm bảo rằng khoá bộ chứa được định dạng đúng cách và tương thích với loại dữ liệu dự kiến trong giản đồ Avro cho miền đầu ra.
Báo cáo theo lô
Để biết thông tin chi tiết về hạn mức quyền riêng tư và chiến lược phân lô, hãy xem tài liệu về chiến lược phân lô. Xin lưu ý rằng các báo cáo tổng hợp có giới hạn MAX_REPORT_AGE (hiện là 90 ngày) giữa scheduled_report_time và ngày chạy hàng loạt.
Báo cáo tóm tắt
Sau khi tạo lô, Dịch vụ tổng hợp sẽ tạo báo cáo tóm tắt ở định dạng Avro bằng cách sử dụng giản đồ results.avsc.
Sau khi công việc hoàn tất, báo cáo tóm tắt sẽ được lưu trữ trong output_data_blob_prefix trong bộ chứa output_data_bucket_name như đã nêu trong yêu cầu createJob.
Đối với các lô Dịch vụ tổng hợp đã bật debug_run, dịch vụ này sẽ tạo hai báo cáo, báo cáo tóm tắt và báo cáo tóm tắt gỡ lỗi. Báo cáo tóm tắt gỡ lỗi nằm trong thư mục output_data_blob_prefix/debug. Báo cáo tóm tắt gỡ lỗi sử dụng giản đồ debug_results.avsc.
Cả báo cáo tóm tắt và báo cáo gỡ lỗi đều được đặt tên là [output_data_blob_prefix]-1-of-1.avro. Nếu output_data_blob_prefix là summary/summary.avro, thì báo cáo sẽ nằm trong thư mục tóm tắt có tên summary-1-of-1.avro.
Ví dụ về results.avsc
Sau đây là ví dụ về giản đồ Avro cho results.avsc:
{
"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"
}
]
}
Giản đồ Avro mẫu xác định một bản ghi có tên là AggregatedFact.
Ví dụ về debug_results.avsc
Sau đây là ví dụ về giản đồ Avro cho debug_results.avsc:
{
"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"]
}
}
]
}
Sau khi chuyển đổi, báo cáo tóm tắt của bạn sẽ giống như ví dụ results.json. Khi debug_run được bật, báo cáo tóm tắt gỡ lỗi trả về sẽ tương tự như ví dụ debug_results.json.
Định dạng báo cáo Avro
Các báo cáo Avro nhận được từ Dịch vụ tổng hợp thường tuân theo một định dạng nhất quán. Định dạng báo cáo Avro bao gồm các trường sau:
bộ chứa: Giá trị nhận dạng duy nhất cho hoạt động tổng hợp dữ liệu (Ví dụ: "\u0005Y").
metric: Giá trị tổng hợp cho bộ chứa tương ứng. Giá trị này thường bao gồm cả độ nhiễu để tăng cường quyền riêng tư.
Ví dụ:
{
"bucket": "\u0005Y",
"metric": 26308
}
Ví dụ về debug_results.json
Báo cáo gỡ lỗi Avro từ Dịch vụ tổng hợp sẽ giống như ví dụ debug_results.json sau. Các báo cáo này bao gồm khoá nhóm, unnoised_metric (thông tin tóm tắt về khoá nhóm trước khi áp dụng nhiễu) và nhiễu được thêm vào chỉ số đó.
{
"bucket": "\u0005Y",
"unnoised_metric": 128,
"noise": -17948,
"annotations": [
"in_reports",
"in_domain"
]
}
Chú thích cũng chứa các giá trị sau:
in_reports: khoá nhóm có trong báo cáo tổng hợpin_domain: khoá bộ chứa có sẵn bên trong tệp Avrooutput_domain