עבודה עם שירות צבירה ב-AWS

1. דרישות מוקדמות

כדי לבצע את ה-Codelab הזה, צריך לעמוד בכמה דרישות מוקדמות. כל דרישה מסומנת בהתאם לסוג הבדיקה שהיא נדרשת עבורה: 'בדיקה מקומית' או 'שירות צבירה'.

1.1. הורדת הכלי לבדיקה מקומית (בדיקה מקומית)

כדי לבצע בדיקה מקומית, צריך להוריד את הכלי לבדיקה מקומית. הכלי ייצור דוחות סיכום מדוחות הניפוי באגים הלא מוצפנים.

אפשר להוריד את הכלי לבדיקה מקומית מארכיוני ה-JAR של Lambda ב-Github. היא צריכה להיקרא LocalTestingTool_{version}.jar.

1.2. אימות ההתקנה של JAVA JRE (שירות בדיקות מקומיות ושירות צבירה)

פותחים את Terminal ומשתמשים ב-java --version כדי לבדוק אם Java או openJDK מותקנים במחשב.

בדיקת הגרסה של Java JRE באמצעות ‎ `java --version`.

אם היא לא מותקנת, אפשר להוריד ולהתקין אותה מאתר Java או מאתר openJDK.

1.3. הורדת כלי להמרת דוחות שניתנים לצבירה (בדיקה מקומית ו-Aggregation Service)

אפשר להוריד עותק של כלי ההמרה של דוחות שניתנים לצבירה ממאגר ההדגמות של ארגז החול לפרטיות ב-GitHub.

1.4. הפעלת ממשקי Ad Privacy API (בדיקה מקומית ושירות צבירה)

בדפדפן, עוברים אל chrome://settings/adPrivacy ומפעילים את כל ממשקי ה-API של פרטיות המודעות.

מוודאים שקובצי Cookie של צד שלישי מופעלים.

בדפדפן, עוברים אל chrome://settings/cookies ובוחרים באפשרות חסימת קובצי Cookie של צד שלישי במצב פרטי.

הגדרה של קובצי Cookie של צד שלישי ב-Chrome.

1.5. הרשמה לאינטרנט ול-Android (Aggregation Service)

כדי להשתמש בממשקי Privacy Sandbox API בסביבת ייצור, צריך לוודא שהשלמתם את ההרשמה והאימות גם ב-Chrome וגם ב-Android.

לצורך בדיקות מקומיות, אפשר להשבית את ההרשמה באמצעות דגל של Chrome ומתג של CLI.

כדי להשתמש ב-flag ב-Chrome להדגמה שלנו, צריך לעבור אל chrome://flags/#privacy-sandbox-enrollment-overrides ולעדכן את שינוי ברירת המחדל באתר שלכם. אם תשתמשו באתר ההדגמה שלנו, לא נדרש עדכון.

דגל Chrome לביטול ההצטרפות לארגז החול לפרטיות.

1.6. הצטרפות ל-Aggregation Service (Aggregation Service)

כדי להשתמש ב-Aggregation Service, צריך להצטרף לתוכנית של מתאמים. ממלאים את טופס ההצטרפות לשירות האגרגציה ומזינים את כתובת האתר של הדוחות, את מזהה החשבון ב-AWS ופרטים נוספים.

1.7. ספק שירותי ענן (Aggregation Service)

כדי להשתמש ב-Aggregation Service, צריך להשתמש בסביבת מחשוב אמינה (TEE) שמשתמשת בסביבת ענן. שירות הצבירה נתמך ב-Amazon Web Services ‏ (AWS) וב-Google Cloud ‏ (GCP). ה-Codelab הזה יתמקד רק בשילוב עם AWS.

‫AWS מספקת סביבת מחשוב אמינה שנקראת Nitro Enclaves. מוודאים שיש לכם חשבון AWS ופועלים לפי ההוראות להתקנה ולעדכון של AWS CLI כדי להגדיר את סביבת AWS CLI.

אם אתם משתמשים ב-AWS CLI חדש, תוכלו להגדיר אותו באמצעות ההוראות להגדרת ה-CLI.

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. הוא ישמש לקריאה לנקודות הקצה של ה-API‏ createJob ו-getJob שנוצרו ב-AWS.

1.7.3. הרשאות משתמשים וקבוצות ב-AWS

כדי לפרוס את Aggregation Service ב-AWS, תצטרכו לתת הרשאות מסוימות למשתמש שמשמש לפריסת השירות. ב-Codelab הזה, צריך לוודא שלמשתמש יש גישת אדמין כדי להיות בטוחים שיש לו הרשאות מלאות לפריסה.

‫1.8. Terraform (Aggregation Service)

ב-Codelab הזה נשתמש ב-Terraform כדי לפרוס את Aggregation Service. מוודאים שקובץ ה-Terraform הבינארי מותקן בסביבה המקומית.

מורידים את קובץ ההפעלה של Terraform לסביבה המקומית.

אחרי שמורידים את קובץ ה-binary של Terraform, מחלצים את הקובץ ומעבירים את קובץ ה-binary של Terraform אל /usr/local/bin.

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

מוודאים ש-Terraform זמין בנתיב המחלקה.

terraform -v

‫1.9. ‫Postman (ל-Aggregation Service AWS)

בשיעור Codelab הזה, נשתמש ב-Postman לניהול בקשות.

כדי ליצור סביבת עבודה, עוברים אל סביבות עבודה בתפריט הניווט העליון ובוחרים באפשרות יצירה של סביבת עבודה.

סביבת עבודה ב-Postman

בוחרים באפשרות סביבת עבודה ריקה, לוחצים על 'הבא' ונותנים לה את השם ארגז החול לפרטיות. בוחרים באפשרות אישי ולוחצים על יצירה.

מורידים את קובצי התצורה בפורמט JSON והסביבה הגלובלית של סביבת העבודה שהוגדרה מראש.

מייבאים את קובצי ה-JSON אל My Workspace באמצעות הלחצן Import.

ייבוא קובצי JSON של Postman.

הפעולה הזו תיצור בשבילכם את אוסף ארגז החול לפרטיות יחד עם בקשות ה-HTTP‏ createJob ו-getJob.

אוסף שייובא מ-Postman.

מעדכנים את מפתח הגישה ואת המפתח הסודי של AWS דרך סקירה מהירה של הסביבה.

סקירה מהירה של סביבת Postman.

לוחצים על עריכה ומעדכנים את הערך הנוכחי של access_key ושל secret_key. שימו לב שfrontend_api_id יסופק בקטע 3.1.4 במסמך הזה. מומלץ להשתמש באזור us-east-1. עם זאת, אם רוצים לפרוס באזור אחר, צריך לוודא שהעתקתם את ה-AMI שפורסם לחשבון שלכם או לבצע בנייה עצמית באמצעות סקריפטים שסופקו.

‫ משתנים גלובליים של Postman. עריכת משתנים גלובליים ב-Postman.

2. ‫Codelab בנושא בדיקות מקומיות

אתם יכולים להשתמש בכלי לבדיקה מקומית במחשב שלכם כדי לבצע צבירה וליצור דוחות סיכום באמצעות דוחות ניפוי הבאגים הלא מוצפנים.

שלבים ב-Codelab

שלב 2.1. הפעלת דוח: הפעלת דיווח של Private Aggregation כדי לאסוף את הדוח.

שלב 2.2. יצירת דוח מצטבר לניפוי באגים: המרת דוח JSON שנאסף לדוח בפורמט AVRO.
השלב הזה דומה למצב שבו טכנולוגיות פרסום אוספות את הדוחות מנקודות הקצה של ה-API לדיווח וממירות את הדוחות בפורמט JSON לדוחות בפורמט AVRO.

שלב 2.3. ניתוח מפתח קטגוריית היעד מדוח הניפוי באגים: מפתחות של קטגוריות יעד מתוכננים על ידי טכנולוגיות פרסום. ב-codelab הזה, מאחר שהקטגוריות מוגדרות מראש, צריך לאחזר את מפתחות הקטגוריות כמו שהם.

שלב 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.

מוודאים שב-Report Body (גוף הדוח), aggregation_coordinator_origin מכיל https://publickeyservice.msmt.aws.privacysandboxservices.com, כלומר הדוח הוא דוח ניתן לצבירה ב-AWS.

דוח של צבירה פרטית.

מציבים את ה-JSON ‏Report Body בקובץ 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. ניתוח מפתח הדלי מדוח ניפוי הבאגים

כשמשתמשים ב-Aggregation Service כדי לעבד נתונים בקבוצות, צריך שני קבצים. הדוח שניתן לצבירה והקובץ של פלט הדומיין. קובץ הפלט של הדומיין מכיל את המפתחות שרוצים לאחזר מהדוחות הניתנים לצבירה. כדי ליצור את הקובץ output_domain.avro, צריך את מפתחות ה-bucket שאפשר לאחזר מהדוחות.

מפתחות של מאגרי מידע מתוכננים על ידי המתקשר של ה-API, ובהדמו יש דוגמאות מוכנות מראש למפתחות של מאגרי מידע. בגלל שמצב ניפוי הבאגים של צבירה פרטית מופעל בהדגמה, אפשר לנתח את מטען הנתונים של הטקסט הגלוי לניפוי באגים מהקטע גוף הדוח כדי לאחזר את מפתח הדלי. עם זאת, במקרה הזה, האתר privacy sandbox demo יוצר את מפתחות הדלי. מכיוון ש-Private Aggregation באתר הזה נמצא במצב ניפוי באגים, אפשר להשתמש ב-debug_cleartext_payload מתוך גוף הדוח כדי לקבל את מפתח הדלי.

מעתיקים את debug_cleartext_payload מגוף הדוח.

ניפוי באגים של מטען ייעודי (payload) בטקסט גלוי מגוף הדוח.

פותחים את הכלי Debug payload decoder for Private Aggregation (מפענח מטען ייעודי למאגרי נתונים פרטיים) ומדביקים את debug_cleartext_payloadבתיבה INPUT (קלט) ואז לוחצים על Decode (פענוח).

מפענח מטען ייעודי (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.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 של דוח סיכום הבדיקה המקומית.

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.

פותחים את קובץ ה-JSON בעורך לבחירתכם כדי לעיין בדוח הסיכום.

3. פריסה של Aggregation Service

כדי לפרוס את Aggregation Service, פועלים לפי השלבים הבאים:

שלב 3. פריסת Aggregation Service: פריסת Aggregation Service ב-AWS
שלב 3.1. משכפלים את מאגר Aggregation Service
שלב 3.2. הורדת יחסי תלות שנוצרו מראש
שלב 3.3. יצירת סביבת פיתוח
שלב 3.4. פריסת Aggregation Service

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

מבטלים את ההערה של הקוד בתיבה האדומה על ידי הסרת התו # ועדכון השמות של דלי הנתונים והמפתח.

עבור AWS main.tf:

קובץ ה-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 שמופיעים בתהליך ההצטרפות ל-Aggregation Service, בסביבה ובאימייל של ההתראות.

עורכים את קובץ ה-tfvars האוטומטי של הסביבה לפיתוח.

אחרי שהעדכונים מסתיימים, לוחצים על esc -> :wq!. קובץ dev.auto.tfvars יישמר ויראה בערך כמו בתמונה הבאה.

‫ קובץ tfvars מעודכן של dev auto.

3.4. פריסת Aggregation Service

כדי לפרוס את Aggregation Service, מאתחלים את Terraform באותה תיקייה /terraform/aws/environments/dev.

terraform init

אמורה להתקבל תגובה שדומה לתמונה הבאה:

terraform init

אחרי שמפעילים את Terraform, יוצרים את תוכנית הביצוע של Terraform. הפלט יכלול את מספר המשאבים שצריך להוסיף ומידע נוסף, כמו בדוגמה הבאה.

terraform plan

בקטע הבא מוצג סיכום של התוכנית. אם זה פריסה חדשה, אמור להופיע מספר המשאבים שיוספו עם 0 לשינוי ו-0 להשמדה.

Terraform plan.

אחרי שמסיימים את השלב הזה, אפשר להמשיך ולהחיל את Terraform.

terraform apply

כשמופיעה הנחיה לאשר את ביצוע הפעולות על ידי Terraform, מזינים yes בערך.

ההודעה להחלת Terraform.

אחרי ש-terraform apply יסיים את הפעולה, יוחזרו נקודות הקצה הבאות עבור createJob ו-getJob. מוחזר גם frontend_api_id שצריך לעדכן ב-Postman בקטע 1.9.

Terraform apply complete.

4. יצירת קלט ל-Aggregation Service

ממשיכים ליצירת דוחות AVRO לאיגוד בחבילות ב-Aggregation Service.

שלב 4. יצירת קלט ל-Aggregation Service: יצירת דוחות של Aggregation Service שנשלחים בחבילות ל-Aggregation Service.
שלב 4.1. דוח טריגר
שלב 4.2. איסוף דוחות שניתן לצבור
שלב 4.3. המרת דוחות ל-AVRO
שלב 4.4. יצירת קובץ AVRO של דומיין הפלט

4.1. דוח טריגרים

עוברים לאתר הדמו של ארגז החול לפרטיות. הפעולה הזו מפעילה דוח צבירה פרטי. אפשר לראות את הדוח בכתובת chrome://private-aggregation-internals.

פרטים פנימיים על צבירה פרטית ב-Chrome.

אם הדוח שלכם במצב בהמתנה, אתם יכולים לבחור את הדוח וללחוץ על שליחת הדוחות שנבחרו. '

שליחת דוח צבירה פרטית.

4.2. איסוף דוחות מצטברים

אוספים את הדוחות שניתן לצבור מנקודות הקצה .well-known של ה-API המתאים.

• Private Aggregation
  [reporting-origin] /.well-known/private-aggregation/report-shared-storage
• דוחות שיוך (Attribution) – דוח סיכום
  [reporting-origin] /.well-known/attribution-reporting/report-aggregate-attribution

ב-Codelab הזה תבצעו את איסוף הדוחות באופן ידני. בסביבת הייצור, ספקי טכנולוגיית פרסום צפויים לאסוף ולהמיר את הדוחות באופן פרוגרמטי.

ב-chrome://private-aggregation-internals, מעתיקים את גוף הדוח שהתקבל בנקודת הקצה [reporting-origin]/.well-known/private-aggregation/report-shared-storage.

מוודאים שב-Report Body (גוף הדוח), aggregation_coordinator_origin מכיל https://publickeyservice.msmt.aws.privacysandboxservices.com, כלומר הדוח הוא דוח ניתן לצבירה ב-AWS.

דוח של צבירה פרטית.

מציבים את ה-JSON ‏Report Body בקובץ 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, צריך את מפתחות ה-bucket שאפשר לאחזר מהדוחות.

מפתחות קטגוריה מתוכננים על ידי טכנולוגיית הפרסום הדיגיטלי. עם זאת, במקרה הזה, האתר Privacy Sandbox demo יוצר את מפתחות הקטגוריה. מכיוון ש-Private Aggregation באתר הזה נמצא במצב ניפוי באגים, אפשר להשתמש ב-debug_cleartext_payload מתוך גוף הדוח כדי לקבל את מפתח הדלי.

אפשר להעתיק את debug_cleartext_payload מגוף הדוח.

ניפוי באגים של מטען ייעודי (payload) בטקסט גלוי מגוף הדוח.

פותחים את goo.gle/ags-payload-decoder, מדביקים את debug_cleartext_payloadבתיבה INPUT ולוחצים על Decode (פענוח).

מפענח מטען ייעודי (payload).

הדף מחזיר את הערך העשרוני של מפתח הדלי. זוהי דוגמה למפתח קטגוריה.

תוצאת פענוח מטען הייעודי.

אחרי שיצרנו את מפתח הקטגוריה, אפשר ליצור את 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 של הדוחות.

אם ה-CLI של 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. שימוש ב-Aggregation Service

מ-terraform apply, המערכת מחזירה את create_job_endpoint, ‏ get_job_endpoint ואת frontend_api_id. מעתיקים את frontend_api_id ומציבים אותו במשתנה הגלובלי frontend_api_id של Postman שהגדרתם בקטע הדרישות המוקדמות 1.9.

שלב 5. שימוש ב-Aggregation Service: משתמשים ב-Aggregation Service API כדי ליצור דוחות סיכום ולעיין בהם.
שלב 5.1. שימוש בנקודת הקצה createJob כדי להוסיף נתונים בכמות גדולה
שלב 5.2. שימוש בנקודת הקצה getJob לאחזור סטטוס של קבוצת קבצים
שלב 5.3. בדיקת דוח הסיכום

5.1. שימוש בנקודת קצה createJob כדי להוסיף קבוצה

ב-Postman, פותחים את האוסף ארגז החול לפרטיות ובוחרים באפשרות createJob.

בוחרים באפשרות Body (גוף) ואז באפשרות raw (גולמי) כדי למקם את מטען הבקשה.

postman createJob request body

סכימת המטען הייעודי (payload) של 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"
    }
}

אחרי שלוחצים על Send (שליחה), נוצרת המשימה עם job_request_id. אחרי ששירות הצבירה יאשר את הבקשה, תקבלו תגובה מסוג HTTP 202. אפשר למצוא קודי החזרה אפשריים אחרים בקודי תגובה של HTTP

postman createJob request status

5.2. שימוש בנקודת הקצה getJob לאחזור סטטוס של קבוצת קבצים

כדי לבדוק את הסטטוס של בקשת העבודה, אפשר להשתמש בנקודת הקצה getJob. בוחרים באפשרות getJob באוסף ארגז החול לפרטיות.

בקטע Params, מעדכנים את הערך של job_request_id ל-job_request_id שנשלח בבקשה createJob.

postman getJob request

התוצאה של getJob צריכה להחזיר את הסטטוס של בקשת העבודה עם סטטוס HTTP של 200. הבקשה Body מכילה את המידע הנדרש כמו job_status, ‏ return_message ו-error_messages (אם העבודה נכשלה).

postman getJob request status

מאחר שאתר הדיווח של דוח ההדגמה שנוצר שונה מהאתר שצורף למזהה AWS שלכם, יכול להיות שתקבלו תגובה עם PRIVACY_BUDGET_AUTHORIZATION_ERROR return_code. זה מצב תקין כי האתר שממנו מדווחים בדוחות לא זהה לאתר שממנו מדווחים ב-AWS ID.

{
      "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 של ערכים מצטברים של כל מפתח bucket, שדומה לתמונה הבאה.

דוח סיכום.

אם הבקשה createJob כוללת את debug_run בתור true, תוכלו לקבל את דוח הסיכום בתיקיית ניפוי הבאגים שנמצאת ב-output_data_blob_prefix. הדוח הוא בפורמט AVRO ואפשר להמיר אותו ל-JSON באמצעות הפקודה הקודמת.

הדוח מכיל את מפתח הסיווג, את המדד ללא רעשי רקע ואת הרעש שנוסף למדד ללא רעשי רקע כדי ליצור את דוח הסיכום. הדוח אמור להיראות כמו בתמונה הבאה.

דוח סיכום ניפוי הבאגים.

ההערות כוללות גם את in_reports וin_domain, שמשמעותן:

• in_reports – מפתח הדלי זמין בדוחות הניתנים לצבירה.
• in_domain – מפתח הקטגוריה זמין בקובץ הפלט AVRO של output_domain.