עבודה עם שירות צבירה ב-Google Cloud Platform (GCP)

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

משך זמן משוער: שעה-שעתיים

יש 2 מצבים לביצוע ה-Codelab הזה: בדיקה מקומית או שירות צבירה. כדי להפעיל את מצב 'בדיקות מקומיות' יש צורך במחשב מקומי ודפדפן Chrome (לא צריך ליצור משאבים ב-Google Cloud או להשתמש בהם). במצב Aggregation Service נדרשת פריסה מלאה של שירות הצבירה ב-Google Cloud.

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

1.1. הרשמה ואימות (attestation) מלאים (שירות צבירת נתונים)

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

1.2. הפעלת ממשקי ה-API של ארגז החול לפרטיות (שירות בדיקות מקומיות וצבירת נתונים)

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

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

צריך גם לוודא שקובצי ה-Cookie של צד שלישי מופעלים.

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

• 'חסימת כל קובצי ה-cookie של צד שלישי' = 'מושבת'
• 'חסימת קובצי cookie של צד שלישי' = 'מושבתת'
• 'חסימת קובצי cookie של צד שלישי במצב פרטי' = מופעלת

יש להפעיל מחדש את Chrome כדי שהשינוי ייכנס לתוקף.

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

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

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

1.4. מוודאים ש-JAVA JRE מותקן (שירות בדיקה וצבירת נתונים מקומי)

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

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

1.5. הורדת aggregatable_report_converter (שירות בדיקה וצבירת נתונים מקומי)

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

1.6. הגדרה של סביבה ל-GCP (שירות צבירה)

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

1.6.1. פריסה

פועלים לפי הוראות הפריסה ב-GitHub כדי להגדיר את ה-CLI של gcloud, להוריד קבצים בינאריים ומודולים של Terraform וליצור משאבי GCP לשירות צבירת נתונים.

הערה חשובה: כדי לפרוס את השירות תצטרכו הרשאות מסוימות. כדי להשתתף ב-Codelab הזה, צריך לוודא שלמשתמש יש הרשאת אדמין / בעלים בפרויקט GCP.

שלבים מרכזיים בהוראות הפריסה:

1. מגדירים את ה-CLI של gcloud ואת Terraform בסביבה שלכם.
2. יצירת קטגוריה של Cloud Storage לאחסון מצבי Terraform.
3. הורדה של יחסי תלות.
4. מעדכנים את adtech_setup.auto.tfvars ומריצים את ה-Terraform adtech_setup. אפשר לעיין בנספח לדוגמה של קובץ adtech_setup.auto.tfvars.
5. מעדכנים את dev.auto.tfvars, מתחזים לחשבון השירות לפריסה ומריצים את dev של Terraform. אפשר לעיין בנספח לדוגמה של קובץ dev.auto.tfvars.
6. בסיום הפריסה, מתעדים את frontend_service_cloudfunction_url מהפלט של Terraform, שיהיה צורך לשלוח בקשות לשירות הצבירה בשלבים הבאים.

1.6.2. קטגוריית הדוחות

אחרי הגדרת הפרויקט, יוצרים קטגוריה ב-Cloud Storage שבה יאוחסנו הדוחות המצטברים ודוחות הסיכום מה-Codelab הזה. זוהי דוגמה לפקודת gcloud ליצירת קטגוריה. מחליפים את ה-placeholders בשם ובמיקום הרצויים.

gcloud storage buckets create gs://<bucket-name> --location=<location>

1.7. השלמה של תהליך ההצטרפות לשירות צבירה (שירות צבירת נתונים)

כדי להשתמש בשירות, המתאמים צריכים להצטרף לשירות הצבירה. ממלאים את טופס ההצטרפות לשירות צבירה. כדי למלא את הפרטים של אתר הדיווח ופרטים נוספים, בוחרים באפשרות Google Cloud ומזינים את הכתובת של חשבון השירות. חשבון השירות הזה נוצר בדרישה המוקדמת הקודמת (1.6. מגדירים סביבת GCP). (רמז: אם משתמשים בשמות ברירת המחדל שסופקו, חשבון השירות הזה יתחיל ב-"worker-sa@").

תהליך ההצטרפות עשוי להימשך עד שבועיים.

1.8. בחירת השיטה לשליחת קריאה לנקודות הקצה (endpoints) של ה-API (שירות צבירה)

ה-Codelab הזה מספק שתי אפשרויות לקריאה לנקודות הקצה של Aggregation Service API: cURL ו-Postman. דרך cURL היא הדרך המהירה והקלה יותר לקרוא לנקודות הקצה של ה-API מה-Terminal, כי נדרשת הגדרה מינימלית וללא תוכנה נוספת. עם זאת, אם אתם לא רוצים להשתמש ב-cURL, תוכלו להשתמש במקום זאת ב-Postman כדי להריץ ולשמור בקשות API לשימוש עתידי.

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

1.8.1. הגדרה של סביבת העבודה

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

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

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

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

לוחצים על הלחצן 'ייבוא' כדי לייבא את שני קובצי ה-JSON אל 'My Workspace'.

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

1.8.2. הגדרת הרשאה

לוחצים על האוסף 'ארגז החול לפרטיות ב-GCP' ועוברים לכרטיסייה 'הרשאה'.

צריך להשתמש בשיטה'אסימון למוכ "ז'. בסביבת הטרמינל, מריצים את הפקודה הזו ומעתיקים את הפלט.

gcloud auth print-identity-token

לאחר מכן, מדביקים את ערך האסימון הבא בשדה "Token" בכרטיסייה 'הרשאה של Postman':

1.8.3. הגדרת סביבה

עוברים לקטע 'מבט מהיר על הסביבה' בפינה הימנית העליונה:

לוחצים על 'עריכה' ומעדכנים את הערך הנוכחי של 'Environment', 'region' ו-'cloud-function-id':

בינתיים אפשר להשאיר את השדה 'request-id' ריק כי נמלא אותו מאוחר יותר. בשדות האחרים, משתמשים בערכים מהשדה frontend_service_cloudfunction_url, שהוחזר בעקבות השלמת הפריסה של Terraform בדרישות המוקדמות 1.6. כתובת ה-URL בפורמט הזה: https://--frontend-service--uc.a.run.app

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

זמן משוער לסיום: פחות משעה

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

שלבי Codelab

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

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

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

שלב 2.4. יוצרים קובץ AVRO של דומיין פלט: לאחר אחזור מפתחות הקטגוריה, יוצרים את קובץ ה-AVRO של הדומיין של הפלט.

שלב 2.5. יצירת דוח סיכום: משתמשים בכלי הבדיקה המקומית כדי ליצור דוחות סיכום בסביבה המקומית.

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

2.1. דוח טריגר

כדי להפעיל דוח צבירת נתונים פרטית, תוכלו להשתמש באתר ההדגמה של ארגז החול לפרטיות (https://privacy-sandbox-demos-news.dev/?env=gcp) או באתר שלכם (למשל, https://adtechexample.com). אם אתם משתמשים באתר משלכם ולא השלמתם את תהליך ההרשמה והאימות ואת ההצטרפות לשירות הצבירה, תצטרכו להשתמש במתג של דגל Chrome ו-CLI.

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

הדוח שנשלח לנקודת הקצה {reporting-origin}/.well-known/private-aggregation/debug/report-shared-storage נמצא גם ב'גוף הדוח' של הדוחות המוצגים בדף Chrome Internals.

יכול להיות שיופיעו כאן דוחות רבים, אבל ל-Codelab הזה, צריך להשתמש בדוח המצטבר שהוא ספציפי ל-GCP, שנוצר על ידי נקודת הקצה לניפוי באגים. 'כתובת ה-URL של הדוח' תכיל את /debug/ , וה-aggregation_coordinator_origin field של 'גוף הדוח' יכיל את כתובת ה-URL הבאה: https://publickeyservice.msmt.gcp.privacysandboxservices.com.

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

2.2. יצירת דוח נצברים לניפוי באגים

מעתיקים את הדוח שנמצא ב'גוף הדוח' של chrome://private-aggregation-internals ויוצרים קובץ JSON בתיקייה privacy-sandbox-demos/tools/aggregatable_report_converter/out/artifacts/aggregatable_report_converter_jar (בתוך המאגר שהורדתם לפי הדרישות המוקדמות 1.5).

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

vim report.json

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

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

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

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

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

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.3 הנדרשת המוקדמת כדי ליצור את דוחות הסיכום באמצעות הפקודה הבאה. מחליפים את {version} בגרסה שהורדתם. חשוב לזכור להעביר את LocalTestingTool_{version}.jar לספרייה הנוכחית או להוסיף נתיב יחסי כדי להפנות למיקום הנוכחי שלו.

java -jar LocalTestingTool_{version}.jar \
  --input_data_avro_file report.avro \
  --domain_avro_file output_domain.avro \
  --output_directory .

אחרי הרצת הפקודה, אמור להופיע משהו שדומה לזה שמופיע למטה. בסיום התהליך ייווצר דוח output.avro.

2.6. עיון בדוח הסיכום

דוח הסיכום שנוצר הוא בפורמט AVRO. כדי לקרוא את המידע הזה, עליך להמיר את הקוד מ-AVRO לפורמט JSON. באופן אידיאלי, adTech צריכה לכתוב קוד כדי להמיר דוחות AVRO בחזרה ל-JSON.

נשתמש ב-aggregatable_report_converter.jar כדי להמיר את דוח ה-AVRO בחזרה ל-JSON.

java -jar aggregatable_report_converter.jar \
  --request_type convertToJson \
  --input_file output.avro

הפעולה הזו תחזיר את הדוח הבא. יחד עם דוח output.json שנוצר באותה ספרייה.

3. 3. Codelab של שירות צבירה

זמן משוער להשלמה: שעה אחת

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

שלבי Codelab

שלב 3.1. יצירת קלט של שירות צבירה: יצירת הדוחות של שירות הצבירה שנאספו באצווה לשירות צבירת נתונים.

• שלב 3.1.1. דוח טריגר
• שלב 3.1.2. איסוף דוחות נצברים
• שלב 3.1.3. המרת דוחות ל-AVRO
• שלב 3.1.4. יצירת Export_domain AVRO
• שלב 3.1.5. העברת דוחות לקטגוריה של Cloud Storage

שלב 3.2. שימוש בשירות צבירה: משתמשים ב-Aggregation Service API כדי ליצור דוחות סיכום ולבדוק את דוחות הסיכום.

• שלב 3.2.1. שימוש בנקודת קצה (endpoint) של createJob כדי לקבץ
• שלב 3.2.2. שימוש בנקודת קצה (endpoint) של getJob כדי לאחזר סטטוס אצווה
• שלב 3.2.3. בדיקת דוח הסיכום

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

ממשיכים ליצירת דוחות AVRO לקיבוץ ב-Service Aggregation Service. את פקודות המעטפת בשלבים האלה אפשר להריץ ב-Cloud Shell של GCP (בתנאי שיחסי התלות מהדרישות המוקדמות משוכפלים בסביבת Cloud Shell) או בסביבת הפעלה מקומית.

3.1.1. דוח טריגר

כדי לעבור לאתר צריך ללחוץ על הקישור. לאחר מכן אפשר יהיה לעיין בדוחות בכתובת chrome://private-aggregation-internals:

הדוח שנשלח לנקודת הקצה {reporting-origin}/.well-known/private-aggregation/debug/report-shared-storage נמצא גם ב'גוף הדוח' של הדוחות המוצגים בדף Chrome Internals.

יכול להיות שיופיעו כאן דוחות רבים, אבל ל-Codelab הזה, צריך להשתמש בדוח המצטבר שהוא ספציפי ל-GCP, שנוצר על ידי נקודת הקצה לניפוי באגים. 'כתובת ה-URL של הדוח' תכיל את /debug/ , וה-aggregation_coordinator_origin field של 'גוף הדוח' יכיל את כתובת ה-URL הבאה: https://publickeyservice.msmt.gcp.privacysandboxservices.com.

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

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

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

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

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

עכשיו נעתיק את דוח ה-JSON אל "גוף הדוח" מ-chrome://private-aggregation-internals.

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

vim report.json

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

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

דוחות שמתקבלים מנקודות הקצה (endpoints) של .well-known הם בפורמט JSON וצריך להמיר אותם לפורמט דוח AVRO. אחרי שמקבלים את דוח ה-JSON, עוברים למקום שבו שמור report.json ומשתמשים ב-aggregatable_report_converter.jar כדי ליצור את הדוח המצטבר לניפוי באגים. הפעולה הזו יוצרת דוח מצטבר בשם report.avro בספרייה הנוכחית.

java -jar aggregatable_report_converter.jar \
  --request_type convertToAvro \
  --input_file report.json

3.1.4. יצירת Export_domain AVRO

כדי ליצור את הקובץ output_domain.avro, צריך את המפתחות של הקטגוריות שאפשר לאחזר מהדוחות.

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

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

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

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

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

java -jar aggregatable_report_converter.jar \
  --request_type createDomainAvro \
  --bucket_key <bucket key>

הסקריפט יוצר את הקובץ output_domain.avro בתיקייה הנוכחית.

3.1.5. העברת דוחות לקטגוריה של Cloud Storage

אחרי שתיצרו את דוחות ה-AVRO ואת דומיין הפלט, תוכלו להמשיך בהעברת הדוחות ודומיין הפלט לקטגוריה ב-Cloud Storage (שיצרתם כשלב האחרון בדרישה מוקדמת 1.6).

אם התקנתם את ה-CLI של gcloud בסביבה המקומית שלכם, תוכלו להעתיק את הקבצים לתיקיות המתאימות באמצעות הפקודות הבאות.

gcloud storage cp report.avro gs://<bucket_name>/reports/

gcloud storage cp output_domain.avro gs://<bucket_name>/output_domain/

אחרת, תוכלו להעלות את הקבצים לקטגוריה באופן ידני. יוצרים תיקייה בשם 'דוחות' ומעלים אליה את הקובץ report.avro. יוצרים תיקייה בשם output_domains ומעלים אליה את הקובץ output_domain.avro.

3.2. שימוש בשירותי צבירה

תזכורת בדרישה מוקדמת 1.8 שבחרתם ב-cURL או ב-Postman לשליחת בקשות API לנקודות קצה של שירות צבירה. בהמשך מופיעות הוראות לשתי האפשרויות.

3.2.1. שימוש בנקודת קצה (endpoint) של createJob כדי לקבץ

תוכלו ליצור משימה בעזרת ההוראות הבאות: cURL או Postman.

cURL

בקטע Terminal, יוצרים קובץ גוף בקשה (body.json) ומדביקים אותו למטה. חשוב לעדכן את הערכים הזמניים לשמירת מקום (placeholder). מידע נוסף על המשמעות של כל שדה זמין במסמכי התיעוד של ה-API.

הערה: attribution_report_to הוא המקור, שנקרא גם 'אתר דיווח של Ad Tech', שצורף בתהליך ההצטרפות לשירות הצבירה (דרישה מוקדמת 1.7).

{
  "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>",
    "report_error_threshold_percentage": "10",
    "debug_run": "true"
  }
}

מריצים את הבקשה הבאה. מחליפים את ערכי ה-placeholder בכתובת ה-URL של בקשת ה-cURL בערכים מהפלט frontend_service_cloudfunction_url, שנוצר אחרי שהפריסה של Terraform תקינה בדרישות המוקדמות 1.6.

curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  -d @body.json \
  https://<environment>-<region>-frontend-service-<cloud-function-id>-uc.a.run.app/v1alpha/createJob

תתקבל תשובה מסוג HTTP 202 אחרי שהבקשה תאושר על ידי שירות הצבירה. קודי תגובה אפשריים אחרים מופיעים במפרט של ה-API.

דוור

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

עוברים לכרטיסייה 'גוף' של הבקשה של createJob:

מחליפים את ה-placeholders בקובץ ה-JSON שסופק. מידע נוסף על השדות האלה ועל מה שהם מייצגים זמין במאמרי העזרה של ה-API.

הערה: attribution_report_to הוא המקור, שנקרא גם 'אתר דיווח של Ad Tech', שצורף בתהליך ההצטרפות לשירות הצבירה (דרישה מוקדמת 1.7).

{
  "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>",
    "report_error_threshold_percentage": "10",
    "debug_run": "true"
  }
}

"שליחה" של בקשת ה-API של createJob:

ניתן למצוא את קוד התגובה בחלק התחתון של הדף:

תתקבל תשובה מסוג HTTP 202 אחרי שהבקשה תאושר על ידי שירות הצבירה. קודי תגובה אפשריים אחרים מופיעים במפרט של ה-API.

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

תוכלו להיעזר בהוראות הבאות של cURL או של Postman כדי למצוא עבודה.

cURL

מבצעים את הבקשה הבאה בטרמינל. מחליפים את ערכי ה-placeholder שבכתובת ה-URL בערכים מ-frontend_service_cloudfunction_url, שהיא אותה כתובת URL שבה השתמשתם בבקשת createJob. בשדה 'job_request_id', משתמשים בערך מהמשימה שיצרתם בנקודת הקצה createJob.

curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  https://<environment>-<region>-frontend-service-<cloud-function-id>-uc.a.run.app/v1alpha/getJob?job_request_id=<job_request_id>

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

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

דוור

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

"שליחה" של בקשת getJob:

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

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

3.2.3. בדיקת דוח הסיכום

אחרי שתקבלו את דוח הסיכום בקטגוריית הפלט של Cloud Storage, תוכלו להוריד אותו לסביבה המקומית שלכם. דוחות סיכום הם בפורמט 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).

‫4. ‫4. ניקוי תלונות

כדי למחוק את המשאבים שנוצרו לשירות צבירת נתונים דרך Terraform, משתמשים בפקודת השמדה בתיקיות adtech_setup ו-dev (או בסביבה אחרת):

$ cd <repository_root>/terraform/gcp/environments/adtech_setup
$ terraform destroy
$ cd <repository_root>/terraform/gcp/environments/dev
$ terraform destroy

כדי למחוק את הקטגוריה של Cloud Storage שמכילה את הדוחות המצטברים ודוחות הסיכום:

$ gcloud storage buckets delete gs://my-bucket

יש לך גם אפשרות להחזיר את ההגדרות של קובצי ה-cookie ב-Chrome ממצב 'דרישה מוקדמת 1.2' למצבן הקודם.

5. 5. נספח

קובץ adtech_setup.auto.tfvars לדוגמה

/**
 * Copyright 2023 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

project = "my-project-id"

# Required to generate identity token for access of Adtech Services API endpoints
service_account_token_creator_list = ["user:[e-mail]"]

# Uncomment the below line if you like Terraform to create an Artifact registry repository
# for self-build container artifacts. "artifact_repo_location" defaults to "us".
artifact_repo_name     = "my-ags-artifacts"

# Note: Either one of [1] or [2] must be uncommented.

# [1] Uncomment below lines if you like Terraform grant needed permissions to
# pre-existing service accounts
# deploy_service_account_email = "<YourDeployServiceAccountName>@<ProjectID>.iam.gserviceaccount.com"
# worker_service_account_email = "<YourWorkerServiceAccountName>@<ProjectID>.iam.gserviceaccount.com"

# [2] Uncomment below lines if you like Terraform to create service accounts
# and needed permissions granted e.g "deploy-sa" or "worker-sa"
deploy_service_account_name = "deploy-sa"
worker_service_account_name = "worker-sa"
# Uncomment the below line if you want Terraform to create the
# below bucket. "data_bucket_location" defaults to "us".
data_bucket_name     = "my-ags-data"

# Uncomment the below lines if you want to specify service account customer role names
# deploy_sa_role_name = "<YourDeploySACustomRole>"
# worker_sa_role_name = "<YourWorkerSACustomRole>"

קובץ dev.auto.tfvars לדוגמה

/**
 * Copyright 2022 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

# Example values required by job_service.tf
#
# These values should be modified for each of your environments.
region      = "us-central1"
region_zone = "us-central1-c"

project_id  = "my-project-id"
environment = "operator-demo-env"

# Co-locate your Cloud Spanner instance configuration with the region above.
# https://cloud.google.com/spanner/docs/instance-configurations#regional-configurations
spanner_instance_config = "regional-us-central1"

# Adjust this based on the job load you expect for your deployment.
# Monitor the spanner instance utilization to decide on scale out / scale in.
# https://console.cloud.google.com/spanner/instances
spanner_processing_units = 100

# Uncomment the line below at your own risk to disable Spanner database protection.
# This needs to be set to false and applied before destroying all resources is possible.
spanner_database_deletion_protection = false

instance_type = "n2d-standard-8" # 8 cores, 32GiB

# Container image location that packages the job service application
# If not set otherwise, uncomment and edit the line below:
#worker_image = "<location>/<project>/<repository>/<image>:<tag or digest>"

# Service account created and onboarded for worker
user_provided_worker_sa_email = "[e-mail]"

min_worker_instances = 1
max_worker_instances = 20