בדיקת הסטטוס והאבחון של הבקשה

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

משתמשים ב-request_id שהוחזר עם RetrieveRequestStatus כדי לבדוק את סטטוס ההעלאה ולעיין בניתוחים.

כדי לבדוק את הסטטוס של הבקשות ולוודא שההעלאות של האירועים והקהלים תקינות, מומלץ לפעול לפי השלבים הבאים:

1. שליחת בקשות לשליחת אירועים או לשליחה או הסרה של משתמשים מקהל היעד.

2. לבדוק את הסטטוס הכללי של כל בקשת הטמעה. בקשה מוצלחת כוללת Status עם code ששווה ל-0 (ערך enum‏ OK, תגובת HTTP‏ 200 OK), ומחזירה IngestEventsResponse,‏ IngestAudienceMembersResponse או RemoveAudienceMembersResponse.

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

   אם הבקשה מצליחה, מתעדים את ה-request_id של התגובה כדי שתוכלו להשתמש בו לבדיקת סטטוס העיבוד בשלב הבא.

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

3. ממתינים 30 דקות ואז שולחים בקשת RetrieveRequestStatus לכל request_id שהושלם בהצלחה.

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

   טיפ: אפשר לנסות לשלוח בקשה בדפדפן באמצעות API Explorer.

   חוזרים על השלב הזה מדי פעם לכל request_id עד שסטטוס היעד של כל יעד מגיע לערך SUCCESS,‏ PARTIAL_SUCCESS או FAILED. כדי להמתין בין כל בקשה, פועלים לפי אסטרטגיית הסקרים המומלצת.

4. כדאי לעיין בכל RetrieveRequestStatusResponse כדי לוודא שההעלאות פועלות כמו שצריך ולזהות בעיות בנתונים.

5. לפתור בעיות בנתונים.

6. חוזרים לשלב 1 וחוזרים על הפעולות עד שכל הבעיות בהעלאות נפתרות.

בדיקת הסטטוס הכולל של היעד

השדה request_status_per_destination ב-RetrieveRequestStatusResponse מכיל רשומה נפרדת לכל יעד בבקשת ההטמעה התואמת.

לדוגמה, אם IngestAudienceMembersRequest הכיל 3 רשומות ברשימה destinations כדי לשלוח נתונים ל-3 קהלים שונים, התגובה של הסטטוס תכיל 3 רשומות ב-request_status_per_destination (רשומה אחת לכל קהל).

בודקים את השדה request_status בכל RequestStatusPerDestination כדי לקבוע אם Data Manager API סיים לעבד את הנתונים של היעד הזה.

אלה הערכים האפשריים של request_status:

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

• ‫SUCCESS: עיבוד הבקשה ליעד הושלם בלי שגיאות. בודקים אם יש אזהרות שסומנו במהלך העיבוד.

• FAILED: כל הרשומות של היעד נכשלו בגלל שגיאות. בודקים אם יש אזהרות ושגיאות כדי להבין למה כל הרשומות נכשלו. כדאי גם לבדוק אם יש אזהרות שסומנו במהלך העיבוד.

• ‫PARTIAL_SUCCESS: חלק מהרשומות ליעד הצליחו, אבל אחרות נכשלו בגלל שגיאות. בודקים אם יש שגיאות כדי להבין למה חלק מהרשומות נכשלו. כדאי גם לבדוק אם יש אזהרות שסומנו במהלך העיבוד.

סקירת האבחון

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

בדיקת הסטטוס של אירוע או קהל לפי יעד

בודקים את שדה הסטטוס שתואם לסוג בקשת ההטמעה. רק אחד מהשדות הבאים מוגדר בכל RequestStatusPerDestination:

• events_ingestion_status

• audience_members_ingestion_status

• audience_members_removal_status

סטטוס הטמעת האירועים

השדה events_ingestion_status מאוכלס אם הבקשה הייתה IngestEventsRequest.

בודקים את record_count של IngestEventStatus כדי לוודא שהמספר הכולל של הרשומות שהתקבלו תואם לציפיות. הקובץ record_count כולל גם רשומות שהצליחו וגם רשומות שנכשלו.

סטטוס הטמעת הנתונים של משתמשים מקהל היעד

השדה audience_members_ingestion_status מאוכלס אם הבקשה הייתה IngestAudienceMembersRequest. כאן מפורט השדה IngestAudienceMembersStatus שצריך לבדוק בכל סוג של נתוני קהל. רק אחד מהשדות האלה מוגדר.

composite_data_ingestion_status

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

בודקים את data_type_counts כדי לוודא שמספר המזהים תואם לציפיות. הרשימה הזו כוללת פירוט של כל המזהים שהתקבלו על ידי DataType (כמו כתובת אימייל, מספר טלפון, כתובת פיזית וכתובת IP).

אם בבקשה היה מספר מספיק של רשומות, השדה upload_match_rate_range מכיל את טווח אחוז הלקוחות לטירגוט של הרשומות בבקשה.

google_user_id_data_ingestion_status

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

בודקים את google_user_id_count כדי לוודא שמספר מזהי המשתמשים ב-Google שהתקבלו תואם לציפיות.

mobile_data_ingestion_status

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

בודקים את mobile_id_count כדי לוודא שמספר ה-Mobile ID (mID) שהתקבלו תואם לציפיות.

pair_data_ingestion_status

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

בודקים את pair_id_count כדי לוודא שמספר המזהים של PAIR שהתקבלו תואם לציפיות.

partner_provided_id_data_ingestion_status

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

בודקים את partner_provided_id_count כדי לוודא שמספר המזהים שסופקו על ידי שותפים תואם לציפיות שלכם.

ppid_data_ingestion_status

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

בודקים את ppid_count כדי לוודא שמספר המזהים שהתקבלו תואם לציפיות.

user_data_ingestion_status

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

בודקים את user_identifier_count כדי לוודא שמספר מזהי המשתמשים שהתקבלו תואם לציפיות.

אם בבקשה היה מספר מספיק של רשומות, השדה upload_match_rate_range מכיל את טווח אחוז הלקוחות לטירגוט של הרשומות בבקשה.

user_id_data_ingestion_status

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

בודקים את user_id_count כדי לוודא שמספר מזהי המשתמשים שהתקבלו תואם לציפיות.

סטטוס ההסרה של משתמשים מקהל היעד

השדה audience_members_removal_status מאוכלס אם הבקשה הייתה RemoveAudienceMembersRequest. כאן מפורט השדה RemoveAudienceMembersStatus שצריך לבדוק בכל סוג של נתוני קהל. רק אחד מהשדות האלה מוגדר.

composite_data_removal_status

סטטוס ההסרה של נתונים מורכבים

google_user_id_data_removal_status

סטטוס ההסרה של נתוני מזהה המשתמש ב-Google

mobile_data_removal_status

סטטוס ההסרה של חבילת הגלישה.

pair_data_removal_status

סטטוס ההסרה של נתוני PAIR.

partner_provided_id_data_removal_status

סטטוס ההסרה של נתוני מזהה שסופקו על ידי שותף

ppid_data_removal_status

סטטוס ההסרה של נתוני ה-PPID.

user_data_removal_status

סטטוס ההסרה של נתוני המשתמשים.

user_id_data_removal_status

סטטוס ההסרה של נתוני מזהה המשתמש

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

בנוסף, כדאי לבדוק את user_identifier_count, mobile_id_count, pair_id_count, ppid_count, user_id_count, google_user_id_count או partner_provided_id_count כדי לאשר את המספר הכולל של המזהים שהתקבלו.

בנתונים מורכבים, בודקים את data_type_counts כדי לוודא שמספר המזהים תואם לציפיות. הרשימה הזו כוללת פירוט של כל המזהים שהתקבלו (כמו כתובת אימייל, מספר טלפון, כתובת פיזית וכתובת IP) לפי DataType.

בדיקת אזהרות ושגיאות

בנוסף לשדות הסטטוס של היעד וסוג הבקשה, RetrieveRequestStatusResponse מכיל פירוט של האזהרות והשגיאות של הבקשה.

• שגיאה מציינת שה-API דחה את הרשומה לחלוטין.

• אזהרה מציינת שה-API לא דחה את הרשומה, אבל הוא נאלץ להתעלם מחלקים מהנתונים של הרשומה.

לדוגמה, אם Event מכיל נתוני UserIdentifier מוצפנים ו-AdIdentifiers כמו gclid, ואי אפשר לפענח את נתוני UserIdentifier, ‏Data Manager API עדיין מעבד את הרשומה באמצעות AdIdentifiers אבל מחזיר את האזהרה PROCESSING_WARNING_REASON_USER_IDENTIFIER_DECRYPTION_ERROR.

עם זאת, אם השדה Event לא מכיל את הערך AdIdentifiers ואי אפשר לפענח את הנתונים בשדה UserIdentifier, ה-Data Manager API דוחה את הרשומה כולה ומדווח על השגיאה PROCESSING_ERROR_REASON_USER_IDENTIFIER_DECRYPTION_ERROR, כי שדה Event תקין חייב להכיל לפחות אחד מהערכים ad_identifiers או user_data.

אלה השדות בתגובה שמכילים מידע על אזהרות ושגיאות. השדות האלה מאוכלסים כשסטטוס היעד הכולל מגיע ל-SUCCESS,‏ PARTIAL_SUCCESS או FAILED.

warning_info

אובייקט WarningInfo. השדה warning_counts מכיל רשימה של אובייקטים מסוג WarningCount. כל WarningCount מכיל reason עם סוג האזהרה, ו-record_count שמציין את מספר הרשומות שבהן הופיעה אזהרה מהסוג הזה.

כדאי לבדוק את warning_info גם אם הסטטוס הכולל של היעד הוא SUCCESS.

error_info

אובייקט מסוג ErrorInfo. השדה error_counts מכיל רשימה של אובייקטים מסוג ErrorCount. כל ErrorCount מכיל reason עם סוג השגיאה, ו-record_count שמציין את מספר הרשומות שנכשלו בגלל סוג השגיאה הזה.

אסטרטגיית דגימה

שולחים מדי פעם את הבקשה RetrieveRequestStatusRequest באמצעות אלגוריתם של השהיה מעריכית לפני ניסיון חוזר (exponential backoff) עד שהערך של request_status מגיע ל-SUCCESS, ל-FAILED או ל-PARTIAL_SUCCESS בכל יעד בבקשה המקורית. התהליך הזה יכול להימשך עד 24 שעות, אבל יכול להיות ש-Data Manager API יסיים לעבד חלק מהבקשות תוך 30 דקות בלבד.

דוגמה להגדרה סבירה של זמן המתנה ראשוני וניסיונות חוזרים, שמאזנת בין זמן התגובה לבין השימוש במכסות:

הגדרה	ערך
זמן ההמתנה לפני בקשת האבחון הראשונה (בדקות)	30
מכפיל השהיה	1.3
השהיה מקסימלית (דקות)	‫60 (שעה אחת)
משך הזמן הכולל המקסימלי (דקות)	‫1440 (24 שעות)

כך נראה רצף של בקשות והזמן שחלף עם ההגדרה הזו:

תרשים

נתונים

ניסיון	הזמן שעבר מאז בקשת ההטמעה (hh:mm)	השהיה לפני ניסיון	הערות
1	00:30	‫30.0 דקות	קודם בודקים אם הסטטוס זמין
2	01:09	‫39.0 דקות
3	01:59	‫50.7 דקות
4	02:59	‫60.0 דקות	העיכוב מוגבל עכשיו לשעה אחת
5	03:59	‫60.0 דקות
6	04:59	‫60.0 דקות
7	05:59	‫60.0 דקות
8	06:59	‫60.0 דקות
9	07:59	‫60.0 דקות
10	08:59	‫60.0 דקות
11	09:59	‫60.0 דקות
12	10:59	‫60.0 דקות
13	11:59	‫60.0 דקות	סימון של 12 שעות
14	12:59	‫60.0 דקות
15	13:59	‫60.0 דקות
16	14:59	‫60.0 דקות
17	15:59	‫60.0 דקות
18	16:59	‫60.0 דקות
19	17:59	‫60.0 דקות
20	18:59	‫60.0 דקות
21	19:59	‫60.0 דקות
22	20:59	‫60.0 דקות
23	21:59	‫60.0 דקות
24	22:59	‫60.0 דקות
25	23:59	‫60.0 דקות	הבקשה האחרונה לפני הזמן המקסימלי הכולל של 24 שעות

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

דרישות הרשאה

RetrieveRequestStatusRequest לא מקבלת חשבונות יעד או כותרות של בקשות. במקום זאת, ה-Data Manager API מזהה את היעדים מבקשת ההטמעה המקורית שמשויכת ל-request_id, ומוודא שלגורם ששלח את הבקשה יש גישה ל-operating_account בכל Destination.

כדי לבדוק את הסטטוס של בקשה, פרטי הכניסה שמשמשים ב-RetrieveRequestStatusRequest צריכים לעמוד בדרישות הבאות לגבי ה-operating_account של כל יעד מבקשת ההטמעה המקורית:

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

  לדוגמה, אם בקשת הטמעה של operating_account ב-Google Ads ציינה חשבון ניהול ראשי בתור login_account, לפרטי הכניסה צריכה להיות גם גישה אל operating_account דרך אותו חשבון ניהול. גם אם לחשבון Google שמשויך לפרטי הכניסה יש גישה ישירה לחשבון הצאצא operating_account, הבקשה תיכשל ותופיע השגיאה PERMISSION_DENIED אם לחשבון הזה אין גישה דרך חשבון הניהול login_account שצוין במהלך ההטמעה.

• רמת גישה מספיקה: לחשבון Google שמשויך לפרטי הכניסה צריכה להיות רמת גישה או תפקיד עם הרשאה להטמיע נתונים ב-operating_account.

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