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

يوضّح هذا الدليل كيفية إرسال تقارير القياس المشفّرة إلى مزوّدي تقنية الإعلان. تُرسِل متصفّحات Chrome وعملاؤها هذه التقارير إلى نقاط نهاية محددة لإعداد التقارير، حيث تتلقّى منصّة تكنولوجيا الإعلان التقارير القابلة للتجميع وتخزّنها. تستضيف المنصة نقاط النهاية هذه، التي تقع على .well-known عنوان URL ضمن مصدر إعداد التقارير لدى مقدّم الخدمة، ما يتيح لمزوّدي تقنية الإعلان الذين يستخدمون Attribution Reporting API أو Private Aggregation API الوصول إليها.

عملية تلقّي التقارير القابلة للتجميع وتخزينها ضمن خدمة التجميع في "مبادرة حماية الخصوصية"
الشكل 1: خدمة تجميع البيانات: معالجة التقارير القابلة للتجميع

توضِّح الخطوات التالية بالتفصيل عملية "خدمة التجميع" لتلقّي التقارير القابلة للتجميع وتخزينها:

  1. عند بدء الميزة، يرسل المتصفّح تقارير قابلة للتجميع تحتوي على تفاصيل عن بيانات الإحالات الناجحة وبيانات المواقع الإلكترونية المختلفة.
  2. يرسل المتصفّح التقارير المشفّرة إلى عنوان URL .well-known ضمن نطاق إعداد تقارير تكنولوجيا الإعلان.
  3. يعيد النظام توجيه دفعات التقارير إلى "خدمة التجميع" لمعالجتها.
  4. تلخِّص خدمة التجميع التقارير إحصائيًا.
  5. تضيف "خدمة التجميع" تشويشًا إلى البيانات الملخّصة لتعزيز خصوصية المستخدم.
  6. يُتيح النظام التقارير لشركة تكنولوجيا الإعلان لأغراض التحليل والقياس.

يوضّح الجدول التالي نقاط النهاية لإصدار التعديل وإصدار البث المباشر لكلّ من Private Aggregation API وAttribution Reporting API:

واجهة برمجة التطبيقات نقطة نهاية الوصف
Private Aggregation API
نقطة نهاية تصحيح الأخطاء:
[reporting-origin]/.well-known/private-aggregation/debug/report-shared-storage
نقاط النهاية المباشرة:
  • [reporting-origin]/.well-known/private-aggregation/report-shared-storage
  • [reporting-origin]/.well-known/private-aggregation/report-protected-audience
نقطة نهاية تصحيح الأخطاء:
لتطوير Private Aggregation API واختبارها
نقاط النهاية المباشرة:
تلقّي تقارير القياس ومعالجتها في البيئات المباشرة
Attribution Reporting API
نقطة نهاية تصحيح الأخطاء:
[reporting-origin]/.well-known/attribution-reporting/debug/report-aggregate-attribution
نقطة النهاية المباشرة:
[reporting-origin]/.well-known/attribution-reporting/report-aggregate-attribution
نقطة نهاية تصحيح الأخطاء:
لتطوير Attribution Reporting API واختبارها
نقاط النهاية المباشرة:
  • نقطة نهاية الإصدار العلني لتقارير الإحالة المجمّعة
  • تتلقّى هذه الخدمة تقارير تحديد المصدر المجمّعة وتعالجها في بيئات الإنتاج المباشر لقياس الأداء.

تتلقّى مصادر إعداد التقارير تقارير JSON من خلال طلبات POST. بعد ذلك، يحوّل النظام هذه التقارير إلى تنسيق Avro ويخزّنها في مساحة التخزين السحابي. بعد معالجة الدفعات، يرسل النظام تقارير Avro إلى خدمة التجميع لتلخيصها.

تُشغّل منصّات تكنولوجيا الإعلان طلبًا لوظائف التجميع إلى "خدمة التجميع" عندما تُعتبر مجموعة من تقارير Avro جاهزة للمعالجة. تسترجع هذه الخدمة، المستضافة في بيئة السحابة الإلكترونية لمنصّة تكنولوجيا الإعلان، تقارير Avro المطلوبة من موقع التخزين نفسه. لأغراض الأمان، يجب ضبط "خدمة التجميع" لاستخدام صورة حاوية موافَق عليها. يُرجى الرجوع إلى مستودع GitHub الخاص بـ "مبادرة حماية الخصوصية"/خدمة التجميع للاطّلاع على صور الحاويات المتاحة.

في ما يلي أمثلة تمثيلية للتقارير التي تعرضها كل واجهة برمجة تطبيقات:

  • مثال على تقرير 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

يجب أن تكون التقارير القابلة للتجميع بتنسيق تسلسل البيانات Apache Avro لأغراض تجميع البيانات. لإنشاء تقرير Avro، يجب استخدام مخطّط AVSC. يحدّد ملف مخطّط AVSC بنية سجلّ Avro ونوع البيانات. للحصول على مثال على مخطّط AVSC، اطّلِع على ملف example.avsc في مستودع GitHub الخاص بـ avrodoc/schemata.

يمكنك العثور على مثال على رمز JavaScript في قسم جمع التقارير وتحويلها وتجميعها ضمن صفحة جمع التقارير القابلة للتجميع وتجميعها في مستودع GitHub على الرابط privacysandbox/aggregation-service.

يمكنك تخزين جميع التقارير في ملف AVRO واحد أو توزيعها على ملفات متعددة. على الرغم من أنّ ملفات AVRO لا تتضمّن حدًا أقصى للحجم، يتم عادةً تحقيق الأداء الأمثل عندما يتراوح عدد الملفات بين عدد وحدات المعالجة المركزية في مثيل السحابة الإلكترونية و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 وتحويله إلى صفيف بايت سواء للتقارير المنشورة أو التقارير العلنية.
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\"}"
}

مواصفات ملف النطاق

تتطلّب إنشاء التقارير التلخيصية باستخدام "خدمة التجميع" التقارير القابلة للتجميع (تقارير JSON التي تم تحويلها إلى Avro) وملف النطاق المرتبط. يستخرج النظام المفاتيح المعلَن عنها مسبقًا من تقاريرك القابلة للتجميع ويُدرِجها في التقارير التلخيصية ضمن نطاقات النتائج. يمكنك العثور على تفاصيل عن مفاتيح التجميع هذه في مقالة فهم مفاتيح التجميع لإعداد تقارير تحديد المصدر وقسم مفتاح التجميع ضمن أساسيات Private Aggregation API. يتضمّن نطاق الإخراج أيضًا الحقل bucket الذي يمثّل قيمة مفتاح الحزمة.

يجب أن يكون ملف النطاق بتنسيق Avro باستخدام المخطّط التالي:

  {
    "type": "record",
    "name": "AggregationBucket",
    "fields": [
      {
        "name": "bucket",
        "type": "bytes",
        "doc": "A single bucket that appears in the aggregation service output. It is an 128-bit integer value encoded as a 16-byte big-endian bytestring."
      }
    ]
  }

مفتاح الحزمة

يجب تمثيل مفتاح الحزمة ضمن نطاق الإخراج كسلسلة بايتات سداسية عشرية.

على سبيل المثال:

إذا كان مفتاح الحزمة هو القيمة العشرية 1369:

  1. حوِّل 1369 إلى القيمة السداسية العشرية المكافئة لها: 559.

  2. حوِّل السلسلة السداسية العشرية "559" إلى سلسلة بايت.

يجب بعد ذلك تضمين تمثيل سلسلة البايتات لمفتاح الحزمة في مخطّط Avro لنطاق الإخراج.

اعتبارات مهمة:

  • نوع البيانات: يجب تعريف مفتاح الحزمة ضمن مخطّط Avro كنوع بايت لاستيعاب تمثيل سلسلة البايت الست عشري.

  • التحويل: يمكن تنفيذ عملية التحويل من النظام العشري إلى النظام الست عشري ثم إلى سلسلة بايت باستخدام Python أو Java.

يضمن هذا النهج أنّ تنسيق مفتاح الحزمة صحيح ومتوافق مع نوع البيانات المتوقّع ضمن مخطّط Avro لنطاق الإخراج.

يجب أن يكون مفتاح الحزمة سلسلة بايت سداسية عشرية. على سبيل المثال، ضع في الاعتبار سلسلة بايت ذات قيمة عشرية تبلغ 1369. عند تحويلها إلى تنسيق سداسي عشري، تكون القيمة 559 لإضافتها إلى نطاق إخراج Avro.
الشكل 2: يوضّح المخطّط البياني عملية تحويل مفتاح الحزمة إلى تمثيل سداسي عشري ثم إلى سلسلة بايت، ويتم استخدامها في النهاية لتعبئة مخطّط AVRO لنطاق الإخراج.

التقارير المجمّعة

للحصول على تفاصيل حول ميزانيات الخصوصية واستراتيجيات تجميع البيانات، يُرجى الاطّلاع على مستندات استراتيجيات تجميع البيانات. يُرجى العلم أنّ التقارير القابلة للتجميع لها حدّ MAX_REPORT_AGE (90 يومًا حاليًا) بين scheduled_report_time وتاريخ تنفيذ الدُفعة.

التقارير الموجزة

بعد تجميع البيانات، تنشئ خدمة التجميع التقرير التلخيصي بتنسيق 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

في ما يلي مثال على مخطّط Avro لـ results.avsc:

{
  "type": "record",
  "name": "AggregatedFact",
  "fields": [
    {
      "name": "bucket",
      "type": "bytes",
      "doc": "Histogram bucket used in aggregation. It is an 128-bit integer value encoded as a 16-byte big-endian bytestring. Leading 0-bits are left out."
    },
    {
      "name": "metric",
      "type": "long",
      "doc": "The metric associated with the bucket"
    }
  ]
}

يحدِّد مثال مخطّط Avro سجلّاً باسم AggregatedFact.

مثال لـ debug_results.avsc

في ما يلي مثال على مخطّط Avro لـ debug_results.avsc:

  {
  "type": "record",
  "name": "DebugAggregatedFact", Output domains include summary reports that contain pre-declared keys extracted from your aggregatable reports.
  "fields": [
      {
        "name": "bucket",
        "type": "bytes",
        "doc": "This represents the histogram bucket used in aggregation. It's a 128-bit integer, encoded as a 16-byte big-endian bytestring, with leading zero bytes omitted.."
      },
      {
        "name": "unnoised_metric",
        "type": "long",
        "doc": "The raw metric for 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.

تنسيق تقارير Avro

تلتزم تقارير Avro التي يتم استلامها من "خدمة التجميع" عادةً بنمط ثابت. يتضمّن تنسيق تقرير Avro الحقول التالية:

  • الحزمة: معرّف فريد لتجميع البيانات (على سبيل المثال، "\u0005Y").

  • المقياس: القيمة المجمّعة للمجموعة المقابلة. غالبًا ما تتضمّن هذه القيمة تشويشًا إضافيًا لتعزيز الخصوصية.

    على سبيل المثال:

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

مثال لـ debug_results.json

ستتشابه تقارير تصحيح أخطاء Avro من "خدمة التجميع" مع مثال debug_results.json التالي. تتضمّن هذه التقارير مفاتيح الحِزم وunnoised_metric (ملخّص مفاتيح الحِزم قبل تطبيق الضوضاء) والضوضاء المُضافة إلى هذا المقياس.

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

تحتوي التعليقات التوضيحية أيضًا على القيم التالية:

  • in_reports: مفتاح الحزمة المتاح داخل التقارير القابلة للتجميع

  • in_domain: مفتاح الحزمة المتوفّر داخل ملف Avro‏ output_domain