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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ضبط chromesetting لملفات تعريف الارتباط التابعة لجهات خارجية

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. إنشاء مفتاح وصول للمستخدم

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

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

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

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

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

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

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

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

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

terraform -v

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

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

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

بوسيلة بريد

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

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

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

استيراد ملفات JSON بوسيلة البريد

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

مجموعة البريد المستوردة

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 بعد اكتمال هذا الإجراء.

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

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 تم إنشاؤه في الدليل نفسه.

ملف 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 main.tf:

ملف 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

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

تيرافورم مع اكتمال عملية

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

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

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

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

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

chrome الخاص بالتجميع الداخلي

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

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

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" وانقر على فك الترميز.

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

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

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

والآن بعد أن أصبح لدينا مفتاح الحزمة، يمكنك المتابعة وإنشاء 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.

اختَر النص الأساسي واختَر 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.

حالة طلب إنشاء وظيفة ساعي البريد

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

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

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

رجل البريد getJobrequest

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

حالة طلب وظيفة getJob

بما أنّ موقع إعداد التقارير في تقرير العرض التوضيحي الذي تم إنشاؤه يختلف عن موقعك الإلكتروني الذي تم تسجيله في AWS ID، قد تتلقّى ردًا يتضمّن سمة return_code PRIVACY_BUDGET_AUTHORIZATION_ERROR. هذا أمر طبيعي لأنّ الموقع الإلكتروني لمصدر إعداد التقارير في التقارير لا يتطابق مع الموقع الإلكتروني لإعداد التقارير الذي تم إعداده لمعرّف 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-dsp.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.