Trang này được dịch bởi Cloud Translation API.

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), báo cáo đã mã hoá sẽ được gửi từ trình duyệt Chrome / phía ứng dụng đến điểm cuối báo cáo của công nghệ quảng cáo. Đây là URL .well-known có nguồn gốc báo cáo của công nghệ quảng cáo. Công nghệ quảng cáo lưu trữ điểm cuối báo cáo để thu thập các báo cáo đã mã hoá.

Sau đây là các điểm cuối của 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
- Trực tiếp [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 các 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 chuyển đổi, báo cáo AVRO sẽ được lưu trữ trong bộ nhớ trên đám mây của công nghệ quảng cáo để tạo báo cáo theo lô sau này.

Khi đã sẵn sàng để tạo lô, công nghệ quảng cáo sẽ kích hoạt yêu cầu công việc tổng hợp thông qua dịch vụ tổng hợp, nơi các báo cáo được truy xuất từ bộ nhớ trên đá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ớ trên đám mây của công nghệ quảng cáo và phải có hình ảnh có 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 báo cáo JSON sang AVRO

Khi tạo báo cáo theo lô, báo cáo tổng hợp cần ở định dạng AVRO. Để tạo báo cáo AVRO, bạn cần có giản đồ báo cáo AVRO (AVSC).

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

Sau đây là Giản đồ AVRO cho báo cáo 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"
      }
    ]
  }

Thông số	Loại	Mô tả
`payload`	Byte	Bạn cần giải mã tải trọng 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 chính thức.
`debug_cleartext_payload`	Byte	Bạn cần giải mã tải trọng 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 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 128 bit tương tự.
`shared_info`	Chuỗi	Đây sẽ là chuỗ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\"}"
}

Miền đầu ra AVRO

Để tạo báo cáo tóm tắt bằng Dịch vụ tổng hợp, công nghệ quảng cáo yêu cầu báo cáo tổng hợp và tệp miền. Báo cáo tổng hợp sẽ là báo cáo JSON nhận được ở 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 sẽ được thu thập từ các báo cáo tổng hợp và sẽ đượ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 Báo cáo phân bổ và các khoá trong tính năng Tổng hợp riêng tư. Miền đầu ra sẽ chứa bộ chứa trường và giá trị bộ chứa sẽ là khoá bộ chứa.

Tệp miền cũng cần ở đị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. 128-bit integer encoded as a 16-byte big-endian bytestring."
      }
    ]
  }

Khoá bộ chứa

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

Báo cáo theo lô

Để hiểu rõ hơn về ngân sách quyền riêng tư và tính năng phân lô, hãy xem tài liệu về chiến lược phân lô. Ngoài ra, xin lưu ý rằng bạn chỉ có thể phân lô một báo cáo 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 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áo cáo tóm tắt sử dụng giản đồ results.avsc.

Báo cáo tóm tắt sẽ nằm trong output_data_blob_prefix trong bộ chứa 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 đã 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 sẽ nằm trong thư mục output_data_blob_prefix/debug.

Báo cáo gỡ lỗi được tạo 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 là summary/summary.avro, báo cáo sẽ nằm trong thư mục tóm tắt có tên 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 sẽ có dạng như results.json mẫu. 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á bộ chứa và giá trị tóm tắt / tổng hợp với độ nhiễu bổ sung của các giá trị bộ chứa.

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

debug_results.json (ví dụ)

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 khoá bộ chứa, unnoised_metric (tóm tắt khoá bộ chứa 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, có nghĩa là:

in_reports: khoá bộ chứa có trong báo cáo tổng hợp
in_domain: khoá bộ chứa có sẵn bên trong tệp AVRO output_domain