با Aggregation Service در AWS کار کنید

۱. پیش‌نیازها

برای انجام این Codelab، چند پیش‌نیاز لازم است. هر نیاز بر اساس اینکه آیا برای «آزمایش محلی» یا «سرویس تجمیع» مورد نیاز است، علامت‌گذاری شده است.

۱.۱. دانلود ابزار تست محلی (Local Testing)

تست محلی نیاز به دانلود ابزار تست محلی دارد. این ابزار گزارش‌های خلاصه‌ای از گزارش‌های اشکال‌زدایی رمزگذاری نشده تولید می‌کند.

ابزار تست محلی برای دانلود در آرشیو Lambda JAR در گیت‌هاب موجود است. باید به صورت LocalTestingTool_{version}.jar نامگذاری شود.

۱.۲. تأیید نصب JAVA و JRE (سرویس تست و تجمیع محلی)

« ترمینال » را باز کنید و با استفاده از java --version بررسی کنید که آیا جاوا یا openJDK روی دستگاه شما نصب شده است یا خیر.

بررسی نسخه جاوا jre با استفاده از `java --version`.

اگر نصب نشده است، می‌توانید آن را از سایت جاوا یا سایت openJDK دانلود و نصب کنید.

۱.۳. دانلود مبدل گزارش تجمیعی (سرویس تست و تجمیع محلی)

می‌توانید یک نسخه از مبدل گزارش تجمیعی را از مخزن گیت‌هاب Privacy Sandbox Demos دانلود کنید.

۱.۴. فعال‌سازی APIهای حریم خصوصی تبلیغات (سرویس تست و تجمیع محلی)

در مرورگر خود، به chrome://settings/adPrivacy بروید و تمام APIهای حریم خصوصی تبلیغات را فعال کنید.

تأیید کنید که کوکی‌های شخص ثالث فعال هستند.

در مرورگر خود، به chrome://settings/cookies بروید و گزینه « مسدود کردن کوکی‌های شخص ثالث در حالت ناشناس » را انتخاب کنید.

تنظیمات کروم کوکی شخص ثالث.

۱.۵. ثبت‌نام تحت وب و اندروید (سرویس تجمیع)

برای استفاده از APIهای Privacy Sandbox در یک محیط عملیاتی، مطمئن شوید که ثبت‌نام و تأیید را برای Chrome و Android تکمیل کرده‌اید.

برای آزمایش محلی، می‌توان ثبت‌نام را با استفاده از یک پرچم کروم و سوئیچ CLI غیرفعال کرد.

برای استفاده از پرچم کروم برای نسخه آزمایشی ما، به chrome://flags/#privacy-sandbox-enrollment-overrides بروید و پرچم را با سایت خود به‌روزرسانی کنید یا اگر از سایت آزمایشی ما استفاده خواهید کرد، نیازی به به‌روزرسانی نیست.

لغو پرچم کروم در ثبت‌نام در سندباکس حریم خصوصی.

۱.۶. پذیرش سرویس تجمیع (سرویس تجمیع)

سرویس تجمیع برای استفاده از سرویس، نیاز به آموزش هماهنگ‌کنندگان دارد. فرم آموزش خدمات تجمیع را با ارائه آدرس سایت گزارش‌دهی، شناسه حساب AWS و سایر اطلاعات خود تکمیل کنید.

۱.۷ ارائه‌دهنده‌ی خدمات ابری (سرویس تجمیع)

سرویس تجمیع نیاز به استفاده از یک محیط اجرای قابل اعتماد دارد که از یک محیط ابری استفاده می‌کند. سرویس تجمیع در سرویس‌های وب آمازون (AWS) و گوگل کلود (GCP) پشتیبانی می‌شود. این Codelab فقط ادغام AWS را پوشش می‌دهد.

AWS یک محیط اجرای قابل اعتماد به نام Nitro Enclaves ارائه می‌دهد. تأیید کنید که یک حساب AWS دارید و دستورالعمل‌های نصب و به‌روزرسانی AWS CLI را برای راه‌اندازی محیط AWS CLI خود دنبال کنید.

اگر AWS CLI شما جدید است، می‌توانید AWS CLI خود را با استفاده از دستورالعمل‌های پیکربندی CLI پیکربندی کنید.

۱.۷.۱ ایجاد باکت AWS S3

یک سطل S3 در AWS برای ذخیره وضعیت Terraform و یک سطل S3 دیگر برای ذخیره گزارش‌ها و خلاصه گزارش‌های خود ایجاد کنید. می‌توانید از دستور CLI ارائه شده استفاده کنید. فیلد <> را با متغیرهای مناسب جایگزین کنید.

aws s3api create-bucket --bucket <tf_bucket_name> --region us-east-1
aws s3api create-bucket --bucket <report_bucket_name> --region us-east-1

۱.۷.۲. ایجاد کلید دسترسی کاربر

با استفاده از راهنمای AWS، کلیدهای دسترسی کاربر را ایجاد کنید. این کلیدها برای فراخوانی نقاط پایانی API مربوط به createJob و getJob که در AWS ایجاد شده‌اند، استفاده خواهند شد.

۱.۷.۳ مجوزهای کاربر و گروه AWS

برای استقرار سرویس تجمیع در AWS، باید مجوزهای خاصی را به کاربری که برای استقرار سرویس استفاده می‌شود، ارائه دهید. برای این Codelab، تأیید کنید که کاربر دارای دسترسی مدیر است تا از مجوزهای کامل در هنگام استقرار مطمئن شوید.

۱.۸. Terraform (سرویس تجمیع)

این Codelab از Terraform برای استقرار سرویس Aggregation استفاده می‌کند. تأیید کنید که فایل باینری Terraform در محیط محلی شما نصب شده است.

فایل باینری Terraform را در محیط محلی خود دانلود کنید.

پس از دانلود فایل باینری Terraform، آن را از حالت فشرده خارج کرده و فایل باینری Terraform را به مسیر /usr/local/bin منتقل کنید.

cp <directory>/terraform /usr/local/bin

بررسی کنید که Terraform در classpath در دسترس باشد.

terraform -v

۱.۹. پستچی (برای سرویس تجمیع AWS)

برای این Codelab، از Postman برای مدیریت درخواست استفاده کنید.

با رفتن به آیتم ناوبری بالای « Workspaces » و انتخاب « ایجاد فضای کاری »، یک فضای کاری ایجاد کنید.

فضای کاری پستچی

« فضای کاری خالی » را انتخاب کنید، روی «بعدی» کلیک کنید و نام آن را « حفظ حریم خصوصی » بگذارید. « شخصی » را انتخاب کنید و روی « ایجاد » کلیک کنید.

فایل‌های پیکربندی JSON و Global Environment از پیش پیکربندی‌شده‌ی فضای کاری را دانلود کنید.

فایل‌های JSON را با استفاده از دکمه‌ی « وارد کردن » به « فضای کاری من » وارد کنید.

فایل‌های JSON پستچی را وارد کنید.

این کار مجموعه Privacy Sandbox را به همراه درخواست‌های HTTP مربوط createJob و getJob برای شما ایجاد می‌کند.

مجموعه وارداتی پستچی.

«کلید دسترسی» و «کلید مخفی» AWS را از طریق « نگاه سریع به محیط » به‌روزرسانی کنید.

نگاه سریع به محیط پستچی.

روی « ویرایش » کلیک کنید و «مقدار فعلی» هر دو « کلید دسترسی » و « کلید مخفی » را به‌روزرسانی کنید. توجه داشته باشید که frontend_api_id در بخش ۳.۱.۴ این سند ارائه خواهد شد. و ما توصیه می‌کنیم از منطقه‌ی us-east-1 استفاده کنید. با این حال، اگر می‌خواهید در منطقه‌ی دیگری مستقر شوید، تأیید کنید که AMI منتشر شده را در حساب خود کپی می‌کنید یا با استفاده از اسکریپت‌های ارائه شده، خودتان آن را بسازید.

متغیرهای سراسری پستمن ویرایش متغیرهای سراسری توسط پستچی

۲. تست محلی Codelab

شما می‌توانید از ابزار تست محلی روی دستگاه خود برای انجام تجمیع و تولید گزارش‌های خلاصه با استفاده از گزارش‌های اشکال‌زدایی رمزگذاری نشده استفاده کنید.

مراحل Codelab

مرحله ۲.۱. فعال‌سازی گزارش : گزارش تجمیع خصوصی را فعال کنید تا بتوانید گزارش را جمع‌آوری کنید.

مرحله ۲.۲. ایجاد گزارش تجمیعی اشکال‌زدایی : گزارش JSON جمع‌آوری‌شده را به یک گزارش با فرمت AVRO تبدیل کنید.
این مرحله مشابه زمانی است که تکنسین‌های تبلیغات گزارش‌ها را از نقاط پایانی گزارش‌دهی API جمع‌آوری کرده و گزارش‌های JSON را به گزارش‌های با فرمت AVRO تبدیل می‌کنند.

مرحله ۲.۳. تجزیه کلید سطل از گزارش اشکال‌زدایی : کلیدهای سطل توسط تکنسین‌های تبلیغات طراحی شده‌اند. در این آزمایشگاه کد، از آنجایی که سطل‌ها از پیش تعریف شده‌اند، کلیدهای سطل را همانطور که ارائه شده‌اند بازیابی کنید.

مرحله ۲.۴. ایجاد دامنه خروجی AVRO : پس از بازیابی کلیدهای سطل، فایل دامنه خروجی AVRO را ایجاد کنید.

مرحله ۲.۵. ایجاد گزارش‌های خلاصه با استفاده از ابزار تست محلی : از ابزار تست محلی برای ایجاد گزارش‌های خلاصه در محیط محلی استفاده کنید.

مرحله ۲.۶. بررسی گزارش خلاصه : گزارش خلاصه‌ای که توسط ابزار تست محلی ایجاد شده است را بررسی کنید.

۲.۱ گزارش محرک

به سایت آزمایشی سندباکس حریم خصوصی بروید. این کار یک گزارش تجمیع خصوصی را فعال می‌کند. می‌توانید گزارش را در chrome://private-aggregation-internals مشاهده کنید.

ویژگی‌های داخلی تجمیع خصوصی کروم.

اگر گزارش شما در وضعیت « در انتظار » است، می‌توانید گزارش را انتخاب کرده و روی « ارسال گزارش‌های انتخاب‌شده » کلیک کنید.

گزارش تجمیع خصوصی ارسال کنید.

۲.۲. ایجاد گزارش تجمیعی اشکال‌زدایی

در chrome://private-aggregation-internals ، « متن گزارش » دریافتی در نقطه پایانی [reporting-origin]/.well-known/private-aggregation/report-shared-storage کپی کنید.

مطمئن شوید که در « متن گزارش »، aggregation_coordinator_origin شامل https://publickeyservice.msmt.aws.privacysandboxservices.com باشد، که به این معنی است که گزارش، یک گزارش قابل تجمیع AWS است.

گزارش تجمیع خصوصی.

JSON " Report Body " را در یک فایل JSON قرار دهید. در این مثال، می‌توانید از vim استفاده کنید. اما می‌توانید از هر ویرایشگر متنی که می‌خواهید استفاده کنید.

vim report.json

گزارش را در report.json قرار دهید و فایل خود را ذخیره کنید.

گزارش فایل JSON.

وقتی این کار را انجام دادید، به پوشه گزارش خود بروید و از aggregatable_report_converter.jar برای ایجاد گزارش تجمیعی اشکال‌زدایی استفاده کنید. این کار یک گزارش تجمیعی به نام report.avro در دایرکتوری فعلی شما ایجاد می‌کند.

java -jar aggregatable_report_converter.jar \
 --request_type convertToAvro \
 --input_file report.json \
 --debug

۲.۳. کلید سطل را از گزارش اشکال‌زدایی تجزیه کنید

سرویس تجمیع (Aggregation Service) هنگام دسته بندی به دو فایل نیاز دارد. گزارش تجمیعی (aggregatable report) و فایل دامنه خروجی (output domain file). فایل دامنه خروجی شامل کلیدهایی است که می‌خواهید از گزارش‌های تجمیعی بازیابی کنید. برای ایجاد فایل output_domain.avro ، به کلیدهای سطلی (bucket keys) که می‌توانند از گزارش‌ها بازیابی شوند، نیاز دارید.

کلیدهای سطل توسط فراخوانی‌کننده‌ی API طراحی می‌شوند و نسخه آزمایشی شامل کلیدهای سطل نمونه از پیش ساخته شده است. از آنجایی که نسخه آزمایشی حالت اشکال‌زدایی را برای تجمیع خصوصی فعال کرده است، می‌توانید بار داده‌ی debug cleartext را از « Report Body » تجزیه کنید تا کلید سطل را بازیابی کنید. با این حال، در این مورد، نسخه آزمایشی sandbox حریم خصوصی سایت، کلیدهای سطل را ایجاد می‌کند. از آنجایی که تجمیع خصوصی برای این سایت در حالت اشکال‌زدایی است، می‌توانید از debug_cleartext_payload از « Report Body » برای دریافت کلید سطل استفاده کنید.

debug_cleartext_payload را از بدنه گزارش کپی کنید.

اشکال‌زدایی بار داده‌ی متن شفاف از بدنه‌ی گزارش.

ابزار Debug payload decoder را برای ابزار Private Aggregation باز کنید و debug_cleartext_payload خود را در کادر « INPUT » قرار دهید و روی « Decode » کلیک کنید.

رمزگشای بار مفید.

این صفحه مقدار اعشاری کلید سطل را برمی‌گرداند. در زیر یک نمونه کلید سطل آمده است.

نتیجه رمزگشایی Payload.

۲.۴ دامنه خروجی AVRO را ایجاد کنید

حالا که کلید سطل را داریم، مقدار اعشاری کلید سطل را کپی می‌کنیم. با استفاده از کلید سطل، فایل output_domain.avro را ایجاد می‌کنیم. مطمئن شوید که جایگزین می‌کنید. با کلید سطلی که برداشتی.

java -jar aggregatable_report_converter.jar \
 --request_type createDomainAvro \
 --bucket_key <bucket key>

اسکریپت، فایل output_domain.avro را در پوشه فعلی شما ایجاد می‌کند.

۲.۵. ایجاد گزارش‌های خلاصه با استفاده از ابزار تست محلی

ما LocalTestingTool_{version}.jar که در بخش ۱.۱ دانلود شده بود، برای ایجاد گزارش‌های خلاصه استفاده خواهیم کرد. از دستور زیر استفاده کنید. شما باید LocalTestingTool_{version}.jar را با نسخه دانلود شده برای LocalTestingTool جایگزین کنید.

برای ایجاد یک گزارش خلاصه در محیط توسعه محلی خود، دستور زیر را اجرا کنید:

java -jar LocalTestingTool_{version}.jar \
--input_data_avro_file report.avro \
--domain_avro_file output_domain.avro \
--output_directory .

پس از اجرای دستور، باید چیزی شبیه به تصویر زیر را ببینید. پس از تکمیل این کار، یک فایل report output.avro ایجاد می‌شود.

گزارش خلاصه آزمایش محلی، فایل avro.

۲.۶ گزارش خلاصه را مرور کنید

گزارش خلاصه‌ای که ایجاد می‌شود در قالب AVRO است. برای اینکه بتوانید آن را بخوانید، باید آن را از AVRO به قالب JSON تبدیل کنید. در حالت ایده‌آل، تکنسین تبلیغات باید کدی بنویسد که گزارش‌های AVRO را به JSON برگرداند.

برای Codelab خود، از ابزار aggregatable_report_converter.jar ارائه شده برای تبدیل گزارش AVRO به JSON استفاده خواهیم کرد.

java -jar aggregatable_report_converter.jar \
--request_type convertToJson \
--input_file output.avro

این دستور گزارشی مشابه تصویر زیر را به همراه گزارشی با فایل output.json که در همان دایرکتوری ایجاد شده است، برمی‌گرداند.

خلاصه فایل avro که به json تبدیل شده است.

برای بررسی گزارش خلاصه، فایل JSON را در ویرایشگر دلخواه خود باز کنید.

۳. استقرار سرویس تجمیع

برای استقرار سرویس Aggregation، مراحل زیر را دنبال کنید:

مرحله 3. استقرار سرویس تجمیع : استقرار سرویس تجمیع روی AWS
مرحله ۳.۱. کلون کردن مخزن سرویس تجمیع
مرحله ۳.۲. دانلود وابستگی‌های از پیش ساخته شده
مرحله ۳.۳. ایجاد یک محیط توسعه
مرحله ۳.۴. استقرار سرویس تجمیع

۳.۱. کپی کردن مخزن سرویس تجمیع

در محیط محلی خود، مخزن Aggregation Service Github را کپی کنید.

git clone https://github.com/privacysandbox/aggregation-service.git

۳.۲. دانلود وابستگی‌های از پیش ساخته شده

پس از اینکه مخزن سرویس تجمیع را کلون کردید، به پوشه Terraform مخزن و پوشه ابر مربوطه بروید. اگر cloud_provider شما AWS است، می‌توانید به مسیر زیر بروید: /terraform/aws

cd <repository_root>/terraform/aws

در /terraform/aws ، download_prebuilt_dependencies.sh را اجرا کنید.

bash download_prebuilt_dependencies.sh

۳.۳ ایجاد یک محیط توسعه

ایجاد یک محیط توسعه در /terraform/aws/environments . پوشه‌ای به نام dev ایجاد کنید.

mkdir dev

محتویات پوشه demo را در پوشه dev کپی کنید.

cp -R demo/* dev

به پوشه dev خود بروید.

cd dev

فایل main.tf خود را به‌روزرسانی کنید و برای input فایل، کلید i را فشار دهید.

vim main.tf

با حذف # و به‌روزرسانی نام سطل‌ها و کلیدها، کد داخل کادر قرمز را از حالت کامنت خارج کنید.

برای AWS main.tf :

فایل tf اصلی AWS.

کد بدون کامنت باید به شکل زیر باشد.

backend "s3" {
  bucket = "<tf_state_bucket_name>"
  key    = "<environment_name>.tfstate"
  region = "us-east-1"
}

پس از اتمام به‌روزرسانی‌ها، آن‌ها را ذخیره کرده و با فشردن esc -> :wq! از ویرایشگر خارج شوید. این کار به‌روزرسانی‌ها را در main.tf ذخیره می‌کند.

در مرحله بعد، نام example.auto.tfvars را به dev.auto.tfvars تغییر دهید.

mv example.auto.tfvars dev.auto.tfvars

فایل dev.auto.tfvars را به‌روزرسانی کنید و برای ویرایش فایل، input i را فشار دهید.

vim dev.auto.tfvars

فیلدهای کادر قرمز تصویر زیر را با پارامترهای صحیح AWS ARN که در طول راه‌اندازی سرویس Aggregation، محیط و ایمیل اعلان ارائه شده‌اند، به‌روزرسانی کنید.

فایل dev auto tfvars را ویرایش کنید.

پس از اتمام به‌روزرسانی‌ها، esc -> :wq! را فشار دهید. با این کار فایل dev.auto.tfvars ذخیره می‌شود و باید چیزی شبیه به تصویر زیر باشد.

فایل tfvars خودکار توسعه‌دهندگان به‌روزرسانی شد.

۳.۴. استقرار سرویس تجمیع

برای استقرار سرویس تجمیع، در همان پوشه /terraform/aws/environments/dev ، Terraform را مقداردهی اولیه کنید.

terraform init

این باید چیزی شبیه به تصویر زیر را برگرداند:

شروع Terraform.

پس از راه‌اندازی اولیه Terraform، طرح اجرایی Terraform را ایجاد کنید. در این طرح، تعداد منابعی که باید اضافه شوند و سایر اطلاعات اضافی مشابه تصویر زیر بازگردانده می‌شود.

terraform plan

در ادامه می‌توانید خلاصه « طرح » را مشاهده کنید. اگر این یک استقرار جدید است، باید تعداد منابعی که اضافه خواهند شد را با 0 برای تغییر و 0 برای تخریب ببینید.

طرح ترافرم.

پس از تکمیل این مرحله، می‌توانید Terraform را اعمال کنید.

terraform apply

پس از درخواست تأیید انجام اقدامات توسط Terraform، مقدار را با yes وارد کنید.

درخواست Terraform فوری.

پس از اتمام terraform apply ، نقاط پایانی زیر برای createJob و getJob بازگردانده می‌شوند. frontend_api_id که باید در Postman در بخش 1.9 به‌روزرسانی کنید نیز بازگردانده می‌شود.

اعمال Terraform کامل شد.

۴. ایجاد ورودی سرویس تجمیع

برای دسته بندی در سرویس تجمیع، گزارش‌های AVRO را ایجاد کنید.

مرحله ۴. ایجاد ورودی سرویس تجمیع : گزارش‌های سرویس تجمیع را که برای سرویس تجمیع دسته‌بندی شده‌اند، ایجاد کنید.
مرحله ۴.۱. گزارش تریگر
مرحله ۴.۲. جمع‌آوری گزارش‌های قابل جمع‌آوری
مرحله ۴.۳. تبدیل گزارش‌ها به AVRO
مرحله ۴.۴. ایجاد دامنه خروجی AVRO

۴.۱ گزارش محرک

به سایت آزمایشی Privacy Sandbox بروید. این کار یک گزارش تجمیع خصوصی را فعال می‌کند. می‌توانید گزارش را در chrome://private-aggregation-internals مشاهده کنید.

ویژگی‌های داخلی تجمیع خصوصی کروم.

اگر گزارش شما در وضعیت « در انتظار » است، می‌توانید گزارش را انتخاب کرده و روی « ارسال گزارش‌های انتخاب‌شده » کلیک کنید.

گزارش تجمیع خصوصی ارسال کنید.

۴.۲ جمع‌آوری گزارش‌های قابل جمع‌آوری

گزارش‌های قابل جمع‌آوری خود را از نقاط پایانی .well-known API مربوطه‌تان جمع‌آوری کنید.

• تجمیع خصوصی
  [reporting-origin] /.well-known/private-aggregation/report-shared-storage
• گزارش انتساب - گزارش خلاصه
  [reporting-origin] /.well-known/attribution-reporting/report-aggregate-attribution

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

در chrome://private-aggregation-internals ، « متن گزارش » دریافتی در نقطه پایانی [reporting-origin]/.well-known/private-aggregation/report-shared-storage کپی کنید.

مطمئن شوید که در « متن گزارش »، aggregation_coordinator_origin شامل https://publickeyservice.msmt.aws.privacysandboxservices.com باشد، که به این معنی است که گزارش، یک گزارش قابل تجمیع AWS است.

گزارش تجمیع خصوصی.

JSON " Report Body " را در یک فایل JSON قرار دهید. در این مثال، می‌توانید از vim استفاده کنید. اما می‌توانید از هر ویرایشگر متنی که می‌خواهید استفاده کنید.

vim report.json

گزارش را در report.json قرار دهید و فایل خود را ذخیره کنید.

گزارش فایل JSON.

۴.۳ تبدیل گزارش‌ها به AVRO

گزارش‌های دریافتی از نقاط انتهایی .well-known در قالب JSON هستند و باید به قالب گزارش AVRO تبدیل شوند. پس از دریافت گزارش JSON، به پوشه گزارش خود بروید و aggregatable_report_converter.jar برای ایجاد گزارش تجمیعی اشکال‌زدایی استفاده کنید. این یک گزارش تجمیعی به نام report.avro در دایرکتوری فعلی شما ایجاد می‌کند.

java -jar aggregatable_report_converter.jar \
 --request_type convertToAvro \
 --input_file report.json

۴.۴. دامنه خروجی AVRO را ایجاد کنید

برای ایجاد فایل output_domain.avro ، به کلیدهای سطلی نیاز دارید که می‌توان آنها را از گزارش‌ها بازیابی کرد.

کلیدهای سطل توسط تکنسین تبلیغات طراحی می‌شوند. با این حال، در این مورد، نسخه آزمایشی Privacy Sandbox سایت، کلیدهای سطل را ایجاد می‌کند. از آنجایی که تجمیع خصوصی برای این سایت در حالت اشکال‌زدایی است، می‌توانید از debug_cleartext_payload از « Report Body » برای دریافت کلید سطل استفاده کنید.

ادامه دهید و debug_cleartext_payload را از بدنه گزارش کپی کنید.

اشکال‌زدایی بار داده‌ی متن شفاف از بدنه‌ی گزارش.

goo.gle/ags-payload-decoder را باز کنید و debug_cleartext_payload خود را در کادر « ورودی » جایگذاری کنید و روی « رمزگشایی » کلیک کنید.

رمزگشای بار مفید.

این صفحه مقدار اعشاری کلید سطل را برمی‌گرداند. در زیر یک نمونه کلید سطل آمده است.

نتیجه رمزگشایی Payload.

حالا که کلید سطل را داریم، فایل output_domain.avro را ایجاد می‌کنیم. مطمئن شوید که جایگزین می‌کنید با کلید سطلی که برداشتی.

java -jar aggregatable_report_converter.jar \
 --request_type createDomainAvro \
 --bucket_key <bucket key>

اسکریپت، فایل output_domain.avro را در پوشه فعلی شما ایجاد می‌کند.

۴.۵. انتقال گزارش‌ها به سطل AWS

پس از ایجاد گزارش‌های AVRO (از بخش ۳.۲.۳) و دامنه خروجی (از بخش ۳.۲.۴)، گزارش‌ها و دامنه خروجی را به سطل‌های گزارش‌دهی S3 منتقل کنید.

اگر تنظیمات AWS CLI را در محیط محلی خود دارید، از دستورات زیر برای کپی کردن گزارش‌ها به پوشه S3 و گزارش مربوطه استفاده کنید.

aws s3 cp report.avro s3://<report_bucket_name>/<report_folder>/
aws s3 cp output_domain.avro s3://<report_bucket_name>/<output_domain_folder>/

۵. استفاده از سرویس تجمیع

از terraform apply ، مقادیر create_job_endpoint ، get_job_endpoint و frontend_api_id به شما بازگردانده می‌شوند. مقادیر frontend_api_id کپی کرده و در متغیر سراسری postman به frontend_api_id که در بخش پیش‌نیاز ۱.۹ تنظیم کرده‌اید، قرار دهید.

مرحله ۵. کاربرد سرویس تجمیع : از API سرویس تجمیع برای ایجاد گزارش‌های خلاصه و بررسی گزارش‌های خلاصه استفاده کنید.
مرحله ۵.۱. استفاده از createJob Endpoint برای دسته بندی
مرحله ۵.۲. استفاده از getJob Endpoint برای بازیابی وضعیت دسته‌ای
مرحله ۵.۳. بررسی خلاصه گزارش

۵.۱. استفاده از نقطه پایانی createJob برای دسته بندی

در Postman، مجموعه « Privacy Sandbox » را باز کنید و « createJob » را انتخاب کنید.

برای قرار دادن درخواست خود، « بدنه » و سپس « خام » را انتخاب کنید.

بدنه درخواست postman createJob

طرحواره‌ی payload createJob در گیت‌هاب موجود است و ظاهری مشابه زیر دارد. <> را با فیلدهای مناسب جایگزین کنید.

{
    "job_request_id": "<job_request_id>",
    "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
    "input_data_blob_prefixes": [
      "<report_folder>/<report_name-1>/",
      "<report_folder>/<report_name-2>/",
      "<report_folder>/<report_name>.avro"
    ], // Mutually exclusive to input_data_blob_prefix as of v2.11.0
    "input_data_bucket_name": "<bucket_name>",
    "output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
    "output_data_bucket_name": "<bucket_name>",
    "job_parameters": {
      "output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
      "output_domain_bucket_name": "<bucket_name>",
      "attribution_report_to": "<reporting origin of report>",
      "reporting_site": "<domain of reporting origin(s) of report>", // Mutually exclusive to attribution_report_to as of v2.7.0
      "report_error_threshold_percentage": "10",
      "debug_run": "true"
    }
}

پس از کلیک روی « ارسال »، این کار با شناسه job_request_id ایجاد می‌شود. پس از پذیرش درخواست توسط سرویس تجمیع، باید پاسخ HTTP 202 دریافت کنید. سایر کدهای برگشتی ممکن را می‌توانید در کدهای پاسخ HTTP بیابید.

وضعیت درخواست createJob پستچی

۵.۲. استفاده از getJob Endpoint برای بازیابی وضعیت دسته‌ای

برای بررسی وضعیت درخواست کار، می‌توانید از نقطه پایانی getJob استفاده کنید. در مجموعه « Privacy Sandbox » گزینه « getJob » را انتخاب کنید.

در بخش « پارامز »، مقدار job_request_id را به job_request_id که در درخواست createJob ارسال شده بود، به‌روزرسانی کنید.

درخواست پستچی getJob

نتیجه‌ی getJob باید وضعیت درخواست کار شما را با وضعیت HTTP برابر با ۲۰۰ برگرداند. درخواست " Body " شامل اطلاعات لازم مانند job_status ، return_message و error_messages (در صورت بروز خطا در کار) است.

وضعیت درخواست پستچی getJob

از آنجایی که سایت گزارش‌دهی گزارش آزمایشی تولید شده با سایت ثبت‌شده شما در AWS ID شما متفاوت است، ممکن است پاسخی با کد بازگشتی PRIVACY_BUDGET_AUTHORIZATION_ERROR دریافت کنید. این طبیعی است زیرا سایت مبدا گزارش‌دهی گزارش‌ها با سایت ثبت‌شده برای AWS ID مطابقت ندارد.

{
      "job_status": "FINISHED",
      "request_received_at": "2023-12-07T22:50:58.830956Z",
      "request_updated_at": "2023-12-07T22:51:10.526326456Z",
      "job_request_id": "<job_request_id>",
      "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
      "input_data_blob_prefixes": [ // Mutually exclusive to input_data_blob_prefix as of v2.11.0
        "<report_folder>/<report_name-1>/",
        "<report_folder>/<report_name-2>/",
        "<report_folder>/<report_name>.avro"
      ],
      "input_data_bucket_name": "<input_bucket_name>",
      "output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
      "output_data_bucket_name": "<output_bucket_name>",
      "postback_url": "",
      "result_info": {
          "return_code": "PRIVACY_BUDGET_AUTHORIZATION_ERROR",
          "return_message": "Aggregation job successfully processed",
          "error_summary": {
              "error_counts": [],
              "error_messages": []
          },
          "finished_at": "2023-12-07T22:51:10.517730898Z"
      },
      "job_parameters": {
          "debug_run": "true",
          "output_domain_bucket_name": "<output_domain_bucket_name>",
          "output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
          "attribution_report_to": "https://privacy-sandbox-demos-dsp.dev",
          "reporting_site": "<domain of reporting origin(s) of report>", // Mutually exclusive to attribution_report_to as of v2.7.0
      },
      "request_processing_started_at": "2023-12-07T22:51:06.034472697Z"
}

۵.۳ بررسی خلاصه گزارش

پس از دریافت گزارش خلاصه خود در خروجی S3 Bucket، می‌توانید آن را در محیط محلی خود دانلود کنید. گزارش‌های خلاصه با فرمت AVRO هستند و می‌توانند به JSON تبدیل شوند. می‌توانید با استفاده از دستور زیر، aggregatable_report_converter.jar برای خواندن گزارش خود استفاده کنید.

java -jar aggregatable_report_converter.jar \
--request_type convertToJson \
--input_file <summary_report_avro>

این یک JSON از مقادیر تجمیع‌شده‌ی هر کلید سطل را برمی‌گرداند که مشابه تصویر زیر است.

گزارش خلاصه.

اگر درخواست createJob شما شامل debug_run به صورت true باشد، می‌توانید گزارش خلاصه خود را در پوشه debug که در output_data_blob_prefix قرار دارد، دریافت کنید. این گزارش با فرمت AVRO است و می‌توان آن را با استفاده از دستور قبلی به JSON تبدیل کرد.

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

گزارش خلاصه اشکال‌زدایی

این حاشیه‌نویسی‌ها همچنین شامل in_reports و in_domain هستند که به معنی زیر است:

• in_reports - کلید bucket در داخل گزارش‌های تجمیعی موجود است.
• in_domain - کلید سطل در داخل فایل output_domain AVRO موجود است.