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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

إذا كان AWS 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 (خدمة التجميع)

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

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

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

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

تأكَّد من توفّر Terraform في classpath.

terraform -v

1.9. Postman (للخدمة AWS Aggregation Service)

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

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

postmanworkspace

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

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

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

استيراد ملفات JSON في Postman

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

postman importedcollection

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

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

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

postman globalvariables

postman edit globalvariables

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

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

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

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

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

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

الخطوة 2.4: إنشاء ملف AVRO لنطاق الإخراج: بعد استرداد مفاتيح الحزمة، أنشئ ملف 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.

private aggregationreport

ضَع نص التقرير بتنسيق 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 من نص التقرير.

تصحيح أخطاء الحمولة النصية الواضحة من reportbody

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

payloaddecoder

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

payload decoderresult

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- نشر "خدمة تجميع البيانات"

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

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

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

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

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

edit dev auto tfvarsfile

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

تم تعديل dev auto tfvarsfile

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

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

terraform init

من المفترض أن يعرض هذا الإجراء شيئًا مشابهًا للصورة التالية:

terraforminit

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

terraform plan

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

terraformplan

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

terraform apply

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

terraform applyprompt

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

terraform applycomplete

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

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

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

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

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

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

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

private aggregationreport

ضَع نص التقرير بتنسيق 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 من نص التقرير.

تصحيح أخطاء الحمولة النصية الواضحة من reportbody

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

payloaddecoder

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

payload decoderresult

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

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

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

في Postman، افتح مجموعة Privacy Sandbox واختَر createJob.

اختَر النص ثمّ اختَر النصّ الأوّلي لوضع الحمولة المطلوبة.

postman createJob requestbody

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

ملاحظة: ننصحك باستخدام 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.6). (على سبيل المثال: 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"
  }
}

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

postman createJob requeststatus

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

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

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

postman getJobrequest

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

postman getJob requeststatus

بما أنّ موقع الويب الذي يتم إعداد التقارير منه في التقرير التجريبي الذي تم إنشاؤه يختلف عن موقعك الإلكتروني الذي تم إعداده في معرّفك على 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-dsp.dev",
        "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
    },
    "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 يتضمّن القيم المجمّعة لكل مفتاح حزمة، ويشبه الصورة التالية.

summaryreport

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

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

debug summaryreport

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

in_reports: يتوفّر مفتاح الحزمة داخل التقارير القابلة للتجميع.
in_domain: يتوفّر مفتاح الحزمة داخل ملف AVRO الخاص بنطاق_الإخراج.