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. 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_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 یافت

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

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. 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 تبدیل کنید. در حالت ایده آل ، AD Tech باید برای تبدیل گزارش های 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. استقرار خدمات تجمیع

برای استقرار خدمات جمع آوری ، از مراحل زیر استفاده کنید:

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

3.1. کلون مخزن خدمات جمع آوری

در محیط محلی خود ، مخزن خدمات جمع آوری GitHub را کلون کنید.

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

3.2. بارگیری وابستگی های از پیش ساخته

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

cd <repository_root>/terraform/aws

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

bash download_prebuilt_dependencies.sh

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

ایجاد یک محیط dev در /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 :

کد غیرقابل توصیف باید مانند موارد زیر باشد.

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 که در طول سرویس جمع آوری ، ایمیل و ایمیل ارائه می شود ، به روز کنید.

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

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

برای استقرار سرویس جمع آوری ، در همان پوشه /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 که باید در بخش 1.9 در Postman به روز کنید نیز بازگردانده می شود.

4. ایجاد ورودی خدمات جمع آوری

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

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

4.1. گزارش ماشه

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

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 ، به کلیدهای سطل نیاز دارید که از گزارش ها قابل بازیابی هستند.

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

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

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

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

اکنون که کلید سطل را داریم ، پیش بروید و 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 frontend_api_id به شما create_job_endpoint get_job_endpoint است. frontend_api_id کپی کرده و این را در متغیر Global Global frontend_api_id که در بخش پیش نیاز 1.9 تنظیم کرده اید قرار دهید.

مرحله 5. استفاده از خدمات جمع آوری : از API خدمات جمع آوری برای ایجاد گزارش های خلاصه و بررسی گزارش های خلاصه استفاده کنید.
مرحله 5.1. با استفاده از CreateJob Endpoint به دسته
مرحله 5.2. با استفاده از نقطه پایانی GetJob برای بازیابی وضعیت دسته ای
مرحله 5.3. بررسی گزارش خلاصه

5.1. با استفاده از createJob Endpoint به دسته

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

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

طرح بار createJob Payload در GitHub موجود است و شبیه به موارد زیر است. <> با زمینه های مناسب جایگزین کنید.

{
    "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 یافت

5.2. با استفاده از نقطه پایانی GetJob برای بازیابی وضعیت دسته ای

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

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

نتیجه getJob باید وضعیت درخواست شغلی شما را با وضعیت HTTP 200 بازگرداند. درخواست " بدنه " حاوی اطلاعات لازم مانند 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_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"
}

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

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