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

وقتی متخصصان تبلیغات، APIهای اندازه‌گیری ( API گزارش‌دهی نسبت‌دهی یا API تجمیع خصوصی ) را فعال می‌کنند، گزارش‌های رمزگذاری‌شده از سمت مرورگر/کلاینت کروم به نقطه پایانی گزارش‌دهی متخصصان تبلیغات ارسال می‌شوند که یک URL .well-known با مبدأ گزارش‌دهی متخصصان تبلیغات است. نقطه پایانی گزارش‌دهی توسط متخصصان تبلیغات میزبانی می‌شود تا گزارش‌های رمزگذاری‌شده را جمع‌آوری کند .

نمودار گزارش AgS.
نمودار گزارش AgS.

نقاط پایانی به ازای هر API به شرح زیر است:

  • تجمیع خصوصی

    • اشکال‌زدایی [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 در فضای ابری تکنسین تبلیغات برای دسته‌بندی‌های بعدی ذخیره می‌شوند.

زمانی که فناوری تبلیغات برای دسته‌بندی آماده شد، فناوری تبلیغات از طریق سرویس تجمیع، درخواست تجمیع را آغاز می‌کند که در آن گزارش‌ها از فضای ذخیره‌سازی ابری فناوری تبلیغات بازیابی می‌شوند. سرویس تجمیع در فضای ذخیره‌سازی ابری فناوری تبلیغات میزبانی می‌شود و باید دارای یک تصویر دارای مجوز باشد.

گزارش‌های دریافتی مشابه موارد زیر هستند:

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\"}"
  }

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) نیاز خواهید داشت.

یک نمونه کد جاوا اسکریپت در مخزن گیت‌هاب سرویس تجمیع موجود است.

در ادامه، طرحواره 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 بایت برای گزارش‌های اشکال‌زدایی، باید Payload به صورت base64 رمزگشایی شده و به آرایه‌ای از بایت‌ها از debug_cleartext_payload تبدیل شود.
key_id رشته این رشته key_id موجود در گزارش خواهد بود. key_id یک شناسه جهانی منحصر به فرد ۱۲۸ بیتی مشابه خواهد بود.
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 خواهند بود. دامنه‌های خروجی شامل کلیدهای از پیش اعلام شده‌ای هستند که از گزارش‌های قابل تجمیع شما جمع‌آوری شده و در گزارش‌های خلاصه نوشته می‌شوند. برای کسب اطلاعات بیشتر در مورد این کلیدها به گزارش‌های انتسابی و کلیدها به تجمیع خصوصی مراجعه کنید . دامنه خروجی شامل فیلد bucket خواهد بود و مقدار bucket، کلید bucket شما خواهد بود.

فایل دامنه همچنین باید با فرمت 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."
      }
    ]
  }

کلید سطل

کلید سطل باید یک رشته بایت‌تست هگز از کلید سطل باشد. یک مثال برای این مورد، داشتن یک کلید ۱۳۶۹ در دسیمال است. وقتی به هگز تبدیل شود، ۵۵۹ خواهد بود. سپس باید ۵۵۹ را به یک رشته بایت‌تست تبدیل کنید تا به دامنه خروجی AVRO اضافه شود.

نمودار کلید سطل AgS.
نمودار کلید سطل AgS.

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

برای درک بیشتر در مورد بودجه‌های حریم خصوصی و دسته‌بندی، به سند استراتژی‌های دسته‌بندی مراجعه کنید. همچنین، به خاطر داشته باشید که یک گزارش تجمیعی فقط می‌تواند در یک دوره زمانی خاص دسته‌بندی شود. یک گزارش نباید از MAX_REPORT_AGE بین زمان 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 شما summary/summary.avro باشد، گزارش در پوشه خلاصه با نام summary-1-of-1.avro قرار خواهد گرفت.

نتایج.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 موجود است.