گزارش های جمع آوری شده را دریافت و ذخیره کنید

این راهنما توضیح می‌دهد که چگونه گزارش‌های اندازه‌گیری رمزگذاری شده به ارائه‌دهندگان فناوری تبلیغات ارائه می‌شود. مرورگرهای Chrome و مشتریان این گزارش‌ها را به نقاط پایانی گزارش‌دهی تعیین‌شده ارسال می‌کنند، جایی که پلتفرم فناوری تبلیغات گزارش‌های انبوهی را دریافت و ذخیره می‌کند. این نقاط پایانی که در نشانی‌های اینترنتی .well-known در مبدا گزارش‌دهنده ارائه‌دهنده قرار دارند، توسط پلتفرم میزبانی می‌شوند و ارائه‌دهندگان فناوری تبلیغات را با استفاده از Attribution Reporting API یا Private Aggregation API قادر می‌سازند به آنها دسترسی داشته باشند.

مراحل زیر به جزئیات روند سرویس Aggregation برای دریافت و ذخیره گزارش‌های انباشته می‌پردازد:

1. وقتی فعال می‌شود، مرورگر گزارش‌های انبوهی را ارسال می‌کند که حاوی جزئیاتی درباره داده‌های بین سایتی و تبدیلی است.
2. مرورگر گزارش‌های رمزگذاری‌شده را به یک URL .well-known دامنه گزارش‌دهی فناوری تبلیغات تحویل می‌دهد.
3. این سیستم دسته‌ای از گزارش‌ها را برای پردازش به سرویس تجمع ارسال می‌کند.
4. سرویس تجمیع گزارش ها را به صورت آماری خلاصه می کند.
5. سرویس تجمع نویز را به داده های خلاصه شده اضافه می کند تا حریم خصوصی کاربر را افزایش دهد.
6. این سیستم گزارش ها را برای اهداف تجزیه و تحلیل و اندازه گیری در اختیار شرکت فناوری تبلیغات قرار می دهد.

جدول زیر اشکال‌زدایی و نقاط پایانی زنده را برای Private Aggregation API و Attribution Reporting API توضیح می‌دهد:

منابع گزارش، گزارش‌های JSON را از طریق تماس‌های POST دریافت می‌کنند. سپس سیستم این گزارش ها را به فرمت Avro تبدیل کرده و در فضای ذخیره سازی ابری قرار می دهد. پس از پردازش دسته ای، سیستم گزارش های Avro را برای جمع بندی به سرویس تجمیع ارسال می کند.

زمانی که دسته‌ای از گزارش‌های Avro برای پردازش آماده می‌شوند، پلتفرم‌های فناوری تبلیغات، یک درخواست کار جمع‌آوری را به سرویس تجمع راه‌اندازی می‌کنند. این سرویس که در محیط ابری پلتفرم فناوری تبلیغات میزبانی می‌شود، گزارش‌های Avro مورد نیاز را از همان مکان ذخیره‌سازی بازیابی می‌کند. برای اهداف امنیتی، سرویس تجمع باید برای استفاده از یک تصویر ظرف تأیید شده پیکربندی شود. برای مشاهده تصاویر کانتینر موجود، به مخزن GitHub سرویس تجمیع حریم خصوصی مراجعه کنید.

موارد زیر نمونه هایی از گزارش های بازگردانده شده توسط هر API را نشان می دهد:

• مثال گزارش API Aggregation Private :

  {
    "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 را در این مخزن avrodoc/schemata GitHub ببینید.

می‌توانید نمونه کد جاوا اسکریپت را در بخش جمع‌آوری، تبدیل و گزارش‌های دسته‌ای در صفحه جمع‌آوری و دسته‌بندی گزارش‌های جمع‌آوری‌شده واقع در مخزن privacysandbox/agregation-service GitHub بیابید.

شما این قابلیت را دارید که همه گزارش ها را در یک فایل AVRO ذخیره کنید یا آنها را در چندین فایل توزیع کنید. در حالی که فایل‌های AVRO محدودیت اندازه ندارند، عملکرد مطلوب معمولاً زمانی حاصل می‌شود که تعداد فایل‌ها از تعداد پردازنده‌های موجود در نمونه ابری شما تا 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"
      }
    ]
  }

در زیر نمونه ای از گزارش 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\"}"
}

مشخصات فایل دامنه

برای ایجاد گزارش‌های خلاصه با سرویس Aggregation به گزارش‌های جمع‌آوری‌شده (گزارش‌های 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 باید به عنوان یک نوع بایت تعریف شود تا نمایش رشته بایت ششصدایی را در خود جای دهد.

• تبدیل: تبدیل از اعشار به هگزا و سپس به رشته بایت را می توان با استفاده از پایتون یا جاوا پیاده سازی کرد.

این رویکرد تضمین می کند که کلید سطل به درستی قالب بندی شده و با نوع داده مورد انتظار در طرحواره Avro برای دامنه خروجی سازگار است.

گزارش های دسته ای

برای جزئیات بیشتر در مورد بودجه حفظ حریم خصوصی و استراتژی های دسته بندی، به مستندات استراتژی های دسته بندی مراجعه کنید. توجه داشته باشید که گزارش‌های جمع‌آوری شده دارای محدودیت MAX_REPORT_AGE (در حال حاضر 90 روز) بین scheduled_report_time و تاریخ اجرای دسته‌ای هستند.

گزارش های خلاصه

پس از دسته‌بندی، سرویس Aggregation گزارش خلاصه را در قالب 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 با نام 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 شامل فیلدهای زیر است:

• bucket: یک شناسه منحصر به فرد برای تجمیع داده ها (به عنوان مثال، "\u0005Y").

• متریک: مقدار تجمیع شده برای سطل مربوطه. این مقدار اغلب شامل نویز اضافه شده برای افزایش حریم خصوصی است.

  به عنوان مثال:

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

مثال debug_results.json

گزارش‌های Debug Avro از سرویس Aggregation شبیه به مثال debug_results.json زیر است. این گزارش ها شامل کلیدهای سطلی، unnoised_metric (خلاصه کلیدهای سطل قبل از اعمال نویز) و نویز اضافه شده به آن متریک است.

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

حاشیه نویسی ها همچنین حاوی مقادیر زیر هستند:

• in_reports : کلید سطلی موجود در گزارش‌های جمع‌آوری‌شده

• in_domain : کلید سطلی موجود در فایل output_domain Avro