تلقّي التقارير القابلة للتجميع وتخزينها

عندما تنشئ تكنولوجيات الإعلان واجهات برمجة تطبيقات لقياس الأداء (Attribution Reporting API أو Private Aggregation API)، يتم إرسال التقارير المشفّرة من متصفّح Chrome أو من جهة العميل إلى نقطة نهاية إعداد تقارير تكنولوجيا الإعلان، وهي عنوان URL‏ .well-known يتضمّن مصدر إعداد تقارير تكنولوجيا الإعلان. تستضيف تقنية الإعلان نقطة نهاية إعداد التقارير من أجل جمع التقارير المشفّرة.

مخطّط بياني لتقرير AgS

في ما يلي نقاط النهاية لكل واجهة برمجة تطبيقات:

  • التجميع الخاص

    • تصحيح الأخطاء [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 الخاص بخدمة تجميع البيانات.

في ما يلي مخطّط 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."
      }
    ]
  }

مفتاح الحزمة

يجب أن يكون مفتاح الحزمة سلسلة ثماني بتات سداسية لمفتاح الحزمة. على سبيل المثال، سيكون المفتاح 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 فيها، يتم إنشاء تقريرَين. التقرير الملخّص وتقرير ملخّص تصحيح الأخطاء سيظهر تقرير ملخّص تصحيح الأخطاء في مجلد output_data_blob_prefix/debug.

يستخدم تقرير تصحيح الأخطاء الذي تم إنشاؤه مخطّط debug_results.avsc.

سيتم تسمية كل من الملخص وتقرير تصحيح الأخطاء باسم [output_data_blob_prefix]-1-of-1.avro. إذا كان البادئة output_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 الواردة من خدمة التجميع مشابهة لما يلي حيث تتلقّى مفاتيح الحِزم و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