العمل باستخدام "خدمة التجميع" على AWS

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

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

1-1- تنزيل "أداة الاختبار المحلّي" (الاختبار المحلّي)

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

يمكن تنزيل أداة "الاختبار المحلي" من أرشيفات Lambda JAR في Github. يجب تسميته LocalTestingTool_{version}.jar.

1.2. التأكّد من تثبيت JAVA JRE (خدمة الاختبار والتجميع المحلية)

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

التحقّق من إصدار Java JRE باستخدام الأمر ‎ `java --version`‎ التحقّق من إصدار Java JRE باستخدام الأمر `java --version`.

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

1.3. تنزيل أداة تحويل التقارير القابلة للتجميع (الاختبار المحلي وخدمة تجميع البيانات)

يمكنك تنزيل نسخة من أداة تحويل التقارير القابلة للتجميع من مستودع GitHub الخاص بعروض Privacy Sandbox التوضيحية.

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

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

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

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

إعدادات ملفات تعريف الارتباط الخارجية في Chrome إعدادات ملفات تعريف الارتباط الخارجية في Chrome

1.5. التسجيل على الويب وAndroid (خدمة تجميع البيانات)

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

لإجراء الاختبارات المحلية، يمكن إيقاف التسجيل باستخدام علامة Chrome وخيار CLI.

لاستخدام ميزة تجريبية في Chrome في العرض التوضيحي، انتقِل إلى chrome://flags/#privacy-sandbox-enrollment-overrides وعدِّل الإعداد التلقائي باستخدام موقعك الإلكتروني، أو إذا كنت ستستخدم موقعنا الإلكتروني التجريبي، لن تحتاج إلى إجراء أي تعديل.

علم Chrome لتجاوز التسجيل في "مبادرة حماية الخصوصية" علم Chrome لتجاوز التسجيل في "مبادرة حماية الخصوصية"

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

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

‫1.7. مقدّم خدمات السحابة الإلكترونية (خدمة تجميع البيانات)

تتطلّب "خدمة التجميع" استخدام "بيئة تنفيذ موثوقة" تستخدم بيئة سحابية. تتوفّر خدمة التجميع على Amazon Web Services ‏ (AWS) وGoogle Cloud ‏ (GCP). سيتناول هذا الدرس التطبيقي حول الترميز عملية الدمج مع AWS فقط.

توفّر AWS بيئة تنفيذ موثوقة تُعرف باسم Nitro Enclaves. تأكَّد من أنّ لديك حسابًا على AWS واتّبِع تعليمات التثبيت والتحديث في واجهة سطر الأوامر من AWS لإعداد بيئة واجهة سطر الأوامر من AWS.

إذا كان AWS CLI جديدًا، يمكنك إعداده باستخدام تعليمات إعداد CLI.

1.7.1. إنشاء حزمة AWS S3

أنشئ حزمة AWS S3 لتخزين حالة Terraform، وحزمة S3 أخرى لتخزين التقارير والتقارير الموجزة. يمكنك استخدام أمر واجهة سطر الأوامر المقدَّم. استبدِل الحقل في <> بالمتغيرات المناسبة.

aws s3api create-bucket --bucket <tf_bucket_name> --region us-east-1
aws s3api create-bucket --bucket <report_bucket_name> --region us-east-1

1.7.2. إنشاء مفتاح وصول للمستخدم

أنشئ مفاتيح وصول المستخدم باستخدام دليل AWS. سيتم استخدام هذا المعرّف لاستدعاء نقاط نهاية واجهة برمجة التطبيقات createJob وgetJob التي تم إنشاؤها على AWS.

1.7.3. أذونات المستخدمين والمجموعات في AWS

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

‫1.8. Terraform (خدمة تجميع البيانات)

يستخدم هذا الدرس التطبيقي حول الترميز Terraform لنشر "خدمة تجميع البيانات". تأكَّد من تثبيت ملف Terraform الثنائي في بيئتك المحلية.

نزِّل ملف Terraform الثنائي إلى بيئتك المحلية.

بعد تنزيل ملف Terraform الثنائي، استخرِج الملف وانقُل ملف Terraform الثنائي إلى /usr/local/bin.

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

تأكَّد من توفّر Terraform على مسار الفئة.

terraform -v

‫1.9. Postman (لخدمة تجميع البيانات على AWS)

في هذا الدرس التطبيقي، استخدِم Postman لإدارة الطلبات.

أنشِئ مساحة عمل من خلال الانتقال إلى عنصر التنقّل العلوي مساحات العمل واختَر إنشاء مساحة عمل.

مساحة عمل Postman مساحة عمل Postman

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

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

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

استيراد ملفات JSON من Postman استيراد ملفات JSON الخاصة بـ Postman

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

مجموعة مستورَدة من Postman مجموعة مستورَدة من Postman

عدِّل "مفتاح الوصول" و"المفتاح السري" في AWS من خلال نظرة سريعة على البيئة.

نظرة سريعة على بيئة Postman نظرة سريعة على بيئة Postman

انقر على تعديل وعدِّل "القيمة الحالية" لكلّ من access_key وsecret_key. يُرجى العِلم أنّه سيتم تقديم frontend_api_id في القسم 3.1.4 من هذا المستند. وننصح باستخدام المنطقة us-east-1. ومع ذلك، إذا كنت تريد النشر في منطقة مختلفة، تأكَّد من نسخ AMI التي تم إصدارها إلى حسابك أو إجراء إنشاء ذاتي باستخدام البرامج النصية المتوفّرة.

المتغيّرات العمومية في Postman متغيّرات Postman العمومية تعديل المتغيرات العمومية في Postman تعديل المتغيّرات العمومية في Postman

2. درس تطبيقي حول الترميز عن الاختبار المحلي

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

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

الخطوة 2.1: تقرير المشغّل: يمكنك تشغيل ميزة إعداد التقارير في Private Aggregation API لتتمكّن من جمع التقرير.

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

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

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

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

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

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

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

البيانات الداخلية لعملية التجميع الخاص في Chrome أجزاء التجميع الخاص الداخلية في Chrome

إذا كان تقريرك في حالة "في انتظار المراجعة"، يمكنك اختيار التقرير والنقر على "إرسال التقارير المحدّدة".

إرسال تقرير التجميع الخاص إرسال تقرير التجميع الخاص

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

في chrome://private-aggregation-internals، انسخ "نص التقرير" الذي تم تلقّيه في نقطة النهاية [reporting-origin]/.well-known/private-aggregation/report-shared-storage.

تأكَّد من أنّ aggregation_coordinator_origin في نص التقرير يحتوي على https://publickeyservice.msmt.aws.privacysandboxservices.com، ما يعني أنّ التقرير هو تقرير قابل للتجميع في AWS.

تقرير التجميع الخاص تقرير التجميع الخاص

ضَع "نص التقرير" بتنسيق JSON في ملف JSON. في هذا المثال، يمكنك استخدام vim. يمكنك استخدام أي محرِّر نصوص تريده.

vim report.json

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

ملف 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 من نص التقرير.

تصحيح أخطاء حمولة النص غير المرمّز من نص التقرير تصحيح أخطاء حمولة النص العادي من نص التقرير

افتح أداة فك ترميز حمولة تصحيح الأخطاء في ميزة "التجميع الخاص" والصِق debug_cleartext_payload في مربّع INPUT (الإدخال) وانقر على Decode (فك الترميز).

أداة فك ترميز الحمولة أداة فك ترميز الحمولة

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

نتيجة فك ترميز الحمولة نتيجة فك ترميز الحمولة

‫2.4. إنشاء AVRO لنطاق الإخراج

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

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

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

‫2.5. إنشاء تقارير ملخّصة باستخدام "أداة الاختبار المحلّي"

سنستخدم ملف LocalTestingTool_{version}.jar الذي تم تنزيله في القسم 1.1 لإنشاء التقارير الموجزة. استخدِم الأمر التالي. عليك استبدال LocalTestingTool_{version}.jar بالإصدار الذي تم تنزيله من LocalTestingTool.

نفِّذ الأمر التالي لإنشاء تقرير ملخّص في بيئة التطوير المحلية:

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

من المفترض أن يظهر لك شيء مشابه للصورة التالية بعد تنفيذ الأمر. يتم إنشاء تقرير output.avro بعد اكتمال هذه العملية.

ملف avro لتقرير ملخّص الاختبار المحلي ملف avro لتقرير ملخّص الاختبار المحلي

‫2.6. مراجعة تقرير الملخّص

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

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

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

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

ملف avro الملخّص الذي تم تحويله إلى json ملف avro الخاص بالملخّص تم تحويله إلى json.

افتح ملف JSON في محرِّر من اختيارك لمراجعة التقرير الموجز.

3- تفعيل "خدمة تجميع البيانات"

لنشر "خدمة التجميع"، اتّبِع الخطوات التالية:

الخطوة 3: نشر "خدمة تجميع البيانات": نشر "خدمة تجميع البيانات" على AWS
الخطوة 3.1 إنشاء نسخة طبق الأصل من مستودع Aggregation Service
الخطوة 3.2 تنزيل التبعيات المُنشأة مسبقًا
الخطوة 3.3 إنشاء بيئة تطوير
الخطوة 3.4 نشر "خدمة تجميع البيانات"

‫3.1. إنشاء نسخة طبق الأصل من مستودع Aggregation Service

في بيئتك المحلية، استنسِخ مستودع GitHub الخاص بخدمة التجميع.

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

3.2. تنزيل الطلبات المرتبطة التي تم إنشاؤها مُسبقًا

بعد استنساخ مستودع Aggregation Service، انتقِل إلى مجلد Terraform الخاص بالمستودع وإلى مجلد السحابة الإلكترونية ذي الصلة. إذا كان cloud_provider هو AWS، يمكنك الانتقال إلى /terraform/aws

cd <repository_root>/terraform/aws

في /terraform/aws، نفِّذ download_prebuilt_dependencies.sh.

bash download_prebuilt_dependencies.sh

‫3.3. إنشاء بيئة تطوير

أنشئ بيئة تطوير في /terraform/aws/environments. أنشئ مجلدًا باسم dev.

mkdir dev

انسخ محتويات المجلد demo إلى المجلد dev.

cp -R demo/* dev

انتقِل إلى مجلد dev.

cd dev

عدِّل ملف main.tf واضغط على i ثم input لتعديل الملف.

vim main.tf

أزِل التعليق من الرمز في المربّع الأحمر عن طريق إزالة علامة # وتعديل اسمَي الحزمة والمفتاح.

بالنسبة إلى ملف main.tf في AWS:

ملف tf الرئيسي في AWS ملف tf الرئيسي في AWS

يجب أن يبدو الرمز غير المعلق على النحو التالي.

backend "s3" {
  bucket = "<tf_state_bucket_name>"
  key    = "<environment_name>.tfstate"
  region = "us-east-1"
}

بعد إكمال التعديلات، احفظها واخرج من المحرّر بالضغط على esc -> :wq!. يؤدي ذلك إلى حفظ التعديلات في main.tf.

بعد ذلك، أعد تسمية example.auto.tfvars إلى dev.auto.tfvars.

mv example.auto.tfvars dev.auto.tfvars

عدِّل dev.auto.tfvars واضغط على i من أجل input لتعديل الملف.

vim dev.auto.tfvars

عدِّل الحقول في المربّع الأحمر في الصورة التالية باستخدام مَعلمات AWS ARN الصحيحة التي يتم تقديمها أثناء إعداد "خدمة تجميع البيانات" والبيئة والبريد الإلكتروني الخاص بالإشعارات.

عدِّل ملف tfvars التلقائي الخاص بالمطوّرين. عدِّل ملف tfvars التلقائي الخاص ببيئة التطوير.

بعد الانتهاء من التعديلات، اضغط على esc -> :wq!. سيؤدي ذلك إلى حفظ ملف dev.auto.tfvars، ومن المفترض أن يظهر على النحو الموضّح في الصورة التالية.

تم تعديل ملف tfvars التلقائي الخاص بالمطوّرين. تم تعديل ملف tfvars التلقائي الخاص بالمطوّرين.

‫3.4. نشر "خدمة تجميع البيانات"

لنشر "خدمة التجميع"، عليك تهيئة Terraform في المجلد نفسه /terraform/aws/environments/dev.

terraform init

من المفترض أن يتم عرض نتيجة مشابهة للصورة التالية:

‫Terraform init. Terraform init

بعد إعداد Terraform، أنشئ خطة تنفيذ Terraform. حيث تعرض عدد المراجع التي ستتم إضافتها ومعلومات إضافية أخرى مشابهة للصورة التالية.

terraform plan

يمكنك الاطّلاع في ما يلي على ملخّص "الخطة". إذا كان هذا نشرًا جديدًا، من المفترض أن يظهر لك عدد الموارد التي ستتم إضافتها مع 0 للتغيير و0 للإزالة.

خطة Terraform خطة Terraform

بعد إكمال هذه الخطوة، يمكنك المتابعة لتطبيق Terraform.

terraform apply

بعد أن يُطلب منك تأكيد تنفيذ الإجراءات من خلال Terraform، أدخِل yes في القيمة.

طلب تطبيق Terraform طلب تطبيق Terraform

بعد انتهاء عملية terraform apply، يتم عرض نقاط النهاية التالية لكل من createJob وgetJob. يتم أيضًا عرض frontend_api_id الذي عليك تعديله في Postman في القسم 1.9.

اكتمل تطبيق Terraform. اكتملت عملية تطبيق Terraform.

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

انتقِل إلى إنشاء تقارير AVRO لتجميعها في "خدمة تجميع البيانات".

الخطوة 4: إنشاء مدخلات "خدمة تجميع البيانات": يمكنك إنشاء تقارير "خدمة تجميع البيانات" التي يتم تجميعها في حِزم من أجل "خدمة تجميع البيانات".
الخطوة 4.1. تقرير المشغِّل
الخطوة 4.2 جمع التقارير القابلة للتجميع
الخطوة 4.3 تحويل التقارير إلى AVRO
الخطوة 4.4 إنشاء AVRO لنطاق الإخراج

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

انتقِل إلى الموقع الإلكتروني للعرض التوضيحي لمبادرة حماية الخصوصية. يؤدي ذلك إلى بدء تقرير التجميع الخاص. يمكنك الاطّلاع على التقرير على chrome://private-aggregation-internals.

البيانات الداخلية لعملية التجميع الخاص في Chrome أجزاء التجميع الخاص الداخلية في Chrome

إذا كان تقريرك في حالة "في انتظار المراجعة"، يمكنك اختيار التقرير والنقر على "إرسال التقارير المحدّدة". '

إرسال تقرير التجميع الخاص إرسال تقرير التجميع الخاص

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

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

  • التجميع الخاص
    [reporting-origin] /.well-known/private-aggregation/report-shared-storage
  • Attribution Reporting - تقرير الملخّص
    [reporting-origin] /.well-known/attribution-reporting/report-aggregate-attribution

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

في chrome://private-aggregation-internals، انسخ "نص التقرير" الذي تم تلقّيه في نقطة النهاية [reporting-origin]/.well-known/private-aggregation/report-shared-storage.

تأكَّد من أنّ aggregation_coordinator_origin في نص التقرير يحتوي على https://publickeyservice.msmt.aws.privacysandboxservices.com، ما يعني أنّ التقرير هو تقرير قابل للتجميع في AWS.

تقرير التجميع الخاص تقرير التجميع الخاص

ضَع "نص التقرير" بتنسيق JSON في ملف JSON. في هذا المثال، يمكنك استخدام vim. يمكنك استخدام أي محرِّر نصوص تريده.

vim report.json

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

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

4.3. تحويل التقارير إلى تنسيق AVRO

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

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

4.4. إنشاء AVRO لنطاق الإخراج

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

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

يمكنك نسخ debug_cleartext_payload من نص التقرير.

تصحيح أخطاء حمولة النص غير المرمّز من نص التقرير تصحيح أخطاء حمولة النص العادي من نص التقرير

افتح goo.gle/ags-payload-decoder والصِق debug_cleartext_payload في المربّع INPUT وانقر على Decode.

أداة فك ترميز الحمولة أداة فك ترميز الحمولة

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

نتيجة فك ترميز الحمولة نتيجة فك ترميز الحمولة

بعد الحصول على مفتاح الحزمة، يمكنك إنشاء output_domain.avro. تأكَّد من استبدال بمفتاح الحزمة الذي استرددته.

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

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

4.5. نقل التقارير إلى حزمة AWS

بعد إنشاء تقارير AVRO (من الفقرة 3.2.3) ونطاق الإخراج (من الفقرة 3.2.4)، انتقِل إلى نقل التقارير ونطاق الإخراج إلى حِزم S3 الخاصة بإعداد التقارير.

إذا كان لديك إعداد AWS CLI في بيئتك المحلية، استخدِم الأوامر التالية لنسخ التقارير إلى حزمة S3 ومجلد التقارير المناسبَين.

aws s3 cp report.avro s3://<report_bucket_name>/<report_folder>/
aws s3 cp output_domain.avro s3://<report_bucket_name>/<output_domain_folder>/

5- استخدام "خدمة تجميع البيانات"

من terraform apply، يتم إرجاع create_job_endpoint وget_job_endpoint وfrontend_api_id إليك. انسخ frontend_api_id وضَعها في متغيّر Postman العام frontend_api_id الذي أعددته في القسم 1.9 من المتطلبات الأساسية.

الخطوة 5: استخدام "خدمة تجميع البيانات": استخدِم واجهة برمجة التطبيقات الخاصة بـ "خدمة تجميع البيانات" لإنشاء تقارير موجَزة ومراجعتها.
الخطوة 5.1. استخدام نقطة النهاية createJob لتنفيذ عملية معالجة مجمّعة
الخطوة 5.2 استخدام نقطة نهاية getJob لاسترداد حالة الدفعة
الخطوة 5.3. مراجعة التقرير الموجز

5.1. استخدام نقطة نهاية createJob لإنشاء حِزم

في Postman، افتح مجموعة مبادرة حماية الخصوصية واختَر createJob.

انقر على النص الأساسي ثم على raw لوضع حمولة الطلب.

نص طلب createJob في Postman نص طلب createJob في Postman

يتوفّر مخطط حمولة createJob في github ويبدو مشابهًا لما يلي. استبدِل <> بالحقول المناسبة.

{
    "job_request_id": "<job_request_id>",
    "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
    "input_data_blob_prefixes": [
      "<report_folder>/<report_name-1>/",
      "<report_folder>/<report_name-2>/",
      "<report_folder>/<report_name>.avro"
    ], // Mutually exclusive to input_data_blob_prefix as of v2.11.0
    "input_data_bucket_name": "<bucket_name>",
    "output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
    "output_data_bucket_name": "<bucket_name>",
    "job_parameters": {
      "output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
      "output_domain_bucket_name": "<bucket_name>",
      "attribution_report_to": "<reporting origin of report>",
      "reporting_site": "<domain of reporting origin(s) of report>", // Mutually exclusive to attribution_report_to as of v2.7.0
      "report_error_threshold_percentage": "10",
      "debug_run": "true"
    }
}

بعد النقر على إرسال، سيتم إنشاء الوظيفة باستخدام job_request_id. من المفترض أن تتلقّى استجابة HTTP 202 بعد أن تقبل "خدمة التجميع" الطلب. يمكن العثور على رموز الإرجاع الأخرى المحتملة في رموز استجابة HTTP.

postman createJob request status حالة طلب createJob في Postman

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

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

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

postman getJob request postman getJob request

يجب أن تعرض نتيجة getJob حالة طلب الوظيفة مع حالة HTTP 200. يحتوي نص الطلب على المعلومات الضرورية، مثل job_status وreturn_message وerror_messages (في حال حدوث خطأ في المهمة).

postman getJob request status حالة طلب getJob في Postman

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

{
      "job_status": "FINISHED",
      "request_received_at": "2023-12-07T22:50:58.830956Z",
      "request_updated_at": "2023-12-07T22:51:10.526326456Z",
      "job_request_id": "<job_request_id>",
      "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
      "input_data_blob_prefixes": [ // Mutually exclusive to input_data_blob_prefix as of v2.11.0
        "<report_folder>/<report_name-1>/",
        "<report_folder>/<report_name-2>/",
        "<report_folder>/<report_name>.avro"
      ],
      "input_data_bucket_name": "<input_bucket_name>",
      "output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
      "output_data_bucket_name": "<output_bucket_name>",
      "postback_url": "",
      "result_info": {
          "return_code": "PRIVACY_BUDGET_AUTHORIZATION_ERROR",
          "return_message": "Aggregation job successfully processed",
          "error_summary": {
              "error_counts": [],
              "error_messages": []
          },
          "finished_at": "2023-12-07T22:51:10.517730898Z"
      },
      "job_parameters": {
          "debug_run": "true",
          "output_domain_bucket_name": "<output_domain_bucket_name>",
          "output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
          "attribution_report_to": "https://privacy-sandbox-demos-dsp.dev",
          "reporting_site": "<domain of reporting origin(s) of report>", // Mutually exclusive to attribution_report_to as of v2.7.0
      },
      "request_processing_started_at": "2023-12-07T22:51:06.034472697Z"
}

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

بعد تلقّي التقرير الموجز في حزمة S3 الناتجة، يمكنك تنزيله إلى بيئتك المحلية. تكون التقارير الموجزة بتنسيق AVRO ويمكن تحويلها مرة أخرى إلى JSON. يمكنك استخدام aggregatable_report_converter.jar لقراءة تقريرك باستخدام الأمر التالي.

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

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

تقرير الملخّص تقرير موجز

إذا كان طلبك createJob يتضمّن debug_run كـ true، يمكنك تلقّي تقريرك الموجز في مجلد تصحيح الأخطاء الموجود في output_data_blob_prefix. يكون التقرير بتنسيق AVRO ويمكن تحويله باستخدام الأمر السابق إلى JSON.

يحتوي التقرير على مفتاح المجموعة والمقياس غير المشوّش والتشويش الذي تتم إضافته إلى المقياس غير المشوّش لتكوين التقرير الموجز. يشبه التقرير الصورة التالية.

تقرير ملخّص تصحيح الأخطاء تقرير ملخّص تصحيح الأخطاء

تحتوي التعليقات التوضيحية أيضًا على in_reports وin_domain، ما يعني:

  • in_reports: يتوفّر مفتاح المجموعة داخل التقارير القابلة للتجميع.
  • in_domain: يتوفّر مفتاح المجموعة داخل ملف AVRO الخاص بـ output_domain.