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

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

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

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

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

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

כלי הבדיקה המקומית זמין להורדה בארכיונים של Lambda JAR ב-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 של צד שלישי במצב פרטי'.

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

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

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

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

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

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

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

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

צריך לוודא ש-Terraform זמינה ב-classpath.

terraform -v

1.9. Postman (לשירות Aggregation Service AWS)

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

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

Postmanworkspace

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

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

לוחצים על הלחצן ייבוא כדי לייבא את קובצי ה-JSON אל "סביבת העבודה שלי".

ייבוא קובצי JSON של פוסטמן

הפעולה הזו תיצור עבורך את האוסף 'ארגז החול לפרטיות' יחד עם בקשות ה-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.

דוח צבירת נתונים פרטי

מציבים את Report Body (גוף הדוח) בקובץ JSON. בדוגמה הזו אפשר להשתמש ב-vim. אבל אפשר להשתמש בכל כלי לעריכת טקסט שרוצים.

vim report.json

מדביקים את הדוח ב-report.json ושומרים את הקובץ.

דוח JSONfile

לאחר מכן, מנווטים לתיקיית הדוחות ומשתמשים ב-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 דרך Report Body (גוף הדוח) כדי לקבל את מפתח הקטגוריה.

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

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

פותחים את הכלי מפענח מטען ייעודי לניפוי באגים לצבירה פרטית ומדביקים את debug_cleartext_payload בתיבה INPUT" ולאחר מכן לוחצים על "Decode".

מפענח מטען

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

payload dederresult

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.

בשביל ה-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. פריסת שירות הצבירה

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

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

3.1. שכפול המאגר של Aggregation Service

בסביבה המקומית, משכפלים את מאגר GitHub של שירות הצבירה.

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

3.2. הורדת יחסי תלות שנוצרו מראש

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

עריכת dev Auto tfvarsfile

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

עדכון dev Auto tfvarsfile

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

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

terraform init

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

טרפורמיניט

אחרי ההפעלה של 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 לאצוות ב-Aggregation Service.

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

4.1. דוח טריגר

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

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

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

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

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

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

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

דוח צבירת נתונים פרטי

מציבים את Report Body (גוף הדוח) בקובץ JSON. בדוגמה הזו אפשר להשתמש ב-vim. אבל אפשר להשתמש בכל כלי לעריכת טקסט שרוצים.

vim report.json

מדביקים את הדוח ב-report.json ושומרים את הקובץ.

דוח JSONfile

4.3. המרת דוחות ל-AVRO

דוחות שמתקבלים מנקודות הקצה (endpoints) של .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 דרך Report Body (גוף הדוח) כדי לקבל את מפתח הקטגוריה.

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

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

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

מפענח מטען

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

payload dederresult

עכשיו, אחרי שיש לנו את מפתח הקטגוריה, אפשר ליצור את 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 של הדו"ח (post-man), שהגדרתם בסעיף 1.9 של הדרישות המוקדמות.

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

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

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

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

דוור נשלחת בקשה ליצור משימה

הסכימה של המטען הייעודי (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. שימוש בנקודת קצה (endpoint) של getJob כדי לאחזר סטטוס של אצווה

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

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

שירות getJobrequest

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

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

אתר הדיווח של דוח ההדגמה שנוצר שונה מהאתר המצורף למזהה ה-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"
    },
    "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 – מפתח הקטגוריה זמין בקובץ ה-AVRO (output_domain).