אבחון הסביבה (חדשה או משודרגת)

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

נושאים במדריך:

• אימות ההגדרה של API למדידת לקוחות
• פתרון בעיות בהגדרת מקור הדיווח
• פתרון בעיות בדוחות המצטברים
• בדיקת גרסת הפריסה

בדיקת תקינות ההגדרה של API למדידת לקוחות

אחרי שמוודאים ששרת המקור נרשם בצורה תקינה, מבצעים את השלבים הבאים:

1. בודקים איך מפעילים את הדוחות. מוודאים שאתם מקבלים את פורמט הדוח הנכון בהתאם ל-API שבו אתם משתמשים:

   • Attribution Reporting API
     • ב-Attribution Reporting API, מוודאים שרשמתם בהצלחה את המקור (אירוע וסיכום). כדי לבצע רישום של טריגר (Event ו-Summary), צריך לוודא שקובץ ה-JSON שמועבר אל Attribution-Reporting-Register-Trigger תקין באמצעות כלי לאימות כותרות. (מידע נוסף על דוחות סיכום של Attribution Reporting API)
   • Private Aggregation API
     • אפשר להשלים את הדיווח ב-Private Aggregation API באמצעות הפונקציה contributeToHistogram. מוודאים שמעבירים את מפתח הדלי ואת הערך שלו. מפתח הדלי צריך להיות בפורמט BigInt. (מידע נוסף על Private Aggregation API)

2. אם אתם מפעילים דוחות כמומלץ, אבל הבעיה עדיין מתרחשת, בדקו אם יש שגיאות ב-Chrome Developer Console בכרטיסיות Console ו-Network.

אם אתם צריכים תמיכה נוספת לפתרון בעיות ב-API של הלקוח, תוכלו לעיין בהנחיות שלנו לניפוי באגים ב-Attribution Reporting API וב-Private Aggregation API + Shared Storage.

פתרון בעיות בהגדרת מקור הדיווח

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

האם המקור של הדוחות מקבל דוחות?

מוודאים ששרת המקור של הדוחות שנפרס רשום ומוגדר בצורה תקינה. בשרת הזה הצהרתם על נקודות הקצה (endpoint) התואמות הנכונות של .well-known, שאליהן יישלחו הדוחות שניתן לצבור.

אחרי שמוודאים ששרת המקור רשום בצורה תקינה, מבצעים את השלבים הבאים:

1. בודקים איך מפעילים את הדוחות. מוודאים שאתם מקבלים את פורמט הדוח הנכון בהתאם ל-API שבו אתם משתמשים:

   • דוחות סיכום של Attribution Reporting API
   • Private Aggregation API

2. אם אתם מפעילים דוחות לפי ההמלצות אבל הבעיה עדיין מתרחשת, כדאי לבדוק אם יש שגיאות ב-Chrome Developer Console בכרטיסיות Console ו-Network.

אם אתם צריכים תמיכה נוספת בפתרון בעיות שקשורות לממשקי הלקוח האלה , תוכלו להמשיך לקרוא את ההנחיות לניפוי באגים ב-Attribution Reporting API וב-Private Aggregation API + Shared Storage.

פתרון בעיות בדוחות הצבירה

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

האם הדוחות שניתן לצבור מהם נתונים מציגים נתוני המרות בצורה נכונה?

מוודאים שנקודת הקצה של הדיווח (.well-known/…) ממירה נכון את דוח ה-JSON המצטבר שצוין ל-AVRO.

אלה שגיאות ה-API שיופיעו בגלל הבעיה הזו:

                "result_info": {
                    "return_code": "REPORTS_WITH_ERRORS_EXCEEDED_THRESHOLD",
                    "return_message": "Aggregation job failed early because the number of reports excluded from aggregation exceeded threshold.",
                    "error_summary": {
                        "error_counts": [
                            {
                                "category": "DECRYPTION_ERROR",
                                "count": 1,
                                "description": "Unable to decrypt the report. This may be caused by: tampered aggregatable report shared info, corrupt encrypted report, or other such issues."
                            },
                            {
                                "category": "NUM_REPORTS_WITH_ERRORS",
                                "count": 1,
                                "description": "Total number of reports that had an error. These reports were not considered in aggregation. See additional error messages for details on specific reasons."
                            }
                        ],
                        "error_messages": []
                    }
                }
            

                "result_info": {
                    "return_code": "REPORTS_WITH_ERRORS_EXCEEDED_THRESHOLD",
                    "return_message": "Aggregation job failed early because the number of reports excluded from aggregation exceeded threshold.",
                    "error_summary": {
                        "error_counts": [{
                            "category": "DECRYPTION_KEY_NOT_FOUND",
                            "count": 1,
                            "description": "Could not find decryption key on private key endpoint."
                        }, {
                            "category": "NUM_REPORTS_WITH_ERRORS",
                            "count": 1,
                            "description": "Total number of reports that had an error. These reports were not considered in aggregation. See additional error messages for details on specific reasons."
                        }],
                        "error_messages": []
                    }
                }
            

                sharedStorage.run('someOperation', {'privateAggregationConfig':
                {'aggregationCoordinatorOrigin': ' https://publickeyservice.msmt.gcp.privacysandboxservices.com'}});

            

                "result_info": {
                        "return_code": "REPORTS_WITH_ERRORS_EXCEEDED_THRESHOLD",
                        "return_message": "Aggregation job failed early because the number of reports excluded from aggregation exceeded threshold.",
                        "error_summary": {
                            "error_counts": [
                                {
                                    "category": "DECRYPTION_KEY_FETCH_ERROR",
                                    "count": 1,
                                    "description": "Fetching the decryption key for report decryption failed. This can happen using an unapproved aggregation service binary, running the aggregation service binary in debug mode, key corruption or service availability issues."
                                },
                                {
                                    "category": "NUM_REPORTS_WITH_ERRORS",
                                    "count": 1,
                                    "description": "Total number of reports that had an error. These reports were not considered in aggregation. See additional error messages for details on specific reasons."
                                }
                            ]
                        }
                }
            

כדי לבצע אימות:

1. אתם יכולים להשתמש בכלי aggregatable_report_converter כדי להמיר את הדוחות המצטברים שאספתם מנקודת הקצה .well-known ל-AVRO, וליצור את מפתחות הדומיין של הפלט. (הערה: קבצי פלט של דומיין צריכים להיות מחרוזת בייט של 16 בייט בפורמט big-endian).

2. פועלים לפי השלבים במעבדת הקוד של ספק הענן הציבורי כדי לאסוף את דוחות הניפוי באגים ולהריץ עבודה של Aggregation Service באמצעות מפתחות הדומיין של הפלט: א. ‫Google Cloud: פועלים לפי שלבים 3.1.2 עד 3.2.3 של ה-Codelab בנושא שירות הצבירה של Google Cloud. ‫ב. ‫Amazon Web Services: פועלים לפי שלבים 4.2 עד 5.3 ב-Codelab של שירות הצבירה של AWS.

אם מוחזרת תשובה SUCCESS, סימן שההמרה פועלת.

האם הדוחות המצטברים שלכם תקינים?

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

אלה שגיאות ה-API שיוצגו לכם אם הבעיה הזו מתרחשת:

כדי לבצע אימות:

1. אימות דוח צבירה:

   • יוצרים דוחות מצטברים ומשתמשים בכלי aggregatable_report_converter כדי להמיר את דומיין הפלט לפורמט AVRO.
   • מריצים בקשת createJob עם הדוח הזה שניתן לצבירה ועם קובץ הפלט של הדומיין.
   • אם הפונקציה מחזירה SUCCESS, המשמעות היא שהדוח המצטבר תקין. אם מוחזרת שגיאה, יש בעיה בדוח המצטבר או בדוח ובדומיין.
   • בשלב הבא בודקים את קובץ הדומיין.

2. מאמתים את קובץ הדומיין של הפלט:

   • יוצרים קובץ של דומיין פלט ומשתמשים בכלי aggregatable_report_converter כדי ליצור את הדוח שניתן לצבירה.
   • מריצים בקשת createJob עם הדוח הזה שניתן לצבירה ועם קובץ הפלט של הדומיין.
   • אם הפקודה מחזירה SUCCESS, המשמעות היא שהדומיין של הפלט תקין ויש בעיה בקוד שיוצר את הדוח שניתן לצבירה.
   • ממשיכים לשלב הבא כדי לבדוק את shared_info.

3. אימות המידע ששותף:

   • מוודאים שהפעלתם דוחות ניפוי באגים. בדוחות שבהם מופעל ניפוי באגים יהיה שדה debug_cleartext_payload.
   • יוצרים דוח ניפוי באגים לשימוש בכלי הבדיקה המקומי ומשתמשים ב-debug_cleartext_payload בתור מטען הייעודי (payload).
   • מריצים את כלי הבדיקה המקומי עם קובץ הדומיין. אם מופיעה הודעת השגיאה SUCCESS, המשמעות היא שהקובץ shared_info עבר שינוי לא מורשה.

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

בדיקה של גרסת הפריסה החדשה

מוודאים שעדיין יש תמיכה בגרסה של שירות הצבירה. אחרי שתקבעו באיזו גרסה אתם משתמשים, תוכלו לעיין ברשימת הגרסאות של Aggregation Service ולוודא שהגרסה שלכם לא כוללת את האזהרה על סיום התמיכה:This release has reached its end of support on { date }. ההוראות הבאות לקביעת הגרסה שפרסתם מיועדות לעננים ציבוריים נתמכים.

שלבים ל-Google Cloud

1. מנווטים אל Compute Engine > VM instances.
2. לוחצים על המכונה הווירטואלית עם -worker- בשם.
3. מוצאים את הקטע Custom Metadata ואז מאתרים את המפתח tee-image-reference.
   • הערה: לכל מכונה וירטואלית שמוקצתת ב-Google Cloud על ידי Terraform צריכים להיות המטא-נתונים האלה (מטא-נתונים של tee-image-reference במודול worker).
4. הערך של tee-image-reference יכיל את מספר הגרסה. לדוגמה, מספר הגרסה של הנתיב הבא הוא v2.9.1. אלה תמונות מוכנות מראש שנמצאות במאגר Artifact Registry של פרויקט ב-Google Cloud.
   • הערה: המידע הזה רלוונטי אם אתם משתמשים בנכסים דיגיטליים מוכנים מראש. אם לא, הערך צריך להיות זהה למה שנתתם לתמונה כשם ותייגתם אותה. (לדוגמה: us.docker.pkg.dev/<gcp_project_name>/artifacts:aggregation-service- container-artifacts-worker_mp_go_prod:2.9.1)

שלבים ל-Amazon Web Services

1. עוברים אל EC2 Instances במסוף Amazon Web Services.
2. לוחצים על המופע עם השם aggregation-service-operator-dev-env.
3. בדף של המופע, מחפשים את הקטע Details (פרטים) > AMI (Amazon Machine Image).
4. נתיב התמונה צריך לכלול את שם הגרסה. לדוגמה, מספר הגרסה של הנתיב הבא הוא v2.9.1.
   • הערה: המידע הזה רלוונטי אם אתם משתמשים בנכסים דיגיטליים מוכנים מראש. אם לא, הערך צריך להיות זהה למה שנתתם לתמונה כשם ותייגתם אותה. (לדוגמה: aggregation-service-enclave_2.9.1--2024-10-03T01-24-25Z)

השלבים הבאים

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