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. Điểm cuối báo cáo do 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

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
- Trực tiếp [reporting-origin]/.well-known/private-aggregation/report-shared-storage hoặc /.well-known/private-aggregation/report-protected-audience
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ô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ông nghệ quảng cáo sẽ thu thập những báo cáo JSON này rồi chuyển đổi chúng thành định dạng AVRO 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 trông giống như sau:

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

  {
    "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 phân lô, các báo cáo tổng hợp cần phải ở đị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.

Bạn có thể có 1 tệp AVRO cho tất cả báo cáo hoặc chia báo cáo thành nhiều tệp AVRO. Không có giới hạn về kích thước AVRO. Để đảm bảo hiệu suất, bạn nên duy trì số lượng tệp AVRO ở mức nằm trong khoảng từ số lượng CPU có sẵn cho phiên bản Cloud của mình và 1.000.

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	Tải trọng cần được giải mã base64 và chuyển đổi thành một mảng byte từ `payload` cho các báo cáo trực tiếp / thực tế.
`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 trên toàn cầu 128 bit.
`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ề tệp json của báo cáo:

{ 
   "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 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 những khoá được khai báo trước mà sẽ được thu thập qua 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á 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 phải ở định dạng AVRO 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á bộ chứa phải là một chuỗi byte hex của khoá bộ chứa. Ví dụ cho trường hợp này là khoá của bạn là 1369 thuộc 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

Sơ đồ khoá bộ chứa AgS

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 tạo lô, hãy xem tài liệu về chiến lược tạo lô. Ngoài ra, xin lưu ý rằng bạn chỉ có thể tạo lô cho một báo cáo tổng hợp trong một khoảng thời gian nhất định. Một báo cáo không được vượt quá MAX_REPORT_AGE 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 giản đồ results.avsc.

Báo cáo tóm tắt sẽ nằm ở output_data_blob_prefix thuộc 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, lô 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 đã 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 đều sẽ đượ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 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 sẽ trông giố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ụ)

Các báo cáo gỡ lỗi AVRO đến từ Dịch vụ tổng hợp sẽ có dạng như sau khi bạn nhận được khoá bộ chứa, unnoised_metric (tóm tắt các 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á nhóm có trong báo cáo tổng hợp
in_domain: khoá nhóm có trong tệp AVRO output_domain