דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

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

כלי הבדיקות המקומיות זמין להורדה בארכיון Lambda JAR Archives ב-GitHub. השם צריך להיות LocalTestingTool_{version}.jar.

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

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

$בודק את גרסת Java jre באמצעות Java\n--גרסה$

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

1.3. הורדת הכלי להמרת דוחות Aggregatable (שירות בדיקה וצבירה מקומית)

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

1.4 הפעלת ממשקי API של ארגז החול לפרטיות (שירות בדיקה וצבירה מקומית)

בדפדפן, עוברים אל chrome://flags/#privacy-sandbox-ads-apis ומפעילים את ממשקי ה-API של ארגז החול לפרטיות.

ודאו שהופעלו קובצי cookie של צד שלישי.

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

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

1.5. רישום לאתר ול-Android (שירות צבירה)

כדי להשתמש בממשקי API של ארגז החול לפרטיות בסביבת הייצור, צריך לוודא שהשלמתם את ההרשמה והאימות של Chrome וגם של Android.

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

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

1.6. הדרכה למשתמשים חדשים של שירות צבירה (שירות צבירה)

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

1.7 ספק שירותי ענן (שירות צבירה)

לשירות צבירה נדרש שימוש בסביבת ביצוע מהימנה שמשתמשת בסביבת ענן. שירות הצבירה נתמך ב-Amazon Web Services (AWS) וב-Google Cloud (GCP). ה-Codelab הזה יעסוק רק בשילוב עם AWS.

AWS מספקת סביבת הפעלה מהימנה שנקראת Nitro Enclaves. צריך לוודא שיש לכם חשבון AWS ולפעול לפי הוראות ההתקנה והעדכון של AWS CLI כדי להגדיר את סביבת 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. הוא ישמש לקריאה לנקודות הקצה (endpoints) של ה-API createJob ו-getJob שנוצרו ב-AWS.

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

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

1.8 Terraform (שירות צבירה)

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

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

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

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

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

terraform -v

1.9 Postman (For Aggregation Service AWS)

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

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

Postmanworkspace

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

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

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

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

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

אוסף דואר מיובא

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

מבט מהיר על סביבת הדואר

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

משתנים גלובליים של Postman

עריכת פוסטמן גלובלית

2. Codelab לבדיקה מקומית

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

שלבים ב-Codelab

שלב 2.1. דוח טריגר: אפשר להפעיל דיווח על צבירה פרטית כדי שיהיה אפשר לאסוף את הדוח.

שלב 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, מעתיקים את גוף הדוח שהתקבל בנקודת הקצה (endpoint) [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, צריך את מפתחות הקטגוריה שאפשר לאחזר מהדוחות.

מפתחות הקטגוריות נוצרים על ידי מבצע הקריאה של ה-API, וההדגמה מכילה מפתחות קטגוריות לדוגמה שנוצרו מראש. מאחר שבהדגמה הופעלה מצב ניפוי הבאגים עבור צבירה פרטית, אפשר לנתח את המטען הייעודי (payload) של ניפוי הבאגים בטקסט ללא באגים מ-"Report Body" (גוף הדוח) כדי לאחזר את מפתח הקטגוריה. עם זאת, במקרה הזה, הדגמת ארגז החול לפרטיות יוצרת את מפתחות הקטגוריה. מאחר שהצבירה הפרטית של האתר הזה נמצאת במצב ניפוי באגים, ניתן להשתמש ב-debug_cleartext_payload מ "גוף הדוח" כדי לקבל את מפתח הקטגוריה.

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

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

פותחים את הכלי Debug payload codeer 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 נוצר לאחר השלמת התהליך.

קובץ vrofile של דוח סיכום בדיקות מקומיות

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:

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

3.1. שכפול מאגר הנתונים של Aggregation Service

משכפלים בסביבה המקומית את מאגר ה-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

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

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

עריכת dev אוטומטי tfvarsfile

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

עדכון אוטומטי של dev auto tfvarsfile

3.4. פריסת שירות צבירה

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

terraform init

היא אמורה להחזיר משהו שדומה לתמונה הבאה:

terraforminit

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

terraform plan

תוכלו לראות את הסיכום הבא של Plan (התוכנית). אם זו פריסה חדשה, מספר המשאבים שיתווספו עם 0 כדי לשנות ו-0 כדי להשמיד.

terraformplan

לאחר שתסיימו את התהליך, תוכלו להמשיך להחיל את Terraform.

terraform apply

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

terraform Applyprompt

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

Applycomplete ב-terraform

4. יצירת קלט של שירות צבירה

יש להמשיך כדי ליצור את דוחות ה-AVRO לקיבוץ ב-Aggregation Service.

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

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

צבירה פרטית של Chrome

אם הסטטוס של הדוח הוא "בהמתנה", אתם יכולים לבחור את הדוח וללחוץ על שליחת דוחות שנבחרו.

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

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

איסוף הדוחות המצטברים מנקודות הקצה (endpoints) של .well-known ב-API המתאים.

צבירה פרטית
[reporting-origin] /.well-known/private-aggregation/report-shared-storage
דוחות ייחוס – דוח סיכום
[reporting-origin] /.well-known/attribution-reporting/report-aggregate-attribution

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

דוח צבירה פרטית

יש להכניס את "גוף הדוח" ל-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 מגוף הדוח.

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

אם ה-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: שימוש בשירות צבירה: שימוש ב-Aggregation Service API כדי ליצור דוחות סיכום ולבדוק את דוחות הסיכום.
שלב 5.1. שימוש ב-createJob Endpoint כדי אצווה
שלב 5.2 שימוש בנקודת קצה של getJob כדי לאחזר סטטוס אצווה
שלב 5.3. עיון בדוח הסיכום

5.1. שימוש בנקודת קצה אחת (`createJob`) כדי לאצוות

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

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

Postman createJob requestbody

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

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

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

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

Postman getJobrequest

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

סטטוס של בקשת getJob של Postman

מאחר שאתר הדיווח שנוצר בדוח ההדגמה שונה מהאתר שיצרתם במזהה AWS שלכם, ייתכן שתקבלו תשובה עם הערך PRIVACY_BUDGET_AUTHORIZATION_ERRORreturn_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 – מפתח הקטגוריה זמין בתוך קובץ ה-output_domain AVRO.