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

توضِّح الخطوات التالية بالتفصيل عملية "خدمة التجميع" لتلقّي التقارير القابلة للتجميع وتخزينها:
- عند بدء الميزة، يرسل المتصفّح تقارير قابلة للتجميع تحتوي على تفاصيل عن بيانات الإحالات الناجحة وبيانات المواقع الإلكترونية المختلفة.
- يرسل المتصفّح التقارير المشفّرة إلى عنوان URL
.well-known
ضمن نطاق إعداد تقارير تكنولوجيا الإعلان. - يعيد النظام توجيه دفعات التقارير إلى "خدمة التجميع" لمعالجتها.
- تلخِّص خدمة التجميع التقارير إحصائيًا.
- تضيف "خدمة التجميع" تشويشًا إلى البيانات الملخّصة لتعزيز خصوصية المستخدم.
- يُتيح النظام التقارير لشركة تكنولوجيا الإعلان لأغراض التحليل والقياس.
يوضّح الجدول التالي نقاط النهاية لإصدار التعديل وإصدار البث المباشر لكلّ من Private Aggregation API وAttribution Reporting API:
واجهة برمجة التطبيقات | نقطة نهاية | الوصف |
---|---|---|
Private Aggregation API |
|
|
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:
حوِّل 1369 إلى القيمة السداسية العشرية المكافئة لها: 559.
حوِّل السلسلة السداسية العشرية "559" إلى سلسلة بايت.
يجب بعد ذلك تضمين تمثيل سلسلة البايتات لمفتاح الحزمة في مخطّط Avro لنطاق الإخراج.
اعتبارات مهمة:
نوع البيانات: يجب تعريف مفتاح الحزمة ضمن مخطّط Avro كنوع بايت لاستيعاب تمثيل سلسلة البايت الست عشري.
التحويل: يمكن تنفيذ عملية التحويل من النظام العشري إلى النظام الست عشري ثم إلى سلسلة بايت باستخدام Python أو Java.
يضمن هذا النهج أنّ تنسيق مفتاح الحزمة صحيح ومتوافق مع نوع البيانات المتوقّع ضمن مخطّط 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
: مفتاح الحزمة المتوفّر داخل ملف Avrooutput_domain