Nhận và lưu trữ báo cáo tổng hợp

Khi công nghệ quảng cáo kích hoạt các API đo lường (Attribution Reporting API hoặc Private Aggregation API), các báo cáo đã mã hoá sẽ được gửi từ trình duyệt Chrome / phía máy khách đến điểm cuối báo cáo của công nghệ quảng cáo. Đây là một URL .well-known có nguồn gốc báo cáo của công nghệ quảng cáo. Điểm cuối báo cáo được công nghệ quảng cáo lưu trữ để thu thập các báo cáo đã mã hoá.

Sơ đồ báo cáo AgS.
Sơ đồ báo cáo AgS.

Sau đây là các điểm cuối cho mỗi API:

  • Tổng hợp riêng tư

    • Gỡ lỗi [reporting-origin]/.well-known/private-aggregation/debug/report-shared-storage
    • [reporting-origin]/.well-known/private-aggregation/report-shared-storage hoặc /.well-known/private-aggregation/report-protected-audience trực tiếp

  • Attribution Reporting

    • Gỡ lỗi [reporting-origin]/.well-known/attribution-reporting/debug/report-aggregate-attribution
    • Tình trạng lúc [reporting-origin]/.well-known/attribution-reporting/report-aggregate-attribution

Các công nghệ quảng cáo sẽ nhận được báo cáo ở định dạng JSON thông qua lệnh gọi POST. Các công nghệ quảng cáo sẽ thu thập những báo cáo JSON này và sau đó chuyển đổi chúng thành định dạng AVRO được dùng trong Dịch vụ tổng hợp. Sau khi được chuyển đổi, báo cáo AVRO sẽ được lưu trữ trong bộ nhớ đám mây của công nghệ quảng cáo để phân lô sau này.

Sau khi công nghệ quảng cáo sẵn sàng phân lô, công nghệ quảng cáo sẽ kích hoạt một yêu cầu về công việc tổng hợp thông qua dịch vụ tổng hợp. Tại đây, các báo cáo sẽ được truy xuất từ bộ nhớ đám mây của công nghệ quảng cáo. Dịch vụ tổng hợp được lưu trữ trên bộ nhớ đám mây của công nghệ quảng cáo và phải có một hình ảnh trong danh sách cho phép.

Các báo cáo nhận được sẽ có dạng như sau:

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"
  }

Chuyển đổi JSON thành báo cáo AVRO

Khi được xử lý theo lô, các báo cáo có thể tổng hợp cần ở định dạng AVRO. Để tạo báo cáo AVRO, bạn sẽ cần có giản đồ AVRO (AVSC) của báo cáo.

Bạn có thể xem mã javascript mẫu trên kho lưu trữ Dịch vụ tổng hợp của GitHub.

Sau đây là giản đồ AVRO cho Báo cáo có thể tổng hợp. Các trường khác nhau cho báo cáo là 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"
      }
    ]
  }
Tham số Loại Mô tả
payload Byte Tải trọng sẽ cần được giải mã base64 và chuyển đổi thành một mảng byte từ payload cho báo cáo trực tiếp / báo cáo sản xuất.
debug_cleartext_payload Byte Tải trọng sẽ cần được giải mã base64 và chuyển đổi thành một mảng byte từ debug_cleartext_payload cho các báo cáo gỡ lỗi.
key_id Chuỗi Đây sẽ là chuỗi key_id có trong báo cáo. key_id sẽ là một giá trị nhận dạng duy nhất trên toàn cầu có độ dài 128 bit.
shared_info Chuỗi Đây sẽ là chuỗi không bị giả mạo trong trường shared_info của báo cáo.

Đây là một 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\"}"
}

AVRO miền đầu ra

Để tạo báo cáo tóm tắt bằng Aggregation Service, công nghệ quảng cáo cần có báo cáo có thể tổng hợp và tệp miền. Các báo cáo có thể tổng hợp sẽ là báo cáo JSON nhận được trong nguồn báo cáo và được chuyển đổi sang định dạng AVRO. Miền đầu ra sẽ chứa các khoá được khai báo trước, được thu thập từ báo cáo tổng hợp và được ghi vào báo cáo tóm tắt. Tìm hiểu thêm về các khoá này trong Attribution Reporting và các khoá trong Private Aggregation. Miền đầu ra sẽ chứa nhóm trường và giá trị nhóm sẽ là khoá nhóm của bạn.

Tệp miền cũng cần ở định dạng AVRO bằng cách sử dụng lược đồ sau:

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

Khoá bộ chứa

Khoá nhóm phải là một chuỗi byte hex của khoá nhóm. Ví dụ: bạn có khoá là 1369 ở dạng số thập phân. Khi chuyển đổi sang hệ thập lục phân, giá trị này sẽ là 559. Sau đó, bạn sẽ cần chuyển đổi 559 thành một chuỗi byte để thêm vào miền đầu ra AVRO

Sơ đồ khoá nhóm AgS.
Sơ đồ khoá nhóm AgS.

Báo cáo theo lô

Để tìm hiểu thêm về hạn mức quyền riêng tư và việc xử lý hàng loạt, hãy xem tài liệu về các chiến lược xử lý hàng loạt. Ngoài ra, hãy lưu ý rằng bạn chỉ có thể xử lý hàng loạt một báo cáo có thể tổng hợp trong một khoảng thời gian nhất định. Báo cáo không được vượt quá MAX_REPORT_AGE trong khoảng thời gian từ scheduled_report_time đến ngày chạy hàng loạt (hiện là 90 ngày).

Báo cáo tóm tắt

Sau khi phân lô, Dịch vụ tổng hợp sẽ tạo báo cáo tóm tắt ở định dạng AVRO. Báo cáo tóm tắt sử dụng lược đồ results.avsc.

Báo cáo tóm tắt sẽ nằm trong output_data_blob_prefix trong nhóm output_data_bucket_name được nêu trong yêu cầu createJob.

Đối với các lô Dịch vụ tổng hợp có bật debug_run, dịch vụ này sẽ tạo 2 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 sẽ nằm trong thư mục output_data_blob_prefix/debug.

Báo cáo gỡ lỗi được tạo sẽ 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 sẽ được đặt tên là [output_data_blob_prefix]-1-of-1.avro. Nếu output_data_blob_prefix của bạn là summary/summary.avro, thì báo cáo sẽ nằm trong thư mục tóm tắt có tên là 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"]
          }
       }
    ]
  }

Sau khi chuyển đổi, báo cáo tóm tắt của bạn sẽ có dạng như ví dụ results.json. Khi debug_run được bật, báo cáo tóm tắt gỡ lỗi sẽ trả về nội dung tương tự như ví dụ debug_results.json.

results.json (ví dụ)

Các báo cáo AVRO đến từ Dịch vụ tổng hợp có thể trông tương tự nhau khi bạn có khoá nhóm và giá trị tóm tắt / tổng hợp có thêm nhiễu của các giá trị nhóm.

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

debug_results.json (ví dụ)

Các báo cáo gỡ lỗi AVRO đến từ Dịch vụ tổng hợp sẽ có dạng tương tự như sau, trong đó bạn nhận được các khoá nhóm, unnoised_metric (thông tin tóm tắt về các khoá nhóm không có nhiễu) và nhiễu được thêm vào unnoised_metric.

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

Chú thích cũng sẽ chứa in_reports và / hoặc in_domain, tức là:

  • in_reports: khoá nhóm có trong báo cáo tổng hợp
  • in_domain: khoá nhóm có trong tệp output_domain AVRO