קבלה ואחסון של דוחות שניתן לצבור

כשטכנולוגיות הפרסום מפעילים ממשקי API למדידה (Attribution Reporting API או Private Aggregation API), הדוחות המוצפנים נשלחים מדפדפן Chrome או מצד הלקוח לנקודת הקצה לדיווח של טכנולוגיית הפרסום, שהיא כתובת URL .well-known עם מקור הדיווח של טכנולוגיית הפרסום. נקודת הקצה של הדיווח מתארחת אצל טכנולוגיות פרסום (ATP) כדי לאסוף את הדוחות המוצפנים.

תרשים של דוח 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
  • דוחות שיוך (Attribution)

    • ניפוי באגים [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 של שירות הצבירה.

אתם יכולים לשמור קובץ AVRO אחד לכל הדוחות או לפצל את הדוחות לכמה קובצי 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 בייטים צריך לפענח את המטען הייעודי (Payload) ב-base64 ולהמיר אותו למערך בייטים מ-payload בדוחות של שידורים חיים או דוחות ייצור.
debug_cleartext_payload בייטים צריך לפענח את המטען הייעודי (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

כדי ליצור דוחות סיכום באמצעות שירות הצבירה, ל-AdTech נדרשים הדוחות שאפשר לצבור ואת קובץ הדומיין. הדוחות הנצברים יהיו דוחות JSON שהתקבלו במקור הדיווח ויומרו לפורמט AVRO. דומיינים של פלט יכילו את המפתחות המוצהרים מראש שייאספו מהדוחות המצטברים ויירשמו בדוחות הסיכום. מידע נוסף על המפתחות האלה זמין בדוחות שיוך (Attribution) ובדוחות על צבירת נתונים פרטית. דומיין הפלט יכיל את קטגוריית השדה וערך הקטגוריה יהיה מפתח הקטגוריה.

קובץ הדומיין צריך להיות גם בפורמט 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 ל-bytestring כדי להתווסף לדומיין הפלט AVRO

תרשים מפתחות של קטגוריית AgS

דוחות באצווה

מידע נוסף על תקציבי פרטיות ועל קיבוץ זמין במסמך שיטות קיבוץ. חשוב לזכור שאפשר לקבץ דוחות שניתנים לצבירה רק בתקופה מסוימת. הדוח לא יכול לחרוג מ-MAX_REPORT_AGE בין scheduled_report_time לבין תאריך ההרצה של האצווה (כיום 90 יום).

דוחות סיכום

אחרי הקיבוץ, שירות הצבירה יוצר את דוח הסיכום בפורמט AVRO. בדוח הסיכום נעשה שימוש בסכימה results.avsc.

דוח הסיכום ימוקם בקטע output_data_blob_prefix בקטגוריה output_data_bucket_name שצוינה בבקשה createJob.

באצווה של שירות צבירה שבה הפונקציה debug_run מופעלת, נוצרים שני דוחות. דוח הסיכום ודוח הסיכום של ניפוי הבאגים. דוח הסיכום של ניפוי הבאגים ימוקם בתיקייה output_data_blob_prefix/debug.

תבנית ה-schema שמשמשת את דוח ניפוי הבאגים שנוצר היא debug_results.avsc.

גם דוח הסיכום וגם דוח ניפוי הבאגים ייקראו [output_data_blob_prefix]-1-of-1.avro. אם הפלט_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.

result.json (דוגמה)

דוחות AVRO שמגיעים מ-Aggregation Service יכולים להיראות דומים, כאשר יש את מפתח הקטגוריה ואת הערך הסיכום/הערך המצטבר עם רעש נוסף של ערכי הקטגוריה.

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

debug_results.json (דוגמה)

דוחות של ניפוי באגים שמקורם בשירות הצבירה אמורים להיראות דומים לאלה שבהם מקבלים את המפתחות של הקטגוריה, unnoised_metric (סיכום של מפתחות הקטגוריה ללא רעש) והרעש שמתווסף לunnoised_metric.

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

ההערות יכללו גם את הערכים in_reports ו/או in_domain, שמשמע:

  • in_reports: מפתח הקטגוריה זמין בדוחות הנצברים
  • in_domain: מפתח הקטגוריה זמין בקובץ AVRO‏ output_domain