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

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

הזמן המשוער לביצוע: שעה עד שעתיים

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

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

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

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

1.2. הפעלת ממשקי API לשמירה על פרטיות בפרסום (שירות למצטבר ולבדיקה מקומית)

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

בדפדפן, עוברים אל chrome://settings/adPrivacy ומפעילים את כל ממשקי ה-API של פרטיות הפרסום.

בנוסף, חשוב לוודא שקובצי ה-cookie של הצד השלישי מופעלים.

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

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

הפעלת קובצי cookie

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

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

הכלי לבדיקות מקומיות זמין להורדה בארכיוני JAR של Cloud Functions ב-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 (Aggregation Service)

כדי להשתמש בשירות הצבירה, צריך להשתמש בסביבת מחשוב אמינה (TEE) שמשתמשת בספק ענן. בקודלאב הזה, נעביר את Aggregation Service ל-GCP, אבל יש תמיכה גם ב-AWS.

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

השלבים העיקריים בהוראות הפריסה:

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

1.7. השלמת תהליך ההצטרפות ל-Aggregation Service (Aggregation Service)

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

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

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

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

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

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

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

Postman Workspace

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

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

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

מייבאים את שני קובצי ה-JSON אל 'המרחב המשותף שלי' באמצעות הלחצן 'ייבוא'.

לחצן יבוא

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

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

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

לחצן ההרשאה

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

gcloud auth print-identity-token

לאחר מכן מדביקים את ערך האסימון הזה בשדה Token (אסימון) בכרטיסייה Authorization (הרשאה) ב-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. אחזור מפתחות הקטגוריות: מפתחות הקטגוריות תוכננו על ידי חברות טכנולוגיות פרסום. ב-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 Internals

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

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

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

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

מעתיקים את הדוח שנמצא בקטע 'Report Body' של 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. עם זאת, במקרה הזה, מפתחות הקטגוריות נוצרים באתר Privacy Sandbox Demo. מכיוון שהצבירה הפרטית באתר הזה נמצאת במצב ניפוי באגים, אפשר להשתמש ב-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.

פלט AVRO

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

דוח הסיכום שנוצר הוא בפורמט AVRO. כדי שתוכלו לקרוא את הקובץ, צריך להמיר אותו מ-AVRO לפורמט JSON. באופן אידיאלי, ספקי הטכנולוגיה לפרסום צריכים לכתוב קוד כדי להמיר דוחות 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!

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

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

3. 3. Codelab בנושא Aggregation Service

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

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

השלבים ב-Codelab

שלב 3.1. יצירת קלט ל-Aggregation Service: יצירת הדוחות של Aggregation Service שמקובצים עבור Aggregation Service.

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

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

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

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

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

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

עוקבים אחרי הקישור כדי לעבור לאתר, ואז אפשר להציג את הדוחות בכתובת chrome://private-aggregation-internals:

הדף Chrome Internals

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

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

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

3.1.2. איסוף דוחות שניתן לצבור

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

  • Private Aggregation: ‏ {reporting-origin}/.well-known/private-aggregation/report-shared-storage
  • דוחות שיוך (Attribution) – דוח סיכום: {reporting-origin}/.well-known/attribution-reporting/report-aggregate-attribution

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

עכשיו מעתיקים את דוח ה-JSON בקטע 'Report Body' (גוף הדוח) מ-chrome://private-aggregation-internals.

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

vim report.json

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

דוח JSON

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

הדוחות שמתקבלים מנקודות הקצה .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. יצירת AVRO של output_domain

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

מפתחות הקטגוריות נוצרים על ידי חברת ה-adTech. עם זאת, במקרה הזה, מפתחות הקטגוריות נוצרים באתר Privacy Sandbox Demo. מכיוון שהצבירה הפרטית באתר הזה נמצאת במצב ניפוי באגים, אנחנו יכולים להשתמש ב-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. שימוש בשירות Aggregation

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

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

3.2.1. שימוש בנקודת קצה createJob כדי ליצור קבוצות

כדי ליצור משימה, פועלים לפי ההוראות הבאות ל-cURL או ל-Postman.

cURL

ב-Terminal, יוצרים קובץ של גוף הבקשה (body.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"
  }
}

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

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

הכרטיסייה &#39;גוף&#39;

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

כדי לקבל משימה, פועלים לפי ההוראות הבאות ל-cURL או ל-Postman.

cURL

מריצים את הבקשה הבאה במסוף. מחליפים את הסמנים הזמניים בכתובת ה-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. החלק 'Body' בבקשה מכיל את המידע הנדרש, כמו job_status,‏ return_message ו-error_messages (אם המשימה נכשלה).

Postman

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

מזהה בקשת העבודה

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

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

התוצאה אמורה להחזיר את הסטטוס של בקשת העבודה עם סטטוס HTTP של 200. החלק 'Body' בבקשה מכיל את המידע הנדרש, כמו 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. ניקוי תלונות

כדי למחוק את המשאבים שנוצרו ל-Aggregation Service דרך Terraform, משתמשים בפקודה destroy בתיקיות 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