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

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

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

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

1.1. تنزيل أداة الاختبار المحلي (الاختبار المحلي)

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

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

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

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

$التحقق من إصدار جافا jre باستخدام جافا\n--الإصدار$

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

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

يمكنك تنزيل نسخة من محوّل التقارير المجمّعة من مستودع GitHub في "مبادرة حماية الخصوصية".

1.4 تفعيل واجهات برمجة تطبيقات "مبادرة حماية الخصوصية" (خدمة الاختبار المحلي والتجميع)

في متصفّحك، انتقِل إلى chrome://flags/#privacy-sandbox-ads-apis وفعِّل واجهات برمجة تطبيقات "مبادرة حماية الخصوصية".

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

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

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

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

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

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

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

1.6. إعداد خدمة التجميع (خدمة التجميع)

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

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

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

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

إذا كان واجهة سطر الأوامر في AWS جديدة، يمكنك ضبط واجهة سطر الأوامر في AWS باتّباع تعليمات إعداد واجهة سطر الأوامر.

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

يمكنك إنشاء حزمة AWS S3 لتخزين حالة Terraform، وحزمة S3 أخرى لتخزين التقارير وتقارير الملخص. ويمكنك استخدام أمر CLI المتوفر. استبدِل الحقل في <> بالمتغيّرات المناسبة.

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

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

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

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

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

1.8 تيريفورم (خدمة التجميع)

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

نزِّل برنامج Teaform الثنائي في بيئتك المحلية.

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

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

تحقق للتأكد من توفر Terraform في مسار الفئة.

terraform -v

1.9 Postman (لخدمة التجميع في AWS)

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

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

Postmanworkspace

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

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

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

استيراد ملفات JSON الشخصية للبريد الإلكتروني

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

مجموعة Postman المستوردة

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

نظرة سريعة على بيئة ساعي البريد

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

المتغيرات العالمية البريدية

تعديل المتغيرات العمومية في البريد الإلكتروني

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

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

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

الخطوة 2.1: تقرير عوامل التشغيل: يمكنك تشغيل تقارير التجميع الخاص لتتمكّن من جمع التقرير.

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

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

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

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

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

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

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

chrome Private aggregationinternals

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

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

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

بعد إجراء ذلك، انتقِل إلى مجلد التقارير واستخدِم 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" وانقر على INPUT.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ملخّص ملف avro وتحويله إلى json

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

3- نشر خدمة التجميع

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

الخطوة الثالثة: نشر خدمة التجميع: نشر خدمة التجميع على AWS
الخطوة 3.1: استنسِخ مستودع خدمة التجميع
الخطوة 3.2. نزِّل التبعيات المُنشأة مسبقًا.
الخطوة 3.3: إنشاء بيئة تطوير
الخطوة 3.4 نشر خدمة التجميع

3.1. استنساخ مستودع خدمة التجميع

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

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

3.2. تنزيل التبعيات المُنشأة مسبقًا

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

cd <repository_root>/terraform/aws

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

bash download_prebuilt_dependencies.sh

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

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

mkdir dev

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

cp -R demo/* dev

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

cd dev

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

vim main.tf

يجب إلغاء تعليق التعليمة البرمجية في المربع الأحمر عن طريق إزالة # وتحديث اسم الحزمة و اسم المفتاح.

بالنسبة إلى الإصدار الرئيسي من AWS:

ملف tffile الرئيسي لخدمة 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 الصحيحة التي يتم توفيرها أثناء إعداد "خدمة التجميع" والبيئة وإرسال إشعار عبر البريد الإلكتروني.

تعديل ملف مطور البرامج تلقائيًا tfvarsfile

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

ملف tfvarsfile المحدّث تلقائيًا

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

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

terraform init

يُفترض أن يؤدي هذا إلى عرض شيء مشابه للصورة التالية:

تيرافورمينيت

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

terraform plan

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

خريطة ترامبولان

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

terraform apply

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

تيراس فورم

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

terraformApplycomplete

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

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

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

4.1. تقرير العوامل المشغِّلة

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

chrome Private aggregationinternals

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

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

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

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

التجميع الخاص
[reporting-origin] /.well-known/private-aggregation/report-shared-storage
إعداد تقارير الإحالة - تقرير الملخص
[reporting-origin] /.well-known/attribution-reporting/report-aggregate-attribution

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

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

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

vim report.json

الصِق التقرير في report.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" وانقر على "INPUT".

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

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

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

الآن بعد أن أصبح لدينا مفتاح الحزمة، يمكنك المتابعة وإنشاء 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 في بيئتك المحلية، استخدِم الأوامر التالية لنسخ التقارير إلى حزمة 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 وضَع هذا العنصر في المتغيّر العمومي لساعي البريد frontend_api_id الذي تضبطه في القسم 1.9 للمتطلبات الأساسية.

الخطوة الخامسة: استخدام خدمة التجميع: استخدام واجهة برمجة تطبيقات خدمة التجميع لإنشاء تقارير موجزة ومراجعة التقارير الموجزة.
الخطوة 5.1 استخدام createJob Endpoint كحزمة
الخطوة 5.2. استخدام getJob Endpoint لاسترداد حالة الحزمة
الخطوة 5.3 مراجعة تقرير الملخص

5.1. استخدام نقطة النهاية `createJob` لتجميع البيانات

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

اختَر Body (النص الأساسي) ثم اختَر raw لإضافة حمولة الطلب.

صانع البريد الإلكتروني ينشئ نص طلب الوظيفة

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

{
  "job_request_id": "<job_request_id>",
  "input_data_blob_prefix": "<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>",
  "job_parameters": {
    "output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
    "output_domain_bucket_name": "<output_domain_bucket_name>",
    "attribution_report_to": "<reporting origin of report>",
    "report_error_threshold_percentage": "10",
    "debug_run": "true"
  }
}

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

حالة طلب وظيفة Postman لإنشاء وظيفة

5.2. استخدام getJob Endpoint لاسترداد حالة الدفعة

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

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

الحصول على وظيفة طلب وظيفة Postman

يجب أن تعرض نتيجة getJob حالة طلب المهمة بحالة HTTP 200. يحتوي الطلب "Body" على المعلومات اللازمة، مثل job_status وreturn_message وerror_messages (إذا كان هناك خطأ في المهمة).

حالة طلب الوظيفة لدى 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_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-news.dev"
    },
    "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 - يتوفّر مفتاح الحزمة داخل ملف exit_domain AVRO.