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

1. پیش نیازها

برای اجرای این Codelab به چند پیش نیاز نیاز است. هر یک از الزامات بر این اساس مشخص می شود، چه برای "تست محلی" یا "سرویس تجمع" مورد نیاز باشد.

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

Local Testing به دانلود Local Testing Tool نیاز دارد. این ابزار گزارش های خلاصه ای را از گزارش های اشکال زدایی رمزگذاری نشده تولید می کند.

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

1.2. اطمینان حاصل کنید که JAVA JRE نصب شده است (سرویس آزمایش و تجمع محلی)

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

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

1.3. دانلود تبدیل گزارش انبوه (خدمات آزمایش و تجمیع محلی)

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

1.4. فعال کردن APIهای حریم خصوصی تبلیغات (سرویس آزمایش و تجمیع محلی)

در مرورگر خود، به chrome://settings/adPrivacy بروید و همه APIهای Ad Privacy را فعال کنید.

اطمینان حاصل کنید که کوکی های شخص ثالث فعال هستند.

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

1.5. ثبت نام وب و اندروید (سرویس تجمع)

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

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

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

1.6. ورود به سرویس تجمع (سرویس تجمع)

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

1.7. ارائه دهنده ابر (سرویس جمع آوری)

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

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

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

1.7.1. سطل AWS S3 ایجاد کنید

یک سطل AWS S3 برای ذخیره وضعیت 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

1.7.2. ایجاد کلید دسترسی کاربر

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

1.7.3. مجوزهای کاربر و گروه AWS

برای استقرار Aggregation Service در AWS، باید مجوزهای خاصی را به کاربر مورد استفاده برای استقرار سرویس ارائه دهید. برای این Codelab، اطمینان حاصل کنید که کاربر برای اطمینان از مجوزهای کامل در استقرار، دسترسی مدیر دارد.

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

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

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

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

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

بررسی کنید تا مطمئن شوید که Terraform در classpath موجود است.

terraform -v

1.9. پستچی (برای خدمات جمع آوری AWS)

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

با رفتن به آیتم ناوبری بالای " Workspaces " و انتخاب " Create Workspace " یک فضای کاری ایجاد کنید.

" Blank workspace " را انتخاب کنید، روی next کلیک کنید و نام آن را " Privacy Sandbox " بگذارید. " شخصی " را انتخاب کنید و روی " ایجاد " کلیک کنید.

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

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

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

AWS "Access Key" و "Secret Key" را از طریق " Environment quick look " به روز کنید.

روی " ویرایش " کلیک کنید و "مقدار فعلی" هر دو " access_key " و " secret_key " را به روز کنید. توجه داشته باشید که frontend_api_id در بخش 3.1.4 این سند ارائه خواهد شد. و ما توصیه می کنیم از منطقه us-east-1 استفاده کنید. با این حال، اگر می‌خواهید در منطقه دیگری مستقر شوید، مطمئن شوید که AMI منتشر شده را در حساب خود کپی کرده‌اید یا با استفاده از اسکریپت‌های ارائه‌شده یک خودسازی انجام دهید.

2. Local Testing Codelab

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

مراحل Codelab

مرحله 2.1. گزارش ماشه : گزارش جمع آوری خصوصی را راه اندازی کنید تا بتوانید گزارش را جمع آوری کنید.

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

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

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

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

مرحله 2.6. گزارش خلاصه را مرور کنید : گزارش خلاصه که توسط Local Testing Tool ایجاد شده است را مرور کنید.

2.1. گزارش ماشه

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

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

2.2. ایجاد گزارش جمع آوری اشکال زدایی

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

اطمینان حاصل کنید که در " بدن گزارش "، aggregation_coordinator_origin حاوی https://publickeyservice.msmt.aws.privacysandboxservices.com است که به این معنی است که گزارش یک گزارش جمع آوری AWS است.

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

vim report.json

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

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

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

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

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

کلیدهای سطل توسط تماس گیرنده API طراحی شده اند و نسخه نمایشی شامل کلیدهای سطل نمونه از پیش ساخته شده است. از آنجایی که نسخه آزمایشی حالت اشکال‌زدایی را برای جمع‌بندی خصوصی فعال کرده است، می‌توانید بار متن شفاف اشکال‌زدایی را از " گزارش بدن " برای بازیابی کلید سطل تجزیه کنید. اما، در این مورد، نسخه نمایشی جعبه حریم خصوصی سایت، کلیدهای سطل را ایجاد می‌کند. از آنجایی که تجمیع خصوصی برای این سایت در حالت اشکال زدایی است، می توانید از debug_cleartext_payload از " گزارش بدن " برای دریافت کلید سطل استفاده کنید.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

3. استقرار خدمات تجمع

برای استقرار Aggregation Service از مراحل زیر استفاده کنید:

مرحله 3. استقرار سرویس تجمع : سرویس تجمع را در AWS مستقر کنید
مرحله 3.1. مخزن خدمات جمع آوری را شبیه سازی کنید
مرحله 3.2. دانلود وابستگی های از پیش ساخته شده
مرحله 3.3. یک محیط توسعه ایجاد کنید
مرحله 3.4. استقرار سرویس تجمع

3.1. مخزن Aggregation Service را کلون کنید

در محیط محلی خود، مخزن Aggregation Service Github را شبیه سازی کنید.

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

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

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

cd <repository_root>/terraform/aws

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

bash download_prebuilt_dependencies.sh

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

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

mkdir dev

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

cp -R demo/* dev

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

cd dev

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

vim main.tf

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

برای AWS main.tf :

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

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 را به روز کنید و i برای input فشار دهید تا فایل را ویرایش کنید.

vim dev.auto.tfvars

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

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

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

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

terraform init

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

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

terraform plan

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

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

terraform apply

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

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

4. ایجاد ورودی سرویس Aggregation

به ایجاد گزارش های AVRO برای دسته بندی در سرویس Aggregation ادامه دهید.

مرحله 4. ایجاد ورودی سرویس جمع‌آوری : گزارش‌های سرویس جمع‌آوری را ایجاد کنید که برای سرویس تجمع دسته‌بندی می‌شوند.
مرحله 4.1. گزارش ماشه
مرحله 4.2. جمع آوری گزارش های جمع آوری
مرحله 4.3. تبدیل گزارش ها به AVRO
مرحله 4.4. دامنه خروجی AVRO را ایجاد کنید

4.1. گزارش ماشه

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

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

4.2. جمع آوری گزارش های جمع آوری

گزارش‌های جمع‌آوری‌شده خود را از نقاط پایانی .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 " گزارش بدن " را در یک فایل JSON قرار دهید. در این مثال می توانید از vim استفاده کنید. اما می توانید از هر ویرایشگر متنی که می خواهید استفاده کنید.

vim report.json

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

4.3. تبدیل گزارش ها به 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

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

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

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

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

goo.gle/ags-payload-decoder را باز کنید و debug_cleartext_payload خود را در کادر " INPUT " قرار دهید و روی " Decode " کلیک کنید.

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

اکنون که کلید سطل را داریم، ادامه دهید و output_domain.avro را ایجاد کنید. از تعویض مطمئن شوید با کلید سطلی که بازیابی کردید.

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

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

4.5. گزارش ها را به سطل AWS منتقل کنید

هنگامی که گزارش های AVRO (از بخش 3.2.3) و دامنه خروجی (از بخش 3.2.4) ایجاد شدند، به انتقال گزارش ها و دامنه خروجی به سطل های گزارش 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>/

5. استفاده از خدمات جمع آوری

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

مرحله 5. استفاده از سرویس تجمع : از API Service Aggregation برای ایجاد گزارش های خلاصه و بررسی گزارش های خلاصه استفاده کنید.
مرحله 5.1. استفاده از createJob Endpoint برای دسته بندی
مرحله 5.2. استفاده از getJob Endpoint برای بازیابی وضعیت دسته ای
مرحله 5.3. بررسی گزارش خلاصه

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

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

برای قرار دادن بار درخواستی خود، " بدن " را انتخاب کنید و " خام " را انتخاب کنید.

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

{
  "job_request_id": "<job_request_id>",
  "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
  "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>", // Only one of attribution_report_to or reporting_site is required as of v2.7.0
    "report_error_threshold_percentage": "10",
    "debug_run": "true"
  }
}

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

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

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

در " Params "، مقدار job_request_id را به job_request_id که در درخواست createJob ارسال شده بود، به روز کنید.

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

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

{
    "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_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>", // Only one of attribution_report_to or reporting_site is required as of v2.7.0
    },
    "request_processing_started_at": "2023-12-07T22:51:06.034472697Z"
}

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

هنگامی که گزارش خلاصه خود را در خروجی 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 باشد، می توانید گزارش خلاصه خود را در پوشه اشکال زدایی که در output_data_blob_prefix قرار دارد دریافت کنید. این گزارش با فرمت AVRO است و با استفاده از دستور قبلی به JSON قابل تبدیل است.

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

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

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

1. پیش نیازها

برای اجرای این Codelab به چند پیش نیاز نیاز است. هر یک از الزامات بر این اساس مشخص می شود، چه برای "تست محلی" یا "سرویس تجمع" مورد نیاز باشد.

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

Local Testing به دانلود Local Testing Tool نیاز دارد. این ابزار گزارش های خلاصه ای را از گزارش های اشکال زدایی رمزگذاری نشده تولید می کند.

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

1.2. اطمینان حاصل کنید که JAVA JRE نصب شده است (سرویس آزمایش و تجمع محلی)

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

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

1.3. دانلود تبدیل گزارش انبوه (خدمات آزمایش و تجمیع محلی)

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

1.4. فعال کردن APIهای حریم خصوصی تبلیغات (سرویس آزمایش و تجمیع محلی)

در مرورگر خود، به chrome://settings/adPrivacy بروید و همه APIهای Ad Privacy را فعال کنید.

اطمینان حاصل کنید که کوکی های شخص ثالث فعال هستند.

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

1.5. ثبت نام وب و اندروید (سرویس تجمع)

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

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

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

1.6. ورود به سرویس تجمع (سرویس تجمع)

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

1.7. ارائه دهنده ابر (سرویس جمع آوری)

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

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

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

1.7.1. سطل AWS S3 ایجاد کنید

یک سطل AWS S3 برای ذخیره وضعیت 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

1.7.2. ایجاد کلید دسترسی کاربر

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

1.7.3. مجوزهای کاربر و گروه AWS

برای استقرار Aggregation Service در AWS، باید مجوزهای خاصی را به کاربر مورد استفاده برای استقرار سرویس ارائه دهید. برای این Codelab، اطمینان حاصل کنید که کاربر برای اطمینان از مجوزهای کامل در استقرار، دسترسی مدیر دارد.

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

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

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

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

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

بررسی کنید تا مطمئن شوید که Terraform در classpath موجود است.

terraform -v

1.9. پستچی (برای خدمات جمع آوری AWS)

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

با رفتن به آیتم ناوبری بالای " Workspaces " و انتخاب " Create Workspace " یک فضای کاری ایجاد کنید.

" Blank workspace " را انتخاب کنید، روی next کلیک کنید و نام آن را " Privacy Sandbox " بگذارید. " شخصی " را انتخاب کنید و روی " ایجاد " کلیک کنید.

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

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

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

AWS "Access Key" و "Secret Key" را از طریق " Environment quick look " به روز کنید.

روی " ویرایش " کلیک کنید و "مقدار فعلی" هر دو " access_key " و " secret_key " را به روز کنید. توجه داشته باشید که frontend_api_id در بخش 3.1.4 این سند ارائه خواهد شد. و ما توصیه می کنیم از منطقه us-east-1 استفاده کنید. با این حال، اگر می‌خواهید در منطقه دیگری مستقر شوید، مطمئن شوید که AMI منتشر شده را در حساب خود کپی کرده‌اید یا با استفاده از اسکریپت‌های ارائه‌شده یک خودسازی انجام دهید.

2. Local Testing Codelab

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

مراحل Codelab

مرحله 2.1. گزارش ماشه : گزارش جمع آوری خصوصی را راه اندازی کنید تا بتوانید گزارش را جمع آوری کنید.

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

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

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

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

مرحله 2.6. گزارش خلاصه را مرور کنید : گزارش خلاصه که توسط Local Testing Tool ایجاد شده است را مرور کنید.

2.1. گزارش ماشه

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

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

2.2. ایجاد گزارش جمع آوری اشکال زدایی

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

اطمینان حاصل کنید که در " بدن گزارش "، aggregation_coordinator_origin حاوی https://publickeyservice.msmt.aws.privacysandboxservices.com است که به این معنی است که گزارش یک گزارش جمع آوری AWS است.

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

vim report.json

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

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

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

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

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

کلیدهای سطل توسط تماس گیرنده API طراحی شده اند و نسخه نمایشی شامل کلیدهای سطل نمونه از پیش ساخته شده است. از آنجایی که نسخه آزمایشی حالت اشکال‌زدایی را برای جمع‌بندی خصوصی فعال کرده است، می‌توانید بار متن شفاف اشکال‌زدایی را از " گزارش بدن " برای بازیابی کلید سطل تجزیه کنید. اما، در این مورد، نسخه نمایشی جعبه حریم خصوصی سایت، کلیدهای سطل را ایجاد می‌کند. از آنجایی که تجمیع خصوصی برای این سایت در حالت اشکال زدایی است، می توانید از debug_cleartext_payload از " گزارش بدن " برای دریافت کلید سطل استفاده کنید.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

3. استقرار خدمات تجمع

برای استقرار Aggregation Service از مراحل زیر استفاده کنید:

مرحله 3. استقرار سرویس تجمع : سرویس تجمع را در AWS مستقر کنید
مرحله 3.1. مخزن خدمات جمع آوری را شبیه سازی کنید
مرحله 3.2. دانلود وابستگی های از پیش ساخته شده
مرحله 3.3. یک محیط توسعه ایجاد کنید
مرحله 3.4. استقرار سرویس تجمع

3.1. مخزن Aggregation Service را کلون کنید

در محیط محلی خود، مخزن Aggregation Service Github را شبیه سازی کنید.

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

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

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

cd <repository_root>/terraform/aws

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

bash download_prebuilt_dependencies.sh

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

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

mkdir dev

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

cp -R demo/* dev

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

cd dev

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

vim main.tf

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

برای AWS main.tf :

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

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 را به روز کنید و i برای input فشار دهید تا فایل را ویرایش کنید.

vim dev.auto.tfvars

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

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

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

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

terraform init

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

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

terraform plan

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

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

terraform apply

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

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

4. ایجاد ورودی سرویس Aggregation

به ایجاد گزارش های AVRO برای دسته بندی در سرویس Aggregation ادامه دهید.

مرحله 4. ایجاد ورودی سرویس جمع‌آوری : گزارش‌های سرویس جمع‌آوری را ایجاد کنید که برای سرویس تجمع دسته‌بندی می‌شوند.
مرحله 4.1. گزارش ماشه
مرحله 4.2. جمع آوری گزارش های جمع آوری
مرحله 4.3. تبدیل گزارش ها به AVRO
مرحله 4.4. دامنه خروجی AVRO را ایجاد کنید

4.1. گزارش ماشه

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

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

4.2. جمع آوری گزارش های جمع آوری

گزارش‌های جمع‌آوری‌شده خود را از نقاط پایانی .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 " گزارش بدن " را در یک فایل JSON قرار دهید. در این مثال می توانید از vim استفاده کنید. اما می توانید از هر ویرایشگر متنی که می خواهید استفاده کنید.

vim report.json

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

4.3. تبدیل گزارش ها به 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

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

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

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

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

goo.gle/ags-payload-decoder را باز کنید و debug_cleartext_payload خود را در کادر " INPUT " قرار دهید و روی " Decode " کلیک کنید.

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

اکنون که کلید سطل را داریم، ادامه دهید و output_domain.avro را ایجاد کنید. از تعویض مطمئن شوید با کلید سطلی که بازیابی کردید.

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

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

4.5. گزارش ها را به سطل AWS منتقل کنید

هنگامی که گزارش های AVRO (از بخش 3.2.3) و دامنه خروجی (از بخش 3.2.4) ایجاد شدند، به انتقال گزارش ها و دامنه خروجی به سطل های گزارش 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>/

5. استفاده از خدمات جمع آوری

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

مرحله 5. استفاده از سرویس تجمع : از API Service Aggregation برای ایجاد گزارش های خلاصه و بررسی گزارش های خلاصه استفاده کنید.
مرحله 5.1. استفاده از createJob Endpoint برای دسته بندی
مرحله 5.2. استفاده از getJob Endpoint برای بازیابی وضعیت دسته ای
مرحله 5.3. بررسی گزارش خلاصه

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

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

برای قرار دادن بار درخواستی خود، " بدن " را انتخاب کنید و " خام " را انتخاب کنید.

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

{
  "job_request_id": "<job_request_id>",
  "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
  "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>", // Only one of attribution_report_to or reporting_site is required as of v2.7.0
    "report_error_threshold_percentage": "10",
    "debug_run": "true"
  }
}

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

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

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

در " Params "، مقدار job_request_id را به job_request_id که در درخواست createJob ارسال شده بود، به روز کنید.

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

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

{
    "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_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>", // Only one of attribution_report_to or reporting_site is required as of v2.7.0
    },
    "request_processing_started_at": "2023-12-07T22:51:06.034472697Z"
}

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

هنگامی که گزارش خلاصه خود را در خروجی 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 باشد، می توانید گزارش خلاصه خود را در پوشه اشکال زدایی که در output_data_blob_prefix قرار دارد دریافت کنید. این گزارش با فرمت AVRO است و با استفاده از دستور قبلی به JSON قابل تبدیل است.

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

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

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

1. پیش نیازها

برای اجرای این Codelab به چند پیش نیاز نیاز است. هر یک از الزامات بر این اساس مشخص می شود، چه برای "تست محلی" یا "سرویس تجمع" مورد نیاز باشد.

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

Local Testing به دانلود Local Testing Tool نیاز دارد. این ابزار گزارش های خلاصه ای را از گزارش های اشکال زدایی رمزگذاری نشده تولید می کند.

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

1.2. اطمینان حاصل کنید که JAVA JRE نصب شده است (سرویس آزمایش و تجمع محلی)

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

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

1.3. دانلود تبدیل گزارش انبوه (خدمات آزمایش و تجمیع محلی)

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

1.4. فعال کردن APIهای حریم خصوصی تبلیغات (سرویس آزمایش و تجمیع محلی)

در مرورگر خود، به chrome://settings/adPrivacy بروید و همه APIهای Ad Privacy را فعال کنید.

اطمینان حاصل کنید که کوکی های شخص ثالث فعال هستند.

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

1.5. ثبت نام وب و اندروید (سرویس تجمع)

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

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

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

1.6. ورود به سرویس تجمع (سرویس تجمع)

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

1.7. ارائه دهنده ابر (سرویس جمع آوری)

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

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

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

1.7.1. سطل AWS S3 ایجاد کنید

یک سطل AWS S3 برای ذخیره وضعیت 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

1.7.2. ایجاد کلید دسترسی کاربر

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

1.7.3. مجوزهای کاربر و گروه AWS

برای استقرار Aggregation Service در AWS، باید مجوزهای خاصی را به کاربر مورد استفاده برای استقرار سرویس ارائه دهید. برای این Codelab، اطمینان حاصل کنید که کاربر برای اطمینان از مجوزهای کامل در استقرار، دسترسی مدیر دارد.

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

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

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

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

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

بررسی کنید تا مطمئن شوید که Terraform در classpath موجود است.

terraform -v

1.9. پستچی (برای خدمات جمع آوری AWS)

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

با رفتن به آیتم ناوبری بالای " Workspaces " و انتخاب " Create Workspace " یک فضای کاری ایجاد کنید.

" Blank workspace " را انتخاب کنید، روی next کلیک کنید و نام آن را " Privacy Sandbox " بگذارید. " شخصی " را انتخاب کنید و روی " ایجاد " کلیک کنید.

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

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

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

AWS "Access Key" و "Secret Key" را از طریق " Environment quick look " به روز کنید.

روی " ویرایش " کلیک کنید و "مقدار فعلی" هر دو " access_key " و " secret_key " را به روز کنید. توجه داشته باشید که frontend_api_id در بخش 3.1.4 این سند ارائه خواهد شد. و ما توصیه می کنیم از منطقه us-east-1 استفاده کنید. با این حال، اگر می‌خواهید در منطقه دیگری مستقر شوید، مطمئن شوید که AMI منتشر شده را در حساب خود کپی کرده‌اید یا با استفاده از اسکریپت‌های ارائه‌شده یک خودسازی انجام دهید.

2. Local Testing Codelab

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

مراحل Codelab

مرحله 2.1. گزارش ماشه : گزارش جمع آوری خصوصی را راه اندازی کنید تا بتوانید گزارش را جمع آوری کنید.

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

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

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

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

مرحله 2.6. گزارش خلاصه را مرور کنید : گزارش خلاصه که توسط Local Testing Tool ایجاد شده است را مرور کنید.

2.1. گزارش ماشه

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

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

2.2. ایجاد گزارش جمع آوری اشکال زدایی

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

اطمینان حاصل کنید که در " بدن گزارش "، aggregation_coordinator_origin حاوی https://publickeyservice.msmt.aws.privacysandboxservices.com است که به این معنی است که گزارش یک گزارش جمع آوری AWS است.

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

vim report.json

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

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

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

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

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

کلیدهای سطل توسط تماس گیرنده API طراحی شده اند و نسخه نمایشی شامل کلیدهای سطل نمونه از پیش ساخته شده است. از آنجایی که نسخه آزمایشی حالت اشکال‌زدایی را برای جمع‌بندی خصوصی فعال کرده است، می‌توانید بار متن شفاف اشکال‌زدایی را از " گزارش بدن " برای بازیابی کلید سطل تجزیه کنید. اما، در این مورد، نسخه نمایشی جعبه حریم خصوصی سایت، کلیدهای سطل را ایجاد می‌کند. از آنجایی که تجمیع خصوصی برای این سایت در حالت اشکال زدایی است، می توانید از debug_cleartext_payload از " گزارش بدن " برای دریافت کلید سطل استفاده کنید.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

3. استقرار خدمات تجمع

برای استقرار Aggregation Service از مراحل زیر استفاده کنید:

مرحله 3. استقرار سرویس تجمع : سرویس تجمع را در AWS مستقر کنید
مرحله 3.1. مخزن خدمات جمع آوری را شبیه سازی کنید
مرحله 3.2. دانلود وابستگی های از پیش ساخته شده
مرحله 3.3. یک محیط توسعه ایجاد کنید
مرحله 3.4. استقرار سرویس تجمع

3.1. مخزن Aggregation Service را کلون کنید

در محیط محلی خود، مخزن Aggregation Service Github را شبیه سازی کنید.

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

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

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

cd <repository_root>/terraform/aws

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

bash download_prebuilt_dependencies.sh

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

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

mkdir dev

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

cp -R demo/* dev

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

cd dev

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

vim main.tf

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

برای AWS main.tf :

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

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 را به روز کنید و i برای input فشار دهید تا فایل را ویرایش کنید.

vim dev.auto.tfvars

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

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

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

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

terraform init

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

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

terraform plan

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

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

terraform apply

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

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

4. ایجاد ورودی سرویس Aggregation

به ایجاد گزارش های AVRO برای دسته بندی در سرویس Aggregation ادامه دهید.

مرحله 4. ایجاد ورودی سرویس جمع‌آوری : گزارش‌های سرویس جمع‌آوری را ایجاد کنید که برای سرویس تجمع دسته‌بندی می‌شوند.
مرحله 4.1. گزارش ماشه
مرحله 4.2. جمع آوری گزارش های جمع آوری
مرحله 4.3. تبدیل گزارش ها به AVRO
مرحله 4.4. دامنه خروجی AVRO را ایجاد کنید

4.1. گزارش ماشه

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

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

4.2. جمع آوری گزارش های جمع آوری

گزارش‌های جمع‌آوری‌شده خود را از نقاط پایانی .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 " گزارش بدن " را در یک فایل JSON قرار دهید. در این مثال می توانید از vim استفاده کنید. اما می توانید از هر ویرایشگر متنی که می خواهید استفاده کنید.

vim report.json

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

4.3. تبدیل گزارش ها به 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

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

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

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

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

goo.gle/ags-payload-decoder را باز کنید و debug_cleartext_payload خود را در کادر " INPUT " قرار دهید و روی " Decode " کلیک کنید.

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

اکنون که کلید سطل را داریم، ادامه دهید و output_domain.avro را ایجاد کنید. از تعویض مطمئن شوید با کلید سطلی که بازیابی کردید.

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

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

4.5. گزارش ها را به سطل AWS منتقل کنید

هنگامی که گزارش های AVRO (از بخش 3.2.3) و دامنه خروجی (از بخش 3.2.4) ایجاد شدند، به انتقال گزارش ها و دامنه خروجی به سطل های گزارش 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>/

5. استفاده از خدمات جمع آوری

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

مرحله 5. استفاده از سرویس تجمع : از API Service Aggregation برای ایجاد گزارش های خلاصه و بررسی گزارش های خلاصه استفاده کنید.
مرحله 5.1. استفاده از createJob Endpoint برای دسته بندی
مرحله 5.2. استفاده از getJob Endpoint برای بازیابی وضعیت دسته ای
مرحله 5.3. بررسی گزارش خلاصه

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

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

برای قرار دادن بار درخواستی خود، " بدن " را انتخاب کنید و " خام " را انتخاب کنید.

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

{
  "job_request_id": "<job_request_id>",
  "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
  "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>", // Only one of attribution_report_to or reporting_site is required as of v2.7.0
    "report_error_threshold_percentage": "10",
    "debug_run": "true"
  }
}

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

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

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

در " Params "، مقدار job_request_id را به job_request_id که در درخواست createJob ارسال شده بود، به روز کنید.

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

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

{
    "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_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>", // Only one of attribution_report_to or reporting_site is required as of v2.7.0
    },
    "request_processing_started_at": "2023-12-07T22:51:06.034472697Z"
}

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

هنگامی که گزارش خلاصه خود را در خروجی 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 باشد، می توانید گزارش خلاصه خود را در پوشه اشکال زدایی که در output_data_blob_prefix قرار دارد دریافت کنید. این گزارش با فرمت AVRO است و با استفاده از دستور قبلی به JSON قابل تبدیل است.

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

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

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