1. 1. پیش نیازها

زمان تخمینی برای تکمیل: 1-2 ساعت

2 حالت برای اجرای این کد لبه وجود دارد: تست محلی یا سرویس تجمع . حالت تست محلی به یک ماشین محلی و مرورگر Chrome نیاز دارد (بدون ایجاد/استفاده از منابع Google Cloud). حالت سرویس تجمع به استقرار کامل سرویس تجمع در Google Cloud نیاز دارد.

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

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

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

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

از آنجایی که ما از Privacy Sandbox استفاده خواهیم کرد، شما را تشویق می‌کنیم که API‌های Privacy Sandbox Ads را فعال کنید.

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

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

از chrome://settings/cookies ، مطمئن شوید که کوکی‌های شخص ثالث مسدود نشده‌اند. بسته به نسخه Chrome خود، ممکن است گزینه های مختلفی را در این منوی تنظیمات مشاهده کنید، اما تنظیمات قابل قبول عبارتند از:

• «مسدود کردن همه کوکی‌های شخص ثالث» = غیرفعال شده است
• "مسدود کردن کوکی های شخص ثالث" = غیرفعال شده است
• "مسدود کوکی های شخص ثالث در حالت ناشناس" = فعال است

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

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

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

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

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

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

1.5. دانلود aggregatable_report_converter (سرویس آزمایش و تجمع محلی)

می توانید یک کپی از aggregatable_report_converter را از مخزن Privacy Sandbox Demos GitHub دانلود کنید. مخزن GitHub استفاده از IntelliJ یا Eclipse را ذکر می کند، اما هیچ کدام مورد نیاز نیستند. اگر از این ابزارها استفاده نمی کنید، به جای آن فایل JAR را در محیط محلی خود دانلود کنید.

1.6. تنظیم یک محیط GCP (سرویس تجمع)

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

دستورالعمل‌های استقرار در GitHub را برای راه‌اندازی gcloud CLI، دانلود باینری‌ها و ماژول‌های Terraform، و ایجاد منابع GCP برای Aggregation Service دنبال کنید.

مراحل کلیدی در دستورالعمل استقرار:

1. "gcloud" CLI و Terraform را در محیط خود راه اندازی کنید.
2. یک سطل Cloud Storage برای ذخیره وضعیت Terraform ایجاد کنید.
3. دانلود وابستگی ها
4. adtech_setup.auto.tfvars را به روز کنید و adtech_setup Terraform را اجرا کنید. برای نمونه فایل adtech_setup.auto.tfvars به ​​پیوست مراجعه کنید. به نام سطل داده‌ای که در اینجا ایجاد می‌شود توجه کنید – از این سطل برای ذخیره فایل‌هایی که ایجاد می‌کنیم، در نرم‌افزار کد استفاده می‌شود.
5. dev.auto.tfvars به روز کنید، جعل هویت حساب Deploy Service و اجرای dev Terraform. برای نمونه فایل dev.auto.tfvars به ​​پیوست مراجعه کنید.
6. پس از تکمیل استقرار، frontend_service_cloudfunction_url از خروجی Terraform بگیرید ، که برای درخواست در مراحل بعدی به سرویس Aggregation مورد نیاز است.

1.7. نصب کامل سرویس تجمع (سرویس تجمع)

Aggregation Service برای اینکه بتواند از این سرویس استفاده کند نیاز به هماهنگی دارد. با ارائه سایت گزارش خود و سایر اطلاعات، انتخاب "Google Cloud" و وارد کردن آدرس حساب سرویس خود، فرم ورود به سرویس جمع آوری را تکمیل کنید. این حساب سرویس در پیش نیاز قبلی ایجاد می شود (1.6. تنظیم یک محیط GCP). (نکته: اگر از نام های پیش فرض ارائه شده استفاده می کنید، این حساب سرویس با "worker-sa@" شروع می شود).

حداکثر 2 هفته فرصت دهید تا فرآیند ورود به سیستم کامل شود.

1.8. روش خود را برای فراخوانی نقاط پایانی API (سرویس تجمع) تعیین کنید

این کد 2 گزینه برای فراخوانی نقاط پایانی API Service Aggregation ارائه می دهد: cURL و Postman . cURL راه سریع‌تر و آسان‌تر برای فراخوانی نقاط پایانی API از ترمینال شما است، زیرا به حداقل تنظیمات و بدون نرم‌افزار اضافی نیاز دارد. با این حال، اگر نمی‌خواهید از cURL استفاده کنید، می‌توانید در عوض از Postman برای اجرا و ذخیره درخواست‌های API برای استفاده در آینده استفاده کنید.

در بخش 3.2. استفاده از خدمات جمع آوری، دستورالعمل های دقیق برای استفاده از هر دو گزینه را خواهید دید. می‌توانید اکنون آنها را پیش‌نمایش کنید تا مشخص کنید از کدام روش استفاده می‌کنید. اگر Postman را انتخاب کنید، تنظیمات اولیه زیر را انجام دهید.

1.8.1. فضای کاری را تنظیم کنید

برای یک حساب پستچی ثبت نام کنید. پس از ثبت نام، یک فضای کاری به طور خودکار برای شما ایجاد می شود.

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

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

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

هر دو فایل JSON را از طریق دکمه "Import" به "My Workspace" وارد کنید.

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

1.8.2. مجوز را تنظیم کنید

روی مجموعه "GCP Privacy Sandbox" کلیک کنید و به برگه "Authorization" بروید.

شما از روش "Bearer Token" استفاده خواهید کرد. از محیط Terminal خود، این دستور را اجرا کنید و خروجی را کپی کنید.

gcloud auth print-identity-token

سپس، این مقدار توکن را در قسمت «Token» برگه مجوز پستچی قرار دهید:

1.8.3. تنظیم محیط

به «نگاه سریع محیط» در گوشه سمت راست بالا بروید:

روی «ویرایش» کلیک کنید و «مقدار فعلی» «محیط»، «region» و «cloud-function-id» را به‌روزرسانی کنید:

می‌توانید فعلاً «Request-id» را خالی بگذارید، زیرا بعداً آن را پر خواهیم کرد. برای سایر فیلدها، از مقادیر frontend_service_cloudfunction_url استفاده کنید، که از تکمیل موفقیت آمیز استقرار Terraform در پیش نیاز 1.6 برگردانده شد. URL از این فرمت پیروی می کند: https:// - -frontend-service- -uc.a.run.app

2. 2. Local Testing Codelab

زمان تخمینی برای تکمیل: <1 ساعت

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

مراحل Codelab

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

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

مرحله 2.3. بازیابی کلیدهای سطل : کلیدهای سطل توسط adTechs طراحی شده اند. در این کد لبه، از آنجایی که سطل ها از قبل تعریف شده اند، کلیدهای سطل را همانطور که ارائه شده است بازیابی کنید.

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

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

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

2.1. گزارش ماشه

برای راه‌اندازی گزارش تجمیع خصوصی، می‌توانید از سایت نمایشی Privacy Sandbox (https://privacy-sandbox-demos-news.dev/?env=gcp) یا سایت خودتان (مثلاً https://adtechexample.com) استفاده کنید. اگر از سایت خود استفاده می‌کنید و ثبت‌نام و تأیید و ورود به سرویس تجمیع را تکمیل نکرده‌اید، باید از پرچم Chrome و سوئیچ CLI استفاده کنید.

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

گزارشی که به {reporting-origin}/.well-known/private-aggregation/debug/report-shared-storage endpoint ارسال می‌شود نیز در "گزارش بدنه" گزارش‌های نمایش داده شده در صفحه Chrome Internals یافت می‌شود.

ممکن است گزارش‌های زیادی را در اینجا ببینید، اما برای این نرم‌افزار، از گزارش جمع‌آوری‌شده استفاده کنید که مختص GCP است و توسط نقطه پایانی اشکال‌زدایی تولید می‌شود . "URL گزارش" حاوی "/debug/" و aggregation_coordinator_origin field از "گزارش بدن" حاوی این URL خواهد بود: https://publickeyservice.msmt.gcp.privacysandboxservices.com.

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

گزارش یافت شده در "گزارش بدنه" chrome://private-aggregation-internals را کپی کنید و یک فایل JSON در پوشه privacy-sandbox-demos/tools/aggregatable_report_converter/out/artifacts/aggregatable_report_converter_jar (در مخزن قبلی دانلود شده در 1.1) ایجاد کنید.

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

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

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

goo.gle/ags-payload-decoder را باز کنید و 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.3 دانلود شده است برای ایجاد گزارش های خلاصه با استفاده از دستور زیر استفاده خواهیم کرد. نسخه ای را که دانلود کردید جایگزین {version} کنید. فراموش نکنید که LocalTestingTool_{version}.jar به دایرکتوری فعلی منتقل کنید یا یک مسیر نسبی برای ارجاع به مکان فعلی آن اضافه کنید.

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 تبدیل کنید. در حالت ایده‌آل، adTech باید کدی را برای تبدیل گزارش‌های AVRO به JSON بنویسد.

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

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

این یک گزارش مشابه زیر را برمی گرداند. به همراه یک گزارش output.json که در همان دایرکتوری ایجاد شده است.

Codelab کامل شد!

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

مراحل بعدی: اکنون که ابزار Local Testing را آزمایش کرده اید، می توانید همان تمرین را با استقرار زنده Aggregation Service در محیط خود امتحان کنید. پیش نیازها را دوباره بررسی کنید تا مطمئن شوید همه چیز را برای حالت "Aggregation Service" تنظیم کرده اید، سپس به مرحله 3 بروید.

3. 3. Codelab Service Aggregation

زمان تخمینی برای تکمیل: 1 ساعت

قبل از شروع ، اطمینان حاصل کنید که همه پیش نیازهای برچسب‌گذاری شده با "سرویس تجمع" را تکمیل کرده اید.

مراحل Codelab

مرحله 3.1. ایجاد ورودی سرویس تجمع : گزارش‌های سرویس تجمع را ایجاد کنید که برای سرویس تجمع دسته‌بندی می‌شوند.

• مرحله 3.1.1. گزارش ماشه
• مرحله 3.1.2. جمع آوری گزارش های جمع آوری
• مرحله 3.1.3. تبدیل گزارش ها به AVRO
• مرحله 3.1.4. output_domain AVRO ایجاد کنید
• مرحله 3.1.5. انتقال گزارش‌ها به سطل فضای ذخیره‌سازی ابری

مرحله 3.2. استفاده از سرویس تجمع : از API Service Aggregation برای ایجاد گزارش های خلاصه و بررسی خلاصه گزارش ها استفاده کنید.

• مرحله 3.2.1. استفاده از createJob Endpoint برای دسته بندی
• مرحله 3.2.2. استفاده از getJob Endpoint برای بازیابی وضعیت دسته ای
• مرحله 3.2.3. بررسی گزارش خلاصه

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

به ایجاد گزارش های AVRO برای دسته بندی به سرویس Aggregation ادامه دهید. دستورات پوسته در این مراحل می‌توانند در پوسته ابری GCP (تا زمانی که وابستگی‌های پیش‌نیازها در محیط Cloud Shell شما شبیه‌سازی شوند) یا در یک محیط اجرای محلی اجرا شوند.

3.1.1. گزارش ماشه

برای رفتن به سایت لینک را دنبال کنید؛ سپس، می‌توانید گزارش‌ها را در chrome://private-aggregation-internals مشاهده کنید:

گزارشی که به {reporting-origin}/.well-known/private-aggregation/debug/report-shared-storage endpoint ارسال می‌شود نیز در "گزارش بدنه" گزارش‌های نمایش داده شده در صفحه Chrome Internals یافت می‌شود.

ممکن است گزارش‌های زیادی را در اینجا ببینید، اما برای این نرم‌افزار، از گزارش جمع‌آوری‌شده استفاده کنید که مختص GCP است و توسط نقطه پایانی اشکال‌زدایی تولید می‌شود . "URL گزارش" حاوی "/debug/" و aggregation_coordinator_origin field از "گزارش بدن" حاوی این URL خواهد بود: https://publickeyservice.msmt.gcp.privacysandboxservices.com.

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

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

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

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

بیایید ادامه دهیم و گزارش JSON را در "گزارش بدن" از chrome://private-aggregation-internals کپی کنیم.

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

vim report.json

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

3.1.3. تبدیل گزارش ها به AVRO

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

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

3.1.4. output_domain AVRO ایجاد کنید

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

کلیدهای سطل توسط adTech طراحی شده اند. با این حال، در این مورد، سایت Privacy Sandbox Demo کلیدهای سطل را ایجاد می کند. از آنجایی که تجمیع خصوصی برای این سایت در حالت اشکال زدایی است، می توانیم از 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 را در پوشه فعلی شما ایجاد می کند.

3.1.5. انتقال گزارش‌ها به سطل فضای ذخیره‌سازی ابری

پس از ایجاد گزارش‌های AVRO و دامنه خروجی، به انتقال گزارش‌ها و دامنه خروجی به سطل در Cloud Storage (که در پیش‌نیاز 1.6 اشاره کردید) ادامه دهید.

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

gcloud storage cp report.avro gs://<bucket_name>/reports/

gcloud storage cp output_domain.avro gs://<bucket_name>/output_domain/

در غیر این صورت فایل ها را به صورت دستی در سطل خود آپلود کنید. پوشه ای به نام "گزارش ها" ایجاد کنید و فایل report.avro در آنجا آپلود کنید. یک پوشه به نام "output_domains" ایجاد کنید و فایل output_domain.avro در آنجا آپلود کنید.

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

در پیش‌نیاز 1.8 به یاد بیاورید که برای درخواست‌های API به نقاط پایانی Aggregation Service یا CURL یا Postman را انتخاب کرده‌اید. در زیر دستورالعمل های هر دو گزینه را مشاهده خواهید کرد.

اگر کار شما با یک خطا با شکست مواجه شد، برای اطلاعات بیشتر در مورد نحوه ادامه، اسناد عیب‌یابی ما را در GitHub بررسی کنید.

3.2.1. استفاده از createJob Endpoint برای دسته بندی

برای ایجاد شغل از دستورالعمل‌های cURL یا Postman زیر استفاده کنید.

CURL

در "Terminal" خود، یک فایل بدنه درخواست ( body.json ) ایجاد کنید و در زیر جای‌گذاری کنید. حتماً مقادیر متغیرهای نگهدارنده را به روز کنید. برای اطلاعات بیشتر در مورد آنچه که هر فیلد نشان می دهد، به این مستندات API مراجعه کنید.

{
    "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": "<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"
    }
}

درخواست زیر را اجرا کنید. متغیرهای موجود در URL درخواست cURL را با مقادیر frontend_service_cloudfunction_url جایگزین کنید، که پس از تکمیل موفقیت آمیز استقرار Terraform در پیش نیاز 1.6 خروجی می شود.

curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  -d @body.json \
  https://<environment>-<region>-frontend-service-<cloud-function-id>-uc.a.run.app/v1alpha/createJob

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

پستچی

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

به برگه "Body" درخواست createJob بروید:

جانشین ها را در JSON ارائه شده جایگزین کنید. برای اطلاعات بیشتر در مورد این فیلدها و آنچه نشان می دهند، به مستندات API مراجعه کنید.

{
    "job_request_id": "<job_request_id>",
    "input_data_blob_prefix": "<report_folder>/",
    "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": "<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"
    }
}

"ارسال" درخواست createJob API:

کد پاسخ را می توانید در نیمه پایین صفحه پیدا کنید:

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

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

از دستورالعمل‌های cURL یا Postman زیر برای یافتن شغل استفاده کنید.

CURL

درخواست زیر را در ترمینال خود اجرا کنید. متغیرهای موجود در URL را با مقادیر frontend_service_cloudfunction_url جایگزین کنید، که همان URL است که برای درخواست createJob استفاده کردید. برای "job_request_id"، از مقدار کاری که با نقطه پایانی createJob ایجاد کردید استفاده کنید.

curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  https://<environment>-<region>-frontend-service-<cloud-function-id>-uc.a.run.app/v1alpha/getJob?job_request_id=<job_request_id>

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

پستچی

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

"ارسال" درخواست getJob :

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

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

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

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

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

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

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

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

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

Codelab کامل شد!

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

مراحل بعدی: به استفاده از Aggregation Service در محیط خود ادامه دهید یا منابع ابری را که به دنبال دستورالعمل های پاکسازی در مرحله 4 ایجاد کرده اید حذف کنید.

4. 4. پاکسازی

برای حذف منابع ایجاد شده برای Aggregation Service از طریق Terraform، از دستور kill در پوشه‌های adtech_setup و dev (یا محیط‌های دیگر) استفاده کنید:

$ cd <repository_root>/terraform/gcp/environments/adtech_setup
$ terraform destroy
$ cd <repository_root>/terraform/gcp/environments/dev
$ terraform destroy

برای حذف سطل Cloud Storage که گزارش‌های جمع‌آوری‌شده و گزارش‌های خلاصه شما را در خود نگه می‌دارد:

$ gcloud storage buckets delete gs://my-bucket

همچنین می‌توانید تنظیمات کوکی Chrome خود را از پیش‌نیاز 1.2 به حالت قبلی بازگردانید.

5. 5. ضمیمه

نمونه فایل adtech_setup.auto.tfvars

/**
 * Copyright 2023 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

project = "my-project-id"

# Required to generate identity token for access of Adtech Services API endpoints
service_account_token_creator_list = ["user:me@email.com"]

# Uncomment the below line if you like Terraform to create an Artifact registry repository
# for self-build container artifacts. "artifact_repo_location" defaults to "us".
artifact_repo_name     = "my-ags-artifacts"

# Note: Either one of [1] or [2] must be uncommented.

# [1] Uncomment below lines if you like Terraform grant needed permissions to
# pre-existing service accounts
# deploy_service_account_email = "<YourDeployServiceAccountName>@<ProjectID>.iam.gserviceaccount.com"
# worker_service_account_email = "<YourWorkerServiceAccountName>@<ProjectID>.iam.gserviceaccount.com"

# [2] Uncomment below lines if you like Terraform to create service accounts
# and needed permissions granted e.g "deploy-sa" or "worker-sa"
deploy_service_account_name = "deploy-sa"
worker_service_account_name = "worker-sa"
# Uncomment the below line if you want Terraform to create the
# below bucket. "data_bucket_location" defaults to "us".
data_bucket_name     = "my-ags-data"

# Uncomment the below lines if you want to specify service account customer role names
# deploy_sa_role_name = "<YourDeploySACustomRole>"
# worker_sa_role_name = "<YourWorkerSACustomRole>"

نمونه فایل dev.auto.tfvars

/**
 * Copyright 2022 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

# Example values required by job_service.tf
#
# These values should be modified for each of your environments.
region      = "us-central1"
region_zone = "us-central1-c"

project_id  = "my-project-id"
environment = "operator-demo-env"

# Co-locate your Cloud Spanner instance configuration with the region above.
# https://cloud.google.com/spanner/docs/instance-configurations#regional-configurations
spanner_instance_config = "regional-us-central1"

# Adjust this based on the job load you expect for your deployment.
# Monitor the spanner instance utilization to decide on scale out / scale in.
# https://console.cloud.google.com/spanner/instances
spanner_processing_units = 100

# Uncomment the line below at your own risk to disable Spanner database protection.
# This needs to be set to false and applied before destroying all resources is possible.
spanner_database_deletion_protection = false

instance_type = "n2d-standard-8" # 8 cores, 32GiB

# Container image location that packages the job service application
# If not set otherwise, uncomment and edit the line below:
#worker_image = "<location>/<project>/<repository>/<image>:<tag or digest>"

# Service account created and onboarded for worker
user_provided_worker_sa_email = "worker-sa@my-project-id.iam.gserviceaccount.com"

min_worker_instances = 1
max_worker_instances = 20

1. 1. پیش نیازها

زمان تخمینی برای تکمیل: 1-2 ساعت

2 حالت برای اجرای این کد لبه وجود دارد: تست محلی یا سرویس تجمع . حالت تست محلی به یک ماشین محلی و مرورگر Chrome نیاز دارد (بدون ایجاد/استفاده از منابع Google Cloud). حالت سرویس تجمع به استقرار کامل سرویس تجمع در Google Cloud نیاز دارد.

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

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

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

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

از آنجایی که ما از Privacy Sandbox استفاده خواهیم کرد، شما را تشویق می‌کنیم که API‌های Privacy Sandbox Ads را فعال کنید.

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

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

از chrome://settings/cookies ، مطمئن شوید که کوکی‌های شخص ثالث مسدود نشده‌اند. بسته به نسخه Chrome خود، ممکن است گزینه های مختلفی را در این منوی تنظیمات مشاهده کنید، اما تنظیمات قابل قبول عبارتند از:

• «مسدود کردن همه کوکی‌های شخص ثالث» = غیرفعال شده است
• "مسدود کردن کوکی های شخص ثالث" = غیرفعال شده است
• "مسدود کوکی های شخص ثالث در حالت ناشناس" = فعال است

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

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

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

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

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

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

1.5. دانلود aggregatable_report_converter (سرویس آزمایش و تجمع محلی)

می توانید یک کپی از aggregatable_report_converter را از مخزن Privacy Sandbox Demos GitHub دانلود کنید. مخزن GitHub استفاده از IntelliJ یا Eclipse را ذکر می کند، اما هیچ کدام مورد نیاز نیستند. اگر از این ابزارها استفاده نمی کنید، به جای آن فایل JAR را در محیط محلی خود دانلود کنید.

1.6. تنظیم یک محیط GCP (سرویس تجمع)

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

دستورالعمل‌های استقرار در GitHub را برای راه‌اندازی gcloud CLI، دانلود باینری‌ها و ماژول‌های Terraform، و ایجاد منابع GCP برای Aggregation Service دنبال کنید.

مراحل کلیدی در دستورالعمل استقرار:

1. "gcloud" CLI و Terraform را در محیط خود راه اندازی کنید.
2. یک سطل Cloud Storage برای ذخیره وضعیت Terraform ایجاد کنید.
3. دانلود وابستگی ها
4. adtech_setup.auto.tfvars را به روز کنید و adtech_setup Terraform را اجرا کنید. برای نمونه فایل adtech_setup.auto.tfvars به ​​پیوست مراجعه کنید. به نام سطل داده‌ای که در اینجا ایجاد می‌شود توجه کنید – از این سطل برای ذخیره فایل‌هایی که ایجاد می‌کنیم، در نرم‌افزار کد استفاده می‌شود.
5. dev.auto.tfvars به روز کنید، جعل هویت حساب Deploy Service و اجرای dev Terraform. برای نمونه فایل dev.auto.tfvars به ​​پیوست مراجعه کنید.
6. پس از تکمیل استقرار، frontend_service_cloudfunction_url از خروجی Terraform بگیرید ، که برای درخواست در مراحل بعدی به سرویس Aggregation مورد نیاز است.

1.7. نصب کامل سرویس تجمع (سرویس تجمع)

Aggregation Service برای اینکه بتواند از این سرویس استفاده کند نیاز به هماهنگی دارد. با ارائه سایت گزارش خود و سایر اطلاعات، انتخاب "Google Cloud" و وارد کردن آدرس حساب سرویس خود ، فرم ورود به سرویس جمع آوری را تکمیل کنید. این حساب سرویس در پیش نیاز قبلی ایجاد می شود (1.6. تنظیم یک محیط GCP). (نکته: اگر از نام های پیش فرض ارائه شده استفاده می کنید، این حساب سرویس با "worker-sa@" شروع می شود).

حداکثر 2 هفته فرصت دهید تا فرآیند ورود به سیستم کامل شود.

1.8. روش خود را برای فراخوانی نقاط پایانی API (سرویس تجمع) تعیین کنید

این کد 2 گزینه برای فراخوانی نقاط پایانی API Service Aggregation ارائه می دهد: cURL و Postman . cURL راه سریع‌تر و آسان‌تر برای فراخوانی نقاط پایانی API از ترمینال شما است، زیرا به حداقل تنظیمات و بدون نرم‌افزار اضافی نیاز دارد. با این حال، اگر نمی‌خواهید از cURL استفاده کنید، می‌توانید در عوض از Postman برای اجرا و ذخیره درخواست‌های API برای استفاده در آینده استفاده کنید.

در بخش 3.2. استفاده از خدمات جمع آوری، دستورالعمل های دقیق برای استفاده از هر دو گزینه را خواهید دید. می‌توانید اکنون آنها را پیش‌نمایش کنید تا مشخص کنید از کدام روش استفاده می‌کنید. اگر Postman را انتخاب کنید، تنظیمات اولیه زیر را انجام دهید.

1.8.1. فضای کاری را تنظیم کنید

برای یک حساب پستچی ثبت نام کنید. پس از ثبت نام، یک فضای کاری به طور خودکار برای شما ایجاد می شود.

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

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

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

هر دو فایل JSON را از طریق دکمه "Import" به "My Workspace" وارد کنید.

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

1.8.2. مجوز را تنظیم کنید

روی مجموعه "GCP Privacy Sandbox" کلیک کنید و به برگه "Authorization" بروید.

شما از روش "Bearer Token" استفاده خواهید کرد. از محیط Terminal خود، این دستور را اجرا کنید و خروجی را کپی کنید.

gcloud auth print-identity-token

سپس، این مقدار توکن را در قسمت «Token» برگه مجوز پستچی قرار دهید:

1.8.3. تنظیم محیط

به «نگاه سریع محیط» در گوشه سمت راست بالا بروید:

روی «ویرایش» کلیک کنید و «مقدار فعلی» «محیط»، «region» و «cloud-function-id» را به‌روزرسانی کنید:

می‌توانید فعلاً «Request-id» را خالی بگذارید، زیرا بعداً آن را پر خواهیم کرد. برای سایر فیلدها، از مقادیر frontend_service_cloudfunction_url استفاده کنید، که از تکمیل موفقیت آمیز استقرار Terraform در پیش نیاز 1.6 برگردانده شد. URL از این فرمت پیروی می کند: https:// - -frontend-service- -uc.a.run.app

2. 2. Local Testing Codelab

زمان تخمینی برای تکمیل: <1 ساعت

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

مراحل Codelab

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

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

مرحله 2.3. بازیابی کلیدهای سطل : کلیدهای سطل توسط AdTechs طراحی شده اند. در این CodeLab ، از آنجا که سطل ها از قبل تعریف شده اند ، کلیدهای سطل را مطابق آنچه پیش آمده است بازیابی کنید.

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

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

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

2.1. گزارش ماشه

برای شروع یک گزارش جمع آوری خصوصی ، می توانید از سایت نسخه ی نمایشی ماسه ای حریم خصوصی (https://privacy-sandbox-demos-news.dev/؟env=gcp) یا سایت خود استفاده کنید (به عنوان مثال https://adtechexample.com). اگر از سایت شخصی خود استفاده می کنید و ثبت نام و تأیید و خدمات جمع آوری را به انجام نکرده اید ، باید از یک پرچم Chrome و سوئیچ CLI استفاده کنید.

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

گزارشی که به {reporting-origin}/.well-known/private-aggregation/debug/report-shared-storage ارسال شده است نیز در "بدنه گزارش" گزارش های نمایش داده شده در صفحه داخلی Chrome یافت می شود.

ممکن است گزارش های زیادی را در اینجا مشاهده کنید ، اما برای این CodeLab ، از گزارش قابل جمع شدن استفاده کنید که خاص GCP است و توسط نقطه انتهایی اشکال زدایی تولید می شود . "URL گزارش" حاوی "/اشکال زدایی/" خواهد بود و aggregation_coordinator_origin field "بدنه گزارش" شامل این آدرس است: https://publickeyservice.msmt.gcp.privacysandboxservice.com.

2.2. گزارش قابل قبول اشکال زدایی را ایجاد کنید

گزارش موجود در "بدنه گزارش" chrome://private-aggregation-internals و ایجاد یک فایل JSON در privacy-sandbox-demos/tools/aggregatable_report_converter/out/artifacts/aggregatable_report_converter_jar (در داخل مجدداً بارگیری شده در Preerequisite 1.5).

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

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

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

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

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

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

اکنون که کلید سطل را داریم ، بیایید 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.3 بارگیری شده است برای ایجاد گزارش های خلاصه با استفاده از دستور زیر استفاده خواهیم کرد. {version} را با نسخه ای که بارگیری کرده اید جایگزین کنید. به یاد داشته باشید که LocalTestingTool_{version}.jar به فهرست فعلی منتقل کنید ، یا یک مسیر نسبی را برای مراجعه به مکان فعلی خود اضافه کنید.

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 تبدیل کنید. در حالت ایده آل ، ADTech باید کد را برای تبدیل گزارش های Avro به JSON بنویسد.

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

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

این گزارشی شبیه به زیر را برمی گرداند. همراه با یک گزارش output.json ایجاد شده در همان فهرست.

CodeLab کامل!

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

مراحل بعدی: اکنون که با ابزار تست محلی آزمایش کرده اید ، می توانید همان تمرین را با استقرار زنده سرویس جمع آوری در محیط شخصی خود امتحان کنید. برای اطمینان از تنظیم همه چیز برای "سرویس جمع آوری" ، پیش نیازها را مجدداً مورد بررسی قرار دهید ، سپس به مرحله 3 بروید.

3. 3

زمان تخمین زده شده برای تکمیل: 1 ساعت

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

مراحل کدگذاری

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

• مرحله 3.1.1. گزارش ماشه
• مرحله 3.1.2. گزارش های قابل جمع را جمع آوری کنید
• مرحله 3.1.3. گزارش ها را به Avro تبدیل کنید
• مرحله 3.1.4. ایجاد خروجی_Domain avro
• مرحله 3.1.5. گزارش ها را به سطل ذخیره سازی ابری منتقل کنید

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

• مرحله 3.2.1. با استفاده از createJob Endpoint به دسته
• مرحله 3.2.2. با استفاده از نقطه پایانی getJob برای بازیابی وضعیت دسته ای
• مرحله 3.2.3. بررسی گزارش خلاصه

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

برای ایجاد گزارش های AVRO برای دسته بندی خدمات جمع آوری اقدام کنید. دستورات پوسته در این مراحل را می توان در پوسته ابر GCP اجرا کرد (تا زمانی که وابستگی های پیش نیازها در محیط پوسته ابر شما کلون شده باشد) یا در یک محیط اجرای محلی.

3.1.1. گزارش ماشه

برای رفتن به سایت ، پیوند را دنبال کنید. سپس ، می توانید گزارش ها را در chrome://private-aggregation-internals :

گزارشی که به {reporting-origin}/.well-known/private-aggregation/debug/report-shared-storage ارسال شده است نیز در "بدنه گزارش" گزارش های نمایش داده شده در صفحه داخلی Chrome یافت می شود.

ممکن است گزارش های زیادی را در اینجا مشاهده کنید ، اما برای این CodeLab ، از گزارش قابل جمع شدن استفاده کنید که خاص GCP است و توسط نقطه انتهایی اشکال زدایی تولید می شود . "URL گزارش" حاوی "/اشکال زدایی/" خواهد بود و aggregation_coordinator_origin field "بدنه گزارش" شامل این آدرس است: https://publickeyservice.msmt.gcp.privacysandboxservice.com.

3.1.2. گزارش های قابل جمع را جمع آوری کنید

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

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

برای این CodeLab ، مجموعه گزارش را به صورت دستی انجام می دهیم. در تولید ، انتظار می رود AdTechs به صورت برنامه ای گزارش ها را جمع آوری و تبدیل کند.

بیایید پیش برویم و گزارش JSON را در "بدنه گزارش" از chrome://private-aggregation-internals کپی کنید.

در این مثال ، ما از VIM استفاده می کنیم زیرا از لینوکس استفاده می کنیم. اما می توانید از هر ویرایشگر متن مورد نظر خود استفاده کنید.

vim report.json

گزارش را به report.json بچسبانید و پرونده خود را ذخیره کنید.

3.1.3. گزارش ها را به Avro تبدیل کنید

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

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

3.1.4. ایجاد خروجی_Domain avro

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

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

3.1.5. گزارش ها را به سطل ذخیره سازی ابری منتقل کنید

پس از ایجاد گزارش و حوزه خروجی AVRO ، گزارش ها و دامنه خروجی را به سطل در ذخیره سازی ابری منتقل کنید (که در پیش نیاز 1.6 به آن اشاره کردید).

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

gcloud storage cp report.avro gs://<bucket_name>/reports/

gcloud storage cp output_domain.avro gs://<bucket_name>/output_domain/

در غیر این صورت ، پرونده ها را به صورت دستی در سطل خود بارگذاری کنید. پوشه ای به نام "گزارش" ایجاد کنید و پرونده report.avro بارگذاری کنید. پوشه ای به نام "output_domains" ایجاد کنید و پرونده output_domain.avro در آنجا بارگذاری کنید.

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

در پیش نیاز 1.8 به یاد بیاورید که شما برای ایجاد درخواست های API به نقاط پایانی خدمات جمع آوری ، Curl یا Postman را انتخاب کرده اید. در زیر دستورالعمل هایی را برای هر دو گزینه پیدا خواهید کرد.

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

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

برای ایجاد شغل از دستورالعمل های CURL یا Postman در زیر استفاده کنید.

CURL

در "ترمینال" خود ، یک پرونده بدنه درخواست ( body.json ) ایجاد کنید و در زیر چسبانده کنید. حتماً مقادیر نگهدارنده مکان را به روز کنید. برای اطلاعات بیشتر در مورد آنچه هر قسمت نشان می دهد ، به این مستندات API مراجعه کنید.

{
    "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": "<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"
    }
}

درخواست زیر را اجرا کنید. متغیرهای موجود در URL درخواست CURL را با مقادیر frontend_service_cloudfunction_url جایگزین کنید ، که پس از اتمام موفقیت آمیز استقرار Terraform در پیش نیاز 1.6 ، خروجی است.

curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  -d @body.json \
  https://<environment>-<region>-frontend-service-<cloud-function-id>-uc.a.run.app/v1alpha/createJob

پس از پذیرش درخواست توسط سرویس جمع ، باید پاسخ HTTP 202 را دریافت کنید. سایر کدهای پاسخ ممکن در مشخصات API ثبت شده است.

پستچی

برای نقطه پایانی createJob ، به منظور ارائه خدمات جمع آوری در محل و نام پرونده های گزارش های قابل جمع ، دامنه های خروجی و گزارش های خلاصه ، یک بدنه درخواست مورد نیاز است.

به برگه "بدنه" درخواست createJob بروید:

متغیرهای موجود در JSON ارائه شده را جایگزین کنید. برای کسب اطلاعات بیشتر در مورد این زمینه ها و آنچه آنها را نشان می دهند ، به مستندات API مراجعه کنید.

{
    "job_request_id": "<job_request_id>",
    "input_data_blob_prefix": "<report_folder>/",
    "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": "<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"
    }
}

"ارسال" درخواست API createJob :

کد پاسخ را می توان در نیمه پایین صفحه یافت:

پس از پذیرش درخواست توسط سرویس جمع ، باید پاسخ HTTP 202 را دریافت کنید. سایر کدهای پاسخ ممکن در مشخصات API ثبت شده است.

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

برای دریافت شغل از دستورالعمل های CURL یا Postman در زیر استفاده کنید.

CURL

درخواست زیر را در ترمینال خود اجرا کنید. متغیرهای موجود در URL را با مقادیر frontend_service_cloudfunction_url جایگزین کنید ، که همان URL است که شما برای درخواست createJob استفاده کرده اید. برای "job_request_id" ، از کاری که ایجاد کرده اید با نقطه انتهایی createJob استفاده کنید.

curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  https://<environment>-<region>-frontend-service-<cloud-function-id>-uc.a.run.app/v1alpha/getJob?job_request_id=<job_request_id>

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

پستچی

برای بررسی وضعیت درخواست شغلی ، می توانید از نقطه پایانی getJob استفاده کنید. در بخش "Params" درخواست getJob ، مقدار job_request_id را به job_request_id که در درخواست createJob ارسال شده است ، به روز کنید.

"ارسال" درخواست getJob :

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

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

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

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

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

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

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

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

• in_reports - کلید سطل در گزارش های قابل جمع شدن در دسترس است.
• IN_DOMAIN - کلید سطل در پرونده Output_domain Avro موجود است.

CodeLab کامل!

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

مراحل بعدی: به استفاده از سرویس جمع آوری در محیط خود ادامه دهید ، یا منابع ابری را که تازه ایجاد کرده اید به دنبال دستورالعمل های پاکسازی در مرحله 4 حذف کنید.

4. 4. پاکسازی

برای حذف منابع ایجاد شده برای خدمات جمع آوری از طریق Terraform ، از دستور Destroy در پوشه های adtech_setup و dev (یا محیط دیگر) استفاده کنید:

$ cd <repository_root>/terraform/gcp/environments/adtech_setup
$ terraform destroy
$ cd <repository_root>/terraform/gcp/environments/dev
$ terraform destroy

برای حذف سطل ذخیره سازی ابری که گزارش ها و گزارش های خلاصه خود را در اختیار شما قرار می دهد:

$ gcloud storage buckets delete gs://my-bucket

همچنین ممکن است تنظیمات کوکی کروم خود را از پیش نیاز 1.2 به وضعیت قبلی خود برگردانید.

5. 5. پیوست

مثال پرونده adtech_setup.auto.tfvars

/**
 * Copyright 2023 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

project = "my-project-id"

# Required to generate identity token for access of Adtech Services API endpoints
service_account_token_creator_list = ["user:me@email.com"]

# Uncomment the below line if you like Terraform to create an Artifact registry repository
# for self-build container artifacts. "artifact_repo_location" defaults to "us".
artifact_repo_name     = "my-ags-artifacts"

# Note: Either one of [1] or [2] must be uncommented.

# [1] Uncomment below lines if you like Terraform grant needed permissions to
# pre-existing service accounts
# deploy_service_account_email = "<YourDeployServiceAccountName>@<ProjectID>.iam.gserviceaccount.com"
# worker_service_account_email = "<YourWorkerServiceAccountName>@<ProjectID>.iam.gserviceaccount.com"

# [2] Uncomment below lines if you like Terraform to create service accounts
# and needed permissions granted e.g "deploy-sa" or "worker-sa"
deploy_service_account_name = "deploy-sa"
worker_service_account_name = "worker-sa"
# Uncomment the below line if you want Terraform to create the
# below bucket. "data_bucket_location" defaults to "us".
data_bucket_name     = "my-ags-data"

# Uncomment the below lines if you want to specify service account customer role names
# deploy_sa_role_name = "<YourDeploySACustomRole>"
# worker_sa_role_name = "<YourWorkerSACustomRole>"

مثال dev.auto.tfvars

/**
 * Copyright 2022 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

# Example values required by job_service.tf
#
# These values should be modified for each of your environments.
region      = "us-central1"
region_zone = "us-central1-c"

project_id  = "my-project-id"
environment = "operator-demo-env"

# Co-locate your Cloud Spanner instance configuration with the region above.
# https://cloud.google.com/spanner/docs/instance-configurations#regional-configurations
spanner_instance_config = "regional-us-central1"

# Adjust this based on the job load you expect for your deployment.
# Monitor the spanner instance utilization to decide on scale out / scale in.
# https://console.cloud.google.com/spanner/instances
spanner_processing_units = 100

# Uncomment the line below at your own risk to disable Spanner database protection.
# This needs to be set to false and applied before destroying all resources is possible.
spanner_database_deletion_protection = false

instance_type = "n2d-standard-8" # 8 cores, 32GiB

# Container image location that packages the job service application
# If not set otherwise, uncomment and edit the line below:
#worker_image = "<location>/<project>/<repository>/<image>:<tag or digest>"

# Service account created and onboarded for worker
user_provided_worker_sa_email = "worker-sa@my-project-id.iam.gserviceaccount.com"

min_worker_instances = 1
max_worker_instances = 20