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

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

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

• تجميع خاص

  • تصحيح الأخطاء [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 واحد لجميع تقاريرك، أو تقسيم التقارير إلى ملفات AVRO متعددة. ما مِن حدّ أقصى لحجم AVRO. لأسباب تتعلّق بالأداء، ننصحك بضبط عدد ملفات AVRO على رقم يتراوح بين عدد وحدات المعالجة المركزية المتاحة لوحدة Cloud و1000.

في ما يلي مخطط 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 بالنظام العشري. وعند تحويله إلى تنسيق Hex، سيكون 559. ثم ستحتاج إلى تحويل 559 إلى سلسلة بايت لإضافتها إلى نطاق الإخراج AVRO

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

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

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

بعد تجميع البيانات في حزم، تنشئ خدمة Aggregation Service التقرير الموجز بتنسيق 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