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 של צד שלישי במצב פרטי' = מופעלת
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 לשירות צבירת נתונים.
שלבים מרכזיים בהוראות הפריסה:
- מגדירים את ה-CLI של gcloud ואת Terraform בסביבה שלכם.
- יצירת קטגוריה של Cloud Storage לאחסון מצבי Terraform.
- הורדה של יחסי תלות.
- מעדכנים את
adtech_setup.auto.tfvars
ומריצים את ה-Terraformadtech_setup
. אפשר לעיין בנספח לדוגמה של קובץadtech_setup.auto.tfvars
. - מעדכנים את
dev.auto.tfvars
, מתחזים לחשבון השירות לפריסה ומריצים אתdev
של Terraform. אפשר לעיין בנספח לדוגמה של קובץdev.auto.tfvars
. - בסיום הפריסה, מתעדים את
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://
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.
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.
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.
{
"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.
{
"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
(אם יש שגיאה למשימה).
דוור
כדי לבדוק את הסטטוס של בקשת המשימה, אפשר להשתמש בנקודת הקצה getJob
. בקטע 'Params' של הבקשה getJob
, מעדכנים את הערך של job_request_id
ל-job_request_id
שנשלח בבקשה createJob
.
"שליחה" של בקשת getJob
:
התוצאה אמורה להחזיר את הסטטוס של בקשת המשימה עם סטטוס HTTP של 200. הבקשה 'גוף' מכילה את המידע הנדרש כמו job_status
, return_message
ו-error_messages
(אם יש שגיאה למשימה).
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: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