דף זה תורגם על ידי 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://settings/adPrivacy ומפעילים את כל ממשקי ה-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 ו'מפתח סודי' באמצעות "מבט מהיר על הסביבה".

תצוגה מהירה של סביבת פוסטמן

לוחצים על עריכה. ולעדכן את העמודה 'ערך נוכחי' בשניהם יחד עם "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, מעתיקים את "גוף הדוח" שהתקבלו בנקודת הקצה [reporting-origin]/.well-known/private-aggregation/report-shared-storage.

מוודאים שבגוף הדוח הערך aggregation_coordinator_origin מכיל את הערך https://publickeyservice.msmt.aws.privacysandboxservices.com, והמשמעות היא שהדוח הוא דוח נצברים של AWS.

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

ממקמים את קובץ ה-JSON "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 מתוך "גוף הדוח" כדי לקבל את מפתח הקטגוריה.

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

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

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

payloaddecoder

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

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

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

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.

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 הזה יתבצע איסוף הדוחות באופן ידני. בסביבת הייצור, טכנולוגיות הפרסום אמורות לאסוף ולהמיר את הדוחות באופן פרוגרמטי.

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

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 מתוך "גוף הדוח" כדי לקבל את מפתח הקטגוריה.

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

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

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

payloaddecoder

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

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 ונראית דומה לזו. מחליפים את השדה <> בשדות המתאימים.

הערה: אם אפשר, מומלץ להשתמש ברכיב reporting_site שמוגדר בjob_parameters, ולא ב-attribution_report_to. השדה attribution_report_to זוהה להוצאה משימוש בשדרוג הגרסה הראשית הבא של ממשק ה-API של שירות צבירה. (מידע נוסף) הפרמטר 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. שימוש בנקודת קצה (endpoint) של getJob כדי לאחזר סטטוס של אצווה

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

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

שירות getJobrequest

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

סטטוס של בקשה למשרות מבוקשות

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

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

דוח סיכום של ניפוי באגים

ההערות מכילות גם את in_reports ו-in_domain, כלומר:

in_reports - מפתח הקטגוריה זמין בדוחות המצטברים.
in_domain – מפתח הקטגוריה זמין בקובץ ה-AVRO (output_domain).