کار با سرویس تجمیع در Google Cloud Platform (GCP)

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

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

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

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

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

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

1.2. فعال کردن Privacy Sandbox API (سرویس آزمایش و تجمع محلی)

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

در مرورگر خود به chrome://flags/#privacy-sandbox-ads-apis بروید و Privacy Sandbox APIs را فعال کنید.

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

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

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

برای اعمال این امر باید 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 دانلود کنید.

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

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

1.6.1. گسترش

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

نکته مهم: برای استقرار سرویس به مجوزهای خاصی نیاز دارید. برای این آزمایشگاه کد، اطمینان حاصل کنید که کاربر دارای مجوز دسترسی سرپرست / مالک در پروژه GCP است.

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

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.6.2. سطل گزارش

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

gcloud storage buckets create gs://<bucket-name> --location=<location>

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 https:// - -frontend-service- -uc.a.run.app https:// - -frontend-service- -uc.a.run.app 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.

توجه: اگر گزارش اشکال‌زدایی مانند آنچه در بالا نشان داده شده است نمی‌بینید، صفحه نمایشی Privacy Sandbox را بازخوانی کنید، سپس صفحه داخلی Chrome را بازخوانی کنید. باید گزارش‌های بیشتری را ببینید، از جمله گزارش‌هایی که توسط نقطه پایانی اشکال‌زدایی ایجاد شده است. اگر نه، دوباره بررسی کنید که کوکی های شخص ثالث فعال هستند.

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

گزارش یافت شده در "گزارش بدن" chrome://private-aggregation-internals کپی کنید و یک فایل JSON در پوشه privacy-sandbox-demos/tools/aggregatable_report_converter/out/artifacts/aggregatable_report_converter_jar ایجاد کنید (در داخل مخزن پیش نیاز دانلود شده 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 طراحی شده اند. با این حال، در این مورد، سایت 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 که در همان دایرکتوری ایجاد شده است.

3. 3. Codelab سرویس تجمع

زمان تخمینی برای تکمیل: 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.

توجه: اگر گزارش اشکال‌زدایی مانند آنچه در بالا نشان داده شده است نمی‌بینید، صفحه نمایشی Privacy Sandbox را بازخوانی کنید، سپس صفحه داخلی Chrome را بازخوانی کنید. باید گزارش‌های بیشتری را ببینید، از جمله گزارش‌هایی که توسط نقطه پایانی اشکال‌زدایی ایجاد شده است. اگر نه، دوباره بررسی کنید که کوکی های شخص ثالث فعال هستند.

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

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

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

حلقه

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

توجه: attribution_report_to مبدأ است که «سایت گزارش فناوری آگهی» نیز نامیده می‌شود، که در هنگام نصب سرویس تجمیع (پیش‌نیاز 1.7) نصب شد.

{
  "job_request_id": "<job_request_id>",
  "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
  "input_data_bucket_name": "<bucket_name>",
  "output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
  "output_data_bucket_name": "<bucket_name>",
  "job_parameters": {
    "output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
    "output_domain_bucket_name": "<bucket_name>",
    "attribution_report_to": "<reporting origin of report>",
    "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 مراجعه کنید.

توجه: attribution_report_to مبدأ است که «سایت گزارش فناوری آگهی» نیز نامیده می‌شود، که در هنگام نصب سرویس تجمیع (پیش‌نیاز 1.7) نصب شد.

{
  "job_request_id": "<job_request_id>",
  "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
  "input_data_bucket_name": "<bucket_name>",
  "output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
  "output_data_bucket_name": "<bucket_name>",
  "job_parameters": {
    "output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
    "output_domain_bucket_name": "<bucket_name>",
    "attribution_report_to": "<reporting origin of report>",
    "report_error_threshold_percentage": "10",
    "debug_run": "true"
  }
}

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

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

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

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

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

حلقه

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

توجه: گزارشی که ما برای این آزمایشگاه کد استفاده می‌کنیم با منبع گزارش سایت نمایشی Privacy Sandbox مرتبط است. با این حال، هنگامی که برای استفاده از سرویس تجمیع در محیط GCP خود سوار شدید، منبع گزارش خود را ارائه کردید. از آنجایی که این گزارش از سایتی متفاوت از سایتی است که در آن نصب شده است، ممکن است پاسخی با return_code PRIVACY_BUDGET_AUTHORIZATION_ERROR دریافت کنید. این مورد انتظار است و می توان آن را نادیده گرفت.

پستچی

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

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

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

توجه: گزارشی که ما برای این آزمایشگاه کد استفاده می‌کنیم با منبع گزارش سایت نمایشی Privacy Sandbox مرتبط است. با این حال، هنگامی که برای استفاده از سرویس تجمیع در محیط GCP خود سوار شدید، منبع گزارش خود را ارائه کردید. از آنجایی که این گزارش از سایتی متفاوت از سایتی است که در آن نصب شده است، ممکن است پاسخی با return_code PRIVACY_BUDGET_AUTHORIZATION_ERROR دریافت کنید. این مورد انتظار است و می توان آن را نادیده گرفت.

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

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:[e-mail]"]

# 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 = "[e-mail]"

min_worker_instances = 1
max_worker_instances = 20