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

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

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

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

הפעלת קובצי cookie

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

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

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

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

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

בדיקת הגרסה של Java

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

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

אפשר להוריד עותק של aggregatable_report_converter ממאגר ההדגמות של ארגז החול לפרטיות ב-GitHub. במאגר של GitHub יש אזכור של IntelliJ או Eclipse, אבל הם לא נדרשים. אם אתם לא משתמשים בכלים האלה, הורידו את קובץ ה-JAR לסביבה המקומית שלכם.

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

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

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

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

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

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

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

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

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

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

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

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

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

סביבת עבודה של Postman

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

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

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

ייבוא של שני קובצי ה-JSON אל 'סביבת העבודה שלי' דרך 'ייבוא' לחצן.

לחצן יבוא

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

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

לוחצים על 'GCP Privacy Sandbox' (ארגז החול לפרטיות ל-GCP) אוסף ומנווטים אל 'הרשאה' .

לחצן הרשאה

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

gcloud auth print-identity-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:

דף פנימי ב-Chrome

הדוח שנשלח לנקודת הקצה {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.

דוח ניפוי באגים ל-GCP

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 ושומרים את הקובץ.

דיווח על 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 מגוף הדוח.

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

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

לחצן פענוח הקוד

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

מפתח קטגוריה

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.

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

פלט JSON

Codelab הושלם!

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

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

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:

דף פנימי ב-Chrome

הדוח שנשלח לנקודת הקצה {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.

דוח ניפוי באגים ל-GCP

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 ושומרים את הקובץ.

דיווח על 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 מגוף הדוח.

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

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

לחצן פענוח הקוד

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

מפתח קטגוריה

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

אם המשימה נכשלה בגלל שגיאה, תוכלו לעיין במסמכי העזרה שלנו לפתרון בעיות ב-GitHub כדי לקבל מידע נוסף לגבי המשך התהליך.

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

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

cURL

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

{
  "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"
  }
}

מריצים את הבקשה הבאה. מחליפים את ערכי ה-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.

Postman

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

ניווט ל'גוף' של הבקשה של createJob :

כרטיסיית גוף

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

{
  "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"
  }
}

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

לחצן &#39;שלח&#39;

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

קוד תגובה

תתקבל תשובה מסוג 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 (אם אירעה שגיאה למשימה).

Postman

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

מזהה בקשת משימה

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

לחצן &#39;שלח&#39;

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

תגובת JSON

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).

Codelab הושלם!

סיכום: פרסתם את שירות הצבירה בסביבת הענן שלכם, אספתם דוח ניפוי באגים, בנית קובץ של דומיין פלט, אחסנתם את הקבצים האלה בקטגוריה של Cloud Storage וביצעתם משימה מוצלחת!

השלבים הבאים: המשיכו להשתמש ב-Aggregation Service בסביבה שלכם, או מוחקים את משאבי הענן שיצרתם כרגע לפי הוראות הניקוי בשלב 4.

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:me@email.com"]

# 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 = "worker-sa@my-project-id.iam.gserviceaccount.com"

min_worker_instances = 1
max_worker_instances = 20