รับและจัดเก็บรายงานที่รวบรวมได้

เมื่อเทคโนโลยีโฆษณาเรียกใช้ Measurement API (Attribution Reporting API หรือ Private Aggregation API) ระบบจะส่งรายงานที่เข้ารหัสจากเบราว์เซอร์ Chrome/ฝั่งไคลเอ็นต์ไปยังปลายทางการรายงานของเทคโนโลยีโฆษณา ซึ่งเป็น URL .well-known ที่มีต้นทางการรายงานของเทคโนโลยีโฆษณา ปลายทางการรายงานโฮสต์โดยเทคโนโลยีโฆษณาเพื่อรวบรวมรายงานที่เข้ารหัส

แผนภาพรายงาน AgS

ปลายทางตาม API มีดังนี้

  • การรวมข้อมูลส่วนบุคคล

    • แก้ไขข้อบกพร่อง [reporting-origin]/.well-known/private-aggregation/debug/report-shared-storage
    • ข้อมูลสด [reporting-origin]/.well-known/private-aggregation/report-shared-storage หรือ /.well-known/private-aggregation/report-protected-audience
  • การรายงานการระบุแหล่งที่มา

    • แก้ไขข้อบกพร่อง [reporting-origin]/.well-known/attribution-reporting/debug/report-aggregate-attribution
    • ถ่ายทอดสด [reporting-origin]/.well-known/attribution-reporting/report-aggregate-attribution

เทคโนโลยีโฆษณาจะได้รับรายงานในรูปแบบ JSON ผ่านการเรียกใช้ POST เทคโนโลยีโฆษณาจะรวบรวมรายงาน JSON เหล่านี้และแปลงเป็นรูปแบบ AVRO ซึ่งใช้ในบริการรวบรวมข้อมูลในภายหลัง เมื่อแปลงแล้ว รายงาน AVRO จะจัดเก็บไว้ในพื้นที่เก็บข้อมูลระบบคลาวด์ของเทคโนโลยีโฆษณาเพื่อจัดกลุ่มในภายหลัง

เมื่อเทคโนโลยีโฆษณาพร้อมสำหรับการจัดกลุ่มแล้ว เทคโนโลยีโฆษณาจะเรียกใช้คำของานการรวมผ่านบริการรวมข้อมูลซึ่งดึงรายงานมาจากพื้นที่เก็บข้อมูลระบบคลาวด์ของเทคโนโลยีโฆษณา บริการรวบรวมข้อมูลจะโฮสต์อยู่ในพื้นที่เก็บข้อมูลระบบคลาวด์ของเทคโนโลยีโฆษณาและควรมีรูปภาพที่อนุญาต

รายงานที่ได้รับจะมีลักษณะคล้ายกับรายงานต่อไปนี้

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

เมื่อมีการจัดกลุ่ม รายงานที่รวบรวมได้จะต้องอยู่ในรูปแบบ AVRO หากต้องการสร้างรายงาน AVRO คุณจะต้องมีสคีมา AVRO ของรายงาน (AVSC)

มีตัวอย่างโค้ด JavaScript ในที่เก็บ GitHub ของ Aggregation Service

คุณมีไฟล์ AVRO 1 ไฟล์สําหรับรายงานทั้งหมดหรือแยกรายงานออกเป็นไฟล์ AVRO หลายไฟล์ก็ได้ ไม่มีการจำกัดขนาด AVRO ด้วยเหตุผลด้านประสิทธิภาพ เราขอแนะนำให้จำกัดจำนวนไฟล์ AVRO ให้อยู่ระหว่างจำนวน CPU ที่ใช้ได้สำหรับอินสแตนซ์ Cloud กับ 1, 000

ต่อไปนี้เป็นสคีมา 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 ไบต์ จะต้องถอดรหัสเพย์โหลดเป็น Base64 และแปลงเป็นอาร์เรย์ไบต์จาก payload สำหรับรายงานเวอร์ชันที่ใช้งานจริง/เวอร์ชันที่เผยแพร่
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 ที่ได้รับในต้นทางการรายงานและแปลงเป็นรูปแบบ AVRO โดเมนเอาต์พุตจะมีคีย์ที่ประกาศไว้ล่วงหน้า ซึ่งจะรวบรวมจากรายงานที่รวบรวมได้และจะถูกเขียนลงในรายงานสรุป ดูข้อมูลเพิ่มเติมเกี่ยวกับคีย์เหล่านี้ในการรายงานการระบุแหล่งที่มาและคีย์ในการรวมข้อมูลส่วนตัว โดเมนเอาต์พุตจะมีที่เก็บข้อมูลฟิลด์ และค่าที่เก็บข้อมูลจะเป็นคีย์ที่เก็บข้อมูล

ไฟล์โดเมนต้องอยู่ในรูปแบบ AVRO ด้วยสคีมาต่อไปนี้

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

คีย์ที่เก็บข้อมูล

คีย์ของที่เก็บข้อมูลควรเป็นสตริงไบต์ฐาน 16 ของคีย์ของที่เก็บข้อมูล ตัวอย่างของกรณีนี้คือการมีคีย์ 1369 ในทศนิยม เมื่อแปลงเป็นเลขฐานสิบหกแล้ว ค่าจะเท่ากับ 559 จากนั้นคุณจะต้องแปลง 559 เป็นสตริงไบต์เพื่อเพิ่มลงในโดเมนเอาต์พุต AVRO

แผนภาพคีย์ที่เก็บข้อมูล AgS

รายงานแบบกลุ่ม

หากต้องการทําความเข้าใจเพิ่มเติมเกี่ยวกับงบประมาณความเป็นส่วนตัวและการรวมกลุ่ม ให้ไปที่เอกสารกลยุทธ์การรวมกลุ่ม และโปรดทราบว่ารายงานที่รวบรวมได้จะรวมกลุ่มได้ภายในระยะเวลาหนึ่งๆ เท่านั้น รายงานไม่ควรเกิน MAX_REPORT_AGE ระหว่างวันที่ scheduled_report_time และวันที่เรียกใช้แบบกลุ่ม (ปัจจุบันคือ 90 วัน)

รายงานสรุป

หลังจากจัดกลุ่มแล้ว บริการรวบรวมข้อมูลจะสร้างรายงานสรุปในรูปแบบ AVRO รายงานสรุปใช้สคีมา results.avsc

รายงานสรุปจะอยู่ใน output_data_blob_prefix ในที่เก็บข้อมูล output_data_bucket_name ที่ระบุไว้ในคำขอ createJob

สําหรับกลุ่มบริการรวบรวมข้อมูลที่มีการเปิดใช้ debug_run ระบบจะสร้างรายงาน 2 ฉบับ รายงานสรุปและรายงานสรุปการแก้ไขข้อบกพร่อง รายงานสรุปการแก้ไขข้อบกพร่องจะอยู่ในโฟลเดอร์ output_data_blob_prefix/debug

รายงานการแก้ไขข้อบกพร่องที่สร้างขึ้นจะใช้สคีมา debug_results.avsc

ระบบจะตั้งชื่อทั้งรายงานสรุปและแก้ไขข้อบกพร่องเป็น [output_data_blob_prefix]-1-of-1.avro หาก out_data_blob_prefix คือ summary/summary.avro รายงานก็จะอยู่ในโฟลเดอร์สรุปชื่อ 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"]
          }
       }
    ]
  }

เมื่อแปลงแล้ว รายงานสรุปของคุณจะมีลักษณะเหมือนตัวอย่าง results.json เมื่อเปิดใช้ debug_run รายงานสรุปการแก้ไขข้อบกพร่องจะแสดงผลลัพธ์ที่คล้ายกับตัวอย่าง debug_results.json

results.json (ตัวอย่าง)

รายงาน AVRO ที่มาจากบริการรวบรวมข้อมูลอาจมีลักษณะคล้ายกันเมื่อคุณมีคีย์ที่เก็บข้อมูลและค่าสรุป/ค่ารวมที่มีค่าที่เก็บข้อมูลเพิ่มเติม

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

debug_results.json (ตัวอย่าง)

การแก้ไขข้อบกพร่องของรายงาน AVRO ที่มาจาก Aggregation Service ควรมีลักษณะคล้ายกับตำแหน่งต่อไปนี้ที่คุณได้รับคีย์ที่เก็บข้อมูล unnoised_metric (สรุปของคีย์ที่เก็บข้อมูลที่ไม่มีสัญญาณรบกวน) และสัญญาณรบกวนที่เพิ่มลงใน unnoised_metric

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

คําอธิบายประกอบจะมี in_reports และ/หรือ in_domain ด้วย ซึ่งหมายความว่า

  • in_reports: คีย์ที่เก็บข้อมูลอยู่ในรายงานที่รวบรวมได้
  • in_domain: คีย์ที่เก็บข้อมูลอยู่ในไฟล์ output_domain AVRO