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

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

مخطّط تقرير AgS
مخطّط تقرير 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 في مستودع Aggregation Service على 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. ستحتوي نطاقات الإخراج على المفاتيح المحدّدة مسبقًا والتي سيتم جمعها من تقاريرك القابلة للتجميع وسيتمّ إدراجها في التقارير الموجزة. مزيد من المعلومات حول هذه المفاتيح في Attribution Reporting والمفاتيح في Private Aggregation سيتضمّن نطاق الإخراج مجموعة الحقول وستكون قيمة المجموعة هي مفتاح المجموعة.

يجب أن يكون ملف النطاق أيضًا بتنسيق 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
مخطّط مفتاح مجموعة 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: يتوفّر مفتاح المجموعة داخل ملف AVRO ‏output_domain