تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

العمل مع خدمة التجميع في Google Cloud Platform (GCP)

1. 1. المتطلبات الأساسية

الوقت المقدَّر لإنهاء الإجراء: من ساعة إلى ساعتَين

هناك وضعان لتنفيذ هذا الدليل التعليمي حول الرموز البرمجية: الاختبار على الجهاز أو خدمة التجميع. يتطلب وضع "الاختبار على الجهاز فقط" جهاز كمبيوتر محلي ومتصفّح Chrome (بدون إنشاء/استخدام موارد Google Cloud). يتطلّب وضع "خدمة تجميع البيانات" نشر "خدمة تجميع البيانات" بالكامل على Google Cloud.

لتنفيذ هذا الدليل التعليمي حول الرموز البرمجية في أيّ من الوضعَين، يجب استيفاء بعض المتطلبات الأساسية. يتم وضع علامة على كل شرط وفقًا لما إذا كان مطلوبًا للاختبار على الجهاز أو خدمة التجميع.

1-1- إكمال عملية التسجيل والإقرار (خدمة تجميع البيانات)

لاستخدام واجهات برمجة تطبيقات "مبادرة حماية الخصوصية"، تأكَّد من إكمال التسجيل والإثبات لكلٍّ من Chrome وAndroid.

1.2. تفعيل واجهات برمجة التطبيقات المتعلّقة بالخصوصية في عرض الإعلانات (خدمة الاختبار المحلي والتجميع)

بما أنّنا سنستخدم "مبادرة حماية الخصوصية"، ننصحك بتفعيل واجهات برمجة التطبيقات لإعلانات "مبادرة حماية الخصوصية".

في المتصفّح، انتقِل إلى chrome://settings/adPrivacy وفعِّل جميع واجهات برمجة التطبيقات المتعلّقة بالخصوصية في عرض الإعلانات.

تأكَّد أيضًا من تفعيل ملفات تعريف الارتباط التابعة لجهات خارجية.

من chrome://settings/cookies، تأكّد من عدم حظر ملفات تعريف الارتباط التابعة لجهات خارجية. استنادًا إلى إصدار Chrome، قد تظهر لك خيارات مختلفة في قائمة الإعدادات هذه، ولكن تشمل الإعدادات المقبولة ما يلي:

"حظر جميع ملفات تعريف الارتباط التابعة لجهات خارجية" = غير مفعَّل
"حظر ملفات تعريف الارتباط التابعة لجهات خارجية" = غير مفعَّل
"حظر ملفات تعريف الارتباط التابعة لجهات خارجية في وضع التصفّح المتخفي" = مفعَّل

تفعيل ملفات تعريف الارتباط

1.3. تنزيل أداة الاختبار على الجهاز (الاختبار على الجهاز)

سيتطلب الاختبار على الجهاز تنزيل "أداة الاختبار على الجهاز". ستنشئ الأداة تقارير تلخيصية من تقارير تصحيح الأخطاء غير المشفّرة.

تتوفّر أداة "الاختبار على الجهاز فقط" للتنزيل في أرشيفات JAR لوظائف Cloud في GitHub. يجب تسميتها LocalTestingTool_{version}.jar.

1.4. التأكّد من تثبيت JAVA JRE (خدمة الاختبار المجمّع على الجهاز)

افتح "وحدة التحكّم الطرفية" واستخدِم java --version للتحقّق مما إذا كان جهازك مزوّدًا بإصدار Java أو openJDK.

التحقّق من إصدار Java

إذا لم يكن مثبّتًا، يمكنك تنزيله وتثبيته من موقع Java الإلكتروني أو موقع openJDK الإلكتروني.

1.5. تنزيل aggregatable_report_converter (خدمة الاختبار المحلي والتجميع)

يمكنك تنزيل نسخة من aggregatable_report_converter من مستودع GitHub الخاص بعروض "مبادرة حماية الخصوصية". يشير مستودع GitHub إلى استخدام IntelliJ أو Eclipse، ولكن لا يُشترط استخدام أي منهما. إذا كنت لا تستخدم هذه الأدوات، يمكنك تنزيل ملف JAR إلى بيئتك المحلية بدلاً من ذلك.

1.6. إعداد بيئة Google Cloud Platform (خدمة تجميع البيانات)

تتطلّب "خدمة التجميع" استخدام بيئة تنفيذ موثوقة تستخدم مقدّم خدمة السحابة الإلكترونية. في هذا الدرس التطبيقي حول الترميز، سيتم نشر "خدمة التجميع" في Google Cloud Platform، ولكن تتوفّر أيضًا خدمة AWS.

اتّبِع تعليمات النشر في GitHub لإعداد gcloud CLI وتنزيل وحدات وثنائيات Terraform وإنشاء موارد Google Cloud Platform لخدمة التجميع.

الخطوات الرئيسية في تعليمات النشر:

إعداد واجهة سطر الأوامر "gcloud" وTerraform في بيئتك
أنشئ حزمة Cloud Storage لتخزين حالة Terraform.
تنزيل التبعيات
عدِّل adtech_setup.auto.tfvars وشغِّل adtech_setup Terraform. اطّلِع على الملحق للحصول على مثال على ملف adtech_setup.auto.tfvars. دوِّن اسم حزمة البيانات التي تم إنشاؤها هنا، وسيتم استخدامها في ورشة رموز البرامج لتخزين الملفات التي ننشئها.
عدِّل dev.auto.tfvars وانتحل هوية حساب الخدمة المخصّص للنشر، ثم نفِّذ dev Terraform. اطّلِع على الملحق للحصول على مثال على ملف dev.auto.tfvars.
بعد اكتمال عملية النشر، انسخ frontend_service_cloudfunction_url من ناتج Terraform، والذي سيكون مطلوبًا لتقديم طلبات إلى خدمة التجميع في الخطوات اللاحقة.

1.7. إكمال عملية إعداد "خدمة تجميع البيانات" (Aggregation Service)

تتطلّب خدمة التجميع إعداد المنسقين لاستخدام الخدمة. أكمِل نموذج إعداد خدمة التجميع من خلال تقديم موقعك الإلكتروني لإعداد التقارير ومعلومات أخرى، واختيار "Google Cloud"، وإدخال عنوان حساب الخدمة. يتم إنشاء حساب الخدمة هذا في الشرط المسبق السابق (1.6. إعداد بيئة على Google Cloud Platform (ملاحظة: في حال استخدام الأسماء التلقائية المقدَّمة، سيبدأ حساب الخدمة هذا بالرمز "worker-sa@").

يُرجى الانتظار لمدة تصل إلى أسبوعَين لإكمال عملية الإعداد.

1.8. تحديد طريقة استدعاء نقاط نهاية واجهة برمجة التطبيقات (خدمة التجميع)

يوفّر هذا الدليل التعليمي خيارَين للاتّصال بنقطتَي نهاية واجهة برمجة التطبيقات لخدمة التجميع: cURL وPostman. وتعدّ cURL الطريقة الأسرع والأسهل للاتّصال بنقطتَي نهاية واجهة برمجة التطبيقات من Terminal، لأنّها تتطلّب الحد الأدنى من الإعدادات ولا تتطلّب أي برامج إضافية. ومع ذلك، إذا كنت لا تريد استخدام cURL، يمكنك بدلاً من ذلك استخدام Postman لتنفيذ طلبات واجهة برمجة التطبيقات وحفظها لاستخدامها في المستقبل.

في القسم 3.2. استخدام خدمة التجميع، حيث ستجد تعليمات تفصيلية لاستخدام كلا الخيارَين يمكنك معاينتها الآن لتحديد الطريقة التي ستستخدمها. إذا اخترت Postman، نفِّذ الإعداد الأوّلي التالي.

1.8.1. إعداد مساحة العمل

اشترِك للحصول على حساب على Postman. بعد الاشتراك، يتم إنشاء مساحة عمل لك تلقائيًا.

Postman Workspace

إذا لم يتم إنشاء مساحة عمل لك، انتقِل إلى عنصر التنقّل العلوي "مساحات العمل" واختَر "إنشاء مساحة عمل".

اختَر "مساحة عمل فارغة"، وانقر على "التالي" وأدخِل اسمًا لها "مبادرة خصوصية Google Cloud Platform". اختَر "شخصية" وانقر على "إنشاء".

نزِّل إعدادات JSON وملفات البيئة الشاملة لمساحة العمل التي تم ضبطها مسبقًا.

استورِد كلا ملفي JSON إلى "مساحة عملي" من خلال الزر "استيراد".

زر الاستيراد

سيؤدي ذلك إلى إنشاء مجموعة "مبادرة حماية الخصوصية في Google Cloud Platform" نيابةً عنك، بالإضافة إلى طلبات HTTP createJob وgetJob.

1.8.2. إعداد التفويض

انقر على مجموعة "مبادرة حماية الخصوصية في Google Cloud Platform" وانتقِل إلى علامة التبويب "تفويض".

زر التفويض

ستستخدم طريقة "Bearer Token". من بيئة Terminal، نفِّذ هذا الأمر وانسخ النتيجة.

gcloud auth print-identity-token

بعد ذلك، ألصِق قيمة الرمز المميّز هذه في حقل "الرمز المميّز" ضمن علامة تبويب التفويض في Postman:

حقل الرمز المميّز

1.8.3. إعداد البيئة

انتقِل إلى "نظرة سريعة على البيئة" في أعلى يسار الشاشة:

زر "البيئة"

انقر على "تعديل" وعدِّل "القيمة الحالية" لكل من "environment" و"region" و "cloud-function-id":

ضبط القيم الحالية

يمكنك ترك "request-id" فارغًا في الوقت الحالي، لأنّنا سنملؤه لاحقًا. بالنسبة إلى الحقول الأخرى، استخدِم القيم الواردة في frontend_service_cloudfunction_url، والتي تم عرضها بعد إكمال عملية نشر Terraform بنجاح في المتطلّبات الأساسية 1.6. يتّبع عنوان URL التنسيق التالي: https://--frontend-service--uc.a.run.app

2. 2. درس تطبيقي حول الاختبار على الجهاز

الوقت المقدّر لإنهاء الدرس: أقل من ساعة

يمكنك استخدام أداة الاختبار على الجهاز لإجراء التجميع وإنشاء تقارير تلخيصية باستخدام تقارير تصحيح الأخطاء غير المشفّرة. قبل البدء، تأكَّد من إكمال جميع المتطلّبات الأساسية التي تحمل التصنيف "الاختبار على الجهاز فقط".

خطوات الدرس التطبيقي حول الترميز

الخطوة 2.1: بدء التقرير: شغِّل ميزة إعداد تقارير التجميع الخاص لتتمكّن من جمع التقرير.

الخطوة 2.2: إنشاء تقرير تصحيح الأخطاء بتنسيق AVRO: تحويل تقرير JSON الذي تم جمعه إلى تقرير بتنسيق AVRO ستكون هذه الخطوة مشابهة لما يحدث عندما تجمع تكنولوجيات الإعلان التقارير من نقاط نهاية إعداد التقارير في واجهة برمجة التطبيقات وتحوّل تقارير JSON إلى تقارير بتنسيق AVRO.

الخطوة 2.3: استرداد مفاتيح الحِزم: يتم تصميم مفاتيح الحِزم من قِبل تكنولوجيات الإعلان. في هذا الدليل التعليمي، بما أنّ الحِزم محدّدة مسبقًا، يمكنك استرداد مفاتيح الحِزم كما هو موضح.

الخطوة 2.4: إنشاء ملف AVRO لنطاق الإخراج: بعد استرداد مفاتيح الحزمة، أنشئ ملف AVRO لنطاق الإخراج.

الخطوة 2.5: إنشاء تقرير تلخيصي: استخدِم "أداة الاختبار على الجهاز" لتتمكّن من إنشاء تقارير تلخيصية في "البيئة المحلية".

الخطوة 2.6: مراجعة التقارير التلخيصية: راجِع التقرير التلخيصي الذي أنشأته "أداة الاختبار على الجهاز".

2.1. تقرير العامل المشغّل

لبدء تقرير تجميع خاص، يمكنك استخدام الموقع الإلكتروني التجريبي لـ "مبادرة حماية الخصوصية" (https://privacy-sandbox-demos-news.dev/?env=gcp) أو موقعك الإلكتروني (مثل https://adtechexample.com). إذا كنت تستخدم موقعك الإلكتروني ولم تكمل عملية إعداد خدمة التسجيل والإثبات و"خدمة التجميع "، عليك استخدام علامة Chrome ومفتاح تبديل سطر الأوامر.

في هذا العرض التوضيحي، سنستخدم الموقع الإلكتروني التجريبي لـ "مبادرة حماية الخصوصية". اتّبِع الرابط للانتقال إلى الموقع الإلكتروني، ثم يمكنك الاطّلاع على التقارير على الرابط chrome://private-aggregation-internals:

صفحة "الميزات الداخلية في Chrome"

يمكن أيضًا العثور على التقرير الذي يتم إرساله إلى نقطة نهاية {reporting-origin}/.well-known/private-aggregation/debug/report-shared-storage في "نص التقرير" للتقارير المعروضة في صفحة "معلومات Chrome الداخلية".

قد تظهر لك العديد من التقارير هنا، ولكن في هذا الدليل التعليمي حول رموز البرامج، استخدِم التقرير القابل للتجميع والمخصّص لخدمة Google Cloud Platform والذي يتم إنشاؤه من خلال نقطة نهاية تصحيح الأخطاء. سيحتوي "عنوان URL للتقرير" على "‎/debug/" وسيحتوي aggregation_coordinator_origin field من "نص التقرير" على عنوان URL التالي: https://publickeyservice.msmt.gcp.privacysandboxservices.com.

تقرير تصحيح الأخطاء في Google Cloud Platform

2.2. إنشاء تقرير قابل للتجميع عن تصحيح الأخطاء

انسخ التقرير المتوفّر في "نص التقرير" ضمن chrome://private-aggregation-internals وأنشئ ملف JSON في مجلد privacy-sandbox-demos/tools/aggregatable_report_converter/out/artifacts/aggregatable_report_converter_jar (ضمن المستودع الذي تم تنزيله في المتطلّبات الأساسية 1.5).

في هذا المثال، سنستخدم vim لأنّنا نستخدم نظام التشغيل Linux. ويمكنك استخدام أي محرِّر نصوص تريده.

vim report.json

الصِق التقرير في report.json واحفظ ملفك.

ملف JSON الخاص بالتقرير

بعد الحصول على ذلك، استخدِم aggregatable_report_converter.jar للمساعدة في إنشاء تقرير تجميعي لتصحيح الأخطاء. سيؤدي ذلك إلى إنشاء تقرير قابل للتجميع باسم report.avro في الدليل الحالي.

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

2.3. استرداد مفتاح الحزمة من التقرير

لإنشاء ملف output_domain.avro، تحتاج إلى مفاتيح الحزمة التي يمكن استرجاعها من التقارير.

يتم تصميم مفاتيح الحِزم من قِبل تكنولوجيا الإعلان. في هذه الحالة، ينشئ الموقع الإلكتروني الإصدار التجريبي من "مبادرة حماية الخصوصية" مفاتيح الحِزم. بما أنّ التجميع الخاص لهذا الموقع الإلكتروني في وضع تصحيح الأخطاء، يمكننا استخدام debug_cleartext_payload من "نص التقرير" للحصول على مفتاح الحزمة.

يُرجى نسخ debug_cleartext_payload من نص التقرير.

تصحيح أخطاء الحمولة النصية غير المشفّرة

افتح goo.gle/ags-payload-decoder والصق debug_cleartext_payload في مربّع "الإدخال" وانقر على "فك التشفير".

زر فك التشفير

تعرض الصفحة القيمة العشرية لمفتاح الحزمة. في ما يلي نموذج لمفتاح حزمة.

مفتاح الحزمة

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 بعد اكتمال هذه العملية.

إخراج AVRO

2.6. مراجعة التقرير الموجز

يكون التقرير الملخّص الذي يتم إنشاؤه بتنسيق AVRO. لتتمكّن من قراءة هذا الملف، عليك تحويله من تنسيق AVRO إلى تنسيق JSON. من المفترض أن تكتب تكنولوجيا الإعلان رمزًا لتحويل تقارير AVRO إلى تنسيق JSON.

سنستخدم aggregatable_report_converter.jar لتحويل تقرير AVRO مرة أخرى إلى تنسيق JSON.

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

يؤدي ذلك إلى عرض تقرير مشابه لما يلي. بالإضافة إلى تقرير output.json تم إنشاؤه في المجلد نفسه.

إخراج ملف JSON

اكتمال الدرس التطبيقي حول الترميز

الملخّص: لقد جمعت تقرير تصحيح أخطاء، وأنشأت ملف نطاق إخراج، وأنشأت تقريرًا تلخيصيًا باستخدام أداة الاختبار المحلي التي تحاكي سلوك التجميع في "خدمة التجميع".

الخطوات التالية: بعد تجربة أداة "الاختبار على الجهاز فقط"، يمكنك تجربة التمرين نفسه من خلال نشر "خدمة التجميع" مباشرةً في بيئتك. راجِع المتطلبات الأساسية للتأكّد من أنّك أعددت كل شيء لتطبيق وضع "خدمة التجميع"، ثم انتقِل إلى الخطوة 3.

3- 3- الدرس التطبيقي حول خدمة تجميع البيانات

الوقت المقدّر لإنهاء الدرس: ساعة واحدة

قبل البدء، تأكَّد من إكمال جميع المتطلّبات الأساسية المُصنَّفة بـ "خدمة التجميع".

خطوات الدرس التطبيقي حول الترميز

الخطوة 3.1: إنشاء إدخالات "خدمة تجميع البيانات": أنشئ تقارير "خدمة تجميع البيانات" التي يتم تجميعها في حِزم لخدمة "تجميع البيانات".

الخطوة 3.1.1: تقرير المشغّل
الخطوة 3.1.2: جمع التقارير القابلة للتجميع
الخطوة 3.1.3: تحويل التقارير إلى AVRO
الخطوة 3.1.4: إنشاء output_domain AVRO
الخطوة 3.1.5: نقل التقارير إلى حزمة Cloud Storage

الخطوة 3.2: استخدام "خدمة تجميع البيانات": استخدِم Aggregation Service API لإنشاء "التقارير التلخيصية" ومراجعتها.

الخطوة 3.2.1: استخدام نقطة نهاية createJob لإجراء عمليات الأركان الأساسية
الخطوة 3.2.2: استخدام نقطة نهاية getJob لاسترداد حالة الدُفعة
الخطوة 3.2.3: مراجعة التقرير الموجز

3.1. إنشاء مدخلات خدمة تجميع البيانات

واصِل إنشاء تقارير AVRO لتجميعها في خدمة التجميع. يمكن تنفيذ أوامر Shell الواردة في هذه الخطوات ضمن Cloud Shell في Google Cloud (ما دام قد تم استنساخ التبعيات من "المتطلّبات الأساسية" إلى بيئة Cloud Shell) أو في بيئة تنفيذ محلية.

3.1.1. تقرير المشغّل

اتّبِع الرابط للانتقال إلى الموقع الإلكتروني، ثم يمكنك الاطّلاع على التقارير على الرابط chrome://private-aggregation-internals:

صفحة "الميزات الداخلية في Chrome"

تقرير تصحيح الأخطاء في Google Cloud Platform

3.1.2. جمع التقارير القابلة للتجميع

اجمع تقاريرك القابلة للتجميع من نقاط النهاية ‎ .well-known لواجهة برمجة التطبيقات المقابلة.

التجميع الخاص: {reporting-origin}/.well-known/private-aggregation/report-shared-storage
تقارير تحديد المصدر - التقرير التلخيصي: {reporting-origin}/.well-known/attribution-reporting/report-aggregate-attribution

في هذا الدرس التطبيقي حول الترميز، نجمع التقارير يدويًا. في مرحلة الإنتاج، من المتوقّع أن تجمع تكنولوجيات الإعلان التقارير وتحوّلها آليًا.

لننسخ تقرير JSON في "نص التقرير" من chrome://private-aggregation-internals.

في هذا المثال، نستخدم vim لأنّنا نستخدم نظام التشغيل Linux. ويمكنك استخدام أي محرِّر نصوص تريده.

vim report.json

الصِق التقرير في report.json واحفظ ملفك.

ملف 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، تحتاج إلى مفاتيح الحزمة التي يمكن استرجاعها من التقارير.

يُرجى نسخ debug_cleartext_payload من نص التقرير.

تصحيح أخطاء الحمولة النصية غير المشفّرة

افتح goo.gle/ags-payload-decoder والصق debug_cleartext_payload في مربّع "الإدخال" وانقر على "فك التشفير".

زر فك التشفير

تعرض الصفحة القيمة العشرية لمفتاح الحزمة. في ما يلي نموذج لمفتاح حزمة.

مفتاح الحزمة

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

ينشئ النص البرمجي ملف output_domain.avro في المجلد الحالي.

3.1.5. نقل التقارير إلى حزمة Cloud Storage

بعد إنشاء تقارير AVRO ونطاق الإخراج، انتقِل إلى نقل التقارير ونطاق الإخراج إلى الحزمة في Cloud Storage (التي تم تحديدها في الشرط المسبق 1.6).

إذا كان لديك إعداد واجهة سطر أوامر gcloud في بيئتك المحلية، استخدِم الأوامر التالية لنسخ الملفات إلى المجلدات المقابلة.

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 أنّك اخترت إما cURL أو Postman لتقديم طلبات واجهة برمجة التطبيقات إلى نقاط نهاية "خدمة التجميع". يمكنك الاطّلاع أدناه على تعليمات لكلا الخيارَين.

إذا تعذّر إكمال المهمة بسبب خطأ، يمكنك الاطّلاع على مستندات تحديد المشاكل وحلّها في GitHub للحصول على مزيد من المعلومات حول كيفية المتابعة.

3.2.1. استخدام نقطة نهاية `createJob` لإجراء عمليات مجمّعة

استخدِم تعليمات cURL أو Postman أدناه لإنشاء وظيفة.

cURL

في "وحدة التحكّم"، أنشئ ملفًا لنص الطلب (body.json) والصقه في ما يلي. احرص على تعديل قيم العناصر النائبة. راجِع مستندات واجهة برمجة التطبيقات هذه للحصول على مزيد من المعلومات حول ما يمثّله كلّ حقل.

ملاحظة: ننصحك باستخدام reporting_site المحدّد في job_parameters بدلاً من attribution_report_to، إن أمكن. تم تحديد الحقل attribution_report_to لإيقافه نهائيًا في ترقية الإصدار الرئيسي التالي لواجهة برمجة التطبيقات لخدمة التجميع. (مزيد من المعلومات) تسمح المَعلمة reporting_site بمصادر متعددة ضمن نطاق واحد تم نشره، في حين تتيح attribution_report_to مصدر خادم واحد. يمكن أن تكون قيمة السلسلة الصالحة لسمة reporting_site هي https://example-dsp-host.com، ما سيشمل مصادر إعداد التقارير، مثل https://dspp-a.example-dsp-host.com أو https://dspp-b.example-dsp-host.com. من ناحية أخرى، يمكن أن يكون مثال على قيمة attribution_report_to هو https://dsp-a.example-dsp-host.com أو https://privacy-sandbox-demos-dsp.dev. يُرجى العلم أنّ المواقع الإلكترونية التي أرسلت تقاريرها هي المواقع الإلكترونية التي قدّمتها أثناء إعداد "خدمة التجميع" (شرط أساسي 1.7). (على سبيل المثال: "https://privacy-sandbox-demos-dsp.dev")

{
  "job_request_id": "<job_request_id>",
  "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
  "input_data_bucket_name": "<bucket_name>",
  "output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
  "output_data_bucket_name": "<bucket_name>",
  "job_parameters": {
    "output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
    "output_domain_bucket_name": "<bucket_name>",
    "attribution_report_to": "<reporting origin of report>",
    "reporting_site": "<domain of reporting origin(s) of report>", // Only one of attribution_report_to or reporting_site is required as of v2.7.0
    "report_error_threshold_percentage": "10",
    "debug_run": "true"
  }
}

نفِّذ الطلب أدناه. استبدِل العناصر النائبة في عنوان 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 بعد قبول الطلب من قِبل "خدمة التجميع". يمكنك الاطّلاع على رموز الاستجابة المحتملة الأخرى في مواصفات واجهة برمجة التطبيقات.

Postman

بالنسبة إلى نقطة النهاية createJob، يجب تقديم محتوى الطلب من أجل تزويد "خدمة التجميع" بأسماء الملفات والموقع الجغرافي للتقارير القابلة للتجميع ونطاقات الإخراج والتقارير التلخيصية.

انتقِل إلى علامة التبويب "النص" لطلب createJob:

علامة التبويب "النص"

استبدِل العناصر النائبة في ملف JSON المقدَّم. لمزيد من المعلومات حول هذه الحقول وما تمثله، يُرجى الرجوع إلى مستندات واجهة برمجة التطبيقات.

{
  "job_request_id": "<job_request_id>",
  "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
  "input_data_bucket_name": "<bucket_name>",
  "output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
  "output_data_bucket_name": "<bucket_name>",
  "job_parameters": {
    "output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
    "output_domain_bucket_name": "<bucket_name>",
    "attribution_report_to": "<reporting origin of report>",
    "reporting_site": "<domain of reporting origin(s) of report>", // Only one of attribution_report_to or reporting_site is required as of v2.7.0
    "report_error_threshold_percentage": "10",
    "debug_run": "true"
  }
}

"أرسِل" طلب واجهة برمجة التطبيقات createJob:

يمكن العثور على رمز الردّ في النصف السفلي من الصفحة:

رمز الاستجابة

من المفترض أن يصلك استجابة HTTP 202 بعد قبول الطلب من خلال "خدمة التجميع". يمكنك الاطّلاع على رموز الاستجابة المحتملة الأخرى في مواصفات واجهة برمجة التطبيقات.

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 (إذا حدث خطأ في المهمة).

Postman

للتحقّق من حالة طلب المهمة، يمكنك استخدام نقطة النهاية getJob. في قسم "المَعلمات" من طلب getJob، عدِّل قيمة job_request_id إلى job_request_id التي تم إرسالها في طلب createJob.

معرّف طلب الوظيفة

"أرسِل" طلب getJob:

زر الإرسال

استجابة JSON

3.2.3. مراجعة التقرير الموجز

بعد تلقّي التقرير الملخّص في حزمة الإخراج على Cloud Storage، يمكنك تنزيله إلى بيئتك المحلية. تكون التقارير التلخيصية بتنسيق 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: يتوفّر مفتاح الحزمة داخل ملف AVRO output_domain.

اكتمال الدرس التطبيقي حول الترميز

الملخّص: لقد تم نشر "خدمة التجميع" في بيئة السحابة الإلكترونية الخاصة بك، وجمع تقرير تصحيح الأخطاء، وإنشاء ملف نطاق إخراج، وتخزين هذه الملفات في حزمة Cloud Storage، وتنفيذ مهمة ناجحة.

الخطوات التالية: يمكنك مواصلة استخدام "خدمة التجميع" في بيئتك، أو حذف موارد السحابة الإلكترونية التي أنشأتها للتو باتّباع تعليمات التنظيف الواردة في الخطوة 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

لحذف حزمة 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

العمل مع خدمة التجميع في Google Cloud Platform (GCP)

1. 1. المتطلبات الأساسية

1-1- إكمال عملية التسجيل والإقرار (خدمة تجميع البيانات)

1.2. تفعيل واجهات برمجة التطبيقات المتعلّقة بالخصوصية في عرض الإعلانات (خدمة الاختبار المحلي والتجميع)

1.3. تنزيل أداة الاختبار على الجهاز (الاختبار على الجهاز)

1.4. التأكّد من تثبيت JAVA JRE (خدمة الاختبار المجمّع على الجهاز)

1.5. تنزيل aggregatable_report_converter (خدمة الاختبار المحلي والتجميع)

1.6. إعداد بيئة Google Cloud Platform (خدمة تجميع البيانات)

1.7. إكمال عملية إعداد "خدمة تجميع البيانات" (Aggregation Service)

1.8. تحديد طريقة استدعاء نقاط نهاية واجهة برمجة التطبيقات (خدمة التجميع)

1.8.1. إعداد مساحة العمل

1.8.2. إعداد التفويض

1.8.3. إعداد البيئة

2. 2. درس تطبيقي حول الاختبار على الجهاز

خطوات الدرس التطبيقي حول الترميز

2.1. تقرير العامل المشغّل

2.2. إنشاء تقرير قابل للتجميع عن تصحيح الأخطاء

2.3. استرداد مفتاح الحزمة من التقرير

2.4. إنشاء نطاق الإخراج بتنسيق AVRO

2.5. إنشاء تقارير تلخيصية باستخدام "أداة الاختبار على الجهاز"

2.6. مراجعة التقرير الموجز

3- 3- الدرس التطبيقي حول خدمة تجميع البيانات

خطوات الدرس التطبيقي حول الترميز

3.1. إنشاء مدخلات خدمة تجميع البيانات

3.1.1. تقرير المشغّل

3.1.2. جمع التقارير القابلة للتجميع

3.1.3. تحويل التقارير إلى AVRO

3.1.4. إنشاء output_domain AVRO

3.1.5. نقل التقارير إلى حزمة Cloud Storage

3.2. استخدام خدمة تجميع البيانات

3.2.1. استخدام نقطة نهاية createJob لإجراء عمليات مجمّعة

cURL

Postman

3.2.2. استخدام نقطة نهاية getJob لاسترداد حالة الدُفعة

cURL

Postman

3.2.3. مراجعة التقرير الموجز

4. 4. الإزالة

5- 5- الملحق

مثال على ملف adtech_setup.auto.tfvars

مثال على ملف dev.auto.tfvars

3.2.1. استخدام نقطة نهاية `createJob` لإجراء عمليات مجمّعة

3.2.2. استخدام نقطة نهاية `getJob` لاسترداد حالة الدُفعة

مثال على ملف `adtech_setup.auto.tfvars`

مثال على ملف `dev.auto.tfvars`